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.

Note

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

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.

Note

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

example

Examples

collapse all

Create Instrumented MEX Function

Open Live Script

This example shows how to create an instrumented MEX function, run a test bench, then view logged results.

Define prototype input arguments.

n = 128;
x = complex(zeros(n,1));
w = 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.

buildInstrumentedMex testfft -o testfft_instrumented -args {x,coder.Constant(w)} -histogram

If you have a MATLAB® Coder™ license, you can also add the -coder option. For example,

buildInstrumentedMex testfft -coder -o testfft_instrumented -args {x,w}

Like the fiaccel function, the buildInstrumentedMex function generates a MEX function. To generate C code, use the MATLAB® Coder™ codegen function.

Run a test file to record instrumentation results. Use the showInstrumentedMex function to open the report. To view the simulation minimum and maximum values and whole number status, pause 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)),w);
end

showInstrumentationResults testfft_instrumented

Close the histogram display, then use the clearInstrumentationResults function to clear the results log.

clearInstrumentationResults testfft_instrumented

Run a different test bench, then view the new instrumentation results.

for i=1:20
   y = testfft_instrumented(cast(rand(size(x))-0.5,'like',x),w);
end

showInstrumentationResults testfft_instrumented

To view the histogram for a variable, click the histogram icon in the Variables tab.

Close the histogram display, then use the clearInstrumentationResults function to clear the results log.

clearInstrumentationResults testfft_instrumented

Clear the MEX function.

clear testfft_instrumented

Create Instrumented MEX Function for Multiple Entry Point Functions

This example uses:

Open Live Script

This example shows how to create an instrumented MEX function for multiple entry point functions. Generating a MEX function for multiple entry point functions using the buildInstrumentedMex function requires using the '-coder' option and a MATLAB® Coder™ license.

This example uses the two entry-point functions, ep1 and ep2.

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

Code generation successful.

Use the generated MEX function to call the first entry-point function.

y1 = sharedmex('ep1',u);

Use the generated MEX function to call the second entry-point function.

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

Show the instrumentation results.

showInstrumentationResults sharedmex

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 Prepare MATLAB Code 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
```

Version History

Introduced in R2011b

expand all

R2023a: Change to default `buildInstrumentedMex` behavior for constant inputs

When the buildInstrumentedMex function generates a MEX file, it no longer automatically removes constants from the call to the MEX file. With this change, buildInstrumentedMex and codegen MEX generation now have the same default behavior with respect to constant inputs.

buildInstrumentedMex myfun -args {x,coder.Constant(c)}
myfun_mex(x,c)

To revert to the prior behavior, set the ConstantInputs property of the coder.MexConfig object to 'Remove'.

cfg = coder.MexConfig;
cfg.ConstantInputs = "Remove";
buildInstrumentedMex myfun -args {x,coder.Constant(c)} -config cfg
myfun_mex(x)