Exporting Filter Coefficients from FDATool :: Working with Texas Instruments Code Composer Studio 3.3 IDE (Embedded Coder™)

Exporting Filter Coefficients from FDATool

About FDATool

Signal Processing Toolbox™ software provides the Filter Design and Analysis tool (FDATool) that lets you design a filter and then export the filter coefficients to a matching filter implemented in a CCS project.

Using FDATool with CCS IDE enables you to:

Design your filter in FDATool
Use CCS to test your filter on a processor
Redesign and optimize the filter in FDATool
Test your redesigned filter on the processor

For instructions on using FDATool, refer to the section "Filter Design and Analysis Tool" in the Signal Processing Toolbox documentation.

Procedures in this chapter demonstrate how to use the FDATool export options to export filter coefficients to CCS. Using these procedures, you can perform the following tasks:

Export filter coefficients from FDATool in a header file—Exporting Filter Coefficients from FDATool to the CCS IDE Editor
Export filter coefficients from FDATool to processor memory—Replacing Existing Coefficients in Memory with Updated Coefficients

Caution As a best practice, export coefficients in a header file for the most reliable results. Exporting coefficients directly to processor memory can generate unexpected results or corrupt memory.

Also see the reference pages for the following functions. These primary functions allow you use to access variables and write them to processor memory from the MATLAB Command window.

address — Return the address of a symbol so you can read or write to it.
ticcs — Create a connection between MATLAB software and CCS IDE so you can work with the project in CCS from the MATLAB Command window.
write — Write data to memory on the processor.

Preparing to Export Filter Coefficients to Code Composer Studio Projects

Features of a Filter

When you create a filter in FDATool, the filter includes defining features identified in the following table.

Defining Feature	Description
Structure	Structure defines how the elements of a digital filter—gains, adders/subtractors, and delays—combine to form the filter. See the Signal Processing Toolbox documentation in the Online Help system for more information about filter structures.
Design Method	Defines the mathematical algorithm used to determine the filter response, length, and coefficients.
Response Type and Specifications	Defines the filter passband shape, such as lowpass or bandpass, and the specifications for the passband.
Coefficients	Defines how the filter structure responds at each stage of the filter process.
Data Type	Defines how to represent the filter coefficients and the resulting filtered output. Whether your filter uses floating-point or fixed-point coefficients affects the filter response and output data values.

When you export your filter, FDATool exports only the number of and value of the filter coefficients and the data type used to define the coefficients.

Selecting the Export Mode

You can export a filter by generating an ANSI C header file, or by writing the filter coefficients directly to processor memory. The following table summarizes when and how to use the export modes.

To… Use Export Mode… When to Use Suggested Use

Add filter coefficients to a project in CCS

To…	Use Export Mode…	When to Use	Suggested Use
Add filter coefficients to a project in CCS	`C header file`	You implemented a filter algorithm in your program, but you did not allocate memory on your processor for the filter coefficients.	Add the generated ANSI C header file to a project. Building and loading this project into your processor allocates static memory locations on the processor and writes your filter coefficients to those locations. Edit the file so the header file allocates extra processor memory and then add the header file to your project. Refer to Allocating Extra Memory for Filter Coefficients in the next section. (For a sample generated header file, refer toReviewing ANSI C Header File Contents.)
Modify the filter coefficients in an embedded application loaded on a processor	`Write directly to memory`	You loaded a program on your processor. The program allocated space in your processor memory to store the filter coefficients.	Optimize your filter design in FDATool. Then, Write the updated filter coefficients directly to the allocated processor memory. Refer to section Preventing Memory Corruption When You Export Coefficients to Processor Memory for more information.

C header file

You implemented a filter algorithm in your program, but you did not allocate memory on your processor for the filter coefficients.

Add the generated ANSI C header file to a project. Building and loading this project into your processor allocates static memory locations on the processor and writes your filter coefficients to those locations.
Edit the file so the header file allocates extra processor memory and then add the header file to your project. Refer to Allocating Extra Memory for Filter Coefficients in the next section.

(For a sample generated header file, refer toReviewing ANSI C Header File Contents.)

Modify the filter coefficients in an embedded application loaded on a processor

Write directly to memory

You loaded a program on your processor. The program allocated space in your processor memory to store the filter coefficients.

Optimize your filter design in FDATool.
Then,
Write the updated filter coefficients directly to the allocated processor memory. Refer to section Preventing Memory Corruption When You Export Coefficients to Processor Memory for more information.

Choosing the Export Data Type

The export process provides two ways you can specify the data type to use to represent the filter coefficients. Select one of the options shown in the following table when you export your filter.

Specify Data Type for Export	Description
Export suggested	Uses the data type that FDATool suggests to preserve the fidelity of the filter coefficients and the performance of your filter in the project
Export as	Lets you specify the data type to use to export the filter coefficients

FDATool exports filter coefficients that use the following data types directly without modifications:

Signed integer (8, 16, or 32 bits)
Unsigned integer (8, 16, or 32 bits)
Double-precision floating point (64 bits)
Single-precision floating point (32 bits)

Filters in FDATool in the Signal Processing Toolbox software use double-precision floating point. You cannot change the data type.

If you have installed DSP System Toolbox software, you can use the filter quantization options in FDATool to set the word and fraction lengths that represent your filter coefficients. For information about using the quantization options, refer to Filter Design and Analysis Tool in the Filter Design Toolbox documentation in the Online help system.

If your filter uses one of the supported data types, Export suggested specifies that data type.

If your filter does not use one of the supported data types, FDATool converts the unsupported data type to one of the supported types and then suggests that data type. For more information about how FDATool determines the data type to suggest, refer to How FDATool Determines the Export Suggested Data Type.

Follow these best-practice guidelines when you implement your filter algorithm in source code and design your filter in FDATool:

Implement your filter using one of the data types FDATool exports without modifications.
Design your filter in FDATool using the data type you used to implement your filter.

To Choose the Export Data Type. When you export your filter, follow this procedure to select the export data type so that the exported filter coefficients closely match the coefficients of your filter in FDATool.

In FDATool, select Targets > Code Composer Studio IDE to open the Export to Code Composer Studio IDE dialog box.

Perform one of the following actions:

Select Export suggested to export the coefficients in the suggested data type.

Select Export as and choose the data type your filter requires from the list.

Caution If you select Export as, the exported filter coefficients can be very different from the filter coefficients in FDATool. As a result, your filter cutoff frequencies and performance may not match your design in FDATool.

How FDATool Determines the Export Suggested Data Type. By default, FDATool represents filter coefficients as double-precision floating-point data. When you export your filter coefficients, FDATool suggests the same data type.

If you set custom word and fraction lengths to represent your filter coefficients, the export process suggests a data type to maintain the best fidelity for the filter.

The export process converts your custom word and fraction lengths to a suggested export data type, using the following rules:

Round the word length up to the nearest larger supported data type. For example, round an 18-bit word length up to 32 bits.
Set the fraction length to the maintain the same difference between the word and fraction length in the new data type as applies in the custom data type.
For example, if you specify a fixed-point data type with word length of 14 bits and fraction length of 11 bits, the export process suggests an integer data type with word length of 16 bits and fraction length of 13 bits, retaining the 3 bit difference.

Exporting Filter Coefficients to Your Code Composer Studio Project

Exporting Filter Coefficients from FDATool to the CCS IDE Editor

In this section, you export filter coefficients to a project by generating an ANSI C header file that contains the coefficients. The header file defines global arrays for the filter coefficients. When you compile and link the project to which you added the header file, the linker allocates the global arrays in static memory locations in processor memory.

Loading the executable file into your processor allocates enough memory to store the exported filter coefficients in processor memory and writes the coefficients to the allocated memory.

Use the following steps to export filter coefficients from FDATool to the CCS IDE text editor.

Start FDATool by entering fdatool at the MATLAB command prompt.
```
fdatool					% Starts FDATool.
```
Design a filter with the same structure, length, design method, specifications, and data type you implemented in your source code filter algorithm.
The following figure shows a Direct-form II IIR filter example that uses second-order sections.
Click Store Filter to store your filter design. Storing the filter allows you to recall the design to modify it.
To export the filter coefficients, select Targets > Code Composer Studio IDE from the FDATool menu bar.
The Export to Code Composer Studio IDE dialog box opens, as shown in the following figure.
Set Export mode to C header file.
In Variable names in C header file, enter variable names for the Numerator, Denominator, Numerator length, and Denominator length parameters where the coefficients will be stored.
The dialog box shows only the variables you need to export to define your filter.

In Data type to use in export, select Export suggested to accept the recommended export data type. FDATool suggests a data type that retains filter coefficient fidelity.

You may find it useful to select the Export as option and select an export data type other than the one suggested.

Caution If you deviate from the suggested data type, the exported filter coefficients can be very different from the filter coefficients in FDATool. As a result, your filter cutoff frequencies and performance may not match your design in FDATool.

For more information about how FDATool decides which data type to suggest, refer to How FDATool Determines the Export Suggested Data Type.

If you know the board number and processor number of your target, enter DSP Board # and DSP Processor # values to identify your board.
When you have only one board or simulator, Embedded Coder software sets DSP Board # and DSP Processor # values for your board automatically.
If you have more than one board defined in CCS Setup:
- Click Select target to open the Selection Utility dialog box.
- From the list of boards and list of processors, select the board name and processor name to use.
- Click Done to set the DSP Board # and DSP Processor # values.
Click Generate to generate the ANSI header file. FDATool prompts you for a file name and location to save the generated header file.
The default location to save the file is your MATLAB working folder. The default file name is fdacoefs.h.
Click OK to export the header file to the CCS editor.
If CCS IDE is not open, this step starts the IDE.
The export process does not add the file to your active project in the IDE.
Drag your generated header file into the project that implements the filter.
Add a #include statement to your project source code to include the new header file when you build your project.
Generate a .out file and load the file into your processor. Loading the file allocates locations in static memory on the processor and writes the filter coefficients to those locations.

To see an example header file, refer to Reviewing ANSI C Header File Contents.

Reviewing ANSI C Header File Contents

The following program listing shows the exported header (.h) file that FDATool generates. This example shows a direct-form II filter that uses five second-order sections. The filter is stable and has linear phase.

Comments in the file describe the filter structure, number of sections, stability, and the phase of the filter. Source code shows the filter coefficients and variables associated with the filter design, such as the numerator length and the data type used to represent the coefficients.

/*
 * Filter Coefficients (C Source) generated by the Filter Design and Analysis Tool
 *
 * Generated by MATLAB(R) 7.8 and the Signal Processing Toolbox 6.11.
 *
 * Generated on: xx-xxx-xxxx 14:24:45
 *
 */

/*
 * Discrete-Time IIR Filter (real)
 * -------------------------------
 * Filter Structure    : Direct-Form II, Second-Order Sections
 * Number of Sections  : 5
 * Stable              : Yes
 * Linear Phase        : No
 */

/* General type conversion for MATLAB generated C-code  */
#include "tmwtypes.h"
/* 
 * Expected path to tmwtypes.h 
 * $MATLABROOT\extern\include\tmwtypes.h 
 */
#define MWSPT_NSEC 11
const int NL[MWSPT_NSEC] = { 1,3,1,3,1,3,1,3,1,3,1 };
const real64_T NUM[MWSPT_NSEC][3] = {
  {
      0.802536131462,                 0,                 0 
  },
  {
     0.2642710234701,   0.5285420469403,   0.2642710234701 
  },
  {
                   1,                 0,                 0 
  },
  {
     0.1743690465012,   0.3487380930024,   0.1743690465012 
  },

⋮

  {
     0.2436793028081,   0.4873586056161,   0.2436793028081 
  },
  {
                   1,                 0,                 0 
  },
  {
     0.3768793219093,   0.7537586438185,   0.3768793219093 
  },
  {
                   1,                 0,                 0 
  }
};
const int DL[MWSPT_NSEC] = { 1,3,1,3,1,3,1,3,1,3,1 };
const real64_T DEN[MWSPT_NSEC][3] = {
  {
                   1,                 0,                 0 
  },
  {
                   1,  -0.1842138030775,   0.1775781189277 
  },
  {
                   1,                 0,                 0 
  },
⋮ {
                   1,  -0.2160098642842,   0.3808329528195 
  },
  {
                   1,                 0,                 0 
  }
};

Preventing Memory Corruption When You Export Coefficients to Processor Memory

Allocating Extra Memory for Filter Coefficients

You can allocate extra memory by editing the generated ANSI C header file. You can then load the associated program file into your processor as described in Example: Using the Exported Header File to Allocate Extra Processor Memory. Extra memory lets you change filter coefficients and overwrite existing coefficients stored in processor memory more easily.

To prevent problems when you update filter coefficients in a project, , such as writing coefficients to unintended memory locations, use the C header file export mode option in FDATool to update filter coefficients in your program.

Example: Using the Exported Header File to Allocate Extra Processor Memory

You can edit the generated header file so the linked program file allocates extra processor memory. By allocating extra memory, you avoid the problem of insufficient memory when you export new coefficients directly to allocated memory.

For example, changing the following command in the header file:

const real64_T NUM[47] = {...}

real64_T NUM[256] = {...}

allocates enough memory for NUM to store up to 256 numerator filter coefficients rather than 47.

Exporting the header file to CCS IDE does not add the filter to your project. To incorporate the filter coefficients from the header file, add a #include statement:

#include	"headerfilename.h"

Refer to Exporting Filter Coefficients to Your Code Composer Studio Project for information about generating a header file to export filter coefficients.

When you export filter coefficients directly to processor memory, the export process writes coefficients to as many memory locations as they need. The write process does not perform bounds checking. Plan memory allocation carefully, so that the software writes to the right locations and has enough memory for filter coefficients.

Replacing Existing Coefficients in Memory with Updated Coefficients

When you redesign a filter and export new coefficients to replace existing coefficients in memory, verify the following conditions for your new design:

Your redesign did not increase the memory required to store the coefficients beyond the allocated memory.
Changes that increase the memory required to store the filter coefficients include the following redesigns:
- Increasing the filter order
- Changing the number of sections in the filter
- Changing the numerical precision (changing the export data type)
Your changes did not change the export data type.

Caution Identify changes that require additional memory to store the coefficients before you begin your export. Otherwise, exporting the new filter coefficients may overwrite data in memory locations you did not allocate for storing coefficients. Also, exporting filter coefficients to memory after you change the filter order, structure, design algorithm, or data type can yield unexpected results and corrupt memory.

Changing the filter design algorithm in FDATool, such as changing from Butterworth to Maximally Flat, often changes the number of filter coefficients (the filter order), the number of sections, or both. Also, the coefficients from the new design algorithm may not work with your source code filter implementation.

If you change the design algorithm, verify that your filter structure and length are the same after you redesign your filter, and that the coefficients will work with the filter you implemented.

If you change the number of sections or the filter order, your filter will not work well unless your filter algorithm implementation accommodates the changes.

Example: Changing Filter Coefficients Stored on Your Processor

This example writes filter coefficients to processor memory to replace the existing coefficients. To perform this process, you need the names of the variables in which your project stores the filter data.

Before you export coefficients directly to memory, verify that your project allocated enough memory for the new filter coefficients. If your project allocated enough memory, you can modify your filter in FDATool and then follow the steps in this example to export the updated filter coefficients to the allocated memory.

If your new filter requires additional memory space, use a C header file to allocate memory on the processor and export the new coefficients as described in Exporting Filter Coefficients to Your Code Composer Studio Project.

For important guidelines on writing directly to processor memory, refer to Preventing Memory Corruption When You Export Coefficients to Processor Memory.

Follow these steps to export filter coefficients from FDATool directly to memory on your processor.

Load the program file that contains your filter into CCS IDE to activate the program symbol table. The symbol must contain the global variables you use to store the filter coefficients and length parameters.
Start FDATool.
Click Filter Manager to open the Filter Manager dialog box, shown in the following figure.
Highlight the filter to modify on the list of filters, and select Edit current filter. The highlighted filter appears in FDATool for you to change.
If you did not store your filter from a previous session, design the filter in FDATool and continue.
Click Close to dismiss the Filter Manager dialog box.
Adjust the filter specifications in FDATool to modify its performance.
In FDATool, select Targets > Code Composer Studio IDE to open the Export to Code Composer Studio IDE dialog box.
Keep the export dialog box open while you work. When you do so, the contents update as you change the filter in FDATool.
In the Export to Code Composer Studio dialog box:
- Set Export mode to Write directly to memory
- Clear Disable memory transfer warnings to get a warning if your processor does not support the export data type.
In Variable names in target symbol table, enter the names of the variables in the processor symbol table that correspond to the memory allocated for the parameters, such as Numerator and Denominator. Your names must match the names of the filter coefficient variables in your program.
Select Export suggested to accept the recommended export data type.
For more information about how FDATool determines the data type to suggest, refer to How FDATool Determines the Export Suggested Data Type.
If you know the board number and processor number of your target, enter DSP Board # and DSP Processor # values to identify your board.
If you have more than one board defined in CCS Setup:
- Click Select target to open the Selection Utility dialog box.
- Select the board name and processor name to use from the list of boards.
Click Generate to export your filter. If your processor does not support the data type you export, you see a warning similar to the following message.

You can continue to export the filter, or cancel the export process. To prevent this warning dialog box from appearing, select Disable memory transfer warnings in the Export to Code Composer Studio IDE dialog box.
(Optional) Continue to optimize filter performance by modifying your filter in FDATool and then export the updated filter coefficients directly to processor memory.
When you finish testing your filter, return to FDATool, and click Store filter to save your changes.