DSP System Toolbox
This example shows how to model an algorithm specification for a three band parametric equalizer which will be used for both simulation and code generation.
Required MathWorks™ products:
Signal Processing Toolbox™
DSP System Toolbox™
|On this page…|
Parametric equalizers are often used to adjust the frequency response of an audio system. For example, a parametric equalizer can be used to compensate for physical speakers which have peaks and dips at different frequencies.
The parametric equalizer algorithm in this example provides three second-order (biquadratic) filters whose coefficients can be adjusted to achieve a desired frequency response. A graphical user interface is used in simulation to dynamically adjust filter coefficients and explore behavior. For code generation, the coefficient variables are named and placed in files such that they could be accessed by other software components that dynamically change the coefficients while running on the target processor.
The following sections will describe how the parametric equalizer algorithm is specified, how the behavior can be explored through simulation, and how the code can be generated and customized.
The parametric equalizer algorithm is specified in two parts: a model specification and a parameterized data specification. The model specification is a Simulink subsystem that specifies the signal flow of the algorithm. The model specification also accesses parameterized data that exists in the MATLAB workspace. The parameterized data specification is a MATLAB script that creates the data that is accessed by the Simulink model.
For this example, the model specification is the Equalizer subsystem of the Simulink model dspparameq.mdldspparameq.mdl. In this subsystem, the input is passed through three cascaded bands of equalization. Coefficient changes within each band are smoothed through a leaky integrator before being passed into a Biquad Filter block. Each Biquad Filter block is configured to use a different filter structure. Different filter structures are selected to show the differences in code generation later in this example.
For this example, the parameterized data specification is the MATLAB script dspparameq_data.mdspparameq_data.m. This MATLAB script specifies the initial filter coefficients as well as code generation attributes. When you open the model dspparameq.mdldspparameq.mdl, the model?s PreLoadFcn callback is configured to run the dspparameq_data.mdspparameq_data.m script that creates the parameter data in the MATLAB workspace.
You can use a simulation test bench to explore the behavior of the algorithm. In this example, the test bench consists of the simulation model, dspparameq.mdldspparameq.mdl, as a well as custom graphical user interface (GUI) programmed in MATLAB, dspparameq_gui.mdspparameq_gui.m.
This GUI is loaded in the StartFcn callback of the model. When you run the model, the GUI is brought up and enables dynamic adjustment of coefficient parameter data in the MATLAB workspace during the simulation.
Once you achieve the desired simulation behavior, you can generate C code for the Equalizer subsystem based on the algorithm specification. This model is configured to show some common code generation customizations accessible from Embedded Coder product. These customizations ease the code review and integration process. The following sections show some of the code customizations for this model and provide references to documentation that describe these customizations in more detail.
To generate C code, right-click on the Equalizer subsystem, select Code Generation > Build Subsystem, then click the Build button when prompted for tunable parameters. You can also generate code by clicking the following hyperlink: Generate Code for the Equalizer SubsystemGenerate Code for the Equalizer Subsystem.
Code Generation Report with Links to and from the Model
The model is configured to generate an HTML report that can be used to navigate the generated source and header files. The report also enables bidirectional linking between the generated code and the model. For example, each Biquad Filter block is configured to implement a different filter structure. You can trace from the block to the associated code by right clicking on any of the Biquad Filter blocks and then selecting Code Generation > Navigate to code.
Calling the Generated Code
You can integrate the generated code into an application by making calls to the model initialization and model step functions. An example ert_main.c file is generated that shows how to call the generated code. Note that the example main() calls Equalizer_initialize() to initialize states. The example rt_OneStep() shows how a periodic mechanism such as an interrupt would call Equalizer_step() from the file Equalizer.c.
Input and Output Data Interface
The parameterized data specification file, dspparameq_data.mdspparameq_data.m, creates in and out signal data objects in the MATLAB workspace. These data objects are associated with signal lines in the model and are used to specify descriptions and storage classes of the corresponding variables in the generated code. For example, the signals in and out are declared as a global variable in Equalizer.c. To run the model step function, an application writes data to in, calls the Equalizer_step() function, and then reads the results from out.
Text Annotations in Code Comments
You can insert design documentation entered as text in the model into the comments of the generated code. The Equalizer subsystem contains annotation text with the keyword S:Description. The code generator identifies that the text starts with this keyword and inserts the text following the keyword as comments into the generated code.
To ease navigation of the generated code, each subsystem for the equalizer bands is configured to be atomic and create its own function. You can see the calling order in the Equalizer_step() function.
For more information on customizing function naming and placement see Nonvirtual Subsystem Modular Function Code GenerationNonvirtual Subsystem Modular Function Code Generation.
Coefficient File Placement
The parameterized data specification file, dspparameq_data.mdspparameq_data.m creates parameter data objects for the coefficients in the MATLAB workspace. These data objects are configured to define and declare coefficient variables in separate files biquad_coeffs.c and biquad_coeffs.h respectively. Partitioning coefficients into separate files enables other software components to access this data. For example, in a deployed application, you could schedule another software component to modify these variables at runtime before they are used by Equalizer_step().
For more information about file placement of Data Objects see Managing File Placement of Data Definitions and DeclarationsManaging File Placement of Data Definitions and Declarations.
Filter Design Parameters in Coefficient Variable Comments
When coefficients are calculated (in the parameterized data file or by the graphical user interface), the filter design parameters are stored in the Description field of the coefficient parameter data objects. The model is configured to insert the design parameters as comments in the generated code. This enables reviewers of the code to easily identify which design parameters were used to design the filters.
Package Generated Files
The generated files referenced by the HTML report exist in the Equalizer_ert_rtw directory. In addition to the files in this directory, other files in the MATLAB application install directory may be required for integration into a project. To ease porting the generated code to other environments, this model is configured to use the PackNGo feature, which packages up all of the required files into the zip file Equalizer.zip. Note that the zip file contains all of the required files, but might also contain additional files that may not be required.
For more information on packaging files for integration into other environments, see Relocating Code to Another Development EnvironmentRelocating Code to Another Development Environment.
To learn how to convert the Equalizer subsystem to fixed point using the Fixed-Point Advisor, see the dspparameqflt2fix example.