Generate compiled C code function including logging instrumentation


buildInstrumentedMex fcn -options
buildInstrumentedMex fcn_1... fcn_n -options -coder



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.


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.

Input Arguments

fcn, fcn_1... fcn_n

MATLAB entry-point functions to be instrumented. The entry-point functions must be suitable for code generation. For more information, see Make the MATLAB Code Suitable for Code Generation (MATLAB Coder).


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.


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:


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 (#).


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.

-histogramCompute 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.


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.


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.


Create an Instrumented MEX Function

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

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

  2. Define prototype input arguments.

    n = 128;
    x = complex(zeros(n,1));
    W = coder.Constant(fidemo.fi_radix2twiddles(n));
  3. 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.)


    Like fiaccel, buildInstrumentedMex generates a MEX function. To generate C code, see the MATLAB Codercodegen function.

    buildInstrumentedMex testfft -o testfft_instrumented...
    -args {x,W} -histogram
  4. Run a test file 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. You can also see proposed data types for double precision numbers in the table.

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

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

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

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

    clearInstrumentationResults testfft_instrumented;
  7. Clear the MEX function, then delete temporary files.

    clear testfft_instrumented;

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;
function y2 = ep2(u, v) %#codegen
        y2 = u + v;

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 


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


  • 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);
    function b = subfun(A,i)
        b = 0.5 * A(i);
    function A = topfun(A)
        N = numel(A);
        for i=1:N
            A(i) = subfun(A(i));   
    function b = subfun(a)
        b = 0.5 * a;

Introduced in R2011b

Was this topic helpful?