Asynchronous Processes

In keeping with the design principle of openness, RT-LAB features can be extended through the use of Asynchronous User Applications also called Asynchronous Processes. This gives RT-LAB users access to the full power of the operating system and allow them to implement their own interfaces to various external devices. Although usually targeted for use with communication devices such as GPS receivers and power monitors, Asynchronous User Applications can be developed to interface acquisition boards, or implement system-specific software such as file management, etc.

Architecture Overview

Asynchronous User Applications allow the user to execute applications asynchronously to RT-LAB while running on the same target computer as RT-LAB. They are asynchronous because they are not synchronized with the model, i.e. they run independently of the RT-LAB model, either at their own periodic rate or triggered by an external interrupt.

To illustrate this, let’s take an example of an application that needs to perform data acquisition on a serial link at a low speed while processing other computation data at a higher speed. It would not be convenient in that case to run the model at the low speed of the serial link.

In the Asynchronous Process architecture, the low-speed serial data acquisition is performed in a process separate from the main RTLAB model, the Asynchronous Program. The RT-LAB model can then be set up with the calculation step required to process the high-speed data. Dedicated Simulink blocks are then placed in the RT-LAB model in order to allow data transfers to and from the Asynchronous Program.

One Asynchronous Process application thus consists of two parts:

One source code written in C or C++ implements the user-specific function and handles communication with the RT-LAB model. This source code is compiled in an executable program which is transferred to the target computer and launched during model initialization,
A set of blocks placed inside the RT-LAB model allows the user to specify the configuration parameters of the Asynchronous Program, and to select the data signals to be sent to, or retrieved from, the Asynchronous Program during the execution of the model.

Note: although the source code of the Asynchronous Program must be designed specifically for the user application using templates and the API of functions provided with RT-LAB, Simulink blocks usually do not require development other than possibly masking the basic blocks provided with RT-LAB to make a specific user interface for the application.

Asynchronous Programs exchange data with the model periodically via a shared memory opened by the RT-LAB model during initialization as presented in Figure 14 below. RT-LAB then starts the asynchronous program which name is defined in a configuration block placed in the RT-LAB model, the Asynchronous Controller block. During model execution, both the model and the Asynchronous Process read from, and write to, the shared memory in order to exchange data.

Communication between asynchronous user program and RT-LAB model.

In the serial communication example described above, data are processed in the Asynchronous Program as soon as they are received on the serial link, and are placed in the shared memory at specific locations determined by the developer of the Asynchronous Program. Asynchronous receive blocks placed in the RT-LAB model periodically access the shared memory and return the data present in the shared memory via the outports of these blocks. The data can then be used within the RT-LAB model for further processing. In a similar way, data can be transferred from the RT-LAB model to the shared memory by the use of Asynchronous Send blocks. These data can then be retrieved by the Asynchronous process in the shared memory and transmitted to the serial link.

Building the Asynchronous Application

Preparing the RT-LAB Model

The blockset of dedicated Simulink blocks can be found in the Simulink library browser in the section: RT-LAB >Communication >Asynchronous as presented in Figure 15 below

RT-LAB Asynchronous Program library in Simulink browser

This library consists of three blocks: OpAsyncGenCtrl, OpAsyncRecv and OpAsyncSend. We describe their main functionalities here. Their full description can be found in the Block library section of the RT-LAB documentation.

OpAsyncGenCtrl

In order to interface the RT-LAB model with an Asynchronous Program running on the target computer, at least one OpAsyncGenCtrl block must be placed in the model. The OpAsyncGenCtrl block is used to define the configuration settings of the Asynchronous Program created by the user.

This block controls the launch of one specific instance of the Asynchronous Program to be run on the target where the model executes. The name of the Asynchronous Program is specified via a mask parameter, and the Asynchronous Program itself must be compiled and transferred to the target prior to model execution. The following sections will detail the build and transfer process.

Several OpAsyncGenCtrl blocks can be placed in the same RT-LAB model to control either several instances of the same Asynchronous Program or several different Asynchronous Programs.

Each OpAsyncGenCtrl block defines one unique Controller ID that is used by the asynchronous Send and Receive blocks to refer to the Asynchronous Program instance controlled by this OpAsyncGenCtrl block.

The OpAsyncGenCtrl block also allows the user to specify a set of parameters to be transferred to the program.

These parameters are retrieved by the Asynchronous Program using the OpalGetAsyncCtrlParameters( ) function of the asynchronous programs API.

OpAsyncRecv

This block is used to receive data from the Asynchronous Program during model execution. Its input allows the user to specify a Timeout value to be optionally used by the Asynchronous Program. The Data output contains the values retrieved by the model in the shared memory. It is possible to use a demux block to receive multiple values.

OpAsyncSend

This block is used to transfer data from the model to the Asynchronous Program. The input is the data to be copied to the shared memory. It is possible to use a mux block to send multiple values. Data is actually updated in the shared memory when the Data Ready line is asserted. The figure below is an example of usage of these three blocks in the example model for TCP/IP communication.

Example model subsystem with RT-LAB asynchronous blocks

Note: In this example, the OpAsyncGenCtrl is replaced by the OpIPSocketCtrl block which uses the same s-function sfun_gen_async_ctrl as the OpAsyncGenCtrl block but with a mask adapted to present only the subset of configuration parameters used by this specific application.

Preparing the C Source Code

Once the user has defined what signals of his model must interface with the Asynchronous Program, he must develop the C source code that will implement the specific algorithm required by his application.

All Asynchronous Programs use minimally the same 4 steps: Initialization, send loop, receives loop and close section. All of these programs use the Asynchronous API functions provided with RT-LAB. The available API\ functions are listed in the header file AsyncApi.h located in folder $RT-LAB$\common\include_target.

Note: RT-LAB provides two complete examples containing the models and their associated Asynchronous Program C code.

These examples are available as templates for RT-LAB Projects:

IO/_Generic_/async_ip is an example of UDP/IP and TCP/IP communication,
IO/_Generic_/async_serial is an example of serial communication.

See New RT-LAB project wizard to learn about RT-LAB templates.

The C code of these examples is commented step-by-step and indicates the sections where the user can insert his application-specific code. They can be used as templates for other applications.

Preparing the Makefile

In order to compile the source code into an executable program, the user must also prepare the associated makefile. It is assumed here that the user is familiar with setting up C makefiles. The abovementioned templates also provide the makefile associated with the C source code.

See example file: %RTLAB_ROOT%\Examples\IO\_Generic_\async_serial\test\Simulink - AsyncSerial.mk.

It’s highly recommended that you base new makefiles on an existing sample to minimize compilation issues.

Note: The $(OPAL_LIBPATH) argument must be added to your library path.

LIBPATH = -L. $(OPAL_LIBPATH)

The following libraries must also be included: libOpalAsyncApiCore.a, libOpalCore.a and libOpalUtils.a.

They contain all the definitions required to link the C source code with the Asynchronous Process API functions. The arguments $(LIB_TARGET) $(OPAL_LIBS) are also necessary. To sum up, the LIBS definition should look like this:

LIBS = -lOpalAsyncApiCore -lOpalCore -lOpalUtils $(LIB_TARGET) $(OPAL_LIBS)

Users already familiar with the Asynchronous Process features provided by RT-LAB may want to ignore these new makefile arguments defined by RT-LAB environment variables. Please note that these arguments are important to ensure portability with future RT-LAB releases.

In the Simulink environment, libraries must be transferred to the model directory on the target prior to model compilation RT-LAB takes care of transferring core libraries such as libOpalCore.a and libOpalUtils.a to the model directory during the build process. The library libOpalAsyncApiCore.a however, is not systematically transferred by RTLAB since it is required only for linking Asynchronous Programs.

RT-LAB models using Asynchronous Process controller blocks provided in the RT-LAB I/O library already take care of transferring all required libraries by the use of Matlab m-file callbacks. Users who have disabled the link of their controller blocks to their original RT-LAB library blocks in their own models need to restore this link in order to retrieve the proper callbacks settings.

Users who have made their own Simulink mask above the s-function sfun_gen_async_ctrl need to add the libOpalAsyncApiCore.a library to the list of files to transfer to the target. This will be explained in the next section.

Furthermore, in order for the makefile to link with the libraries found in the model directory, the model folder must be added to the library path by adding the option ‘-L.’ to the link flags.

Configuring RT-LAB for the build of the asynchronous program

After preparing both the Asynchronous Process source code and the RT-LAB model, the first two compile steps in Running H/F 2 (i.e. Generate model and Generate Code) automatically add the required files to compile the Asynchronous Process executable. The makefile, the source files, and the header files will be detected as long as they are all placed at the same level in the project folder. It is recommended to run these two compile steps before continuing and to ensure that the list of files to be transferred is correct (see below to edit the Files Page). The remaining compile steps will confirm if everything is well configured for the creation of the Asynchronous Program. The log is present in the Compilation View.

Depending on the complexity of the Asynchronous Program, there may be compilation errors. More settings could be required. In this case, follow these steps:

In RT-LAB, open a Model Editor and go to the Files Page.

This page allows the user to specify what files are uploaded to the target and what files are retrieved from the target:

Specifying file transfer at compilation time

File names may be full-qualified (i.e. path + filename) or may be relative to the model folder.

As explained in the previous section, the library libOpalAsyncApiCore.a may need to be added to this list if it is not added to the build process in a Matlab callback of the controller block. The path to this library is (replace $RTLAB-ROOT$ by the actual path to the RT-LAB root folder):

$RTLAB_ROOT$/common/lib/redhawk/libOpalAsyncApiCore.a for Red Hat targets.

This library must be transferred in binary mode.

During model initialization, the OpAsyncGenCtrl block will attempt to launch the Asynchronous Program. For this reason, the executable file of the Asynchronous Program must be found in the model directory.

If the execution node is different from the compilation node, the executable file of the Asynchronous Program, which was created in the model directory during compilation, needs to be transferred back to the host computer. This is done by adding this file to the list of files to be retrieved from the target after compilation.

Because this page is used for other features, any files related to Asynchronous Programs should be set with the “Asynchronous Process“ category tag.

This executable file must be transferred in binary mode.

On the Development page, under the Compiler option tab, specify the following command in the Compiler command text box as shown in Figure 18. The compilation command for OPAL-RTLinux (x86- based) targets is:

/usr/bin/make -f /usr/opalrt/common/bin/opalmodelmk

Setting the compilation command
You are then ready to build the model completely. Note that if there is a problem in the C file of the Asynchronous process, errors will be displayed in the Compilation View during compilation.

Running the Asynchronous Program

Loading the Model

The executable file of the Asynchronous Program must be added to the list of files to be transferred to the execution node at load time as shown in the next figure:

Specifying executable transfer at load time

After retrieval from the compilation target, the executable file is found in the subsystem sub-directory created in the model directory of the host computer during compilation. Remember that the executable must be transferred in binary mode.

The model is then ready to be loaded by clicking the Load button of the RT-LAB Main Toolbar. As mentioned above, the sfun_gen_async_ctrl s-function (used by the OpGenAsyncCtrl block or the replacement controller block developed for the specific application) will attempt to launch the Asynchronous Program during initialization of the model. Note that because the Asynchronous Program is asynchronous to the model, its own initialization phase may span longer than the model initialization.

Messages prepared by the Asynchronous Program are displayed in the Display View together with messages from the model.

Executing the Model

During model execution data are exchanged with the Asynchronous program via the shared memory. The Data Ready of the OpGenAsyncSend block specifies when to initiate a data transfer towards the Asynchronous Program. The OpGenAsyncRecv blocks return data placed by the Asynchronous program in the shared memory. The developer of the Asynchronous Program specifies how these data are handled by the Asynchronous Program.

Resetting the Model

During model reset, RT-LAB attempts to close the shared memory opened during model initialization. In order to be able to do so, the model will first wait for the Asynchronous Program to exit.

The Asynchronous Program is notified that the user has requested a Reset by checking the MODEL_STATE variable. Upon detecting a Reset, or an Error state, the Asynchronous Program should exit properly.

If it fails to do so, for example, because it is too busy processing data from an external device at that time, the RT-LAB model may fail to close the shared memory and will display a message to warn the user about this. The user may then need to kill the Asynchronous Program manually on the target computer before the next load of the model.

It is the responsibility of the Asynchronous Program developer to ensure that Reset or Error states are handled properly by the Asynchronous Program.