Real-Time Workshop User's Guide

System Target File Structure

This section is a guide to the structure and contents of a system target file. You may want to refer to the system target files provided with the Real-Time Workshop while reading this section. Most of these files are stored in the target-specific directories under matlabroot/rtw/c. Additional system target files are stored in matlabroot/toolbox/rtw/targets/rtwin/rtwin and matlabroot/toolbox/rtw/targets/xpc/xpc.

Before creating or modifying a system target file, you should acquire a working knowledge of the Target Language Compiler. The Target Language Compiler Reference Guide documents the features and syntax of the language.

Figure 17-2 shows the general structure of a system target file.

Figure 17-2: Structure of a System Target File

Browser Comments

This section is optional. You can place comment lines at the head of the file to identify your system target file to the System Target File Browser. These lines have significance to the browser only. During code generation, the Target Language Compiler treats them as comments.

Note that you must place the browser comments at the head of the file, before any other comments or TLC statements.

The comments contain the following directives:

• SYSTLC: This string is a descriptor that appears in the browser.
• TMF: Name of the template makefile to use during build process. When the target is selected, this filename is displayed in the Template makefile field of the Target configuration section of the Real-Time Workshop page.
• MAKE: make command to use during build process. When the target is selected, this command is displayed in the Make command field of the Target configuration section of the Real-Time Workshop page.
• EXTMODE: Name of external mode interface file (if any) associated with your target. If your target does not support external mode, use no_ext_comm.

The following browser information comments are from matlabroot/rtw/c/grt/grt.tlc.

%% SYSTLC: Generic Real-Time Target 
%%    TMF: grt_default_tmf MAKE: make_rtw EXTMODE: ext_comm

See Adding a Custom Target to the System Target File Browser for further information.

Target Language Compiler Configuration Variables

This section assigns global TLC variables that affect the overall code generation process. The following variables must be assigned:

• CodeFormat: The CodeFormat variable selects one of the available code formats:
• RealTime: Designed for rapid prototyping, with static memory allocation.
• RealTimeMalloc: Similar to RealTime, but with dynamic memory allocation.
• Embedded-C: Designed for production code, minimal memory usage, simplified interface to generated code.
• S-Function: For use by S-function and Accelerator targets only.
• Ada: Designed for production code, minimal memory usage, simplified interface to generated code.

The default CodeFormat value is RealTime.

Chapter 4, Generated Code Formats summarizes available code formats and provides pointers to further details.

• Language: Selects code generation in one of the supported languages:
• C
• Ada

When Ada is selected, Real-Time Workshop generates Ada95 code by default. To generate Ada83 code, set the variable AdaVersion as follows.

%assign AdaVersion = "83"

It is possible to generate code in a language other than C or Ada. To do this would require considerable development effort, including reimplementation of all block target files to generate the desired target language code. See the Target Language Compiler Reference Guide for a discussion of the issues.

• TargetType: The Real-Time Workshop defines the preprocessor symbols RT and NRT to distinguish simulation code from real-time code. These symbols are used in conditional compilation. The TargetType variable determines whether RT or NRT is defined.

Most targets are intended to generate real-time code. They assign TargetType as follows.

%assign TargetType = "RT"

Some targets, such as the Simulink Accelerator, generate code for use in non real-time only. Such targets assign TargetType as follows.

%assign TargetType = "NRT"

See Conditional Compilation for Simulink and Real-Time for further information on the use of these symbols.

Target Language Compiler Program Entry Point

The code generation process normally begins with codegenentry.tlc. The system target file invokes codegenentry.tlc as follows.

%include "codegenentry.tlc"

codegenentry.tlc in turn invokes other TLC files:

• genmap.tlc maps the block names to corresponding language-specific block target files.
• commonsetup.tlc sets up global variables.
• commonentry.tlc starts the process of generating code in the format specified by CodeFormat.

To customize the code generation process, you can call the lower-level TLC files explicitly and include your own TLC functions at each stage of the process. See the Target Language Compiler Reference Guide for guidelines.

Note    codegenentry.tlc and the lower-level TLC files assume that CodeFormat, TargetType, and Language have been correctly assigned. Set these variables before including codegenentry.tlc.

RTW_OPTIONS Section

The RTW_OPTIONS section (see Figure 17-2) is bounded by the directives:

%/
BEGIN_RTW_OPTIONS
.
.
END_RTW_OPTIONS
/%

The first part of the RTW_OPTIONS section defines an array of rtwoptions structures. The rtwoptions structure is discussed in this section.

The second part of the RTW_OPTIONS section defines rtwgensettings, a structure defining the build directory name and other settings for the code generation process. See Build Directory Name for information about rtwgensettings.

The rtwoptions Structure.   The fields of the rtwoptions structure define variables and associated user interface elements to be displayed in the Real-Time Workshop page. Using the rtwoptions structure array, you can customize the Category menu in the Real-Time Workshop page, define the options displayed in each category, and specify how these options are processed.

When the Real-Time Workshop page opens, the rtwoptions structure array is scanned and the listed options are displayed. Each option is represented by an assigned user interface element (check box, edit field, pop-up menu, or pushbutton), which displays the current option value.

The user interface elements can be in an enabled or disabled (grayed-out) state. If the option is enabled, the user can change the option value.

The elements of the rtwoptions structure array are organized into groups that correspond to items in the Category menu in the Real-Time Workshop page. Each group of items begins with a header element of type Category. The default field of a Category header must contain a count of the remaining elements in the category.

The header is followed by options to be displayed on the Real-Time Workshop page. The header in each category is followed by a maximum of seven elements.

Table 17-2 summarizes the fields of the rtwoptions structure.

The following example is excerpted from matlabroot/rtw/c/rtwsfcn/rtwsfcn.tlc, the system target file for the S-Function target. The code defines an rtwoptions structure array of three elements. The default field of the first (header) element is set to 2, indicating the number of elements that follow the header.

  rtwoptions(1).prompt = 'RTW S-function code generation options';
  rtwoptions(1).type = 'Category';
  rtwoptions(1).enable = 'on';  
  rtwoptions(1).default = 2; % Number of items under this category
                             % excluding this one.

  rtwoptions(2).prompt = 'Create New Model';
  rtwoptions(2).type = 'Checkbox';
  rtwoptions(2).default = 'on';
  rtwoptions(2).tlcvariable = 'CreateModel';
  rtwoptions(2).makevariable = 'CREATEMODEL';
  rtwoptions(2).tooltip = ...
    ['Create a new model containing the generated RTW S-Function block inside 
it'];

  rtwoptions(3).prompt = 'Use Value for Tunable Parameters';
  rtwoptions(3).type = 'Checkbox';
  rtwoptions(3).default = 'off';
  rtwoptions(3).tlcvariable = 'UseParamValues';
  rtwoptions(3).makevariable = 'USEPARAMVALUES';
  rtwoptions(3).tooltip = ...
['Use value instead of variable name in generated block mask edit fields'];

The first element adds the RTW S-function code generation options item to the Category menu of the Real-Time Workshop page. The options defined in rtwoptions(2) and rtwoptions(3) display as shown in Figure 17-3.

Figure 17-3: Code Generation Options for S-Function Target

If you want to define more than seven options, you can define multiple Category menu items within a single system target file. For an example, see the Tornado system target file, matlabroot/rtw/c/tornado/tornado.tlc.

For further examples of target-specific rtwoptions definitions, see the system target files in the other target directories under matlabroot/rtw/c.

Note that to verify the syntax of your rtwoptions definitions, you can execute the commands in MATLAB by copying and pasting them to the MATLAB command window.

The following table lists the fields of the rtwoptions structure.

Table 17-2: rtwoptions Structure Fields Summary

Field Name	Description
callback	Name of M-code function to call when value of option changes.
default	Default value of the option (empty if the type is Pushbutton).
enable	Must be on or off. If on, the option is displayed as an enabled item; otherwise, as a disabled item.
makevariable	Template makefile token (if any) associated with option. The makevariable will be expanded during processing of the template makefile. See Template Makefile Tokens.
opencallback	M-code to be executed when dialog opens. The purpose of the code is to synchronize the displayed value of the option with its previous setting. See matlabroot/rtw/c/ert/ert.tlc for an example.
popupstrings	If type is Popup, popupstrings defines the items in the pop-up menu. Items are delimited by the "|" (vertical bar) character. The following example defines the items of the Function management menu used by the GRT and other targets: ['None|Function splitting|File ', ... 'splitting|Function and file splitting']
prompt	Label for the option.
tlcvariable	Name of TLC variable associated with the option.
tooltip	Help string displayed when mouse is over the item.
type	Type of element: Checkbox, Edit, Popup, Pushbutton, or Category.

Additional Code Generation Options

Target Language Compiler Variables and Options describes additional code generation variables. For readability, it is recommended that you assign these variables in the Configure RTW code generation settings section of the system target file.

Alternatively, you can append statements of the form

-aVariable=val

to the System target filename field on the Real-Time Workshop page.

Build Directory Name

The final part of the system target file defines the BuildDirSuffix field of the rtwgensettings structure. The build process appends the BuildDirSuffix string to the model name to form the name of the build directory. For example, if you define BuildDirSuffix as follows

rtwgensettings.BuildDirSuffix = '_mytarget_rtw'

the build directories are named model_mytarget_rtw.

See the Target Language Compiler Reference Manual for further information on the rtwgensettings structure.

Customizing the Build Process

Adding a Custom Target to the System Target File Browser