Targeting Tornado for Real-Time Applications (Real-Time Workshop)

Real-Time Workshop

Downloading and Running the Executable
Interactively

If automatic downloading is disabled, you must use the Tornado tools to complete the process. This involves three steps:

Establishing a communication link to transfer files between the host and the VxWorks target
Transferring the object file from the host to the VxWorks target
Running the program

Connecting to the VxWorks Target

After completing the build process, you are ready to connect the host workstation to the VxWorks target. The first step is starting the target server that is used for communication between the Tornado tools on the host and the target agent on the target. This is done either from the DOS command line or from within the Tornado development environment. From the DOS command line use

```
tgtsvr target_network_name
```

Downloading the Real-Time Program

To download the real-time program, use the VxWorks ld routine from within WindSh. WindSh (wind shell) can also be run from the command line or from within the Tornado development environment. (For example, if you want to download the file vx_equal.lo, which is in the /home/my_working_dir directory, use the following commands at the WindSh prompt.

cd "/home/my_working_dir"
ld <vx_equal.lo

You will also need to load the StethoScope libraries if the StethoScope option was selected during the build. The Tornado User's Guide describes the ld library routine.

Running the Program

The real-time program defines a function, rt_main(), that spawns the tasks to execute the model code and communicate with Simulink (if you selected external mode during the build procedure.) It also initializes StethoScope if you selected this option during the build procedure.

The rt_main function is defined in the rt_main.c application module. This module is located in the matlabroot/rtw/c/tornado directory.

The rt_main function takes six arguments, and is defined by the following ANSI C function prototype.

    RT_MODEL * (*model_name)(void),
    char_T      *optStr,
    char_T      *scopeInstallString,
    int_T        scopeFullNames,
    int_T        priority,
    int_T        port

Table 12-1 lists the arguments to this function.

Table 12-1: Arguments to the rt_main RT_MODEL
Argument
Description

model_name

A pointer to the entry point function in the generated code. This function has the same name as the Simulink model. It registers the local functions that implement the model code by adding function pointers to the model's rtM. See Program Architecture for more information.

optStr

The options string used to specify a stop time (-tf) and whether to wait (-w) in external mode for a message from Simulink before starting the simulation. An example options string is

"-tf 20 -w"

The -tf option overrides the stop time that was set during code generation. If the value of the -tf option is inf, the program runs indefinitely.

scopeInstallString

A character string that determines which signals are installed to StethoScope. Possible values are:

NULL -- Install no signals. This is the default value.

"*" -- Install all signals.

"[A-Z]*" -- Install signals from blocks whose names start with an uppercase letter.

Specifying any other string installs signals from blocks whose names start with that string.

scopeFullNames

This argument determines whether StethoScope uses full hierarchical block names for the signals it accesses or just the individual block name. Possible values are:

1 Use full block names.

0 Use individual block names. This is the default value.

It is important to use full block names if your program has multiple instances of a model or S-function.

priority

The priority of the program's highest priority task (tBaseRate). Not specifying any value (or specifying a value of zero) assigns tBaseRate to the default priority, 30.

port

The port number that the external mode sockets connection should use. The valid range is 256 to 65535. When nothing is specified, the port number defaults to 17725.

**Table 12-1: Arguments to the rt_main RT_MODEL**
Argument	Description
`model_name`	A pointer to the entry point function in the generated code. This function has the same name as the Simulink model. It registers the local functions that implement the model code by adding function pointers to the model's `rtM`. See Program Architecture for more information.
`optStr`	The options string used to specify a stop time (`-tf`) and whether to wait (`-w`) in external mode for a message from Simulink before starting the simulation. An example options string is `"-tf 20 -w"` The `-tf` option overrides the stop time that was set during code generation. If the value of the `-tf` option is `inf`, the program runs indefinitely.
`scopeInstallString`	A character string that determines which signals are installed to StethoScope. Possible values are: `NULL` -- Install no signals. This is the default value. "``" -- Install all signals. "`[A-Z]`" -- Install signals from blocks whose names start with an uppercase letter. Specifying any other string installs signals from blocks whose names start with that string.
`scopeFullNames`	This argument determines whether StethoScope uses full hierarchical block names for the signals it accesses or just the individual block name. Possible values are: `1` Use full block names. `0` Use individual block names. This is the default value. It is important to use full block names if your program has multiple instances of a model or S-function.
`priority`	The priority of the program's highest priority task (`tBaseRate`). Not specifying any value (or specifying a value of zero) assigns `tBaseRate` to the default priority, 30.
`port`	The port number that the external mode sockets connection should use. The valid range is 256 to 65535. When nothing is specified, the port number defaults to 17725.

Passing optStr Via the Template Makefile. You can also pass the -w and -tf options (see optStr in Table 12-1) to rt_main by using the PROGRAM_OPTS macro in tornado.tmf. PROGRAM_OPTS passes a string of the form

```
-opt1 val1 -opt2 val2
```

In the following examples, the PROGRAM_OPTS directive sets an infinite stop time and instructs the program to wait for a message from Simulink before starting the simulation. Note that the argument string must be delimited by single quotes nested within double quotes:

```
PROGRAM_OPTS = "'-tf inf -w'"
```

Including the extra single quotes ensures that the argument string will be passed to the target program correctly, under both Windows and UNIX.

Calling rt_main. To begin program execution, call rt_main from WindSh. For example,

sp(rt_main, vx_equal, "-tf 20 -w", "*", 0, 30, 17725)

Begins execution of the vx_equal model
Specifies a stop time of 20 seconds
Provides access to all signals (block outputs) in the model by StethoScope
Uses only individual block names for signal access (instead of the hierarchical name)
Uses the default priority (30) for the tBaseRate task
Uses TCP port 17725, the default

Building the Program Asynchronous Support