Executing models

This chapter describes the simulation types available with RT-LAB, explains how to build and execute a model.

Target Platform

RT-LAB supports three different target platforms:

Windows versions	For pure simulation or pseudo-real-time execution.
OPAL-RT Linux (x86-based)	For pure simulation or real-time execution for targets with an Intel x86 processor.

Simulation Mode

Standard Mode

Simulation	Free-run, as-fast-as-possible simulation on target. In this mode, no synchronization is done. Target nodes in a distributed simulation are synchronized with the communication link. The data exchanged depends on the model’s data flow.
Simulation in low priority (Win32 target only)	Same as a simulation but the computation subsystem runs in lower priority. It is useful when the simulation runs on the command station; it will let CPU resources be used by other applications.
Software synchronized	The model runs in real-time. In this mode, the model is synchronized on the internal RTOS timer. Only one computation node is synchronized when executing a distributed simulation. Other subsystems are synchronized with the communication link. The data exchanged depends on the model’s data flow.
Hardware synchronized	The model runs in real-time. In this mode, the model is synchronized on an external hardware timer. A specific block is required to be inserted in the model to specify and configure where the external clock is located. Only one computation node is synchronized when executing a distributed simulation. Other subsystems are synchronized with the communication link. The data exchanged depends on the model’s data flow.

eXtreme High Performance (XHP) mode

The XHP mode is a means for the real-time operating system to disable interrupts. This is done on a per-subsystem (thus per-core) basis. Not allowing interrupts prevents process switching which removes latencies time for additional computation in the same time slice.

The XHP mode is aimed at real-time applications of a given base sample time that cause overruns (overflow their allowed time-step for computation) while running in RT-LAB in the standard mode.

In XHP mode, the model waits in an empty loop for its next scheduled computation step. The next model step is then computed.

In this mode, we use the CPU counter as our time reference. Because this counter operates at the CPU's frequency, it offers a very high resolution, even for step-sizes in the microsecond range. Because the counter resides on the CPU and reading its value is done within one CPU cycle, this operation introduces almost no latency.

Issues Introduced by XHP Mode on Red Hat Linux targets

On Red Hat Linux targets, the XHP mode is enabled on a per-core basis. It means that only the core assigned to an XHP subsystem will not be available to other processes and OS. If the number of subsystems running in XHP mode on a target is less than the number of cores, the OS will not be disabled and all the functionalities provided by the OS will be available. In this case, the following paragraph explaining limitations for XHP mode will not apply.

If the number of subsystems running in XHP mode is equal to the number of cores, the target will be set in full XHP model and all limitations will apply. In practice, this is not allowed by RT-LAB since core 0 will be forced to non-XHP mode to ensure OS operability.

Limitations and Solutions for XHP Mode

Acquisition and Model Control from the Command Station

Because the network card driver is not available during XHP runs, the communication between this computation node and the command station is not available. Only the inter-computation node communication using real-time PCIe or shared memory is still available. This means that signals you
wish to be acquired during execution in XHP mode must be routed to another, non-XHP, computation node, which is able to send these signals to the command station.

If you do not have a second computation node to use as a relay, you can also set your model to pause automatically (using the RTLAB Pause, a Clock and some logic blocks) at a given interval. When the model pauses, it switches back to normal mode and the acquired signals can be sent to the command station. Be sure to set your acquisition window to the size of your execution interval. Be aware that this is only possible for models that can be interrupted regularly and is rarely a viable solution because of this.

Distributed computation using UDP/IP communication

Again, because the network card driver is not available during XHP runs, communication protocols which use this card are not possible. You need to use real-time PCIe cards for communication between target nodes or shared-memory for intra-node communication. Multi-rate models cannot be executed in true multi-rate.

Because the ability to maintain multiple threads is disabled in the XHP mode for increased performance, it is not possible to run a multi-rate model in multi-tasking form (true multi-rate). Multi-rate systems can be still executed in single-tasking mode, but this has many disadvantages. See more about true vs. pseudo-multi-rate for details or the Real-Time Workshop User's Guide.

Parameter Tuning

Just as for acquisition, parameter modification is not possible for parameters of subsystems running in XHP mode. If you want to be able to modify some parameters, they will have to be relocated on a non- XHP node and wired to the XHP subsystem at the diagram level or while the model is paused.

Snapshot and dynamic signal acquisition

Also because of the single thread restriction, no snapshot can be taken and no signal can be dynamically selected when a subsystem is running in XHP mode. You can, however, pause the model to perform these functions and then continue execution. Some I/O interfaces are not available

Because system interrupts and multi-tasking are disabled for computation nodes running in XHP mode, any I/O boards which require these features are not available during XHP runs. These blocks are mainly limited to serial interfaces (which require an asynchronous process) and discrete event detectors/generators (which require interrupts).

Using XHP Mode

The XHP mode can only be applied at the subsystem level. To enable the XHP mode, you must check the XHP box in Assignation Page from Model Editor.

Subsystems running in XHP mode won't be able to communicate using the Ethernet network. They will only be able to communicate with other subsystems using the real-time PCIe Interconnect from Dolphin ICS.

It is recommended that you use the XHP mode only on slave subsystems so that the master can relay the communications between the slave nodes running in XHP and the command station (host computer) through Ethernet (or other TCP/IP transport).

Communication type

Two computation subsystems on the same physical node (regardless of the number of logical nodes) will exchange real-time signals using shared memory.

If computation subsystems (SM or SS) are on different physical nodes, you must select which real-time network type to use, either UDP/IP (slow, any targets) or Dolphin (fast, Red Hat Linux targets only).

The real-time link is configured using Model Editor in the Execution Page.

UDP/IP

This link requires an ethernet board on targets. It is a slow link and it should not be used for hard real-time simulation.

Dolphin

This link requires one Dolphin IXH610 or DX510 PCI Express host adapter to be installed on each target. Dolphin DXH510 adapter offers bi-directional link of up to 20Gbits/s, and Dolphin IXH610 adapter can support a communication speed up to 40Gbits/s (if installed on an x8 Gen 2 PCI Express
slot). These adapters should be used when high data throughput with very low latency is needed. For now, support for this communication type is only available on Red Hat.

Executing steps

Compilation

Select your target platform.
Start the compilation. This an automated process; no user interaction is needed.

Here is the list of the steps when compiling a model:

1. Separation	It is where the original model is separated into as many separate models as there are top-level subsystems.
2. Code generation	For each computation subsystem (SM and SS), Simulink Coder (Real-Time Workshop) is called to generate the C code for RT-LAB using a set of templates specific to the target OS.
3. Transfer to RTOS	The newly generated C files are transferred to one of the computation nodes (called the development or compilation node) via the FTP protocol.
4. Compilation	For each computation subsystem (SM and SS), the compiler will compile and link the C code into an executable file for RT-LAB.
5. Retrieval of Executables	Retrieve the executable(s) via FTP. This allows RT-LAB to load a subsystem on a different node than the compilation node.

Execution

Assign the subsystems to physical nodes. You can assign more than one subsystem to one physical node If there is more than one processor (logical node), then the load will automatically be distributed among the processors.If there is only one processor, then RT-LAB will rely on the RTOS to perform the task switching between the subsystem processes. This is equivalent to not distributing the model.

Select Handle console automatically from Simulation Tools Page from Model Editor if you want to use the user interface based on the original model’s SC subsystem.
Select a simulation mode.
Configure the communication type (optional).
Load the subsystem on the computation node(s). The executables (one per computation subsystem) are transferred to their assigned nodes using the FTP protocol. The subsystems are then loaded and ready to run. Note that only one model per target is allowed by default to ensure real-time integrity (Linux targets only). This option could be disabled by creating a file /usr/opalrt/multimodels on the target where you want to enable multiple running models at the same time.
Execute the model. The simulation is started. The RT-LAB generated console starts displaying the data retrieved. Note that it is NOT the original model, just the SC part of it. You could also create your own UI using our API instead.
At this point, you could modify parameters, log data to files...
Reset the model when your simulation is completed. The model could also reset itself by inserting a stop block inside it. RT-LAB automatically transfer all generated file to the command station to be reviewed later.

Additional files

Some simulation requires additional files in order to compile and execute the model. Refer to Files Page to see how to set up new files. Usually, header files and source files to be compiled are transferred during the compilation. Data files to be used at run-time are usually transferred while loading the model.

User script files

Since many different configurations may be required in order to run a simulation, RT-LAB supports script calls during the compilation and execution of a model. Scripts, created using Python, can be global to a node or local to a subsystem, called on a command station or target, and are available during the compilation step and the load/reset step. In addition, script outputs can be viewed to the RT-LAB display panel.

The following table lists available scripts:

Script	Step
host_preseparate.py	called on by command station during the compilation before separating the model.
hot_postgenerate.py	called on by command station during the compilation after the model's code generation.
target_precompile.py	called on by target during the compilation before compiling the model.
host_postcompile.py	called on by command station at the end of the compilation.
host_preload.py	called on by command station during the execution before loading the model.
target_preload.py	called on by target during the execution before executing the model.
target_postreset.py	called on by target during the execution after resetting the model.
host_postreset.py	called on by command station during the execution after resetting the model. Used for analysis after the model's execution.

Using Local User Scripts

In order to execute a local user script (only for this model), just create the corresponding file to the step you want to customize in the model’s directory on the command station. The file will be automatically transferred on target if required and executed. Many user scripts for different steps could be created. In order to disable a script, rename the file to a different name.

Using Global User Scripts

In order to share a script among models on the command station or target(s), the same python scripts are located under RTLAB_ROOT\common\python\rtlab\global. Modify these files in order to create a global execution of your script. Remember that these scripts will be applied to every model, they have to be modified with caution.

Debugging: Installing Debugger on a Target

Red Hat

The DDD debugger has been installed with the operating system. No other installation is necessary. Install the Nightstar Suite from Concurrent Computer Corporation if you want to debug your model using NightView.

Windows

The Microsoft Visual Studio 6 debugger will be used to debug the model. Since MS Visual studio is required in order to compile a model on Windows target, no more steps are required to install the debugger.

Setting RT-LAB configuration

Select the model you want to debug in your project.
In Diagnostic Page from Model Editor, check Use extended timeout and Compile Model in debug mode.
Uncheck the Enable Watchdog checkbox.

Build the model.
Configure where to display the debugger, in Environment Variables Page from Model Editor defines (Add) the following variables:
- Red Hat target:
- DISPLAY=:0.0

In Assignation Page from Model Editor check the subsystem(s) you want to debug. (check the Advanced field to add the Debug column)

Debugging the Model: Debugging Locally on Target Red Hat

By default, the NightView debugger will be used to debug the model. Refer to NightStart documentation to learn how to use it.

If you want to use DDD instead, edit the ini file <RT-LAB_ROOT_DIR>/common/bin/Hardware.config and in the section [General_REDHAWK] ([General_REDHAWK64] for RedHawk 64) and add the following key:
[General_REDHAWK]
DEBUGGER=ddd

To debug a model:

Start the graphical interface on the target (if it is not already done) and log as root.
Load the model.
Open the source file you want to debug and insert your breakpoint if any. for instance (DDD), if you want to debug the mdlStart (Simulink) of Rtdemo1 model, go to menu File->Open source... then select rtdemo1_1_sm_computation.c and click on Open button. The source file will open. Look for the MdlStart function, put the cursor on the first line and add a breakpoint (click on the Break button on the toolbar). A breakpoint should have been inserted. When the model will be executed, the execution will stop at this breakpoint.
Debugger should open on the target screen terminal. (DDD) Go to menu Program > Run again.

Windows

Load the model
Model arguments are copied to the clipboard. These arguments are used later in order to start the debugger. Press OK.

MS Visual Studio open and ask to create a project. Click Yes.

At the next screen, click OK.

At the next screen, click Save.

Go to Project > settings

Open source file you want to debug and insert breakpoints. Press F5 to start the debugger.

Debugging Remotely from the Command Station (Windows)

OPAL-RT Linux (x86-based) targets

To debug remotely, an application called X server is required to display the debugger. This document explains how to use cygwin (one of the most popular) as an X server.
Download and install Cygwin at http://www.cygwin.com (make sure that the Xfree86 package is selected)
Start Cygwin
Start the X server: XWin -screen 0 1024 768 -emulate3buttons &
Set the DISPLAY: export DISPLAY=<IP_ADRESS_OF_WINDOWS>:0.0
Start the window manager: wmaker &
Enable remote access: xhost +
On paragraph Setting RT-LAB configuration on page 474, replace DISPLAY value by DISPLAY=<IP_ADRESS_OF_WINDOWS>:0.0 (for instance DISPLAY=192.168.0.1:0.0).
Load model. DDD should open in the X server.

Windows Targets

This option is not supported by this target.

Executing Models