Main Content

executioninfo

Retrieve execution coverage information from cvdata object

Description

covInfo = executioninfo(cvdo,modelObject) returns execution coverage results from the cvdata object cvdo for the model component specified by modelObject. If cvdo contains code coverage data, executioninfo returns the sum of statement coverage, function coverage, and function call coverage metrics.

covInfo = executioninfo(cvdo,modelObject,simMode) returns execution coverage results for the simulation mode simMode.

covInfo = executioninfo(cvdo,modelObject,ignoreDescendants) returns execution coverage results for modelObject with or without its descendants, depending on the value of ignoreDescendants.

[covInfo,description] = executioninfo(cvdo,modelObject) returns description structure arrays for each execution point associated with modelObject. If cvdo contains coverage data for the code coverage metrics statement coverage, function coverage, or function call coverage, description contains structure arrays for each relevant metric.

example

Examples

collapse all

This example shows how to extract execution coverage results for a block from a cvdata object.

Load the slvnvdemo_cv_small_controller model.

modelName = "slvnvdemo_cv_small_controller";
load_system(modelName)

Configure the coverage settings for the model by using a Simulink.SimulationInput object.

simIn = Simulink.SimulationInput(modelName);
simIn = setModelParameter(simIn,"CovEnable","on");
simIn = setModelParameter(simIn,"CovMetricStructuralLevel",...
                                "BlockExecution");
simIn = setModelParameter(simIn,"CovSaveSingleToWorkspaceVar","on");
simIn = setModelParameter(simIn,"CovSaveName","covData");

Simulate the model by passing simIn as the input to sim.

simOut = sim(simIn);
covData = simOut.covData;

Retrieve the handle for the Saturation block by using get_param.

blockHandle = get_param(modelName+"/Saturation","Handle");

Extract the execution coverage information by using executioninfo.

executionCov = executioninfo(covData,blockHandle)
executionCov =

     1     1

Compute the percentage of execution outcomes satisfied.

percentCoverage = 100*executionCov(1) / executionCov(2)
percentCoverage =

   100

This example shows how to extract statement, function, and function call coverage for a model simulated in software-in-the-loop (SIL) mode.

Load the model.

modelName = "SILTopModel";
load_system(modelName);

Configure the coverage settings for the model by using a Simulink.SimulationInput object.

simIn = Simulink.SimulationInput(modelName);
simIn = setModelParameter(simIn,"CovEnable","on");
simIn = setModelParameter(simIn,"CovMetricStructuralLevel","MCDC");
simIn = setModelParameter(simIn,"CovSaveSingleToWorkspaceVar","on");
simIn = setModelParameter(simIn,"CovSaveName","covData");
simIn = setModelParameter(simIn,"SimulationMode","software-in-the-loop (sil)");

Simulate the model by passing simIn as the input to sim.

simOut = sim(simIn);
covDataSIL = simOut.covData;
### Starting build procedure for: SILTopModel
### Successful completion of build procedure for: SILTopModel

Build Summary

Top model targets:

Model        Build Reason                                         Status                        Build Duration
==============================================================================================================
SILTopModel  Information cache folder or artifacts were missing.  Code generated and compiled.  0h 0m 30.848s 

1 of 1 models built (0 models already up to date)
Build duration: 0h 0m 34.496s
### Preparing to start SIL simulation ...
Building with 'gcc'.
MEX completed successfully.
### Updating code generation report with SIL files ...
### Starting SIL simulation for component: SILTopModel
### Application stopped
### Stopping SIL simulation for component: SILTopModel
### Completed code coverage analysis

Pass covDataSIL and the file name SILTopModel.c as inputs to executioninfo.

[covMetricsSIL,covMetricsSILdesc] = executioninfo(covDataSIL,"SILTopModel.c")
covMetricsSIL =

    21    24


covMetricsSILdesc = 

  struct with fields:

             isFiltered: 0
      justifiedCoverage: 0
            isJustified: 0
        filterRationale: ''
               function: [1x6 struct]
           functionCall: [1x4 struct]
    executableStatement: [1x18 struct]
               decision: [1x24 struct]

When you analyze coverage on a model in SIL mode, executioninfo returns the data for these code coverage metrics:

  • Statement coverage

  • Function coverage

  • Function call coverage

covMetricsSIL, the first output argument, contains two values: the total satisfied code coverage objectives and the total number of code coverage objectives. Determine the percentage of satisfied statement, function, and function call coverage by dividing the numbers.

percentCodeCov = 100 * covMetricsSIL(1) / covMetricsSIL(2)
percentCodeCov =

   87.5000

To retrieve the details about the individual metrics, use the second output argument, covMetricsSILdesc. The analyzed code is missing coverage for three statements. To determine which statements are missing coverage, you can search for which fields of the statement coverage description object have an execution count of zero.

execCounts = [covMetricsSILdesc.executableStatement.executionCount];
missingCovIdxs = execCounts == 0;
missingCov = covMetricsSILdesc.executableStatement(missingCovIdxs);

The missingCov array contains the location of the three missing statement objectives in the structure array. Look at the structure for the first missing statement.

disp(missingCov(1))
           isFiltered: 0
    justifiedCoverage: 0
          isJustified: 0
      filterRationale: ''
                 text: 'Statement executed'
       executionCount: 0
             fileName: 'SILTopModel.c'
         functionName: 'CounterTypeB'
       sourceLocation: [1x1 struct]
                 kind: 'if'
        modelElements: {1x2 cell}

You can see that it is an if statement located in the function counterTypeB, which is in the file SILTopModel.c. Look at its sourceLocation field, to see the exact line numbers that represent the missing statement objective.

disp(missingCov(1).sourceLocation)
    startLine: 113
     startCol: 5
      endLine: 115
       endCol: 5

In SILTopModel.c, lines 114 through 116 are missing statement coverage.

Input Arguments

collapse all

Coverage data, specified as a cvdata object.

Data Types: cvdata

Model object, specified as a character array, string array, Simulink handle, Stateflow ID, or cell array.

To specify a model object, such as a block or a Stateflow chart, use one of these formats:

Object SpecificationDescription

BlockPath

Full path to a model or block

BlockHandle

Handle to a model or block

slObj

Handle to a Simulink API object

sfID

Stateflow ID

sfObj

Handle to a Stateflow API object from a singly instantiated Stateflow chart

{BlockPath, sfID}

Cell array with the path to a Stateflow chart or atomic subchart and the ID of an object contained in that chart or subchart

{BlockPath, sfObj}

Cell array with the path to a Stateflow chart or subchart and a Stateflow object API handle contained in that chart or subchart

{BlockHandle, sfID}

Cell array with a handle to a Stateflow chart or atomic subchart and the ID of an object contained in that chart or subchart

To specify an S-Function block or its contents, use one of these formats:

Object SpecificationDescription

{BlockPath, fName}

Cell array with the path to an S-Function block and the name of a source file

{BlockHandle, fName}

Cell array with an S-Function block handle and the name of a source file

{BlockPath, fName, funName}

Cell array with the path to an S-Function block, the name of a source file, and a function name

{BlockHandle, fName, funName}

Cell array with an S-Function block handle, the name of a source file, and a function name

To specify a code coverage result, such as coverage data collected during software-in-the-loop (SIL) or processor-in-the-loop (PIL) analysis, use one of these formats:

Object SpecificationDescription

{fileName, funName}

Cell array with the name of a source file and a function name

{Model, fileName}

Cell array with a model name or model handle and the name of a source file

{Model, fileName, funName}

Cell array with a model name or model handle, the name of a source file, and a function name

Data Types: char | string | cell | Stateflow.State | Stateflow.Transition

Simulation mode during coverage analysis, specified as one of these options:

Object SpecificationDescription

"Normal"

Model in normal simulation mode.

"SIL" or "PIL"

Model in software-in-the-loop (SIL) or processor-in-the-loop (PIL) simulation mode.

"ModelRefSIL" or "ModelRefPIL"

Model reference in SIL or PIL simulation mode.

"ModelRefTopSIL" or "ModelRefTopPIL"

Model reference in SIL or PIL simulation mode with the code interface set to top model.

Data Types: char | string

Whether to ignore descendants in coverage results, specified as a numeric or logical 1 (true) or 0 (false), where:

  • 0 (false) includes coverage results of descendant objects.

  • 1 (true) ignores coverage results of descendant objects.

Data Types: single | double | logical

Output Arguments

collapse all

Coverage information, returned as a two-element scalar array of the form [covered_outcomes,total_outcomes] if cvdo contains execution coverage data, or an empty array if it does not. The elements in the array are:

covered_outcomesNumber of execution outcomes satisfied for object
total_outcomesNumber of execution outcomes for object

Data Types: double

Execution coverage description, returned as a structure with these fields:

Block exclusion flag, returned as 1 if the block is excluded and 0 if it is not.

Data Types: double

Block coverage filter rationale, returned as a character array.

Data Types: char

Number of justified coverage objective outcomes, returned as a scalar double.

Data Types: double

Block justification flag, returned as 1 if the block is justified or 0 if it is not.

Data Types: double

Information for individual decisions, returned as a structure array with these fields:

Block execution text, returned as the character array 'Block executed'. The text field does not change even if the block has 0% execution coverage.

Data Types: char

Number of time steps the model object executed, returned as a scalar double.

Data Types: double

Data Types: struct

Function coverage information, returned as Nf structure arrays, where Nf is the number of functions analyzed. function appears when cvdo contains code coverage data for the function coverage metric. Each structure contains these fields:

Function exclusion flag, returned as 1 if the function is excluded and 0 if it is not.

Data Types: double

Number of justified coverage outcomes, returned as a scalar double.

Data Types: double

Function justification flag, returned as 1 if the function is justified and 0 if it is not.

Data Types: double

Function coverage filter rationale, returned as a character array. If the function is not filtered or the filter rationale is not set, filterRationale returns an empty array.

Data Types: char

Function coverage text, returned as 'Function entry'.

Data Types: char

Execution count of the function, returned as a 64-bit integer.

Data Types: int64

Name of the file containing the function, returned as a character array.

Data Types: char

Name of the analyzed function, returned as a character array.

Data Types: char

Location of the analyzed function in the source code, returned as a structure array with these fields:

Field NameDescriptionDatatype

startLine

Line of the source code where the function begins

int64

startCol

Column of the source code where the function begins

int64

endLine

Line of the source code where the function ends

int64

endCol

Column of the source code where the function ends

int64

Data Types: struct

Model elements that correspond to the function, returned as a character array. The modelElements field appears when you analyze a model in SIL or PIL mode.

Data Types: char

Data Types: struct

Function call coverage information, returned as a Nc structure arrays, where Nc is the number of function calls analyzed. functionCall appears when cvdo contains code coverage data for the function call coverage metric. Each structure contains these fields:

Function call exclusion flag, returned as 1 if the function call is excluded and 0 if it is not.

Data Types: double

Number of justified coverage outcomes, returned as a scalar double.

Data Types: double

Function call outcome justification flag, returned as 1 if the function call outcome is justified and 0 if it is not.

Data Types: double

Function call coverage filter rationale, returned as a character array. If the function call is not filtered or the filter rationale is not set, filterRationale returns an empty array.

Data Types: char

Function call coverage text, returned as 'Function called'.

Data Types: char

Execution count of the function call, returned as a 64-bit integer.

Data Types: int64

Name of the file containing the function call, returned as a character array.

Data Types: char

Name of the analyzed function call, returned as a character array.

Data Types: char

Location of the analyzed function call in the source code, returned as a structure array with these fields:

Field NameDescriptionDatatype

startLine

Line of the source code where the function call begins

int64

startCol

Column of the source code where the function call begins

int64

endLine

Line of the source code where the function call ends

int64

endCol

Column of the source code where the function call ends

int64

Data Types: struct

Function call expression, returned as a character array.

Data Types: char

Model element that corresponds to the function call, returned as a character array. The modelElements field appears when you analyze a model in SIL or PIL mode.

Data Types: char

Data Types: struct

Statement coverage information, returned as Ns structure arrays, where Ns is the number of executable statements. executableStatement appears when cvdo contains code coverage data for the statement coverage metric. Each structure array contains these fields:

Statement exclusion flag, returned as 1 if the statement is excluded and 0 if it is not.

Data Types: double

Number of justified statement outcomes, returned a scalar double.

Data Types: double

Statement outcome justification flag, returned as 1 if the statement outcome is justified and 0 if it is not.

Data Types: double

Statement coverage filter rationale, returned as a character array. If the statement is not filtered or the filter rationale is not set, filterRationale returns an empty array.

Data Types: char

Statement coverage text, returned as 'Statement executed'.

Data Types: char

Statement execution count, returned as a 64-bit integer.

Data Types: int64

Name of the file containing the statement, returned as a character array.

Data Types: char

Name of the function containing the statement, returned as a character array.

Data Types: char

Location of the analyzed statement in the source code, returned as a structure array with these fields:

Field NameDescriptionDatatype

startLine

Line of the source code where the statement begins

int64

startCol

Column of the source code where the statement begins

int64

endLine

Line of the source code where the statement ends

int64

endCol

Column of the source code where the statement ends

int64

Data Types: struct

Type of statement analyzed, returned as a character array.

Example: 'stmt', 'if'

Data Types: char

Model element that corresponds to the statement, returned as a character array. The modelElements field appears when you analyze a model in SIL or PIL mode.

Data Types: char

Data Types: struct

Alternatives

Use the coverage settings to collect and display execution coverage results:

  1. Open the model.

  2. In the Model Editor, in the Modeling tab, select Model Settings.

  3. On the Coverage pane of the Configuration Parameters dialog box, select Enable coverage analysis.

  4. Under Coverage metrics, set Structural coverage level to Block Execution .

  5. Click OK to close the Configuration Parameters dialog box and save your changes.

  6. Simulate the model by clicking the Run button and review the results.

Version History

Introduced in R2006b