Documentation |
This example shows how to propose fixed-point data types using an instrumented MEX function.
This capability is not compatible with automatic fixed-point conversion. If you select Convert to fixed point at build time, you cannot build instrumented MEX functions.
On this page… |
---|
Create a New Folder and Copy Relevant Files Check Code Generation Readiness Create and set up a MATLAB Coder Project About the fun_with_matlab_test Script Build Instrumented MEX Function |
Prerequisites
To complete this example, you must install the following products:
MATLAB^{®}
MATLAB Coder™
Fixed-Point Designer™
C compiler (for most platforms, a default C compiler is supplied with MATLAB) For a list of supported compilers, see Supported Compilers
You can use mex -setup to change the default compiler. See Changing Default Compiler.
Create a New Folder and Copy Relevant Files
Create a local working folder, for example, c:\coder\fun_with_matlab.
Change to the docroot\toolbox\coder\examples folder. At the MATLAB command line, enter:
cd(fullfile(docroot, 'toolbox', 'coder', 'examples'))
Copy the fun_with_matlab.m and fun_with_matlab_test.m files to your local working folder.
Type | Name | Description |
---|---|---|
Function code | fun_with_matlab.m | Entry-point MATLAB function |
Test file | fun_with_matlab_test.m | MATLAB script that tests fun_with_matlab.m |
The fun_with_matlab Function
function y = fun_with_matlab(x) %#codegen persistent z if isempty(z) z = zeros(2,1); end % [b,a] = butter(2, 0.25) b = [0.0976310729378175, 0.195262145875635, 0.0976310729378175]; a = [1, -0.942809041582063, 0.3333333333333333]; y = zeros(size(x)); for i = 1:length(x) y(i) = b(1)*x(i) + z(1); z(1) = b(2)*x(i) + z(2) - a(2) * y(i); z(2) = b(3)*x(i) - a(3) * y(i); end end
Check Code Generation Readiness
In the current working folder, right-click the fun_with_matlab.m function. From the context menu, select Check Code Generation Readiness.
The code generation readiness tool screens the code for features and functions that are not supported for code generation. The tool reports that the fun_with_matlab.m function is already suitable for code generation.
If your entry-point function is not suitable for code generation, the tool provides a report that lists the source files that contain unsupported features and functions. The report also provides an indication of how much work you must do to make the MATLAB code ready for code generation. Before proposing data types, you must fix these issues. For more information, see Detect and Debug Code Generation Errors.
Create and set up a MATLAB Coder Project
Navigate to the work folder that contains the file for this tutorial.
On the MATLAB Apps tab, select MATLAB Coder and then, in the MATLAB Coder Project dialog box, set Name to fun_with_matlab_project.prj.
Alternatively, at the MATLAB command line, enter
coder -new fun_with_matlab_project.prj
By default, the project opens in the MATLAB workspace.
On the project Overview tab, click the Add files link. Browse to the file fun_with_matlab.m and then click OK to add the file to the project.
About the fun_with_matlab_test Script
The test script runs the fun_with_matlab function with three input signals: chirp, step, and impulse. The script then plots the results.
Contents of fun_with_matlab_test
Define Input Types
On the project Overview tab, click the Autodefine types link.
In the Autodefine Input Types dialog box, add fun_with_matlab_test as a test file and then click Run.
The test file runs and displays the outputs of the filter for each of the input signals.
MATLAB Coder determines the input types from the test file and then displays them in the Autodefine Input Types dialog box.
In this dialog box, click Use These Types.
MATLAB Coder sets the type of x to double(1x256).
Why Specify an Input Definition?
Build Instrumented MEX Function
In the project, click the Build tab.
On the Build tab, set the Output type to Instrumented MEX Function.
Click the Build button.
The Build progress dialog box opens. When the build is complete, MATLAB Coder generates an instrumented MEX function fun_with_matlab_mex in the current folder. It also provides a link to the report on the Show Instrumentation Results pane. In this report, you can view the types of variables in your MATLAB code.
View Data Type Proposal Settings
On the Show Instrumentation Results pane, click the Data type proposal and report settings link.
This example uses the default data type proposal settings which propose fraction lengths for the specified word lengths. Because the MATLAB code is floating-point, the word length is specified by the Default data type of all floating-point expressions field. You can specify the numerictype signedness, word length and fraction length. Specifying [] for signedness instructs MATLAB Coder to choose the signedness based on simulation values. The default word length is 16. The default fraction length is 12.
Close the dialog box.
Run Simulation
On the Run Simulation pane, verify that the test file is set to fun_with_matlab_test and that Redirect entry-point calls to MEX function is selected. That way, each call to fun_with_matlab is replaced with a call to the instrumented MEX function fun_with_matlab_mex.
On the Run Simulation pane, click Run.
The fun_with_matlab_test file runs and calls fun_with_matlab_mex. The outputs of the filters are displayed as before.
View Code Generation Report
On the Show Instrumentation Results pane, click View Report.
In the Code Generation Report, click the Variables tab.
The report displays the simulation minimum and maximum values and the proposed data types.
MATLAB Coder proposes data types with word length of 16 and fraction length optimized to avoid overflows.
Next Steps
To learn how to apply the proposed data types to your entry-point MATLAB function and verify that the fixed-point version of your algorithm is functionally equivalent to your original MATLAB algorithm, see Apply Fixed-Point Data Types Using an Instrumented Mex Function.