buildInstrumentedMex - Generate MEX function with logging instrumentation

Syntax

buildInstrumentedMex fcn -options

Description

buildInstrumentedMex fcn -options translates the MATLAB file fcn.m to a MEX function and enables instrumentation for logging minimum and maximum values of all named and intermediate variables.

Note Instrumentation results are accumulated every time the instrumented MEX function is called. Use clearInstrumentationResults to clear previous results in the log.

Arrays of structures are not logged. Only scalar (1x1) structures are logged.

You cannot instrument MATLAB functions. If your top-level function is a MATLAB function, nothing is logged.

Input Arguments

fcn

MATLAB function to be instrumented. fcn must be suitable for code generation. For more information, see Making the MATLAB Code Suitable for Code Generation.

options

Choice of compiler options. buildInstrumentedMex gives precedence to individual command-line options over options specified using a configuration object. If command-line options conflict, the rightmost option prevails.

`-args example_inputs`	Define the size, class, and complexity of all MATLAB function inputs. Use the values in `example_inputs` to define these properties. `example_inputs` must be a cell array that specifies the same number and order of inputs as the MATLAB function.
`-config config_object`	Specify MEX generation parameters, based on `config_object`, defined as a MATLAB variable using `coder.mexconfig`. For example: cfg = coder.mexconfig;
`-d out_folder`	Store generated files in the absolute or relative path specified by `out_folder`. If the folder specified by `out_folder` does not exist, `buildInstrumentedMex` creates it for you. If you do not specify the folder location, `buildInstrumentedMex` generates files in the default folder: `fiaccel`/`mex`/`fcn`. `fcn` is the name of the MATLAB function specified at the command line. The function does not support the following characters in folder names: asterisk (`*`), question-mark (`?`), dollar ($), and pound (`#`).
`-g`	Compiles the MEX function in debug mode, with optimization turned off. If not specified, `buildinstrumentedMex` generates the MEX function in optimized mode.
`-global global_values`	Specify initial values for global variables in MATLAB file. Use the values in cell array `global_values` to initialize global variables in the function you compile. The cell array should provide the name and initial value of each global variable. You must initialize global variables before compiling with `buildInstrumentedMex`. If you do not provide initial values for global variables using the `-global` option, `buildInstrumentedMex` checks for the variable in the MATLAB global workspace. If you do not supply an initial value, `buildInstrumentedMex` generates an error. The generated MEX code and MATLAB each have their own copies of global data. To ensure consistency, you must synchronize their global data whenever the two interact. If you do not synchronize the data, their global variables might differ.
`-I include_path`	Add `include_path` to the beginning of the code generation path. `buildInstrumentedMex` searches the code generation path first when converting MATLAB code to MEX code.
`-launchreport`	Generate and open a code generation report. If you do not specify this option, `buildInstrumentedMex` generates a report only if error or warning messages occur or you specify the `-report` option.
`-o output_file_name`	Generate the MEX function with the base name `output_file_name` plus a platform-specific extension. `output_file_name` can be a file name or include an existing path. If you do not specify an output file name, the base name is `fcn_mex`, which allows you to run the original MATLAB function and the MEX function and compare the results.
`-O optimization_option`	Optimize generated MEX code, based on the value of `optimization_option`: `enable:inline` — Enable function inlining `disable:inline` — Disable function inlining `enable:blas` — Use BLAS library, if available `disable:blas` — Do not use BLAS library If not specified, `buildInstrumentedMex` uses inlining and BLAS library functions for optimization.
`-report`	Generate a code generation report. If you do not specify this option, `buildInstrumentedMex` generates a report only if error or warning messages occur or you specify the `-launchreport` option.

Examples

Create an instrumented MEX function. Run a test bench, then view logged results.

Create a temporary directory, then import a demo function from Fixed-Point Toolbox.

tempdirObj=fidemo.fiTempdir('showInstrumentationResults')
copyfile(fullfile(matlabroot,'toolbox','fixedpoint',...
   'fidemos','fi_m_radix2fft_withscaling.m'),...
   'testfft.m','f')

Define prototype input arguments.

n = 128;
x = zeros(n,1);
W = coder.Constant(fi(fidemo.fi_radix2twiddles(n));

Generate an instrumented MEX function. Use the -o option to specify the MEX function name.
```
buildInstrumentedMex testfft -o testfft_instrumented...
-args {x,W}
```
Run a test bench to record instrumentation results. Call showInstrumentationResults to open the Code Generation Report. View the simulation minimum and maximum values and whole number status by hovering over a variable in the report.
```
for i=1:20
   y = testfft_instrumented(randn(size(x)));
end

showInstrumentationResults testfft_instrumented
```

Clear the results log.

clearInstrumentationResults testfft_instrumented

Clear the MEX function, then delete temporary files.
```
clear testfft_instrumented;
tempdirObj.cleanUp;
```

Search MATLAB Documentation
R2012a Documentation → Fixed-Point Toolbox
View documentation for other releases	Learn more about Fixed-Point Toolbox

buildInstrumentedMex - Generate MEX function with logging instrumentation

Syntax

Description

Input Arguments

Examples

See Also