executioninfo - Retrieve execution coverage information from cvdata
object - MATLAB ([original](https://in.mathworks.com/help/slcoverage/ref/executioninfo.html)) ([raw](?raw))
Retrieve execution coverage information from cvdata
object
Syntax
Description
[covInfo](#bviney2-1-coverage) = executioninfo([cvdo](#bviney2-1%5Fsep%5Fbrxo2jj-1-cvdo),[modelObject](#bviney2-1%5Fsep%5Fbswieqq-1-object))
returns execution coverage results from the cvdata
objectcvdo
for the model component specified bymodelObject
. If cvdo
contains code coverage data, executioninfo
returns the sum of statement coverage, function coverage, and function call coverage metrics.
[covInfo](#bviney2-1-coverage) = executioninfo([cvdo](#bviney2-1%5Fsep%5Fbrxo2jj-1-cvdo),[modelObject](#bviney2-1%5Fsep%5Fbswieqq-1-object),[simMode](#bviney2-1%5Fsep%5Fbswieqq-1-mode))
returns execution coverage results for the simulation modesimMode
.
[covInfo](#bviney2-1-coverage) = executioninfo([cvdo](#bviney2-1%5Fsep%5Fbrxo2jj-1-cvdo),[modelObject](#bviney2-1%5Fsep%5Fbswieqq-1-object),[ignoreDescendants](#bviney2-1%5Fsep%5Fmw%5Ffeb2a172-08b8-4e3b-b2bb-6c8d51d75f21))
returns execution coverage results for modelObject
with or without its descendants, depending on the value ofignoreDescendants
.
[[covInfo](#bviney2-1-coverage),[description](#bviney2-1-description)] = executioninfo([cvdo](#bviney2-1%5Fsep%5Fbrxo2jj-1-cvdo),[modelObject](#bviney2-1%5Fsep%5Fbswieqq-1-object))
returns description structure arrays for each execution point associated withmodelObject
. 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.
Examples
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)
Compute the percentage of execution outcomes satisfied.
percentCoverage = 100*executionCov(1) / executionCov(2)
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;
Searching for referenced models in model 'SILTopModel'.
Total of 1 models to build.
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 24.491s
1 of 1 models built (0 models already up to date) Build duration: 0h 0m 25.861s
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: [1×6 struct]
functionCall: [1×4 struct]
executableStatement: [1×18 struct]
decision: [1×24 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)
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.
isFiltered: 0
justifiedCoverage: 0
isJustified: 0
filterRationale: ''
text: 'Statement executed'
executionCount: 0
fileName: 'SILTopModel.c'
functionName: 'CounterTypeB'
sourceLocation: [1×1 struct]
kind: 'if'
modelElements: {1×2 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
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 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,fileName} | Cell array with the path to an S-Function block and the name of a source file |
{BlockHandle,fileName} | Cell array with an S-Function block handle and the name of a source file |
{BlockPath,fileName,functionName} | Cell array with the path to an S-Function block, the name of a source file, and a function name |
{BlockHandle,fileName,functionName} | 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,functionName} | 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,functionName} | 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 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
Whether to ignore descendants in coverage results, specified as a numeric or logical1 (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
Coverage information, returned as a two-element scalar array of the form[covered_outcomes,total_outcomes]
ifcvdo 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 forobject |
---|---|
total_outcomes | Number of execution outcomes forobject |
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'
. Thetext
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 whencvdo contains code coverage data for the function coverage metric. Each structure contains these fields:
Function exclusion flag, returned as1
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 as1
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 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
Model elements that correspond to the function, returned as a character array. ThemodelElements 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 whencvdo
contains code coverage data for the function call coverage metric. Each structure contains these fields:
Function call exclusion flag, returned as1
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 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
Function call expression, returned as a character array.
Data Types: char
Model element that corresponds to the function call, returned as a character array. ThemodelElements
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 as1
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 as1
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 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
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. ThemodelElements
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, selectModel 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