Quantcast

Documentation Center

  • Trial Software
  • Product Updates

buildInstrumentedMex

Generate compiled C code function including 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. 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.

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.

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

Examples

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.

    tempdirObj=fidemo.fiTempdir('buildInstrumentedMex')
    copyfile(fullfile(matlabroot,'toolbox','fixedpoint',...
       'fidemos','fi_m_radix2fft_withscaling.m'),...
       'testfft.m','f')
  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.)

      Note:   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)));
    end
    
    showInstrumentationResults testfft_instrumented

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

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

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

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

    clear testfft_instrumented;
    tempdirObj.cleanUp;

More About

expand all

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
    

See Also

| | | | |

Was this topic helpful?