..
Copyright 2022 Xilinx, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.. _FILTERS:
=======
Filters
=======
The DSPLib contains several variants of Finite Impulse Response (FIR) filters.
These include single-rate FIRs, half-band interpolation/decimation FIRs, as well as integer and fractional interpolation/decimation FIRs. More details in the :ref:`FILTER_ENTRY`.
.. _FILTER_ENTRY:
~~~~~~~~~~~
Entry Point
~~~~~~~~~~~
FIR filters have been categorized into classes and placed in a distinct namespace scope: xf::dsp::aie::fir, to prevent name collision in the global scope. Namespace aliasing can be utilized to shorten instantiations:
.. code-block::
namespace dsplib = xf::dsp::aie;
Additionally, each FIR filter has been placed in its unique FIR type namespace. The available FIR filter classes and the corresponding graph entry point are listed below:
.. _tab-fir-filter-classes:
.. table:: Table 1 : FIR Filter Classes
:align: center
+----------------------------------+-----------------------------------------------------------+
| **Function** | **Namespace and class name** |
+==================================+===========================================================+
| Single rate, asymmetrical | dsplib::fir::sr_asym::fir_sr_asym_graph |
+----------------------------------+-----------------------------------------------------------+
| Single rate, symmetrical | dsplib::fir::sr_sym::fir_sr_sym_graph |
+----------------------------------+-----------------------------------------------------------+
| Interpolation asymmetrical | dsplib::fir::interpolate_asym::fir_interpolate_asym_graph |
+----------------------------------+-----------------------------------------------------------+
| Decimation, halfband | dsplib::fir::decimate_hb::fir_decimate_hb_graph |
+----------------------------------+-----------------------------------------------------------+
| Interpolation, halfband | dsplib::fir::interpolate_hb::fir_interpolate_hb_graph |
+----------------------------------+-----------------------------------------------------------+
| Decimation, asymmetric | dsplib::fir::decimate_asym::fir_decimate_asym_graph |
+----------------------------------+-----------------------------------------------------------+
| Interpolation, fractional, | dsplib::fir::interpolate_fract_asym:: |
| asymmetric | fir_interpolate_fract_asym_graph |
| Note: superseded by resampler | |
+----------------------------------+-----------------------------------------------------------+
| Interpolation or decimation, | dsplib::fir::resampler::fir_resampler_graph |
| fractional, asymmetric | |
+----------------------------------+-----------------------------------------------------------+
| Decimation, symmetric | dsplib::fir::decimate_sym::fir_decimate_sym_graph |
+----------------------------------+-----------------------------------------------------------+
~~~~~~~~~~~~~~~
Supported Types
~~~~~~~~~~~~~~~
All FIR filters can be configured for various types of data and coefficients. These types can be int16, int32, or float, and also real or complex.
However, configurations with real data versus complex coefficients are not supported nor are configurations where the coefficents are a higher precision type than the data type. Data and coefficients must both be integer types or both be float types, as mixes are not supported.
The following table lists the supported combinations of data type and coefficient type.
.. _tab_supported_combos:
.. table:: Table 2 : Supported Combinations of Data Type and Coefficient Type
:align: center
+-------------------------------+--------------------------------------------------------------------------+
| | **Data Type** |
| +-----------+------------+-----------+------------+-----------+------------+
| | **Int16** | **Cint16** | **Int32** | **Cint32** | **Float** | **Cfloat** |
+----------------------+--------+-----------+------------+-----------+------------+-----------+------------+
| **Coefficient type** | Int16 | Supported | Supported | Supported | Supported | 3 | 3 |
| +--------+-----------+------------+-----------+------------+-----------+------------+
| | Cint16 | 1 | Supported | 1 | Supported | 3 | 3 |
| +--------+-----------+------------+-----------+------------+-----------+------------+
| | Int32 | 2 | 2 | Supported | Supported | 3 | 3 |
| +--------+-----------+------------+-----------+------------+-----------+------------+
| | Cint32 | 1, 2 | 2 | 1 | Supported | 3 | 3 |
| +--------+-----------+------------+-----------+------------+-----------+------------+
| | Float | 3 | 3 | 3 | 3 | Supported | Supported |
| +--------+-----------+------------+-----------+------------+-----------+------------+
| | Cfloat | 3 | 3 | 3 | 3 | 3 | Supported |
+----------------------+--------+-----------+------------+-----------+------------+-----------+------------+
| 1. Complex coefficients are not supported for real-only data types. |
| 2. Coefficient type of higher precision than data type is not supported. |
| 3. A mix of float and integer types is not supported. |
| 4. The fir_interpolate_asym variant does not support int16/int16. |
+----------------------------------------------------------------------------------------------------------+
~~~~~~~~~~~~~~~~~~~
Template Parameters
~~~~~~~~~~~~~~~~~~~
The following table lists parameters common to all the FIR filters:
.. _fir_supported_params:
.. table:: Table 3 : Parameters Supported by FIR Filters
:align: center
+------------------------+----------------+-----------------+---------------------------------+
| Parameter Name | Type | Description | Range |
+========================+================+=================+=================================+
| TP_FIR_LEN | Unsigned | The number of | Min - 4, |
| | int | taps | |
| | | | Max - see :ref:`MAX_FIR_LENGTH` |
+------------------------+----------------+-----------------+---------------------------------+
| TP_RND | Unsigned | Round mode | 0 = |
| | int | | truncate or |
| | | | floor |
| | | | |
| | | | 1 = |
| | | | ceiling |
| | | | |
| | | | 2 = |
| | | | positive |
| | | | infinity |
| | | | |
| | | | 3 = |
| | | | negative |
| | | | infinity |
| | | | |
| | | | 4 = |
| | | | symmetrical |
| | | | to infinity |
| | | | |
| | | | 5 = |
| | | | symmetrical |
| | | | to zero |
| | | | |
| | | | 6 = |
| | | | convergent |
| | | | to even |
| | | | |
| | | | 7 = |
| | | | convergent |
| | | | to odd |
+------------------------+----------------+-----------------+---------------------------------+
| TP_SHIFT | Unsigned | The number of | 0 to 61 |
| | int | bits to shift | |
| | | unscaled | |
| | | result | |
| | | down by before | |
| | | output. | |
+------------------------+----------------+-----------------+---------------------------------+
| TT_DATA | Typename | Data Type | int16, |
| | | | cint16, |
| | | | int32, |
| | | | cint32, |
| | | | float, |
| | | | cfloat |
+------------------------+----------------+-----------------+---------------------------------+
| TT_COEFF | Typename | Coefficient | int16, |
| | | type | cint16, |
| | | | int32, |
| | | | cint32, |
| | | | float, |
| | | | cfloat |
+------------------------+----------------+-----------------+---------------------------------+
| TP_INPUT_WINDOW_VSIZE | Unsigned | The number | Must be a |
| | int | of samples | multiple of |
| | | in the | the number |
| | | input | of lanes |
| | | window. For | used |
| | | streams, it | (typically |
| | | impacts the | 4 or 8). |
| | | number of input | |
| | | samples operated| No |
| | | on in a single | enforced |
| | | iteration | range, but |
| | | of the kernel. | large |
| | | | windows |
| | | | will result |
| | | | in mapper |
| | | | errors due |
| | | | to |
| | | | excessive |
| | | | RAM use, for windowed |
| | | | API implementations. |
| | | | |
+------------------------+----------------+-----------------+---------------------------------+
| TP_CASC_LEN | Unsigned | The number | 1 to 9. |
| | int | of cascaded | |
| | | kernels to | Defaults to |
| | | use for | 1 if not |
| | | this FIR. | set. |
| | | | |
+------------------------+----------------+-----------------+---------------------------------+
| TP_DUAL_IP | Unsigned | Use dual | Range 0 |
| | int | inputs ports. | (single |
| | | | input), 1 |
| | | An additional | (dual |
| | | 'in2' input | input). |
| | | port will | |
| | | appear on | Defaults to |
| | | the graph | 0 if not |
| | | when set to 1. | set. |
| | | | |
| | | | |
+------------------------+----------------+-----------------+---------------------------------+
| TP_USE_COEFF_RELOAD | Unsigned | Enable | 0 (no |
| | int | reloadable | reload), 1 |
| | | coefficient | (use |
| | | feature. | reloads). |
| | | | |
| | | An additional | Defaults to |
| | | 'coeff' RTP | 0 if not |
| | | port will | set. |
| | | appear on | |
| | | the graph. | |
+------------------------+----------------+-----------------+---------------------------------+
| TP_NUM_OUTPUTS | Unsigned | Number of | |
| | int | fir output | 1 to 2 |
| | | ports | |
| | | | |
| | | An additional | Defaults to |
| | | 'out2' output | 1 if not |
| | | port will | set. |
| | | appear on | |
| | | the graph | |
| | | when set to 2. | |
+------------------------+----------------+-----------------+---------------------------------+
| TP_API | Unsigned | I/O interface | 0 = Window |
| | int | port type | |
| | | | 1 = Stream |
+------------------------+----------------+-----------------+---------------------------------+
| TP_SSR | Unsigned | Parallelism | min=1 |
| | int | factor | |
| | | | Defaults to |
| | | | 1 if not |
| | | | set. |
| | | | |
| | | | Max = limited by resource |
| | | | availability |
+------------------------+----------------+-----------------+---------------------------------+
.. _lanes-note:
.. note:: The number of lanes is the number of data elements that are being processed in parallel. This varies depending on the data type (i.e., number of bits in each element) and the register or bus width.
For a list of template parameters for each FIR variant, see :ref:`API_REFERENCE`.
**TP_CASC_LEN** describes the number of AIE processors to split the operation over, which allows resource to be traded for higher performance. TP_CASC_LEN must be in the range 1 (default) to 9.
FIR graph instance consists of TP_CASC_LEN kernels and the FIR length (TP_FIR_LEN) is divided by the requested cascade length and each kernel in the graph gets assigned a fraction of the workload.
Kernels are connected with cascade ports, which pass partial accumulation products downstream until last kernel in chain produces the output.
**TP_DUAL_IP** is an implementation trade-off between performance and resource utilization.
Symmetric FIRs may be instanced with 2 input ports to alleviate the potential for memory read contention, which would otherwise result in stall cycles and therefore lower throughput.
In addition, FIRs with streaming interface may utilize the second input port to maximize the available throughput.
* When set to 0, the FIR is created with a single input port.
* When set to 1, two input ports will be created.
.. note:: when used, port ``` port in2;``` will be added to the FIR.
**TP_USE_COEFF_RELOAD** allows the user to select if runtime coefficient reloading should be used.
When defining the parameter:
* 0 = static coefficients, defined in filter constructor
* 1 = reloadable coefficients, passed as argument to runtime function.
.. note:: when used, port ``` port coeff;``` will be added to the FIR.
**TP_NUM_OUTPUTS** sets the number of output ports to send the output data to. Supported range: 1 to 2.
For Windows API, additional output provides flexibility in connecting FIR output with multiple destinations.
Additional output ``out2`` is an exact copy of the data of the output port ``out``.
Stream API uses the additional output port to increase the FIR's throughput. Please refer to :ref:`FIR_STREAM_OUTPUT` for more details.
.. note:: when used, port ``` port