Main Content

buildInstrumentedMex

Generate compiled C code function including logging instrumentation

collapse all in page

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

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

instrumentation-report-tb1.png

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

instrumentation-report-tb2.png

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

numeric-type-scope-x-tb2.png

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

clearInstrumentationResults testfft_instrumented

Clear the MEX function.

clear testfft_instrumented

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

report-multiple-entry-point-functions.png

Input Arguments

collapse all

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

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.

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

-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

See Also

| | | | (MATLAB Coder) |