18. Reactis for EML Plugin#
The V2015 release of Reactis included a new product the Reactis for EML Plugin, which integrates with Reactis to offer white-box testing of the Embedded MATLAB (EML) portions of a model. When using the plugin, Reactis Tester will generate tests which attempt to exercise targets in EML code and Reactis Simulator will track and display the coverage status of EML code. The V2016 release of Reactis extends Simulator functionality to include basic debugging of EML code, including breakpoints, single-stepping, and the ability to view variable values.
Note that if not using the Reactis for EML Plugin, you can still test models with EML code, but the EML portions of a model will be treated as block boxes. They will be executed but coverage within EML code not be tracked or targeted by generated tests, and EML code will not be visible within Reactis Simulator.
EML can be introduced into a model in several ways:
Simulink
MATLAB Function block
Truth Table block
Stateflow
MATLAB functions
Truth Table functions with MATLAB language option
Note that a subset of the full Embedded MATLAB language is supported. To use models containing EML in Reactis, your model must only use the language subset supported by Reactis. Note that the same language restrictions apply no matter which of the four model constructs listed above are used to incorporate EML into your model. To avoid confusion we use the following abbreviations in the following discussion:
- Embedded MATLAB (EML)
the subset of MATLAB supported by MathWorks for code generation.
- Reactis Embedded MATLAB (REML)
the subset of EML supported by Reactis.
REML is under active development toward the ultimate goal of supporting a very large subset of EML. Please send requests to Reactive Systems (help@reactive-systems.com) if there are unsupported EML features you would like use.
Whether in white-box or black-box mode for EML, Reactis supports the same subset of EML. This subset is defined in the Subset of Embedded MATLAB Supported by Reactis section.
18.1. Enabling the Reactis for EML Plugin#
Enable the plugin by selecting File > Global Settings…, selecting the Reactis for EML tab, and then in the resulting dialog (Figure 18.1) select Enable white-box analysis of Embedded MATLAB code (requires license for EML Plugin).
The other controls in this tab let you toggle the display of line numbers in the main panel, set the background color of the line number bar, and toggle and set the color for drawing a grid (alternating the background color of each line) in the main panel.
As shown in Figure 18.2, after enabling the EML Plugin, the EML code contained in a model element will be displayed in the Reactis main panel when the element is selected in the hierarchy panel. Since Simulink stores the EML code within the model’s .slx file, no special configuration is required within Reactis. Reactis automatically extracts the EML code from the .slx file. If this EML code from the .slx file calls external functions residing outside the .slx file in separate .m files, then the external functions should be identified within Reactis as described in the External EML Functions section.
18.2. External EML Functions#
Simulink supports calling functions stored in .m files external to a model. To call such a function from a MATLAB Function block (or any EML embedded in the model e.g. Stateflow, Truth Tables, etc.) the .m file must reside in a folder which is included in the MATLAB path.
Reactis also supports external EML functions, but you must identify the .m files containing external functions called from your model. You enumerate the external EML functions from the External EML Functions pane of the Reactis Info File Editor (Opened by selecting Edit > External EML Functions from the Reactis main window). After you list the functions here, Reactis lists them in the External EML Functions section of the hierarchy panel as shown in Figure 18.3. Additionally, Reactis will identify coverage targets withing the external functions, attempt to exercise those targets when generating tests, and allow you to step into the external functions when executing your model in Reactis Simulator.
18.3. EML Coverage Metrics#
Reactis uses a number of different coverage metrics to measure how thoroughly a test or set of tests exercises a model. In general, coverage metrics record how many of a given class of coverage targets (model features such as Stateflow states, EML program statements, etc.) have been executed at least once. Coverage metrics may be visualized using Simulator and are central to test generation and model validation using Tester and Validator.
The Reactis Coverage Metrics chapter describes the coverage metrics that are tracked within the Simulink and Stateflow portions of models. Those metrics include some which are specific to Simulink, some which appear only in Stateflow, and others which are generic and can appear in either Simulink or Stateflow. Four of the generic metrics are also tracked in the EML code portions of models by the Reactis for EML Plugin. These are decision coverage, condition coverage, multiple condition coverage (MCC), and modified condition / decision coverage (MC/DC).
Decision coverage tracks whether each decision in a program has evaluated to both true and false. The program elements that the Reactis for EML Plugin identifies as decisions are the conditional expressions in if statements and while loops.
Condition coverage tracks whether each condition (atomic Boolean expression) in a decision has evaluated to both true and false.
For the definition of MC/DC and MCC coverage, please see the Reactis Coverage Metrics chapter.
Finally, in addition to these generic coverage metrics, the Reactis for EML Plugin also tracks statement coverage - whether or not each EML statement has been executed at least once.
18.3.1. Tracking Coverage in EML Code#
In Reactis Simulator, when Coverage > Show Details is selected, unexercised coverage targets in EML code are reported visually as shown in Figure 18.4. Any unexecuted EML statement is rendered in red. If a decision has not evaluated to true it has a thin red overline. If a decision has not evaluated to false it has a thin red underline. If a condition has not evaluated to true it has a thick red overline. If a condition has not evaluated to false it has a thick red underline. If a decision has not met the MC/DC criteria, then the text of the decision is displayed in red. The MC/DC and MCC-related coverage details associated with a decision (Figure 18.5) may be displayed by right clicking on the decision and selecting View Coverage Details. For a description of this dialog, please see the Reactis Coverage Metrics chapter.
Lines containing unexercised targets are distinguished by a a thin red bar which is drawn just to the right of the line number of that line.
18.3.2. Debugging EML Code#
When the EML Plugin is enabled, Simulator will step seamlessly into EML code, as shown in Figure 18.6. The numbered items in Figure 18.6 are the primary debugging operations supported by Simulator. These operations are:
Breakpoints. A breakpoint may be toggled on lines within EML code which contain an executable statement by double-clicking on the line number, or by right-clicking on the line number and selecting Toggle Breakpoint.
Single Stepping. EML code may be stepped through one statement at a time by clicking on the mini-step button or by selecting Simulate > Step Into.
Hovering. When execution is paused within EML code, hovering on a variable causes the value of the variable to be displayed. If execution has not yet passed the point where the variable was initialized, no value is displayed.
When execution is stopped between simulation steps, hovering on a coverage target in EML code causes the coverage status to be displayed.
Watched Variables. When execution is paused within EML code and a variable is active, the variable may be added to the watched variable panel by right clicking on the name of the variable and selecting Add to Watched.
18.4. Subset of Embedded MATLAB Supported by Reactis#
This section describes the subset of EML that constitutes REML. REML supports the following aspects of EML. Note that in some cases not all aspects of a feature are supported. For example, a function might not support all numbers and types of input arguments.
18.4.1. Syntax#
While REML generally supports the rich EML notation for defining matrices, REML does impose some syntax restrictions. The most prominent restriction is that if any element of a row is a non-trivial expression, then the row must be delimited with commas instead of spaces. For example, if a = 5 and b = 4 then [ a + b -4 -3 ]
is a valid EML matrix which evaluates to [ 9 -4 -3 ]
. The REML syntax does not allow this expression. Instead it requires it to be written [ a + b, -4, -3 ]
.
Literals with the prefix “0x” followed by one or more digits 0-9 or letters in the range A-F shall be interpreted as hexadecimal unsigned integers of the smallest size uint8, uint16, or uint32 that can represent the number. If a hexadecimal literal has a suffix in the set u8, u16, u32, s8, s16, s32, the token shall be interpreted as a hexadecimal integer with type corresponding to its suffix:
Suffix |
Type of Literal |
---|---|
u8 |
uint8 |
u16 |
uint16 |
u32 |
uint32 |
s8 |
int8 |
s16 |
int16 |
s32 |
int32 |
18.4.2. Types#
18.4.3. Control Flow#
if statements
while loops
for loops
switch statement
break statement
continue statement
return statement
18.4.4. User-Defined Functions, Subfunctions, and External Functions#
local and persistent variables
18.4.5. Array Indexing#
scalar indexing, e.g.
x(4)
vector indexing, e.g.
x(2:5)
orx(2:end)
orx(:,3)
18.4.6. Logical Operators#
&
,|
,&&
,||
,~
and, or, xor, not, any, all
18.4.7. Relational Operators#
<
,<=
,==
,~=
,>=
,>
18.4.8. Math Operators#
+
,-
,*
,/
,^
18.4.9. Math Functions#
sin, cos, tan
csc, sec, cot
asin, acos, atan, atan2
exp, log, log2, log10
sinh, cosh, tanh
sqrt
fix, floor, ceil, round
mod, rem
sign, abs, deg2rad
18.4.10. Statistical Functions#
These functions support vector and matrix inputs, but not higher dimensional arrays.
mean, var, std
18.4.11. Matrix Operations#
transpose
( ' )
addition, subtraction
multiplication, division
det, diag, expm, eye, inv, norm, ones, zeros, repmat, rcond, cond
A ^ n
if A is a square matrix and n is an integer
18.4.12. Element-Wise Array Operations#
.*
,./
,.\
,.^
18.4.13. Vector Operations#
dot, length, max, min, polyfit, polyval, prod, size, sort, sum
18.4.14. Bit Operations#
bitset, bitget, bitand, bitor, bitxor, bitcmp, bitshift
18.4.15. Cast Operations#
double, single, uint8, int8, uint16, int16, uint32, int32, logical
18.4.16. Fixed Point Functions#
fi, ufi, sfi
Arithmetic operators:
+
,-
,*
,/
Relational operators:
<
,<=
,==
,~=
,>=
,>
bitconcat, bitset, bitget, bitand, bitor, bitsra, bitsll, bitsrl
Casting to MATLAB built-in numeric types, e.g. uint8(x) when x is a fixed point variable
storedInteger, and storedIntegerToDouble
18.4.17. String Operations#
strcmp
18.4.18. Miscellaneous Functions#
class
true, false
intmin, intmax, realmin, realmax
isempty, isequal
isfinite, isinf, isnan
struct
erf
eps