18. Reactis for EML Plugin#

The Reactis for EML Plugin integrates with Reactis for Simulink 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 and offers 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).

_images/emlSettings.png

Fig. 18.1 The Settings dialog with tab Reactis for EML selected.#

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.

_images/cruise_eml.png

Fig. 18.2 In the hierarchy panel, the names of MATLAB Function blocks are prefixed with the red ML symbol and when such a node in the hierarchy is selected the block’s EML code is displayed in the main panel.#

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.

_images/emlExternalFuns.png

Fig. 18.3 The External EML Functions section of the hierarchy panel lists external EML functions. If you select an external function in the tree, the function is displayed in the main panel.#

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.

_images/emlpCvgHighlight.png

Fig. 18.4 Coverage highlighting in EML code.#

_images/emlpCvgDetails.png

Fig. 18.5 View the MC/DC and MCC-related coverage details associated with a decision by right-clicking on the decision and selecting View Coverage Details.#

18.3.2. Debugging EML Code#

_images/emlDebug.png

Fig. 18.6 Debugging EML Code in Simulator.#

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:

  1. 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.

  2. Single Stepping. EML code may be stepped through one statement at a time by clicking on the mini-step miniStepBtn button or by selecting Simulate > Step Into.

  3. 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.

  4. 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#

  • double, single, uint8, int8, uint16, int16, uint32, int32, fixed point types with binary point scaling, logical, string[1], enumerations[2], structures[3]

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) or x(2:end) or x(:,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, num2str, str2num, strlength, char

18.4.18. Mask Drawing Functions#

Masked subsystems can have a custom icon created by executing a MATLAB script that uses drawing functions to draw the block icon. Reactis supports the following functions for mask drawing:

  • dpoly, droots, disp, text, image, patch, color, plot

18.4.19. Miscellaneous Functions#

  • class

  • true, false

  • intmin, intmax, realmin, realmax

  • isempty, isequal

  • isfinite, isinf, isnan, isfloat, isinteger, islogical

  • struct

  • erf

  • eps

  • exist