showInstrumentationResults

Results logged by instrumented, compiled C code function

Syntax

showInstrumentationResults('mex_fcn')

showInstrumentationResults('mex_fcn','-options')

showInstrumentationResults mex_fcn

showInstrumentationResults mex_fcn -options

Description

showInstrumentationResults('mex_fcn') opens the Instrumentation Report Viewer, showing results from calling the instrumented MEX function mex_fcn.

Hovering over variables and expressions in the report displays the logged information. The logged information includes minimum and maximum values, proposed fraction or word lengths, percent of current range, and whether the value is always a whole number, depending on which options you specify. If you specify to include them in the buildInstrumentedMex function, histograms are also included. The same information is displayed in a summary table in the Variables tab.

When you call showInstrumentationResults, a file named instrumentation/mex_fcn/html/printable.html is created. mex_fcn is the name of the corresponding instrumented MEX function. Selecting this file opens a web-based version of the Instrumentation Report Viewer. To open this file from within MATLAB^®, right-click the file and select Open Outside MATLAB.

The showInstrumentationResults function returns an error if the instrumented mex_fcn has not yet been called.

Note

The logged results from the showInstrumentationResults function are an accumulation of all previous calls to the instrumented MEX function. To clear the log, see clearInstrumentationResults.

showInstrumentationResults('mex_fcn','-options') specifies options for the instrumentation results section of the Instrumentation Report Viewer.

showInstrumentationResults mex_fcn and showInstrumentationResults mex_fcn -options are alternative syntaxes for opening the Instrumentation Report Viewer.

Examples

Create Instrumented MEX Function

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

Input Arguments

mex_fcn — Instrumented MEX function

MEX function

Instrumented MEX function created using buildInstrumentedMex.

options — Instrumentation results options

-defaultDT T | -nocode | -optimizeWholeNumbers | -percentSafetyMargin N | -printable | -proposeFL | -proposeWL

Instrumentation results options, specified as:

-defaultDT T	Default data type to propose for double or single data type inputs, where T is either a numerictype object or one of the following: 'remainFloat' (default), 'double', 'single', 'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', or 'uint64'. If you specify an int or uint, the signedness and word length are that int or uint value and a fraction length is proposed. The default is remainFloat, which does not propose any data types.
-nocode	Do not display MATLAB code in the printable report. Display only the tables of logged variables. This option only has effect in combination with the -printable option.
-optimizeWholeNumbers	Optimize the word length of variables whose simulation min/max logs indicate that they are always whole numbers.
-percentSafetyMargin N	Safety margin for simulation min/max, where N is a percent value.
-printable	Create and open a printable HTML report. The report opens in the system browser.
-proposeFL	Propose fraction lengths for specified word lengths.
-proposeWL	Propose word lengths for specified fraction lengths.

Version History

Introduced in R2011b

R2018a: Redesigned code generation reports

The code generation report showInstrumentationResults has a new user interface.

Some benefits of the new interface are:

• Improved navigation. For example, if you double-click a variable in the MATLAB code, you see the variable in the Variables tab.

• Easier to use pop-up displays data type information in the showInstrumentationResults report. For example, you can pin the pop-up display to the report.

In R2018a, the reports are located in the same folders as in previous releases, but have a different file format. In previous releases, a report was saved with an HTML format and consisted of many files. In R2018a, a report is saved as one file with an .mldatx file extension. You can open a file with an .mldatx extension in MATLAB.

If you generate a report in R2018a, you cannot open it in a previous release. In R2018a, you can open reports that you generated in a previous release, but they look and behave as they did in that release.