GDFLIB User's Guide
ARM® Cortex® M7
Document Number: CM7GDFLIBUG
Rev. 0, 10/2015
GDFLIB User's Guide, Rev. 0, 10/2015
2
Freescale Semiconductor, Inc.
Contents
Section number
Title
Page
Chapter 1
Library
1.1
Introduction.................................................................................................................................................................... 5
1.2
Library integration into project (Keil µVision) ............................................................................................................. 7
1.3
Library integration into project (IAR Embedded Workbench) ..................................................................................... 14
Chapter 2
Algorithms in detail
2.1
GDFLIB_FilterIIR1........................................................................................................................................................21
2.2
GDFLIB_FilterIIR2........................................................................................................................................................26
2.3
GDFLIB_FilterIIR3........................................................................................................................................................31
2.4
GDFLIB_FilterIIR4........................................................................................................................................................36
2.5
GDFLIB_FilterMA.........................................................................................................................................................41
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
3
GDFLIB User's Guide, Rev. 0, 10/2015
4
Freescale Semiconductor, Inc.
Chapter 1
Library
1.1 Introduction
1.1.1 Overview
This user's guide describes the General Digital Filters Library (GDFLIB) for the family
of ARM Cortex M7 core-based microcontrollers. This library contains optimized
functions.
1.1.2 Data types
GDFLIB supports several data types: (un)signed integer, fractional, and accumulator. The
integer data types are useful for general-purpose computation; they are familiar to the
MPU and MCU programmers. The fractional data types enable powerful numeric and
digital-signal-processing algorithms to be implemented. The accumulator data type is a
combination of both; that means it has the integer and fractional portions.
The following list shows the integer types defined in the libraries:
•
•
•
•
Unsigned 16-bit integer —<0 ; 65535> with the minimum resolution of 1
Signed 16-bit integer —<-32768 ; 32767> with the minimum resolution of 1
Unsigned 32-bit integer —<0 ; 4294967295> with the minimum resolution of 1
Signed 32-bit integer —<-2147483648 ; 2147483647> with the minimum resolution
of 1
The following list shows the fractional types defined in the libraries:
• Fixed-point 16-bit fractional —<-1 ; 1 - 2-15> with the minimum resolution of 2-15
• Fixed-point 32-bit fractional —<-1 ; 1 - 2-31> with the minimum resolution of 2-31
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
5
Introduction
The following list shows the accumulator types defined in the libraries:
• Fixed-point 16-bit accumulator —<-256.0 ; 256.0 - 2-7> with the minimum
resolution of 2-7
• Fixed-point 32-bit accumulator —<-65536.0 ; 65536.0 - 2-15> with the minimum
resolution of 2-15
1.1.3 API definition
GDFLIB uses the types mentioned in the previous section. To enable simple usage of the
algorithms, their names use set prefixes and postfixes to distinguish the functions'
versions. See the following example:
f32Result = MLIB_Mac_F32lss(f32Accum, f16Mult1, f16Mult2);
where the function is compiled from four parts:
•
•
•
•
MLIB—this is the library prefix
Mac—the function name—Multiply-Accumulate
F32—the function output type
lss—the types of the function inputs; if all the inputs have the same type as the
output, the inputs are not marked
The input and output types are described in the following table:
Table 1-1. Input/output types
Type
Output
Input
frac16_t
F16
s
frac32_t
F32
l
acc32_t
A32
a
1.1.4 Supported compilers
GDFLIB for the ARM Cortex M7 core is written in . The library is built and tested using
the following compilers:
• IAR Embedded Workbench
• Keil µVision
For the IAR Embedded Workbench, the library is delivered in the gdflib.a file.
For the Keil µVision, the library is delivered in the gdflib.lib file.
GDFLIB User's Guide, Rev. 0, 10/2015
6
Freescale Semiconductor, Inc.
Chapter 1 Library
The interfaces to the algorithms included in this library are combined into a single public
interface include file, gdflib.h. This is done to lower the number of files required to be
included in your application.
1.1.5 Special issues
1. The equations describing the algorithms are symbolic. If there is positive 1, the
number is the closest number to 1 that the resolution of the used fractional type
allows. If there are maximum or minimum values mentioned, check the range
allowed by the type of the particular function version.
2. The library functions that round the result (the API contains Rnd) round to nearest
(half up).
1.2 Library integration into project (Keil µVision)
This section provides a step-by-step guide on how to quickly and easily include GDFLIB
into an empty project using Keil µVision. This example uses the Freescale
MKV58F1M0xxx22 part, and the default installation path (C:\Freescale\FSLESL
\CM7_FSLESL_4.2_KEIL) is supposed. If you have a different installation path, use that
path instead.
1.2.1 Freescale pack installation
If the compiler has never been used to create any Freescale MCU-based projects before,
check whether the Freescale MCU pack for the particular device is installed. Follow these
steps:
1. Launch Keil µVision.
2. In the main menu, go to Project > Manage > Pack Installer….
3. In the left-hand dialog (under the Devices tab), expand the All Devices > Freescale
node.
4. Look for a line called "KVxx Series" and click it.
5. In the right-hand dialog (under the Packs tab), expand the Device Specific node.
6. Look for a node called "Keil::Kinetis_KVxx_DFP." If there are the Install or Update
options, click the button to install/update the package. See Figure 1-1.
7. When installed, the button has the "Up to date" title. Now close the Pack Installer.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
7
Library integration into project (Keil µVision)
Figure 1-1. Pack Installer
1.2.2 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Follow these steps to create a new project:
1. Launch Keil µVision.
2. In the main menu, select Project > New µVision Project…, and the Create New
Project dialog appears.
3. Navigate to the folder where you want to create the project, for example C:
\KeilProjects\MyProject01. Type the name of the project, for example MyProject01.
Click Save. See Figure 1-2.
4.
5.
6.
7.
Figure 1-2. Create New Project dialog
In the next dialog, select the Software Packs in the very first box.
Type '' into the Search box, so that the device list is reduced to the devices.
Expand the node.
Click the MKV58F1M0xxx22 node, and then click OK. See Figure 1-3.
GDFLIB User's Guide, Rev. 0, 10/2015
8
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-3. Select Device dialog
8. In the next dialog, expand the Device node, and tick the box next to the Startup node.
See Figure 1-4.
9. Expand the CMSIS node, and tick the box next to the CORE node.
Figure 1-4. Manage Run-Time Environment dialog
10. Click OK, and a new project is created. The new project is now visible in the lefthand part of Keil µVision. See Figure 1-5.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
9
Library integration into project (Keil µVision)
Figure 1-5. Project
11. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog
appears.
12. Select the Target tab.
13. Select Not Used in the Floating Point Hardware option. See Figure 1-5.
Figure 1-6. FPU
1.2.3 Linking the files into the project
GDFLIB requires MLIB to be included too. The following steps show how to include all
dependent modules.
To include the library files in the project, create groups and add them.
1. Right-click the Target 1 node in the left-hand part of the Project tree, and select Add
Group… from the menu. A new group with the name New Group is added.
2. Click the newly created group, and press F2 to rename it to FSLESL.
3. Right-click the FSLESL node, and select Add Existing Files to Group 'FSLESL'…
from the menu.
4. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7_FSLESL_4.2_KEIL\MLIB\Include, and select the mlib.h file. If the file does
not appear, set the Files of type filter to Text file. Click Add. See Figure 1-7.
GDFLIB User's Guide, Rev. 0, 10/2015
10
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-7. Adding .h files dialog
5. Navigate to the parent folder C:\Freescale\FSLESL\CM7_FSLESL_4.2_KEIL
\MLIB, and select the mlib.lib file. If the file does not appear, set the Files of type
filter to Library file. Click Add. See Figure 1-8.
Figure 1-8. Adding .lib files dialog
6. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7_FSLESL_4.2_KEIL\GFLIB\Include, and select the gflib.h file. If the file does
not appear, set the Files of type filter to Text file. Click Add.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
11
Library integration into project (Keil µVision)
7. Navigate to the parent folder C:\Freescale\FSLESL\CM7_FSLESL_4.2_KEIL
\GDFLIB, and select the gdflib.lib file. If the file does not appear, set the Files of
type filter to Library file. Click Add.
8. Now, all necessary files are in the project tree; see Figure 1-9. Click Close.
Figure 1-9. Project workspace
1.2.4 Library path setup
The following steps show the inclusion of all dependent modules.
1. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog
appears.
2. Select the C/C++ tab. See Figure 1-10.
3. In the Include Paths text box, type the following paths (if there are more paths, they
must be separated by ';') or add them by clicking the … button next to the text box:
• "C:\Freescale\FSLESL\CM7_FSLESL_4.2_KEIL\MLIB\Include"
• "C:\Freescale\FSLESL\CM7_FSLESL_4.2_KEIL\GDFLIB\Include"
4. Click OK.
5. Click OK in the main dialog.
GDFLIB User's Guide, Rev. 0, 10/2015
12
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-10. Library path addition
Type the #include syntax into the code. Include the library into a source file. In the new
project, it is necessary to create a source file:
1. Right-click the Source Group 1 node, and Add New Item to Group 'Source Group
1'… from the menu.
2. Select the C File (.c) option, and type a name of the file into the Name box, for
example 'main.c'. See Figure 1-11.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
13
Library integration into project (IAR Embedded Workbench)
Figure 1-11. Adding new source file dialog
3. Click Add, and a new source file is created and opened up.
4. In the opened source file, include the following lines into the #include section, and
create a main function:
#include "mlib.h"
#include "gdflib.h"
int main(void)
{
while(1);
}
When you click the Build (F7) icon, the project will be compiled without errors.
1.3 Library integration into project (IAR Embedded
Workbench)
This section provides a step-by-step guide on how to quickly and easily include the
GDFLIB into an empty project using IAR Embedded Workbench. This example uses the
Freescale MKV58F1M0xxx22 part, and the default installation path (C:\Freescale
\FSLESL\CM7_FSLESL_4.2_IAR) is supposed. If you have a different installation path,
then use that path instead.
GDFLIB User's Guide, Rev. 0, 10/2015
14
Freescale Semiconductor, Inc.
Chapter 1 Library
1.3.1 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Perform these steps to create a new project:
1. Launch IAR Embedded Workbench.
2. In the main menu, select Project > Create New Project… so that the "Create New
Project" dialog appears. See Figure 1-12.
Figure 1-12. Create New Project dialog
3. Expand the C node in the tree, and select the "main" node. Click OK.
4. Navigate to the folder where you want to create the project, for example, C:
\IARProjects\MyProject01. Type the name of the project, for example, MyProject01.
Click Save, and a new project is created. The new project is now visible in the lefthand part of IAR Embedded Workbench. See Figure 1-13.
Figure 1-13. New project
5. In the main menu, go to Project > Options…, and a dialog appears.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
15
Library integration into project (IAR Embedded Workbench)
6. In the Target tab, select the Device option, and click the button next to the dialog to
select the MCU. In this example, select Freescale > KV5x > Freescale
MKV58F1M0xxx22. Select None in the FPU option. Click OK. See Figure 1-14.
Figure 1-14. Options dialog
1.3.2 Library path variable
To make the library integration easier, create a variable that will hold the information
about the library path.
1. In the main menu, go to Tools > Configure Custom Argument Variables…, and a
dialog appears.
2. Click the New Group button, and another dialog appears. In this dialog, type the
name of the group PATH, and click OK. See Figure 1-15.
GDFLIB User's Guide, Rev. 0, 10/2015
16
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-15. New Group
3. Click on the newly created group, and click the Add Variable button. A dialog
appears.
4. Type this name: FSLESL_LOC
5. To set up the value, look for the library by clicking the '…' button, or just type the
installation path into the box: C:\Freescale\FSLESL\CM7_FSLESL_4.2_IAR. Click
OK.
6. In the main dialog, click OK. See Figure 1-16.
Figure 1-16. New variable
1.3.3 Linking the files into the project
GDFLIB requires MLIB to be included too. The following steps show the inclusion of all
dependent modules.
To include the library files into the project, create groups and add them.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
17
Library integration into project (IAR Embedded Workbench)
1. Go to the main menu Project > Add Group…
2. Type FSLESL, and click OK.
3. Click on the newly created node FSLESL, go to Project > Add Group…, and create a
MLIB subgroup.
4. Click on the newly created node MLIB, and go to the main menu Project > Add
Files… See Figure 1-18.
5. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7_FSLESL_4.2_IAR\MLIB\Include, and select the mlib.h file. (If the file does
not appear, set the file-type filter to Source Files.) Click Open. See Figure 1-17.
6. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7_FSLESL_4.2_IAR\MLIB, and select the mlib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
Figure 1-17. Add Files dialog
7. Click on the FSLESL node, go to Project > Add Group…, and create a GDFLIB
subgroup.
8. Click on the newly created node GDFLIB, and go to the main menu Project > Add
Files….
9. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7_FSLESL_4.2_IAR\GDFLIB\Include, and select the gdflib.h file. (If the file
does not appear, set the file-type filter to Source Files.) Click Open.
10. Navigate into the library installation folder C:\Freescale\FSLESL
\CM7_FSLESL_4.2_IAR\GDFLIB, and select the gdflib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
11. Now you will see the files added in the workspace. See Figure 1-18.
GDFLIB User's Guide, Rev. 0, 10/2015
18
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-18. Project workspace
1.3.4 Library path setup
The following steps show the inclusion of all dependent modules:
1. In the main menu, go to Project > Options…, and a dialog appears.
2. In the left-hand column, select C/C++ Compiler.
3. In the right-hand part of the dialog, click on the Preprocessor tab (it can be hidden in
the right; use the arrow icons for navigation).
4. In the text box (at the Additional include directories title), type the following folder
(using the created variable):
• $FSLESL_LOC$\MLIB\Include
• $FSLESL_LOC$\GDFLIB\Include
5. Click OK in the main dialog. See Figure 1-19.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
19
Library integration into project (IAR Embedded Workbench)
Figure 1-19. Library path adition
Type the #include syntax into the code. Include the library included into the main.c file.
In the workspace tree, double-click the main.c file. After the main.c file opens up, include
the following lines into the #include section:
#include "mlib.h"
#include "gdflib.h"
When you click the Make icon, the project will be compiled without errors.
GDFLIB User's Guide, Rev. 0, 10/2015
20
Freescale Semiconductor, Inc.
Chapter 2
Algorithms in detail
2.1 GDFLIB_FilterIIR1
This function calculates the first-order direct form 1 IIR filter.
For a proper use, it is recommended that the algorithm is initialized by the
GDFLIB_FilterIIR1Init function, before using the GDFLIB_FilterIIR1 function. The
GDFLIB_FilterIIR1Init function initializes the buffer and coefficients of the first-order
IIR filter.
The GDFLIB_FilterIIR1 function calculates the first-order infinite impulse response
(IIR) filter. The IIR filters are also called recursive filters, because both the input and the
previously calculated output values are used for calculation. This form of feedback
enables the transfer of energy from the output to the input, which leads to an infinitely
long impulse response (IIR). A general form of the IIR filter, expressed as a transfer
function in the Z-domain, is described as follows:
Equation 1.
where N denotes the filter order. The first-order IIR filter in the Z-domain is expressed as
follows:
Equation 2.
which is transformed into a time-domain difference equation as follows:
Equation 3.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
21
GDFLIB_FilterIIR1
The filter difference equation is implemented in the digital signal controller directly, as
given in Equation 3 on page 21; this equation represents a direct-form 1 first-order IIR
filter, as shown in Figure 2-1.
Figure 2-1. Direct form 1 first-order IIR filter
The coefficients of the filter shown in Figure 2-1 can be designed to meet the
requirements for the first-order low-pass filter (LPF) or high-pass filter (HPF). The
coefficient quantization error is not important in the case of a first-order filter due to a
finite precision arithmetic. A higher-order LPF or HPF can be obtained by connecting a
number of first-order filters in series. The number of connections gives the order of the
resulting filter.
The filter coefficients must be defined before calling this function. As some coefficients
can be greater than 1 (and lesser than 2), the coefficients are scaled down (divided) by 2.0
for the fractional version of the algorithm. For faster calculation, the A coefficient is signinverted. The function returns the filtered value of the input in the step k, and stores the
input and the output values in the step k into the filter buffer.
2.1.1 Available versions
This function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1).
The available versions of the GDFLIB_FilterIIR1Init function are shown in the following
table:
Table 2-1. Init function versions
Function name
GDFLIB_FilterIIR1Init_F16
Parameters
GDFLIB_FILTER_IIR1_T_F32 *
Result
type
void
Description
Filter initialization (reset) function. The
parameters' structure is pointed to by a
pointer.
GDFLIB User's Guide, Rev. 0, 10/2015
22
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the GDFLIB_FilterIIR1 function are shown in the following
table:
Table 2-2. Function versions
Function name
Input
type
GDFLIB_FilterIIR1_F16
frac16_t
Parameters
Result
type
GDFLIB_FILTER_IIR1_T_F32 *
frac16_t
Description
The input argument is a 16-bit
fractional value of the input signal to
be filtered within the range <-1 ; 1).
The parameters' structure is pointed
to by a pointer. The function returns
a 16-bit fractional value within the
range <-1 ; 1).
2.1.2 GDFLIB_FILTER_IIR1_T_F32
Variable name
Input type
Description
sFltCoeff
GDFLIB_FILTER_IIR1_COEFF_T_F32 *
Substructure containing filter coefficients.
f32FltBfrY[1]
frac32_t
Internal buffer of y-history. Controlled by the
algorithm.
f16FltBfrX[1]
frac16_t
Internal buffer of x-history. Controlled by the
algorithm.
2.1.3 GDFLIB_FILTER_IIR1_COEFF_T_F32
Variable name
Type
Description
f32B0
frac32_t
B0 coefficient of the IIR1 filter. Set by the user, and must be divided by 2.
f32B1
frac32_t
B1 coefficient of the IIR1 filter. Set by the user, and must be divided by 2.
f32A1
frac32_t
A1 (sign-inverted) coefficient of the IIR1 filter. Set by the user, and must be divided by -2.
2.1.4 Declaration
The available GDFLIB_FilterIIR1Init functions have the following declarations:
void GDFLIB_FilterIIR1Init_F16(GDFLIB_FILTER_IIR1_T_F32 *psParam)
The available GDFLIB_FilterIIR1 functions have the following declarations:
frac16_t GDFLIB_FilterIIR1_F16(frac16_t f16InX, GDFLIB_FILTER_IIR1_T_F32 *psParam)
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
23
GDFLIB_FilterIIR1
2.1.5 Calculation of filter coefficients
There are plenty of methods for calculating the coefficients. The following example
shows the use of Matlab to set up a low-pass filter with the 500 Hz sampling frequency,
and 240 Hz stopped frequency with a 20 dB attenutation. Maximum passband ripple is 3
dB at the cut-off frequency of 50 Hz.
% sampling frequency 500 Hz, low pass
Ts = 1 / 500
% cut-off frequency 50 Hz
Fc = 50
% max. passband ripple 3 dB
Rp = 3
% stopped frequency 240Hz
Fs = 240
% attenuation 20 dB
Rs = 20
% checking order of the filter
n = buttord(2 * Ts * Fc, 2 * Ts * Fs, Rp, Rs)
% n = 1, i.e. the filter is achievable with the 1st order
% getting the filter coefficients
[b, a] = butter(n, 2 * Ts * Fc, 'low');
% the coefs are:
% b0 = 0.245237275252786, b1 = 0.245237275252786
% a0 = 1.0000, a1 = -0.509525449494429
The filter response is shown in Figure 2-2.
GDFLIB User's Guide, Rev. 0, 10/2015
24
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Figure 2-2. Filter response
2.1.6 Function use
The use of the GDFLIB_FilterIIR1Init and GDFLIB_FilterIIR1 functions is shown in the
following example. The filter uses the above-calculated coefficients:
#include "gdflib.h"
static frac16_t f16Result;
static frac16_t f16InX;
static GDFLIB_FILTER_IIR1_T_F32 sFilterParam;
void Isr(void);
void main(void)
{
sFilterParam.sFltCoeff.f32B0 = FRAC32(0.245237275252786 / 2.0);
sFilterParam.sFltCoeff.f32B1 = FRAC32(0.245237275252786 / 2.0);
sFilterParam.sFltCoeff.f32A1 = FRAC32(-0.509525449494429 / -2.0);
GDFLIB_FilterIIR1Init_F16(&sFilterParam);
}
f16InX = FRAC16(0.1);
/* periodically called function */
void Isr(void)
{
f16Result = GDFLIB_FilterIIR1_F16(f16InX, &sFilterParam);
}
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
25
GDFLIB_FilterIIR2
2.2 GDFLIB_FilterIIR2
This function calculates the second-order direct-form 1 IIR filter.
For a proper use, it is recommended that the algorithm is initialized by the
GDFLIB_FilterIIR2Init function, before using the GDFLIB_FilterIIR2 function. The
GDFLIB_FilterIIR2Init function initializes the buffer and coefficients of the secondorder IIR filter.
The GDFLIB_FilterIIR2 function calculates the second-order infinite impulse response
(IIR) filter. The IIR filters are also called recursive filters, because both the input and the
previously calculated output values are used for calculation. This form of feedback
enables the transfer of energy from the output to the input, which leads to an infinitely
long impulse response (IIR). A general form of the IIR filter, expressed as a transfer
function in the Z-domain, is described as follows:
Equation 4.
where N denotes the filter order. The second-order IIR filter in the Z-domain is expressed
as follows:
Equation 5.
which is transformed into a time-domain difference equation as follows:
Equation 6.
The filter difference equation is implemented in the digital signal controller directly, as
given in Equation 6 on page 26; this equation represents a direct-form 1 second-order IIR
filter, as depicted in Figure 2-3.
GDFLIB User's Guide, Rev. 0, 10/2015
26
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Figure 2-3. Direct-form 1 second-order IIR filter
The coefficients of the filter depicted in Figure 2-3 can be designed to meet the
requirements for the second-order low-pass filter (LPF), high-pass filter (HPF), band-pass
filter (BPF) or band-stop filter (BSF). The coefficient quantization error can be neglected
in the case of a second-order filter due to a finite precision arithmetic. A higher-order
LPF or HPF can be obtained by connecting a number of second-order filters in series.
The number of connections gives the order of the resulting filter.
The filter coefficients must be defined before calling this function. As some coefficients
can be greater than 1 (and lesser than 2), the coefficients are scaled down (divided) by 2.0
for the fractional version of the algorithm. For faster calculation, the A coefficients are
sign-inverted. The function returns the filtered value of the input in the step k, and stores
the input and output values in the step k into the filter buffer.
2.2.1 Available versions
This function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1).
The available versions of the GDFLIB_FilterIIR2Init function are shown in the following
table:
Table 2-3. Init function versions
Function name
GDFLIB_FilterIIR2Init_F16
Parameters
GDFLIB_FILTER_IIR2_T_F32 *
Result
type
void
Description
Filter initialization (reset) function. The
parameters' structure is pointed to by a
pointer.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
27
GDFLIB_FilterIIR2
The available versions of the GDFLIB_FilterIIR2 function are shown in the following
table:
Table 2-4. Function versions
Function name
Input
type
GDFLIB_FilterIIR2_F16
frac16_t
Parameters
Result
type
GDFLIB_FILTER_IIR2_T_F32 *
frac16_t
Description
Input argument is a 16-bit fractional
value of the input signal to be filtered
within the range <-1 ; 1). The
parameters' structure is pointed to
by a pointer. The function returns a
16-bit fractional value within the
range <-1 ; 1).
2.2.2 GDFLIB_FILTER_IIR2_T_F32
Variable name
Input type
Description
sFltCoeff
GDFLIB_FILTER_IIR2_COEFF_T_F32 *
Substructure containing filter coefficients.
f32FltBfrY[2]
frac32_t
Internal buffer of y-history. Controlled by the
algorithm.
f16FltBfrX[2]
frac16_t
Internal buffer of x-history. Controlled by the
algorithm.
2.2.3 GDFLIB_FILTER_IIR2_COEFF_T_F32
Variable name
Type
Description
f32B0
frac32_t
B0 coefficient of the IIR2 filter. Set by the user, and must be divided by 2.
f32B1
frac32_t
B1 coefficient of the IIR2 filter. Set by the user, and must be divided by 2.
f32B2
frac32_t
B2 coefficient of the IIR2 filter. Set by the user, and must be divided by 2.
f32A1
frac32_t
A1 (sign-inverted) coefficient of the IIR2 filter. Set by the user, and must be divided by -2.
f32A2
frac32_t
A2 (sign-inverted) coefficient of the IIR2 filter. Set by the user, and must be divided by -2.
2.2.4 Declaration
The available GDFLIB_FilterIIR2Init functions have the following declarations:
void GDFLIB_FilterIIR2Init_F16(GDFLIB_FILTER_IIR2_T_F32 *psParam)
The available GDFLIB_FilterIIR2 functions have the following declarations:
GDFLIB User's Guide, Rev. 0, 10/2015
28
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
frac16_t GDFLIB_FilterIIR2_F16(frac16_t f16InX, GDFLIB_FILTER_IIR2_T_F32 *psParam)
2.2.5 Calculation of filter coefficients
There are plenty of methods for calculating the coefficients. The following example
shows the use of Matlab to set up a stopband filter with the 1000 Hz sampling frequency,
100 Hz stop frequency with 10 dB attenuation, and 30 Hz bandwidth. Maximum
passband ripple is 3 dB.
% sampling frequency 1000 Hz, stop band
Ts = 1 / 1000
% center stop frequency 100 Hz
Fc = 50
% attenuation 10 dB
Rs = 10
% bandwidth 30 Hz
Fbw = 30
% max. passband ripple 3 dB
Rp = 3
% checking order of the filter
n = buttord(2 * Ts * [Fc - Fbw /2 Fc + Fbw / 2], 2 * Ts * [Fc - Fbw Fc + Fbw], Rp, Rs)
% n = 2, i.e. the filter is achievable with the 2nd order
% getting the filter coefficients
[b, a] = butter(n / 2, 2 * Ts * [Fc - Fbw /2 Fc + Fbw / 2], 'stop')
% the coefs are:
% b0 = 0.913635972986238, b1 = -1.745585863109291, b2 = 0.913635972986238
% a0 = 1.0000, a1 = -1.745585863109291, a2 = 0.827271945972476
The filter response is shown in Figure 2-4.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
29
GDFLIB_FilterIIR2
Figure 2-4. Filter response
2.2.6 Function use
The use of the GDFLIB_FilterIIR2Init and GDFLIB_FilterIIR2 functions is shown in the
following example. The filter uses the above-calculated coefficients:
#include "gdflib.h"
static frac16_t f16Result;
static frac16_t f16InX;
static GDFLIB_FILTER_IIR2_T_F32 sFilterParam;
void Isr(void);
void main(void)
{
sFilterParam.sFltCoeff.f32B0
sFilterParam.sFltCoeff.f32B1
sFilterParam.sFltCoeff.f32B2
sFilterParam.sFltCoeff.f32A1
sFilterParam.sFltCoeff.f32A2
=
=
=
=
=
FRAC32(0.913635972986238 / 2.0);
FRAC32(-1.745585863109291 / 2.0);
FRAC32(0.913635972986238 / 2.0);
FRAC32(-1.745585863109291 / -2.0);
FRAC32(0.827271945972476 / -2.0);
GDFLIB_FilterIIR2Init_F16(&sFilterParam);
}
f16InX = FRAC16(0.1);
/* periodically called function */
void Isr(void)
{
f16Result = GDFLIB_FilterIIR2_F16(f16InX, &sFilterParam);
}
GDFLIB User's Guide, Rev. 0, 10/2015
30
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.3 GDFLIB_FilterIIR3
This function calculates the third-order direct-form 1 IIR filter.
For a proper use, it is recommended to initialize the algorithm by the
GDFLIB_FilterIIR3Init function before using the GDFLIB_FilterIIR3 function. The
GDFLIB_FilterIIR3Init function initializes the buffer and coefficients of the third-order
IIR filter.
The GDFLIB_FilterIIR3 function calculates the third-order infinite impulse response
(IIR) filter. The IIR filters are also called recursive filters because both the input and the
previously calculated output values are used for calculation. This form of feedback
enables the transfer of energy from the output to the input, which leads to an infinitely
long impulse response (IIR). A general form of the IIR filter (expressed as a transfer
function in the Z-domain) is described as follows:
Equation 7.
where N denotes the filter order. The third-order IIR filter in the Z-domain is expressed
as follows:
Equation 8.
which is transformed into a time-domain difference equation as follows:
Equation 9.
The filter difference equation is implemented in the digital signal controller directly, as
given in Equation 9 on page 31. This equation represents a direct-form 1 third-order IIR
filter, as depicted in Figure 2-5.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
31
GDFLIB_FilterIIR3
Figure 2-5. Direct-form 1 third-order IIR filter
The coefficients of the filter depicted in Figure 2-5 can be designed to meet the
requirements for the third-order low-pass filter (LPF) or high-pass filter (HPF). The
coefficient quantization error can be neglected in the case of a third-order filter due to a
finite precision arithmetic. A higher-order LPF or HPF can be obtained by connecting a
number of third-order filters in series. The number of connections gives the order of the
resulting filter.
Define the filter coefficients before calling this function. As some coefficients can be
greater than 1 (and lesser than 4), the coefficients are scaled down (divided) by 4.0 for the
fractional version of the algorithm. For a faster calculation, the A coefficients are signinverted. The function returns the filtered value of the input in the step k, and stores the
input and output values in the step k into the filter buffer.
2.3.1 Available versions
This function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1).
The available versions of the GDFLIB_FilterIIR3Init function are shown in the following
table:
Table 2-5. Init function versions
Function name
GDFLIB_FilterIIR3Init_F16
Parameters
GDFLIB_FILTER_IIR3_T_F32 *
Result
type
void
Description
Filter initialization (reset) function. The
parameters' structure is pointed to by a
pointer.
GDFLIB User's Guide, Rev. 0, 10/2015
32
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the GDFLIB_FilterIIR3 function are shown in the following
table:
Table 2-6. Function versions
Function name
Input
type
GDFLIB_FilterIIR3_F16
frac16_t
Parameters
Result
type
GDFLIB_FILTER_IIR3_T_F32 *
frac16_t
Description
Input argument is a 16-bit fractional
value of the input signal to be filtered
within the range <-1 ; 1). The
parameters' structure is pointed to
by a pointer. The function returns a
16-bit fractional value within the
range <-1 ; 1).
2.3.2 GDFLIB_FILTER_IIR3_T_F32
Variable name
Input type
Description
sFltCoeff
GDFLIB_FILTER_IIR3_COEFF_T_F32 *
Substructure containing filter coefficients.
f32FltBfrY[3]
frac32_t
Internal buffer of y-history. Controlled by the
algorithm.
f16FltBfrX[3]
frac16_t
Internal buffer of x-history. Controlled by the
algorithm.
2.3.3 GDFLIB_FILTER_IIR3_COEFF_T_F32
Variable name
Type
Description
f32B0
frac32_t
B0 coefficient of the IIR3 filter. Set by the user, and must be divided by 4.
f32B1
frac32_t
B1 coefficient of the IIR3 filter. Set by the user, and must be divided by 4.
f32B2
frac32_t
B2 coefficient of the IIR3 filter. Set by the user, and must be divided by 4.
f32B3
frac32_t
B3 coefficient of the IIR3 filter. Set by the user, and must be divided by 4.
f32A1
frac32_t
A1 (sign-inverted) coefficient of the IIR3 filter. Set by the user. Must be divided by -4.
f32A2
frac32_t
A2 (sign-inverted) coefficient of the IIR3 filter. Set by the user. Must be divided by -4.
f32A3
frac32_t
A3 (sign-inverted) coefficient of the IIR3 filter. Set by the user. Must be divided by -4.
2.3.4 Declaration
The available GDFLIB_FilterIIR3Init functions have the following declarations:
void GDFLIB_FilterIIR3Init_F16(GDFLIB_FILTER_IIR3_T_F32 *psParam)
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
33
GDFLIB_FilterIIR3
The available GDFLIB_FilterIIR3 functions have the following declarations:
frac16_t GDFLIB_FilterIIR3_F16(frac16_t f16InX, GDFLIB_FILTER_IIR3_T_F32 *psParam)
2.3.5 Calculation of filter coefficients
There are plenty of methods for calculating the coefficients. The following example
shows the use of Matlab to set up a high-pass filter with the 10000 Hz sampling
frequency and 200 Hz stop frequency with 60 dB attenuation. The ripple is 3 dB at the
cut-off frequency of 2000 Hz.
% sampling frequency 10000 Hz, high pass
Ts = 1 / 10000
% cut-off frequency 2 KHz
Fc = 2000
% attenuation 60 dB
Rs = 60
% stop frequency 200 Hz
Fs = 200
% max. passband ripple 3 dB
Rp = 3
% checking order of the filter
n = buttord(2 * Ts * Fc, 2 * Ts * Fs, Rp, Rs)
% n = 3, i.e. the filter is achievable with the 3rd order
% getting the filter coefficients
[b, a] = butter(n, 2* Ts * Fc, 'high')
%
%
%
%
the coefs are:
b0 = 0.256915601248463, b1 = -0.770746803745390, b2 = 0.770746803745390,
b3 = -0.256915601248463
a0 = 1.0000, a1 = -0.577240524806303, a2 = 0.421787048689562, a3 = -0.056297236491843
The filter response is shown in Figure 2-6.
GDFLIB User's Guide, Rev. 0, 10/2015
34
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Figure 2-6. Filter response
2.3.6 Function use
The use of the GDFLIB_FilterIIR3Init and GDFLIB_FilterIIR3 functions is shown in the
following example. The filter uses the above-calculated coefficients:
#include "gdflib.h"
static frac16_t f16Result;
static frac16_t f16InX;
static GDFLIB_FILTER_IIR3_T_F32 sFilterParam;
void Isr(void);
void main(void)
{
sFilterParam.sFltCoeff.f32B0
sFilterParam.sFltCoeff.f32B1
sFilterParam.sFltCoeff.f32B2
sFilterParam.sFltCoeff.f32B3
sFilterParam.sFltCoeff.f32A1
sFilterParam.sFltCoeff.f32A2
sFilterParam.sFltCoeff.f32A3
=
=
=
=
=
=
=
FRAC32(0.256915601248463 / 4.0);
FRAC32(-0.770746803745390 / 4.0);
FRAC32(0.770746803745390 / 4.0);
FRAC32(-0.256915601248463 / 4.0);
FRAC32(-0.577240524806303 / -4.0);
FRAC32(0.421787048689562 / -4.0);
FRAC32(-0.056297236491843 / -4.0);
GDFLIB_FilterIIR3Init_F16(&sFilterParam);
}
f16InX = FRAC16(0.1);
/* periodically called function */
void Isr(void)
{
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
35
GDFLIB_FilterIIR4
}
f16Result = GDFLIB_FilterIIR3_F16(f16InX, &sFilterParam);
2.4 GDFLIB_FilterIIR4
This function calculates the fourth-order direct-form 1 IIR filter.
For a proper use, it is recommended to initialize the algorithm by the
GDFLIB_FilterIIR4Init function, before using the GDFLIB_FilterIIR4 function. The
GDFLIB_FilterIIR4Init function initializes the buffer and coefficients of the fourth-order
IIR filter.
The GDFLIB_FilterIIR4 function calculates the fourth-order infinite impulse response
(IIR) filter. The IIR filters are also called recursive filters, because both the input and the
previously calculated output values are used for calculation. This form of feedback
enables the transfer of energy from the output to the input, which leads to an infinitely
long impulse response (IIR). A general form of the IIR filter (expressed as a transfer
function in the Z-domain) is described as follows:
Equation 10.
where N denotes the filter order. The fourth-order IIR filter in the Z-domain is expressed
as follows:
Equation 11.
which is transformed into a time-domain difference equation as follows:
Equation 12.
The filter difference equation is implemented directly in the digital signal controller, as
given in Equation 12 on page 36; this equation represents a direct-form 1 fourth-order IIR
filter, as shown in Figure 2-7.
GDFLIB User's Guide, Rev. 0, 10/2015
36
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Figure 2-7. Direct-form 1 fourth-order IIR filter
The coefficients of the filter shown in Figure 2-7 can be designed to meet the
requirements for the fourth-order low-pass filter (LPF), high-pass filter (HPF), band-pass
filter (BPF), or band-stop filter (BSF). The coefficient quantization error can be ignored
in the case of a fourth-order filter due to a finite precision arithmetic. A higher-order LPF
or HPF can be obtained by connecting a number of fourth-order filters in series. The
number of connections gives the order of the resulting filter.
Define the filter coefficients before calling this function. As some coefficients can be
greater than 1 (and lesser than 8), the coefficients are scaled down (divided) by 8.0 for the
fractional version of the algorithm. For a faster calculation, the A coefficients are signinverted. The function returns the filtered value of the input in step k, and stores the input
and output values in the step k into the filter buffer.
2.4.1 Available versions
This function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1).
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
37
GDFLIB_FilterIIR4
The available versions of the GDFLIB_FilterIIR4Init function are shown in the following
table:
Table 2-7. Init function versions
Function name
Parameters
GDFLIB_FilterIIR4Init_F16
GDFLIB_FILTER_IIR4_T_F32 *
Result
type
void
Description
Filter initialization (reset) function. The
parameters' structure is pointed to by a
pointer.
The available versions of the GDFLIB_FilterIIR4 function are shown in the following
table:
Table 2-8. Function versions
Function name
Input
type
GDFLIB_FilterIIR4_F16
frac16_t
Parameters
Result
type
GDFLIB_FILTER_IIR4_T_F32 *
frac16_t
Description
Input argument is a 16-bit fractional
value of the input signal to be filtered
within the range <-1 ; 1). The
parameters' structure is pointed to
by a pointer. The function returns a
16-bit fractional value within the
range <-1 ; 1).
2.4.2 GDFLIB_FILTER_IIR4_T_F32
Variable name
Input type
Description
sFltCoeff
GDFLIB_FILTER_IIR4_COEFF_T_F32 *
Substructure containing filter coefficients.
f32FltBfrY[4]
frac32_t
Internal buffer of y-history. Controlled by the
algorithm.
f16FltBfrX[4]
frac16_t
Internal buffer of x-history. Controlled by the
algorithm.
2.4.3 GDFLIB_FILTER_IIR4_COEFF_T_F32
Variable name
Type
Description
f32B0
frac32_t
B0 coefficient of the IIR4 filter. Set by the user, and must be divided by 8.
f32B1
frac32_t
B1 coefficient of the IIR4 filter. Set by the user, and must be divided by 8.
f32B2
frac32_t
B2 coefficient of the IIR4 filter. Set by the user, and must be divided by 8.
Table continues on the next page...
GDFLIB User's Guide, Rev. 0, 10/2015
38
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Variable name
Type
Description
f32B3
frac32_t
B3 coefficient of the IIR4 filter. Set by the user, and must be divided by 8.
f32B4
frac32_t
B4 coefficient of the IIR4 filter. Set by the user, and must be divided by 8.
f32A1
frac32_t
A1 (sign-inverted) coefficient of the IIR4 filter. Set by the user, and must be divided by -8.
f32A2
frac32_t
A2 (sign-inverted) coefficient of the IIR4 filter. Set by the user, and must be divided by -8.
f32A3
frac32_t
A3 (sign-inverted) coefficient of the IIR4 filter. Set by the user, and must be divided by -8.
f32A4
frac32_t
A4 (sign-inverted) coefficient of the IIR4 filter. Set by the user, and must be divided by -8.
2.4.4 Declaration
The available GDFLIB_FilterIIR4Init functions have the following declarations:
void GDFLIB_FilterIIR4Init_F16(GDFLIB_FILTER_IIR4_T_F32 *psParam)
The available GDFLIB_FilterIIR4 functions have the following declarations:
frac16_t GDFLIB_FilterIIR4_F16(frac16_t f16InX, GDFLIB_FILTER_IIR4_T_F32 *psParam)
2.4.5 Calculation of filter coefficients
There are plenty of methods for the coefficients calculation. The following example
shows the use of Matlab to set up a band-pass filter with the 10000 Hz sampling
frequency, 1000 Hz pass frequency, and 250 Hz bandwidth. The maximum passband
ripple is 3 dB, and the attenuation is 20 dB.
% sampling frequency 10000 Hz, band pass
Ts = 1 / 10000
% center pass frequency 2000 Hz
Fc = 2000
% attenuation 20 dB
Rs = 20
% bandwidth 250 Hz
Fbw = 250
% max. passband ripple 3 dB
Rp = 3
% checking order of the filter
n = buttord(2 * Ts * [Fc - Fbw /2 Fc + Fbw / 2], 2 * Ts * [Fc - Fbw Fc + Fbw], Rp, Rs)
% n = 4, i.e. the filter is achievable with the 4th order
% getting the filter coefficients
[b, a] = butter(n / 2, 2 * Ts * [Fc - Fbw /2 Fc + Fbw / 2])
% the coefs are:
% b0 = 0.005542717210281, b1 = 0, b2 = -0.011085434420561, b3 = 0, b4 = 0.005542717210281
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
39
GDFLIB_FilterIIR4
% a0 = 1.0000, a1 = -1.171272075750262, a2 = 2.122554479822350, a3 = -1.047780658093187,
% a4 = 0.800802646665706
The filter response is shown in Figure 2-8.
Figure 2-8. Filter response
2.4.6 Function use
The use of the GDFLIB_FilterIIR4Init and GDFLIB_FilterIIR4 functions is shown in the
following example. The filter uses the above-calculated coefficients:
#include "gdflib.h"
static frac16_t f16Result;
static frac16_t f16InX;
static GDFLIB_FILTER_IIR4_T_F32 sFilterParam;
void Isr(void);
void main(void)
{
sFilterParam.sFltCoeff.f32B0
sFilterParam.sFltCoeff.f32B1
sFilterParam.sFltCoeff.f32B2
sFilterParam.sFltCoeff.f32B3
sFilterParam.sFltCoeff.f32B4
sFilterParam.sFltCoeff.f32A1
sFilterParam.sFltCoeff.f32A2
sFilterParam.sFltCoeff.f32A3
sFilterParam.sFltCoeff.f32A4
=
=
=
=
=
=
=
=
=
FRAC32(0.005542717210281 / 8.0);
FRAC32(0.0 / 8.0);
FRAC32(-0.011085434420561 / 8.0);
FRAC32(0.0 / 8.0);
FRAC32(0.005542717210281 / 8.0);
FRAC32(-1.171272075750262 / -8.0);
FRAC32(2.122554479822350 / -8.0);
FRAC32(-1.047780658093187 / -8.0);
FRAC32(0.800802646665706 / -8.0);
GDFLIB_FilterIIR4Init_F16(&sFilterParam);
GDFLIB User's Guide, Rev. 0, 10/2015
40
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
}
f16InX = FRAC16(0.1);
/* periodically called function */
void Isr(void)
{
f16Result = GDFLIB_FilterIIR4_F16(f16InX, &sFilterParam);
}
2.5 GDFLIB_FilterMA
The GDFLIB_FilterMA function calculates a recursive form of a moving average filter.
For a proper use, it is recommended that the algorithm is initialized by the
GDFLIB_FilterMAInit function, before using the GDFLIB_FilterMA function.
The filter calculation consists of the following equations:
Equation 13.
Equation 14.
Equation 15.
where:
•
•
•
•
x(k) is the actual value of the input signal
acc(k) is the internal filter accumulator
y(k) is the actual filter output
np is the number of points in the filter window
The size of the filter window (number of filtered points) must be defined before calling
this function, and must be equal to or greater than 1.
The function returns the filtered value of the input at step k, and stores the difference
between the filter accumulator and the output at step k into the filter accumulator.
2.5.1 Available versions
This function is available in the following versions:
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
41
GDFLIB_FilterMA
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1). The parameters use the accumulator types.
The available versions of the GDFLIB_FilterMAInit function are shown in the following
table:
Table 2-9. Function versions
Function name
Input
type
GDFLIB_FilterMAInit_F16
frac16_t
Parameters
Result
type
GDFLIB_FILTER_MA_T_A32 *
void
Description
Input argument is a 16-bit fractional
value that represents the initial value
of the filter at the current step. The
input is within the range <-1 ; 1). The
parameters' structure is pointed to
by a pointer.
The available versions of the GDFLIB_FilterMA function are shown in the following
table:
Table 2-10. Function versions
Function name
Input type
Value
GDFLIB_FilterMA_F16 frac16_t
Result type
Description
Parameter
GDFLIB_FILTER_MA_T_A32 * frac16_t
Input argument is a 16-bit fractional value
of the input signal to be filtered within the
range <-1 ; 1). The parameters' structure
is pointed to by a pointer. The function
returns a 16-bit fractional value within the
range <-1 ; 1).
2.5.2 GDFLIB_FILTER_MA_T_A32
Variable name
Input
type
Description
a32Acc
acc32_t
Filter accumulator. The parameter is a 32-bit accumulator type within the range <-65536.0 ;
65536.0). Controlled by the algorithm.
u16Sh
uint16_t
Number of samples for averaging filtered points (size of the window) defined as a number
of shifts:
The parameter is a 16-bit unsigned integer type within the range <0 ; 15>. Set by the user.
GDFLIB User's Guide, Rev. 0, 10/2015
42
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
2.5.3 Declaration
The available GDFLIB_FilterMAInit functions have the following declarations:
void GDFLIB_FilterMAInit_F16(frac16_t f16InitVal, GDFLIB_FILTER_MA_T_A32 *psParam)
The available GDFLIB_FilterMA functions have the following declarations:
frac16_t GDFLIB_FilterMA_F16(frac16_t f16InX, GDFLIB_FILTER_MA_T_A32 *psParam)
2.5.4 Function use
The use of GDFLIB_FilterMAInit and GDFLIB_FilterMA functions is shown in the
following example:
#include "gdflib.h"
static frac16_t f16Result;
static frac16_t f16InitVal, f16InX;
static GDFLIB_FILTER_MA_T_A32 sFilterParam;
void Isr(void);
void main(void)
{
f16InitVal = FRAC16(0.0);
/* f16InitVal = 0.0 */
/* Filter window = 2 ^ 2 = 4 points */
sFilterParam.u16Sh = 2;
GDFLIB_FilterMAInit_F16(f16InitVal, &sFilterParam);
}
f16InX =
FRAC16(0.8);
/* periodically called function */
void Isr(void)
{
f16Result = GDFLIB_FilterMA_F16(f16InX, &sFilterParam);
}
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
43
GDFLIB_FilterMA
GDFLIB User's Guide, Rev. 0, 10/2015
44
Freescale Semiconductor, Inc.
Appendix A
A.1 bool_t
The bool_t type is a logical 16-bit type. It is able to store the boolean variables with two
states: TRUE (1) or FALSE (0). Its definition is as follows:
typedef unsigned short bool_t;
The following figure shows the way in which the data is stored by this type:
Table A-1. Data storage
15
14
13
12
11
10
9
Value
TRUE
FALSE
8
7
6
5
4
3
2
1
Unused
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
Logi
cal
0
0
0
1
0
0
1
0
0
0
0
0
0
To store a logical value as bool_t, use the FALSE or TRUE macros.
A.2 uint8_t
The uint8_t type is an unsigned 8-bit integer type. It is able to store the variables within
the range <0 ; 255>. Its definition is as follows:
typedef unsigned char int8_t;
The following figure shows the way in which the data is stored by this type:
Table A-2. Data storage
Table continues on the next page...
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
45
uint16_t
Table A-2. Data storage (continued)
7
6
5
4
Value
2
1
0
1
1
1
1
1
1
0
0
1
1
Integer
1
255
3
1
1
1
F
0
11
0
F
0
0
1
0
0
124
0
1
1
0
B
1
1
1
1
0
1
1
1
7
159
C
9
F
A.3 uint16_t
The uint16_t type is an unsigned 16-bit integer type. It is able to store the variables
within the range <0 ; 65535>. Its definition is as follows:
typedef unsigned short uint16_t;
The following figure shows the way in which the data is stored by this type:
Table A-3. Data storage
15
14
13
12
11
10
9
8
Value
65535
5
15518
40768
7
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
1
1
0
0
0
Integer
1
1
1
1
1
1
F
0
0
0
0
0
0
0
1
0
F
0
0
0
0
1
1
1
1
1
0
1
0
0
0
1
0
1
0
5
0
1
1
1
9
1
F
F
0
C
0
9
1
0
3
1
1
F
0
0
1
1
0
1
E
0
4
0
0
0
0
A.4 uint32_t
GDFLIB User's Guide, Rev. 0, 10/2015
46
Freescale Semiconductor, Inc.
Appendix A
The uint32_t type is an unsigned 32-bit integer type. It is able to store the variables
within the range <0 ; 4294967295>. Its definition is as follows:
typedef unsigned long uint32_t;
The following figure shows the way in which the data is stored by this type:
Table A-4. Data storage
31
24 23
16 15
Value
8 7
0
Integer
4294967295
F
F
F
F
F
F
F
F
2147483648
8
0
0
0
0
0
0
0
55977296
0
3
5
6
2
5
5
0
3451051828
C
D
B
2
D
F
3
4
A.5 int8_t
The int8_t type is a signed 8-bit integer type. It is able to store the variables within the
range <-128 ; 127>. Its definition is as follows:
typedef char int8_t;
The following figure shows the way in which the data is stored by this type:
Table A-5. Data storage
7
Value
127
-128
60
-97
6
5
4
Sign
0
3
2
1
1
1
1
1
0
0
0
0
0
1
0
0
0
0
0
1
1
0
1
1
1
1
3
1
1
F
8
0
0
Integer
7
1
1
0
C
0
1
1
9
1
F
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
47
int16_t
A.6 int16_t
The int16_t type is a signed 16-bit integer type. It is able to store the variables within the
range <-32768 ; 32767>. Its definition is as follows:
typedef short int16_t;
The following figure shows the way in which the data is stored by this type:
Table A-6. Data storage
15
Value
32767
-32768
15518
-24768
14
13
12
11
10
9
8
Sign
7
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
0
1
0
0
0
Integer
0
1
1
1
1
1
7
1
0
0
0
0
0
0
1
0
1
F
0
0
0
0
0
1
1
1
3
1
1
F
8
0
1
0
1
1
0
1
0
0
0
0
0
0
1
0
C
9
F
0
0
1
1
1
9
1
1
0
1
F
E
0
0
0
0
4
0
A.7 int32_t
The int32_t type is a signed 32-bit integer type. It is able to store the variables within the
range <-2147483648 ; 2147483647>. Its definition is as follows:
typedef long int32_t;
The following figure shows the way in which the data is stored by this type:
Table A-7. Data storage
31
Value
24 23
16 15
S
8 7
0
Integer
2147483647
7
F
F
F
F
F
F
F
-2147483648
8
0
0
0
0
0
0
0
55977296
0
3
5
6
2
5
5
0
-843915468
C
D
B
2
D
F
3
4
GDFLIB User's Guide, Rev. 0, 10/2015
48
Freescale Semiconductor, Inc.
Appendix A
A.8 frac8_t
The frac8_t type is a signed 8-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef char frac8_t;
The following figure shows the way in which the data is stored by this type:
Table A-8. Data storage
7
Value
0.99219
-1.0
0.46875
-0.75781
6
5
4
3
Sign
2
1
0
1
1
1
0
0
0
0
1
1
Fractional
0
1
1
1
1
7
1
0
F
0
0
0
0
8
0
0
0
1
1
1
1
3
1
0
C
0
1
1
1
9
F
To store a real number as frac8_t, use the FRAC8 macro.
A.9 frac16_t
The frac16_t type is a signed 16-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef short frac16_t;
The following figure shows the way in which the data is stored by this type:
Table A-9. Data storage
15
Value
0.99997
-1.0
14
13
12
11
10
9
8
Sign
0
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
0
Fractional
1
1
1
1
1
7
1
7
0
1
1
1
F
0
0
0
0
F
0
0
0
0
F
0
0
0
0
Table continues on the next page...
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
49
frac32_t
Table A-9. Data storage (continued)
8
0.47357
-0.75586
0
0
0
1
1
1
1
3
1
0
0
0
0
1
0
C
0
1
1
1
9
0
0
1
1
1
9
1
1
0
1
F
1
0
0
0
E
0
0
0
0
4
0
To store a real number as frac16_t, use the FRAC16 macro.
A.10 frac32_t
The frac32_t type is a signed 32-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef long frac32_t;
The following figure shows the way in which the data is stored by this type:
Table A-10. Data storage
31
Value
24 23
16 15
S
8 7
0
Fractional
0.9999999995
7
F
F
F
F
F
F
F
-1.0
8
0
0
0
0
0
0
0
0.02606645970
0
3
5
6
2
5
5
0
-0.3929787632
C
D
B
2
D
F
3
4
To store a real number as frac32_t, use the FRAC32 macro.
A.11 acc16_t
The acc16_t type is a signed 16-bit fractional type. It is able to store the variables within
the range <-256 ; 256). Its definition is as follows:
typedef short acc16_t;
The following figure shows the way in which the data is stored by this type:
GDFLIB User's Guide, Rev. 0, 10/2015
50
Freescale Semiconductor, Inc.
Appendix A
Table A-11. Data storage
15
Value
255.9921875
-256.0
1.0
-1.0
13.7890625
-89.71875
14
13
12
Sign
11
10
9
8
7
6
5
4
Integer
0
1
1
1
1
1
0
0
0
0
8
0
0
0
1
0
0
0
1
1
1
1
0
0
0
0
0
1
0
1
D
1
1
1
0
0
0
0
0
0
0
0
0
1
0
0
0
1
0
0
0
0
0
0
1
0
0
0
0
0
0
8
1
0
1
8
1
1
1
0
0
1
1
6
0
0
F
0
F
0
1
0
0
1
0
1
1
0
1
1
F
0
0
F
0
1
0
0
1
1
F
0
2
Fractional
1
7
3
0
1
0
0
1
E
1
1
0
0
3
5
1
0
0
1
2
4
To store a real number as acc16_t, use the ACC16 macro.
A.12 acc32_t
The acc32_t type is a signed 32-bit accumulator type. It is able to store the variables
within the range <-65536 ; 65536). Its definition is as follows:
typedef long acc32_t;
The following figure shows the way in which the data is stored by this type:
Table A-12. Data storage
31
Value
24 23
S
16 15
8 7
Integer
0
Fractional
65535.999969
7
F
F
F
F
F
F
F
-65536.0
8
0
0
0
0
0
0
0
1.0
0
0
0
0
8
0
0
0
-1.0
F
F
F
F
8
0
0
0
23.789734
0
0
0
B
E
5
1
6
-1171.306793
F
D
B
6
5
8
B
C
To store a real number as acc32_t, use the ACC32 macro.
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
51
FALSE
A.13 FALSE
The FALSE macro serves to write a correct value standing for the logical FALSE value
of the bool_t type. Its definition is as follows:
#define FALSE
((bool_t)0)
#include "mlib.h"
static bool_t bVal;
void main(void)
{
bVal = FALSE;
}
/* bVal = FALSE */
A.14 TRUE
The TRUE macro serves to write a correct value standing for the logical TRUE value of
the bool_t type. Its definition is as follows:
#define TRUE
((bool_t)1)
#include "mlib.h"
static bool_t bVal;
void main(void)
{
bVal = TRUE;
}
/* bVal = TRUE */
A.15 FRAC8
The FRAC8 macro serves to convert a real number to the frac8_t type. Its definition is as
follows:
#define FRAC8(x) ((frac8_t)((x) < 0.9921875 ? ((x) >= -1 ? (x)*0x80 : 0x80) : 0x7F))
The input is multiplied by 128 (=27). The output is limited to the range <0x80 ; 0x7F>,
which corresponds to <-1.0 ; 1.0-2-7>.
GDFLIB User's Guide, Rev. 0, 10/2015
52
Freescale Semiconductor, Inc.
Appendix A
#include "mlib.h"
static frac8_t f8Val;
void main(void)
{
f8Val = FRAC8(0.187);
}
/* f8Val = 0.187 */
A.16 FRAC16
The FRAC16 macro serves to convert a real number to the frac16_t type. Its definition is
as follows:
#define FRAC16(x) ((frac16_t)((x) < 0.999969482421875 ? ((x) >= -1 ? (x)*0x8000 : 0x8000) :
0x7FFF))
The input is multiplied by 32768 (=215). The output is limited to the range <0x8000 ;
0x7FFF>, which corresponds to <-1.0 ; 1.0-2-15>.
#include "mlib.h"
static frac16_t f16Val;
void main(void)
{
f16Val = FRAC16(0.736);
}
/* f16Val = 0.736 */
A.17 FRAC32
The FRAC32 macro serves to convert a real number to the frac32_t type. Its definition is
as follows:
#define FRAC32(x) ((frac32_t)((x) < 1 ? ((x) >= -1 ? (x)*0x80000000 : 0x80000000) :
0x7FFFFFFF))
The input is multiplied by 2147483648 (=231). The output is limited to the range
<0x80000000 ; 0x7FFFFFFF>, which corresponds to <-1.0 ; 1.0-2-31>.
#include "mlib.h"
static frac32_t f32Val;
void main(void)
{
f32Val = FRAC32(-0.1735667);
}
/* f32Val = -0.1735667 */
GDFLIB User's Guide, Rev. 0, 10/2015
Freescale Semiconductor, Inc.
53
ACC16
A.18 ACC16
The ACC16 macro serves to convert a real number to the acc16_t type. Its definition is as
follows:
#define ACC16(x) ((acc16_t)((x) < 255.9921875 ? ((x) >= -256 ? (x)*0x80 : 0x8000) : 0x7FFF))
The input is multiplied by 128 (=27). The output is limited to the range <0x8000 ;
0x7FFF> that corresponds to <-256.0 ; 255.9921875>.
#include "mlib.h"
static acc16_t a16Val;
void main(void)
{
a16Val = ACC16(19.45627);
}
/* a16Val = 19.45627 */
A.19 ACC32
The ACC32 macro serves to convert a real number to the acc32_t type. Its definition is as
follows:
#define ACC32(x) ((acc32_t)((x) < 65535.999969482421875 ? ((x) >= -65536 ? (x)*0x8000 :
0x80000000) : 0x7FFFFFFF))
The input is multiplied by 32768 (=215). The output is limited to the range
<0x80000000 ; 0x7FFFFFFF>, which corresponds to <-65536.0 ; 65536.0-2-15>.
#include "mlib.h"
static acc32_t a32Val;
void main(void)
{
a32Val = ACC32(-13.654437);
}
/* a32Val = -13.654437 */
GDFLIB User's Guide, Rev. 0, 10/2015
54
Freescale Semiconductor, Inc.
How to Reach Us:
Home Page:
freescale.com
Web Support:
freescale.com/support
Information in this document is provided solely to enable system and
software implementers to use Freescale products. There are no express
or implied copyright licenses granted hereunder to design or fabricate
any integrated circuits based on the information in this document.
Freescale reserves the right to make changes without further notice to
any products herein.
Freescale makes no warranty, representation, or guarantee regarding
the suitability of its products for any particular purpose, nor does
Freescale assume any liability arising out of the application or use of
any product or circuit, and specifically disclaims any and all liability,
including without limitation consequential or incidental damages.
“Typical” parameters that may be provided in Freescale data sheets
and/or specifications can and do vary in different applications, and
actual performance may vary over time. All operating parameters,
including “typicals,” must be validated for each customer application by
customer's technical experts. Freescale does not convey any license
under its patent rights nor the rights of others. Freescale sells products
pursuant to standard terms and conditions of sale, which can be found
at the following address: www.freescale.com/salestermsandconditions.
Freescale and the Freescale logo are trademarks of Freescale
Semiconductor, Inc. ARM and Cortex are the registered trademarks of
ARM Limited, in EU and/or elsewhere. ARM logo is the trademark of
ARM Limited. All rights reserved. All other product or service names are
the property of their respective owners.
© 2015 Freescale Semiconductor, Inc.
Document Number CM7GDFLIBUG
Revision 0, 10/2015