executioninfo

Retrieve execution coverage information from cvdata object

Syntax

covInfo = executioninfo(cvdo,modelObject)

covInfo = executioninfo(cvdo,modelObject,simMode)

covInfo = executioninfo(cvdo,modelObject,ignoreDescendants)

[covInfo,description]
= executioninfo(cvdo,modelObject)

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

Retrieve Execution Coverage Results for a Block

Open Script

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

Retrieve Statement and Function Coverage

Open Script

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 25.955s 

1 of 1 models built (0 models already up to date)
Build duration: 0h 0m 29.07s
### 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: 110
     startCol: 5
      endLine: 112
       endCol: 5

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

Input Arguments

collapse all

`cvdo` — Coverage data
`cvdata` object

Coverage data, specified as a cvdata object.

Data Types: cvdata

`modelObject` — Model object
`character array` | `string array` | `Simulink^® handle` | `Stateflow^® ID` | `cell array`

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 Specification	Description
`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 Specification	Description
`{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 Specification	Description
`{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

`simMode` — Simulation mode
`character array` | `string array`

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

Object Specification	Description
`"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

`ignoreDescendants` — Whether to ignore descendants in coverage results
`false` or `0` (default) | `true` or `1`

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

`covInfo` — Coverage information
scalar

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_outcomes`	Number of execution outcomes satisfied for `object`
`total_outcomes`	Number of execution outcomes for `object`

Data Types: double

`description` — Execution coverage description
structure

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

`isFiltered` — Block exclusion flag
`0` | `1`

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

Data Types: double

`filterRationale` — Block coverage filter rationale
`character array`

Block coverage filter rationale, returned as a character array.

Data Types: char

`justifiedCoverage` — Number of justified coverage objective outcomes
`scalar`

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

Data Types: double

`isJustified` — Block justification flag
`0` | `1`

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

Data Types: double

`decision` — Information for individual decisions
`structure array`

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

`text` — Block execution text
`'Block executed'`

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

`executionCount` — Number of time steps the model object executed
scalar double

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

Data Types: double

Data Types: struct

`function` — Function coverage information
`structure array`

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

`isFiltered` — Function exclusion flag
`0` | `1`

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

Data Types: double

`justifiedCoverage` — Number of justified coverage outcomes
`scalar`

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

Data Types: double

`isJustified` — Function justification flag
`0` | `1`

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

Data Types: double

`filterRationale` — Function coverage filter rationale
`[]` (default) | `character array`

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

`text` — Function coverage text
`'Function entry'`

Function coverage text, returned as 'Function entry'.

Data Types: char

`executionCount` — Execution count of function
`integer`

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

Data Types: int64

`fileName` — Name of file containing function
`character array`

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

Data Types: char

`functionName` — Name of analyzed function
`character array`

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

Data Types: char

`sourceLocation` — Location of analyzed function in source code
`structure array`

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

Field Name	Description	Datatype
`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

`modelElements` — Model elements that correspond to function
`character array`

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

`functionCall` — Function call coverage information
`structure array`

Function call coverage information, returned as a N_c structure arrays, where N_c 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:

`isFiltered` — Function call exclusion flag
`0` | `1`

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

Data Types: double

`justifiedCoverage` — Number of justified coverage outcomes
`scalar`

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

Data Types: double

`isJustified` — Function call outcome justification flag
`0` | `1`

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

Data Types: double

`filterRationale` — Function call coverage filter rationale
`[]` (default) | `character array`

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

`text` — Function call coverage text
`'Function called'`

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

Data Types: char

`executionCount` — Execution count of function call
`integer`

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

Data Types: int64

`fileName` — Name of file containing function call
`character array`

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

Data Types: char

`functionName` — Name of analyzed function call
`character array`

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

Data Types: char

`sourceLocation` — Location of analyzed function call in source code
`structure array`

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

Field Name	Description	Datatype
`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

`expression` — Function call expression
`character array`

Function call expression, returned as a character array.

Data Types: char

`modelElements` — Model element that corresponds to function call
`character array`

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

`executableStatement` — Statement coverage information
`structure array`

Statement coverage information, returned as N_s structure arrays, where N_s 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:

`isFiltered` — Statement exclusion flag
`0` | `1`

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

Data Types: double

`justifiedCoverage` — Number of justified statement outcomes
`scalar`

Number of justified statement outcomes, returned a scalar double.

Data Types: double

`isJustified` — Statement outcome justification flag
`0` | `1`

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

Data Types: double

`filterRationale` — Statement coverage filter rationale
`character array`

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

`text` — Statement coverage text
`'Statement executed'`

Statement coverage text, returned as 'Statement executed'.

Data Types: char

`executionCount` — Statement execution count
`scalar`

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

Data Types: int64

`fileName` — Name of file containing statement
`character array`

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

Data Types: char

`functionName` — Name of function containing statement
`character array`

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

Data Types: char

`sourceLocation` — Location of analyzed statement in source code
`structure array`

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

Field Name	Description	Datatype
`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

`kind` — Type of statement analyzed
`character array`

Type of statement analyzed, returned as a character array.

Example: 'stmt', 'if'

Data Types: char

`modelElements` — Model element that corresponds to statement
`character array`

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:

Open the model.
In the Model Editor, in the Modeling tab, select Model Settings.
On the Coverage pane of the Configuration Parameters dialog box, select Enable coverage analysis.
Under Coverage metrics, set Structural coverage level to Block Execution .
Click OK to close the Configuration Parameters dialog box and save your changes.
Simulate the model by clicking the Run button and review the results.

Version History

Introduced in R2006b

executioninfo

Syntax

Description

Examples

Retrieve Execution Coverage Results for a Block

Retrieve Statement and Function Coverage

Input Arguments

cvdo — Coverage data cvdata object

modelObject — Model object character array | string array | Simulink® handle | Stateflow® ID | cell array

simMode — Simulation mode character array | string array

ignoreDescendants — Whether to ignore descendants in coverage results false or 0 (default) | true or 1

Output Arguments

covInfo — Coverage information scalar

description — Execution coverage description structure

isFiltered — Block exclusion flag 0 | 1

filterRationale — Block coverage filter rationale character array

justifiedCoverage — Number of justified coverage objective outcomes scalar

isJustified — Block justification flag 0 | 1

decision — Information for individual decisions structure array

text — Block execution text 'Block executed'

executionCount — Number of time steps the model object executed scalar double

function — Function coverage information structure array

isFiltered — Function exclusion flag 0 | 1

justifiedCoverage — Number of justified coverage outcomes scalar

isJustified — Function justification flag 0 | 1

filterRationale — Function coverage filter rationale [] (default) | character array

text — Function coverage text 'Function entry'

executionCount — Execution count of function integer

fileName — Name of file containing function character array

functionName — Name of analyzed function character array

sourceLocation — Location of analyzed function in source code structure array

modelElements — Model elements that correspond to function character array

functionCall — Function call coverage information structure array

isFiltered — Function call exclusion flag 0 | 1

justifiedCoverage — Number of justified coverage outcomes scalar

isJustified — Function call outcome justification flag 0 | 1

filterRationale — Function call coverage filter rationale [] (default) | character array

text — Function call coverage text 'Function called'

executionCount — Execution count of function call integer

fileName — Name of file containing function call character array

functionName — Name of analyzed function call character array

sourceLocation — Location of analyzed function call in source code structure array

expression — Function call expression character array

modelElements — Model element that corresponds to function call character array

executableStatement — Statement coverage information structure array

isFiltered — Statement exclusion flag 0 | 1

justifiedCoverage — Number of justified statement outcomes scalar

isJustified — Statement outcome justification flag 0 | 1

filterRationale — Statement coverage filter rationale character array

text — Statement coverage text 'Statement executed'

executionCount — Statement execution count scalar

fileName — Name of file containing statement character array

functionName — Name of function containing statement character array

sourceLocation — Location of analyzed statement in source code structure array

kind — Type of statement analyzed character array

modelElements — Model element that corresponds to statement character array

Alternatives

Version History

See Also

Topics

`cvdo` — Coverage data
`cvdata` object

`modelObject` — Model object
`character array` | `string array` | `Simulink^® handle` | `Stateflow^® ID` | `cell array`

`simMode` — Simulation mode
`character array` | `string array`

`ignoreDescendants` — Whether to ignore descendants in coverage results
`false` or `0` (default) | `true` or `1`

`covInfo` — Coverage information
scalar

`description` — Execution coverage description
structure

`isFiltered` — Block exclusion flag
`0` | `1`

`filterRationale` — Block coverage filter rationale
`character array`

`justifiedCoverage` — Number of justified coverage objective outcomes
`scalar`

`isJustified` — Block justification flag
`0` | `1`

`decision` — Information for individual decisions
`structure array`

`text` — Block execution text
`'Block executed'`

`executionCount` — Number of time steps the model object executed
scalar double

`function` — Function coverage information
`structure array`

`isFiltered` — Function exclusion flag
`0` | `1`

`justifiedCoverage` — Number of justified coverage outcomes
`scalar`

`isJustified` — Function justification flag
`0` | `1`

`filterRationale` — Function coverage filter rationale
`[]` (default) | `character array`

`text` — Function coverage text
`'Function entry'`

`executionCount` — Execution count of function
`integer`

`fileName` — Name of file containing function
`character array`

`functionName` — Name of analyzed function
`character array`

`sourceLocation` — Location of analyzed function in source code
`structure array`

`modelElements` — Model elements that correspond to function
`character array`

`functionCall` — Function call coverage information
`structure array`

`isFiltered` — Function call exclusion flag
`0` | `1`

`justifiedCoverage` — Number of justified coverage outcomes
`scalar`

`isJustified` — Function call outcome justification flag
`0` | `1`

`filterRationale` — Function call coverage filter rationale
`[]` (default) | `character array`

`text` — Function call coverage text
`'Function called'`

`executionCount` — Execution count of function call
`integer`

`fileName` — Name of file containing function call
`character array`

`functionName` — Name of analyzed function call
`character array`

`sourceLocation` — Location of analyzed function call in source code
`structure array`

`expression` — Function call expression
`character array`

`modelElements` — Model element that corresponds to function call
`character array`

`executableStatement` — Statement coverage information
`structure array`

`isFiltered` — Statement exclusion flag
`0` | `1`

`justifiedCoverage` — Number of justified statement outcomes
`scalar`

`isJustified` — Statement outcome justification flag
`0` | `1`

`filterRationale` — Statement coverage filter rationale
`character array`

`text` — Statement coverage text
`'Statement executed'`

`executionCount` — Statement execution count
`scalar`

`fileName` — Name of file containing statement
`character array`

`functionName` — Name of function containing statement
`character array`

`sourceLocation` — Location of analyzed statement in source code
`structure array`

`kind` — Type of statement analyzed
`character array`

`modelElements` — Model element that corresponds to statement
`character array`