XCORE SDK
XCORE Software Development Kit
Public Attributes | List of all members
xs3_filter_fir_s16_t Struct Reference

16-bit Discrete-Time Finite Impulse Response (FIR) Filter More...

#include <xs3_filters.h>

Public Attributes

unsigned num_taps
 
right_shift_t shift
 
int16_t * coef
 
int16_t * state
 

Detailed Description

16-bit Discrete-Time Finite Impulse Response (FIR) Filter

Filter Model

This struct represents an N-tap 16-bit discrete-time FIR Filter.

At each time step, the FIR filter consumes a single 16-bit input sample and produces a single 16-bit output sample.

To process a new input sample and compute a new output sample, use xs3_filter_fir_s16(). To add a new input sample to the filter without computing a new output sample, use xs3_filter_fir_s16_add_sample().

An N-tap FIR filter contains N 16-bit cofficients (pointed to by coef) and N int16_ts of state data (pointed to by state. The state data is a vector of the N most recent input samples. When processing a new input sample at time step t, x[t] is the new input sample, x[t-1] is the previous input sample, and so on, up to x[t-(N-1)], which is the oldest input considered when computing the new output sample (see note 1 below). The coefficients form a vector b[], where b[k] is the coefficient by which the kth oldest input sample is multiplied. There is an additional parameter shift which scales the output as described below. Both the coefficients and shift are considered to be constants which do not change after initialization (although nothing should break if they are changed to new valid values).

At time step t, the output sample y[t] is computed based on the inner product (i.e. sum of element-wise products) of the coefficients and state data as follows (a more detailed description is below):

acc = x[t-0] * b[0] + x[t-1] * b[1] + x[t-2] * b[2] + ... + x[t-(N-1)] * b[N-1]
y[t] = acc >> shift

Unlike the 32-bit FIR filters (see xs3_filter_fir_s16_t), the products x[t-k] * b[k] are the raw 32-bit products of the 16-bit elements. These element-wise products accumulate into a 32-bit accumulator which saturates the sums at symmetric 32-bit bounds (see Symmetrically Saturating Arithmetic).

After all taps have been accumulated, a rounding arithmetic right-shift of shift bits is applied to the 64-bit sum, and the final result is saturated to the symmetric 16-bit range (-INT16_MAX to INT16_MAX inclusive).

Below is a more detailed description of the operations performed (not including the saturation logic applied by the accumulators).

\[ & y[t] = sat_{16} \left( round \left( \left( \sum_{k=0}^{N-1} round(x[t-k] \cdot b[k]) \right) \cdot 2^{-shift} \right) \right) \\ & \qquad\text{where } sat_{32}() \text{ saturates to } \pm(2^{15}-1) \\ & \qquad\text{ and } round() \text{ rounds to the nearest integer, with ties rounding towards } +\!\infty \]

Operations

Initialize: A xs3_filter_fir_s16_t filter is initialized with a call to xs3_filter_fir_s16_init(). The caller supplies information about the filter, including the number of taps and pointers the coefficients and a state buffer. It is typically recommended that the state buffer be cleared to all 0s before initializing.

Add Sample: To add a new input sample without computing a new output sample, use xs3_filter_fir_s16_add_sample(). Unlike xs3_filter_fir_s32_add_sample(), this is not a constant-time operation, and does depend on the number of filter taps. Nevertheless, this is faster than computing output samples, and may be useful in some situations, for example, to moer quickly pre-load the filter's state buffer with multiple samples, without incurring the cost of computing an output with each added sample.

Process Sample: To process a new input sample and produce a new output sample, use xs3_filter_fir_s16().

Fields

After initialization via xs3_filter_fir_s16_init(), the contents of the xs3_filter_fir_s16_t struct are considered to be opaque, and may change between major versions. In general, user code should not need to access its members.

num_taps is the order of the filter, or the number of taps. It is also the (minimum) size of the buffers to which coef and state point, in elements (where each element is 2 bytes). The time required to process an input sample and produce an output sample is approximately linear in num_taps (see Performance below).

shift is the unsigned arithmetic rounding saturating right-shift applied to internal accumulator to get a final output.

coef is a pointer to a buffer (supplied by the user at initialization) containing the tap coefficients. The coefficients are stored in forward order, with lower indices corresponding to newer samples. coef[0], then, corresponds to b[0], coef[1] to b[1], and so on. None of the functions which operate on xs3_filter_fir_s16_t structs in this library will modify the contents of the buffer to which coef points. This buffer must be at least num_taps elements long, and must begin at a word-aligned address.

state is a pointer to a buffer (supplied by the user at initialization) containing the state data – a history of the num_taps most recent input samples. state must begin at a word-aligned address.

Coefficient Scaling

Filter Conversion

This library includes a python script which converts existing floating-point FIR filter coefficients into a suitable representation and generates code for easily initializing and executing the filter. See Note: Digital Filter Conversion for more.

Usage Example

Todo:
See also
xs3_filter_fir_s16_init, xs3_filter_fir_s16_add_sample, xs3_filter_fir_s16

Member Data Documentation

◆ coef

int16_t* xs3_filter_fir_s16_t::coef

Pointer to a buffer containing the filter coefficients. Must point to word-aligned address.

◆ num_taps

unsigned xs3_filter_fir_s16_t::num_taps

The number of taps in the FIR filter.

This is also the number of elements in state and coef

◆ shift

right_shift_t xs3_filter_fir_s16_t::shift

Unsigned arithmetic rounding right-shift applied to accumulator when computing filter output.

◆ state

int16_t* xs3_filter_fir_s16_t::state

Pointer to a circular buffer containing the previous input samples. Must point to word-aligned address.


The documentation for this struct was generated from the following file: