| Stateflow® | |
| On this page… |
|---|
Types of Model Coverage in Embedded MATLAB™ Functions |
The Model Coverage tool reports model coverages for the decisions and conditions of Embedded MATLAB™ functions. For example, the Embedded MATLAB function if statement
if (x > 0 || y > 0) reset = 1;
contains a decision with two conditions (x > 0 and y > 0). You use the Model Coverage tool for Embedded MATLAB functions to make sure that all decisions and conditions are taken during simulation of the model.
For a description of model coverage for other Stateflow® objects, see Understanding Model Coverage for Stateflow® Charts.
Note The Model Coverage tool requires a Simulink® Verification and Validation™ software license. |
During simulation, these Embedded MATLAB function statements are tested for Decision Coverage:
function header — Decision coverage is 100% if the function or subfunction is executed.
if — Decision coverage is 100% if the if expression evaluates to true at least once and false at least once.
switch — Decision coverage is 100% if every switch case is taken, including the fall-through case.
for — Decision coverage is 100% if the equivalent loop condition evaluates to true at least once, and false at least once.
while — Decision coverage is 100% if the equivalent loop condition evaluates to true at least once, and false at least once.
During simulation, these logical conditions are tested for Condition Coverage and MCDC in the Embedded MATLAB function:
if statement conditions
while statement conditions, if present
In this topic, you examine an example model you can use to generate a model coverage report for two Embedded MATLAB functions. The following model is named intersecting_rectangles and contains a single Stateflow block with output data sent to a Scope block as shown.
The preceding Stateflow chart has a state with a default transition and entry and during actions. The state executes its entry action the first time that it is entered for the first time sample. Each succeeding time sample calls the during action of the active state.
The entry and during actions of state A call the Embedded MATLAB function run_intersect_test, which appears as follows in the Embedded MATLAB Editor:
run_intersect_test calls the function rect_intersect with two rectangle arguments that each consist of coordinates for the lower left corner of the rectangle (origin), and its width and height. The first rectangle is a test rectangle, and the second is a stationary rectangle. The coordinates for the origin of the test rectangle are represented by the Stateflow data x1 and y1, which are both initialized to -1. This means that x1 and y1 are 0 for the first sample. The progression of rectangle arguments during simulation is as follows:
In the preceding display, the stationary rectangle is shown in bold with a lower left origin of (2,4) and a width and height of 2. At time t = 0, the first test rectangle has an origin of (0,0) and a width and height of 2. For each succeeding sample, the origin of the test rectangle is incremented by (1,1). The rectangles at sample times t = 2, 3, and 4 intersect with the test rectangle.
The function rect_intersect, as shown, checks to see if two rectangles intersect.
rect_intersect receives the two rectangle arguments from run_intersect_test. It first calculates horizontal (x) coordinates for the left and right sides, and vertical (y) values for the top and bottom sides for each rectangle and compares them in the nested if-else decisions shown. The function returns a logical value of 1 if the rectangles intersect and 0 if they do not.
Scope output during simulation, which plots the return value against the sample time, confirms the intersecting rectangles for sample 2, 3, and 4.
Model coverage reports are generated during simulation if you specify them (see Making Model Coverage Reports). When simulation is finished, the model coverage report appears in a browser window. After the summary for the model, the Details section reports on each of the parts of the model. Model coverage for the parts of the example model in Creating a Model with Embedded MATLAB™ Function Decisions appears in the following order:
Model "intersecting_rectangles"
Subsystem "Chart"
Chart "Chart"
Function rect_intersect
#1: function out = rect_intersect(rect1,rect2)
#14: if (top1 < bottom2 || top2 < bottom1)
#17: if (right1 < left2 || right2 < left1
Function "run_intersect_test"
#1: function out = run_intersect_test
The reports for the Embedded MATLAB functions rect_intersect and run_intersect_test appear in alphabetical order as part of the report on their parent, the Stateflow block Chart. The reports on individual decisions for each function appear in numerical line order. Line numbers are indicated by the # character.
The following subtopics examine the model coverage report for the example model in reverse order of the report. Reversing the order helps you make sense of the summary information that appears at the top of each section.
Model coverage for the Embedded MATLAB function run_intersect_test, which sends test rectangles to the function rect_intersect, appears in the model coverage report as shown.
The report on run_intersect_test begins with the function name run_intersect_test, which links to an Embedded MATLAB Editor for the function. Following the name is a link to the model coverage report for the parent of run_intersect_test, the Stateflow chart Chart. Coverage continues with a summary of the coverage metrics for the function followed by a code listing. The line number for the first line of the listing is highlighted in bold red, which is actually a link to an analysis for that decision below.
The first line of every function receives coverage analysis indicative of the decision to run the function. Its coverage here indicates that the function run_intersect_test executed 8 out of 8 times for the samples taken at 0 through 7 seconds. Because this is the only decision in the function run_intersect_test, coverage for it in the metrics table above indicates the occurrence of 1 out of 1 possible outcomes. In this case, the only possible outcome is function execution. In other words, the function was executed during simulation.
Model coverage for the Embedded MATLAB function rect_intersect, which tests rectangles for intersection, appears first in the model coverage report as shown.
The coverage metrics for rect_intersect include Decision, Condition, and MCDC coverage. These metrics are best understood after you examine the coverage for the decisions in rect_intersect highlighted in the listing below.
The listing for rect_intersect includes three highlighted line numbers. The first line is highlighted as the decision on whether or not to execute the function. Highlighted line numbers 14 and 17 indicate decisions in a nested if-else statement. Notice that the condition right1 < left2 in line 17 is highlighted in red. This means that this condition did not test both the true and false possible outcomes for this decision during simulation. Exactly which of the outcomes was not tested is answered by the metrics for the decision in line 17. The metrics for line 17 and the remaining decisions appear below in numerical line order, and are accessed through the line number links in the listing.
Coverage for Line 1. Coverage metrics for line 1 appear directly below the listing for rect_intersect as shown.
The first line of every function receives coverage analysis indicative of the decision to run the function in response to a call. The preceding table indicates that rect_intersect executed. Coverage for this decision, which is equivalent to decision D1 in the metrics table for rect_intersect, is therefore 100%.
Coverage for Line 14. Coverage metrics for line 14 appear directly below the coverage metrics for line 1 as shown.
The Decisions analyzed table indicates that there are two possible outcomes for the decision in line 14: false and true. 5 of 8 times the decision evaluated false, and the remaining times (3) it evaluated true. Because both the true and false outcome occurred during simulation, Decision Coverage is 100%.
The following Conditions analyzed table sheds some light on the decision in line 14. Because this decision consists of two conditions linked by a logical or (||) operation, only one condition must evaluate true for the decision to be true. Also, if the first condition evaluates to true, there is no need to evaluate the second condition. The first condition, top1 < bottom2, was evaluated 8 times, and was true twice. This means it was necessary to evaluate the second condition only 6 times. In only one case was the second condition true, so that the total true occurrences for the decision equals 3, as reported in the Decisions analyzed table.
MCDC coverage looks for decision reversals that occur because one condition outcome changes from T to F or from F to T. The table identifies all possible combinations of outcomes for the conditions that lead to a reversal in the decision. The character x is used to indicate a condition outcome that is irrelevant to the decision reversal. Reversing condition outcomes that are not achieved during simulation are marked with a set of parentheses. There are no parentheses, so all decision reversing outcomes occurred, and MCDC Coverage is complete for this decision.
Coverage for rect_intersect Line 17. Coverage metrics for line 17 appear directly below the coverage metrics for line 14, as shown.
The line 17 decision if (right1 < left2 || right2 < left1) is nested in the if statement of the line 14 decision and is evaluated only if the line 14 decision is false. Because the line 14 decision evaluated false 5 times, line 17 is evaluated 5 times, 3 of which were false. Because both the true and false outcomes were achieved, Decision Coverage for line 17 is 100%.
Because line 17, like line 14, has two conditions related by a logical OR operator (||), condition 2 is tested only if condition 1 is false. Because condition 1 tests false 5 times, condition 2 is tested 5 times. Of these, condition 2 tests true 2 times and false 3 times, which accounts for the two occurrences of the true outcome for this decision.
Because the first condition of the line 17 decision does not test true, both outcomes did not occur for that condition, and the Condition Coverage for the first condition is highlighted with a rose color. Because the first condition of the line 17 decision does not test true, MCDC coverage is also highlighted in the same way for a decision reversal based on the true outcome for that condition.
Coverage for All rect_intersect Lines. Reviewing the coverage report for each line of rect_intersect in the previous topics makes sense of the coverage metrics reported at the beginning of the model coverage report for rect_intersect, which is as shown.
Based on the model coverage reports for each line of rect_intersect, you can draw these conclusions:
There are five decision outcomes reported for rect_intersect in the line reports: one for line 1 (execute), two for line 14 (true and false), and two for line 17 (true and false). The decision coverage for each line shows 100% coverage. This means that decision coverage for rect_intersect is 5 of 5, or 100%.
There are four conditions reported for rect_intersect in the line reports. Lines 14 and 17 each have two conditions, and each condition has two condition outcomes (true and false), for a total of eight condition outcomes in rect_intersect. All conditions tested for both the true and false outcome, except for the first condition of line 17 (right1 < left2). This means that condition coverage for rect_intersect is 7 of 8, or 88%.
The MCDC tables for each line list two cases of decision reversal for each condition. Only the decision reversal from changing the condition 1 outcome from true to false did not occur during simulation. This means that 3 of 4, or 75%, of the possible reversal cases were tested for during simulation. Therefore, only three of a possible four reversals were observed and coverage is 75%.
| Debugging an Embedded MATLAB™ Function | Working with Structures and Bus Signals in Embedded MATLAB™ Functions | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |