relationalboundaryinfo

R2026b

Retrieve relational boundary coverage from cvdata object

Syntax

covInfo = relationalboundaryinfo(cvdo,modelObject)

covInfo = relationalboundaryinfo(cvdo,modelObject,simMode)

covInfo = relationalboundaryinfo(cvdo,modelObject,ignoreDescendants)

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

Description

covInfo = relationalboundaryinfo(cvdo,modelObject) returns relational boundary coverage results from the cvdata object cvdo for the model object specified by object and its descendants.

covInfo = relationalboundaryinfo(cvdo,modelObject,simMode) returns relational boundary coverage results from the cvdata object cvdo for the model object specified by modelObject and its descendants for the simulation mode simMode.

covInfo = relationalboundaryinfo(cvdo,modelObject,ignoreDescendants) returns relational boundary coverage results from the cvdata object cvdo for the model object specified by modelObject and, depending on the value of ignoreDescendants, descendant objects.

[covInfo,description] = relationalboundaryinfo(cvdo,modelObject) returns the relational boundary coverage results and textual descriptions of each coverage outcome in modelObject in description. The textual descriptions exclude descendants.

Examples

Collect Relational Boundary Coverage for Supported Block in Model

This example shows how to collect relational boundary coverage information for a Saturation block in a model. For more information on blocks supported for relational boundary coverage, see Model Objects That Receive Coverage.

Open the slvnvdemo_cv_small_controller model. Create a model coverage test specification object for the model.

openExample('slvnvdemo_cv_small_controller');
open_system('slvnvdemo_cv_small_controller');
testObj = cvtest('slvnvdemo_cv_small_controller');

In the model coverage test specification object, activate relational boundary coverage.

testObj.settings.relationalop = 1;

Simulate the model and collect coverage results in a cvdata object.

dataObj = cvsim(testObj);

Obtain relational boundary coverage results for the Saturation block in slvnvdemo_cv_small_controller. The coverage results are stored in a two-element vector of the form [covered_outcomes total_outcomes].

blockHandle = get_param('slvnvdemo_cv_small_controller/Saturation','Handle');
[covResults,covDesc] = relationalboundaryinfo(dataObj,blockHandle)

covResults =

     2     4


covDesc = 

    isFiltered: 0
      decision: [1x2 struct]

The field decision is a 1 X 2 structure. Each element of decision corresponds to a relational operation in the block. The Saturation block contains two comparisons. The first comparison is with a lower limit and the second with an upper limit. Therefore, decision is a 2-element structure.

View the first operation in the block that receives relational boundary coverage. For the Saturation block, the first relational operation is input > lowerlimit.

covDesc.decision(1)

ans = 

            outcome: [1x2 struct]
               text: 'input - lowerlimit'
         isFiltered: 0
    filterRationale: ''

The text field shows the two operands. The isFiltered field is set to 1 if the block is filtered from relational boundary coverage. For more information, see Coverage Filtering.

View results for the first relational operation in the block.

for(i=1:2)
  covDesc.decision(1).outcome(i)
end

ans = 

     isActive: 1
    execCount: 0
         text: '[-tol..0]'


ans = 

     isActive: 1
    execCount: 0
         text: '(0..tol]'

View the second operation in the block that receives relational boundary coverage. For the Saturation block, the second relational operation is input < upperlimit.

covDesc.decision(2)

ans = 

            outcome: [1x2 struct]
               text: 'input - upperlimit'
         isFiltered: 0
    filterRationale: ''

View results for the second relational operation in the block.

for(i=1:2)
  covDesc.decision(2).outcome(i)
end

ans = 

     isActive: 1
    execCount: 1
         text: '[-tol..0)'


ans = 

     isActive: 1
    execCount: 2
         text: '[0..tol]'

Extract Relational Boundary Coverage Results from a Model in Software-in-the-Loop Mode

In this example, you analyze code coverage for a model in software-in-the-loop mode and extract the relational boundary coverage results.

Open the example and load the model.

openExample("slcoverage/RetrieveCodeCoverageResultsExample");

Use the setupSILCoverage helper function to configure the model for code coverage analysis. The output is a Simulink.SimulationInput object.

simIn = setupSILCoverage("slvnvdemo_counter_harness");

Simulate the model.

simOut = sim(simIn);

To retrieve coverage results for the generated code that represents a specific block, use the block path. For example, retrieve the relational boundary coverage results for the Relational Operator block named upper GE input by passing the block path relative to the top model.

covDataSIL = simOut.covdata;
relboundBlockSIL = relationalboundaryinfo(covDataSIL,...
                                     "slvnvdemo_counter/upper GE input")

    
    relboundBlockSIL =
    
         2     2

To retrieve coverage results for a function in the generated code, use a cell array that contains the generated source file name and function name. For example, retrieve the relational boundary coverage results for the function slvnvdemo_counter located in the source file slvnvdemo_counter.c.

relboundSILFunction = relationalboundaryinfo(covDataSIL,...
                        {"slvnvdemo_counter.c","slvnvdemo_counter"})

    relboundSILFunction =
    
         3     4

Extract Relational Boundary Code Coverage Results from an S-Function Block

In this example, you analyze coverage for a model and extract the relational boundary coverage results for the S-Function counterbusFcn.

Open the example, load the model, and load data into the workspace.

openExample("slcoverage/RetrieveSFunCoverageResultsExample");
load slcoverage_lct_data.mat

Use the setupSFcnCoverage helper function to configure the model for coverage analysis. The output is a Simulink.SimulationInput object.

simIn = setupSFcnCoverage("slcoverage_lct_bus");

Simulate the model.

simOut = sim(simIn);

To retrieve coverage results for an S-function, use the relationalboundaryinfo function and specify a cell array that contains the handle or full path of the block, followed by the file name of the S-function source file. Optionally, you can also specify a specific function inside that source file. For this example, retrieve the relational boundary coverage results for the function named counterbusFcn in the S-function file counterbus.c, which the S-Function block slcoverage_sfun_counterbus calls. The S-Function block is inside the TestCounter subsystem in the model slcoverage_lct_bus.

covDataSFcn = simOut.covdata;
relboundSFun = relationalboundaryinfo(covDataSFcn,...
    {"slcoverage_lct_bus/TestCounter/slcoverage_sfun_counterbus",...
    "counterbus.c","counterbusFcn"})

    
    relboundSFun =
    
         4     6

Input Arguments

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

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
"Accelerator"	Model in accelerator 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 — Option to ignore descendants in coverage results

false or 0 (default) | true or 1

Option to ignore descendants in coverage results, specified as one of these values:

• 0 or false – includes coverage results of descendant objects.

• 1 or true – ignores coverage results of descendant objects.

Data Types: single | double | logical

Output Arguments

covInfo — Coverage information

scalar | []

Coverage information for modelObject and its descendants, returned as an array of the form [covered_outcomes, total_outcomes] if cvdo contains relational boundary coverage data, or an empty array if it does not.

covered_outcomes	Number of relational boundary outcomes satisfied plus number of justified outcomes for modelObject.
total_outcomes	Number of total relational boundary outcomes minus number of excluded outcomes for modelObject.

To exclude descendants from covInfo, use the ignoreDescendants input argument.

Data Types: double

description — Textual description of coverage outcomes

structure array

Textual description of coverage outcomes for modelObject, excluding its descendants, returned as a structure array. Depending on the types of model coverage collected, the structure array can have different fields. If only relational boundary coverage is collected, the structure array contains these fields:

isFiltered	0 if the model component specified by object is not excluded from coverage recording. 1 if the model component specified by object is excluded from coverage recording. For more information about excluding objects from coverage, see Coverage Filtering.
decision.text	Character vector or string of the form: op_1-op_2 op_1 is the left operand in the relational operation. op_2 is the right operand in the relational operation.
decision.outcome	Structure array containing two fields for each coverage outcome: isActive Boolean variable. If this variable is false, it indicates that decisions were not evaluated during simulation due to variable signal size. execCount Number of times op_1-op_2 fell in the range described by text text The range around the relational boundary considered for coverage. For more information, see Relational Boundary.
decision.isFiltered	0 if the model component specified by object is not excluded from coverage recording. 1 if the model component specified by object is excluded from coverage recording. For more information about excluding objects from coverage, see Coverage Filtering.
decision.filterRationale	Rationale for filtering the model component specified by object, if object is excluded from coverage and a rationale is specified. For more information about excluding objects from coverage, see Coverage Filtering.

Data Types: struct

Limitations

Even though the relationalboundaryinfo function supports "Accelerator" as the simMode argument, it does not return results because Simulink Coverage™ does not support collecting relational boundary coverage in accelerator mode.

Version History

Introduced in R2014b