buildInstrumentedMex

Generate compiled C code function including logging instrumentation

Syntax

buildInstrumentedMex fcn -options

buildInstrumentedMex fcn_1... fcn_n -options -coder

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. Optionally, you can enable instrumentation for log2 histograms of all named, intermediate and expression values. The general syntax and options of buildInstrumentedMex and fiaccel are the same, except buildIntstrumentedMex has no fi object restrictions and supports the '-coder' option.

example

buildInstrumentedMex fcn_1... fcn_n -options -coder translates the MATLAB functions fcn_1 through fcn_n to a MEX function and enables instrumentation for logging minimum and maximum values of all named and intermediate variables. Generating a MEX function for multiple entry-point functions requires the '-coder' option.

Examples

collapse all

Create an Instrumented MEX Function

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

Create a temporary directory, then import an example function from Fixed-Point Designer™.

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

Define prototype input arguments.

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

Generate an instrumented MEX function. Use the -o option to specify the MEX function name. Use the -histogram option to compute histograms. (If you have a MATLAB Coder™ license, you may want to also add the -coder option. In this case, use buildInstrumentedMex testfft -coder -o testfft_instrumented -args {x,W} instead of the following line of code.)

Note

Like fiaccel, buildInstrumentedMex generates a MEX function. To generate C code, see the MATLAB Coder codegen (MATLAB Coder) function.

buildInstrumentedMex testfft -o testfft_instrumented...
-args {x,W} -histogram

Run a test file to record instrumentation results. Call showInstrumentationResults to open the report. View the simulation minimum and maximum values and whole number status by pausing over a variable in the report. You can also see proposed data types for double precision numbers in the table.

for i=1:20
   y = testfft_instrumented(randn(size(x)));
end

showInstrumentationResults testfft_instrumented

View the histogram for a variable by clicking in the Variables tab.

For information on the figure, refer to the NumericTypeScope reference page.

Close the histogram display and then, clear the results log.

clearInstrumentationResults testfft_instrumented;

Clear the MEX function, then delete temporary files.

clear testfft_instrumented;
tempdirObj.cleanUp;

Build an Instrumented MEX Function for Multiple Entry Point Functions

In a local writable folder, create the functions ep1.m and ep2.m.

function y1 = ep1(u) %#codegen
y1 = u;
end

function y2 = ep2(u, v) %#codegen
y2 = u + v;
end

Generate an instrumented MEX function for the two entry-point functions. Use the -o option to specify the name of the MEX function. Use the -histogram option to compute histograms. Use the -coder option to enable generating multiple entry points with the buildInstrumentedMex function.

u = 1:100;
v = 5:104;
buildInstrumentedMex -o sharedmex ...
ep1 -args {u} ... % Entry point 1
ep2 -args {u, v} ... % Entry point 2
-histogram -coder

Call the first entry-point function using the generated MEX function.

y1 = sharedmex('ep1', u);

Call the second entry-point function using the generated MEX function.

y2 = sharedmex('ep2', u, v);

Show the instrumentation results.

showInstrumentationResults sharedmex

Note

Generating a MEX function for multiple entry-point functions using the buildInstrumentedMex function requires a MATLAB Coder license.

Input Arguments

collapse all

`fcn` — Entry-point functions to instrument
function name

MATLAB entry-point functions to be instrumented, specified as a function existing in the current working folder or on the path. The entry-point functions must be suitable for code generation. For more information, see Make the MATLAB Code Suitable for Code Generation (MATLAB Coder).

`options` — Compiler options
option value | space delimited list of option values

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.
`-coder`	Use MATLAB Coder software to compile the MEX file, instead of the default Fixed-Point Designer `fiaccel` function. This option removes `fiaccel` restrictions and allows for full code generation support. You must have a MATLAB Coder license to use this option.
`-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.
`-histogram`	Compute the log2 histogram for all named, intermediate and expression values. A histogram column appears in the code generation report table.
`-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 If not specified, `buildInstrumentedMex` uses inlining 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.

Tips

You cannot instrument MATLAB functions provided with the software. If your top-level function is such a MATLAB function, nothing is logged. You also cannot instrument scripts.
Instrumentation results are accumulated every time the instrumented MEX function is called. Use clearInstrumentationResults to clear previous results in the log.
Some coding patterns pass a significant amount of data, but only use a small portion of that data. In such cases, you may see degraded performance when using buildInstrumentedMex. In the following pattern, subfun only uses one element of input array, A. For normal execution, the amount of time to execute subfun once remains constant regardless of the size of A. The function topfun calls subfun N times, and thus the total time to execute topfun is proportional to N. When instrumented, however, the time to execute subfun once becomes proportional to N^2. This change occurs because the minimum and maximum data are calculated over the entire array. When A is large, the calculations can lead to significant performance degradation. Therefore, whenever possible, you should pass only the data that the function actually needs.
```
function A = topfun(A)
    N = numel(A);
    for i=1:N
        A(i) = subfun(A,i);
    end
end
function b = subfun(A,i)
    b = 0.5 * A(i);
end
  
function A = topfun(A)
    N = numel(A);
    for i=1:N
        A(i) = subfun(A(i));   
    end  
end
function b = subfun(a)
    b = 0.5 * a;
end
```