Chapter 16 Reactis for C Plugin

The base Reactis product treats S-Functions and Stateflow custom C code as black boxes. Models containing such C code can be processed, but the C source code is inaccessible. Hence, there is no way to perform basic debugging operations such as single-stepping, viewing variable values, setting breakpoints, or browsing the source code during simulation. Furthermore, targets cannot be created within the C source code when generating tests. Reactis for C Plugin integrates seamlessly with Reactis to offer white-box testing and validation of the C-code portions of models (S-Functions and C code called from Stateflow). Together, Reactis and Reactis for C Plugin automate the generation of test data from, and validation of models constructed with Simulink, Stateflow, and C code.

A separate license is required to use the Reactis for C Plugin. If your organization does not yet own such a license please contact sales@reactive-systems.com to inquire about purchase options or to obtain a demo license for the product. Reactis for C Plugin also requires base Reactis to run.

16.1 Quick Start

In the main Reactis window, select File -> Settings... and then display the Reactis for C tab. Make sure the “Enable white-box analysis of C code” checkbox is selected.
To subject an S-Function to white-box analysis, do the following:
1. right-click on the S-Function in the main Reactis panel and select Assign RSM File...
2. accept the default file name
3. click Yes to create a new .rsm file
4. add the C source files that implement the S-Function using the dialog.
Stateflow custom C code will be processed automatically when Reactis for C Plugin is enabled. No .rsm file is necessary.
Navigate to an S-Function in the hierarchy panel to display the C code for the S-Function. C code called from Stateflow will be listed at the bottom of the hierarchy panel under C Libraries -> Library: Stateflow User Sources.
The C code can be observed from Simulator and targets within the C code will be used by Tester to generate test suites that aim to maximize coverage of the C code.

16.2 Reactis for C Tab of the Settings Dialog

Figure 16.1: The Settings dialog with tab “Reactis for C” selected.

Enable white-box analysis of C code.

Enable or disable Reactis for C Plugin features.

S-Function source code coverage tracking.

This menu item configures the global setting for tracking coverage within the C code in S-Functions. This setting may be overridden for an individual S-Function within the .rsm file for the S-Function. The supported settings are:

Off: Turn off coverage tracking within S-Functions.
Cumulative: When there are multiple instances of the same S-Function in a model track coverage cumulatively for all instances.
Separate: When there are multiple instances of the same S-Function in a model, track coverage separately for the instances.

Create and use cache files for C code (files with extension '.rso').

In order to analyze C code, Reactis for C Plugin must convert the source file into a Reactis object file (.rso file ). Enabling this feature causes .rso files to be stored on disk (in the folder where the C code resides). Subsequently, a C source file will only be recompiled if the C source file is modified, or if a new version of Reactis is installed.

Display line numbers.

Toggle the display of line numbers in the main Reactis panel when displaying C source files.

Display line grid.

Toggle the highlighting of every other line in the specified background color to facilitate identifying the line number of a given code fragment.

16.3 Specifying the C Source Files to Build an S-Function

Simulink does not require the user to specify the C source files that implement an S-Function; instead only a name is given. For white-box testing, Reactis for C Plugin requires the C source files that implement an S-Function as well as the source files for any libraries referenced by the S-Function. Since the .mdl file does not include this information, Reactis for C Plugin has a mechanism for listing the C source files which comprise an S-Function. This mechanism is described in the rest of this section.

The collection of C source files that implement an S-Function is specified using a Reactis Make File (.rsm file ), which is created and modified by the simple editor shown in Figure 16.2. A .rsm file is created to specify how Reactis for C Plugin should compile the S-Function. Additionally, a separate .rsm file is constructed for each library referenced by the S-Function. The .rsm files for the S-Function and any libraries referenced by the S-Function are defined in the same way. In the following discussion we denote the library compiled from an .rsm file as the library under construction (LUC).

The following sections appear within the .rsm file editor window:

Source Files

The C source files that implement the LUC.

Libraries

The .rsm files for any libraries referenced by the C code in the Source Files section.

Include Directories

The list of directories that should be searched for files targeted by #include directives within the Source Files section.

Export global symbols, prefix

This checkbox option facilitates using Reactis for C Plugin to build libraries that have wrappers generated by tools such as the GNU dllwrap utility. If this option is enabled, then the string specified in the textbox will be prefixed to the name of each global variable in the LUC. Since the S-Functions do not use such a wrapper, this option is disabled for S-Function .rsm files.

Coverage Tracking

This menu specifies how coverage is tracked within the LUC. The coverage tracking options are as follows:

Inherited: Use the global coverage tracking setting for the LUC. Note that the Inherited option is only available for S-Function .rsm files.
Off: Turn off coverage tracking within the LUC.
Cumulative: When there are multiple instances of the LUC in a model, track coverage cumulatively for all instances.
Separate: When there are multiple instances of the LUC in a model, track coverage separately for the instances. Note that the Separate option is only available for S-Function .rsm files.

Figure 16.2: The Reactis Make File Editor is used to specify the C source files that make up an S-Function.

16.3.1 S-Function Requirements

All source code (for both an S-Function and any referenced libraries) must be available. In addition, all code must satisfy the requirements listed in Section 14.2.1.

16.4 Specifying the C Source Files Called from Stateflow

Reactis for C Plugin does not require an .rsm file to list the files containing custom C code called from Stateflow. This is because Stateflow requires the user to specify the C source files in the Target Options dialog ¹ and stores the names of the files in the .mdl file for a model. Reactis for C Plugin will therefore automatically process custom C code without any action required from the user. The C files called from Stateflow will be listed at the bottom of the Reactis hierarchy panel under C Libraries -> Library: Stateflow User Sources.

16.4.1 Stateflow Custom Code Requirments

Source code for all custom C code must be available.
Reactis for C Plugin does not currently support calling libraries from Stateflow custom C code.

16.5 C Code Coverage Criteria

Reactis uses a number of different coverage criteria to measure how thoroughly a test or set of tests exercises a model. In general, coverage criteria record how many of a given class of coverage targets (model features such as stateflow states, C program statements, etc.) have been executed at least once. Coverage criteria may be visualized using Simulator and are central to test generation and model validation using Tester and Validator.

Chapter 6 describes the coverage criteria that are tracked within the Simulink and Stateflow portions of models. Those criteria 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. Three of the generic critera are also tracked by the C code portions of models by Reactis for C Plugin. These are decision coverage, condition coverage, and modified condition / decision coverage (MC/DC).

Reactis for C Plugin uses precise criteria to determine which elements of C a program are decisions and which are conditions. A decision is any boolean-valued expression used to determine which execution path to follow. Conditions represent the atomic (i.e. smallest) boolean expressions within decisions. Specifically, decisions within a program are identified as follows:

For each if statement, the expression within parentheses following the if keyword is a decision.
For each while and do/while statement, the expression within parentheses following the while keyword is a decision.
For each for statement, the second expression within the parentheses following the for keyword is a decision.

Note that the argument expression of a switch statement is not a decision, and neither is the argument of the conditional expression operator pair ?:.

Decision coverage tracks whether each decision in a program has evaluated to both true and false.

Condition coverage tracks whether each condition in a program has evaluated to both true and false.

For the definition of MC/DC coverage, please see Chapter 6.

Finally, in addition to the generic coverage criteria discussed above, Reactis for C Plugin also tracks statement coverage, which records for each statement in a C program, whether or not the statement has been executed at least once.

16.5.1 Tracking Coverage in C Code

When Coverage -> Show Details in Simulator is selected, unexercised coverage targets in C code are reported visually as shown in Figure 16.3. Any unexecuted C 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 dispayed in red. The MC/DC-related coverage details associated with a decision (Figure 16.4) may be displayed by right clicking on the decision and selecting View Coverage Details. For a description of this dialog, please see Chapter 6.

To aid the user in finding unexercised targets, a thin red bar is drawn just to the right of the line number for any line that contains at least one unexercised coverage target.

Figure 16.3: Coverage highlighting in C code.

Figure 16.4: Viewing the MC/DC-related coverage details associated with a decision.

16.6 C Code in the Main Reactis Window

As shown in Figure 16.5, an .rsm file may be assigned, edited, or removed by right-clicking on the S-Function in the main panel when Simulator is disabled. After an .rsm file is assigned, the C source files for an S-Function are listed in the hierarchy panel and “RSM” appears in the upper right corner of the S-Function in the main panel.

Figure 16.5: Assigning .rsm files to S-Functions.

Figure 16.6 shows that a C file may be displayed in the main panel by clicking on the filename in the hierarchy panel. Line numbers and the grid may be turned on or off from the Reactis for C tab of the Settings dialog.

Figure 16.6: Clicking on a C filename in the hierarchy panel displays the C file in the main panel.

16.7 Debugging C Code with Reactis Simulator

When Reactis for C Plugin is enabled, Simulator seamlessly steps into Stateflow C code and S-Functions that have .rsm files assigned. The Simulator controls in the tool bar work in the same way within C code as they do for the Simulink and Stateflow portions of models. Within C code, the mini-step button ( ) executes a single C statement. Other buttons continue to operate in terms of a step of the model containing the C code. For example, the step button ( ) reads all top-level inputs of the model and then executes the blocks (possibly including C code), updating the top-level outputs of the model with the results of the execution.

As shown in Figure 16.7, a breakpoint may be toggled on lines within a C file which contain a C statement by double clicking just to the right of the line number, or by right-clicking to the right of the line number and selecting Toggle Breakpoint.

When paused at a breakpoint within a function, you may hover over any local variable within the function to query its current value.

For a description of how Simulator visually presents coverage information please see Section 16.5.1.

Figure 16.7: Debugging C code in Simulator.

16.8 Generating Tests from C Code in Reactis Tester

When Reactis for C Plugin is enabled, Tester automatically tries to exercise the coverage targets (described in Section 16.5) in Stateflow custom C code and S-Functions that have .rsm files assigned. The launch dialog includes a checkbox to enable or disable C statement coverage.

16.9 Validating C Code with Reactis Validator

Reactis Validator can check requirements on top-level S-Function inputs and outputs. To do so, Validator objectives are inserted within the subsystem which contains the S-Function. Reactis for C Plugin does not currently support the insertion of Validator objectives within the C code.

16.10 Unsupported C Features

Reactis for C Plugin supports a very large subset of the C99 standard. The following features, however, are not currently supported.

Static linking. Currently, all libraries must be dynamically-linked.
Variable-sized arrays, e.g., int f(int n, char s[n]) { ... }
ANSI Trigraphs.
Universal character codes (a \u or \U escape which can be followed by a UCS-2 or UCS-4 hex code).
Signals.
Execption handling via setjmp and longjmp.
Types _Bool, _Complex and _Imaginary.
Wide characters.
File I/O is currently limited to stdout and stderr.
Variable-length arrays.
Designated struct initializers.
Non-constant static initializers.

The following restrictions apply for white-box analysis of S-Functions:

All general restrictions for S-Function support as mentioned in section 14.2.1.
Fixpoint data types are not supported.
Matlab external interface functions dealing with sparse matrices (mxCreateSparse, mxCreateSparseLogicalMatrix, mxGetIr, mxGetJc, mxSetIr and mxSetJc) are not supported.
Matlab external interface functions dealing with imaginary data (mxGetImagData, mxGetPi, mxSetImagData, mxSetPi) are not supported.

The following runtime library functions are currently unimplemented:

dlfcn.h: dlopen dlsym dlclose dlerror
math.h: expm1 log1p ilogb expm1f log1pf ilogbf expm1l log1pl ilogbl rint rintf rintl scalbln scalblnf scalblnl
setjmp.h: setjmp longjmp sigsetjmp siglongjmp
signal.h: raise
stdio.h: freopen fseek ftell rewind fgetpos fsetpos ungetc fscanf scanf vfprintf vfscanf vscanf vsscanf fread fwrite feof
ferror: clearerr rename remove tmpfile tmpname
stdlib.h: rand srand atexit getenv system execl execlp execle execv execvp execve bsearch qsort
wchar.h: wcscat wcsncat wcscmp wcsncmp wcscpy wcsncpy wcslen wcschr wcsrchr wcsspn wcscspn wcspbrk wcstok wcsstr wcscoll wcsxfrm wmemchr wmemcmp wmemcpy wmemmove wmemset fwide fgetwc getwc getwchar ungetwc fgetws fwscanf wscanf swscanf fputwc putwc putwchar fputws fwprintf wprintf swprintf vfwprintf vswprintf vwprintf vfwscanf vswscanf vwscanf
wctype.h: mbrlen btowc mbrtowc wctob wcrtomb mbsinit iswalnum iswalpha iswcntrl iswdigit iswxdigit iswgraph iswpunct iswprint iswlower iswupper iswspace towlower towupper wctype iswctype wctrans towctrans

One additional restriction is that the size of type long long int is currently 32 bits.

1: The Target Options dialog is opened from the Stateflow window by selecting Tools -> Open Simulation Target... and then clicking the Target Options button.