Real-Time Workshop

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 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 documentation documents the features and syntax of the language.

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

Figure 14-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 pane.
• 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 pane.
• 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.

• The default CodeFormat value is RealTime.

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

• Language: Selects code generation (currently C only).

• It is possible to generate code in a language other than C. 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 documentation for a discussion of the issues.

• TargetType: 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 documentation 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 14-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 pane. Using the rtwoptions structure array, you can customize the Category menu in the Real-Time Workshop pane, define the options displayed in each category, and specify how these options are processed.

When the Real-Time Workshop pane 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.

You can also use the rtwoptions structure array to define special NonUI elements that cause callback functions to be executed, but that are not displayed in the Real-Time Workshop pane. See NonUI Elements for details.

The elements of the rtwoptions structure array are organized into groups that correspond to items in the Category menu in the Real-Time Workshop pane. 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 pane. The header in each category is followed by a maximum of seven elements.

Table 14-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(1).popupstrings  = '';
  rtwoptions(1).tlcvariable   = '';
  rtwoptions(1).tooltip       = '';
  rtwoptions(1).callback      = '';
  rtwoptions(1).opencallback  = '';
  rtwoptions(1).closecallback = '';
  rtwoptions(1).makevariable  = '';
  
  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 pane. The options defined in rtwoptions(2) and rtwoptions(3) display as shown in Figure 14-3.

Figure 14-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.

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.

For further examples of target-specific rtwoptions definitions, see Using rtwoptions: the Real-Time Workshop Options Example Target.

The following table lists the fields of the rtwoptions structure.

Table 14-2: rtwoptions Structure Fields Summary

Field Name	Description
callback	Name of M-code function to call when value of option changes. To access objects such as your Simulation Parameters dialog custom option fields, pass in a handle to the Simulation Parameters dialog. To do this, use the reserved keyword DialogFig. Note that DialogFig is a reserved keyword that should be used with extreme caution. For an example of callback usage, see Using rtwoptions: the Real-Time Workshop Options Example Target.
closecallback	Name of M-code function to call when be executed when dialog closes. To access objects such as your Simulation Parameters dialog custom option fields, pass in a handle to the Simulation Parameters dialog. To do this, use the reserved keyword DialogFig. Note that DialogFig is a reserved keyword that should be used with extreme caution. For an example of closecallback usage, see Using rtwoptions: the Real-Time Workshop Options Example Target.
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. For an example of opencallback usage, see Using rtwoptions: the Real-Time Workshop Options Example Target.
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 MAT-file variable name modifier menu used by the GRT target: 'rt_|_rt|none'
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, NonUI, Popup, Pushbutton, or Category.

NonUI Elements

Elements of the rtwoptions array that have type NonUI exist solely to invoke callbacks. A NonUI element is not displayed in the Simulation Parameters dialog. You can use a NonUI element if you wish to execute a callback that is not associated with any user interface element, when the dialog opens or closes. Only the opencallback and closecallback fields of a NonUI element have significance. See the next section,Using rtwoptions: the Real-Time Workshop Options Example Target for an example.

Using rtwoptions: the Real-Time Workshop Options Example Target

A working system target file, with M-file callback functions, has been provided as an example of how to use the rtwoptions structure to display and process custom options on the Real-Time Workshop pane. The example files are in the directory
matlabroot/toolbox/rtw/rtwdemos/rtwoptions_demo. The example target files are:

• usertarget.tlc: the example system target file. This file defines several popups, checkboxes, an edit field, and a nonUI item. The file demonstrates the use of callbacks, open callbacks, and close callbacks.
• usertargetcallback.m: an M-file callback invoked by a popup.
• usertargetclosecallback.m: an M-file callback invoked by an edit field.

Please refer to the example files while reading this section. The example system target file, usertarget.tlc: demonstrates the use of callbacks associated with the following UI elements:

• The Execution Mode popup executes an open callback that is coded inline within the system target file. This callback displays a message and sets a model property via a set_param().
• The Real-Time Interrupt Source popup executes a callback defined in an external M-file, usertargetcallback.m. A handle to the popup object is passed in to the callback, which displays the popup's current value.
• The edit field Signal Logging Buffer Size in Doubles executes a close callback defined in an external M-file, usertargetclosecallback.m. The callback obtains a handle to the edit field object and displays the current value of the edit field.
• The External Mode checkbox executes an open callback that is coded inline within the system target file. The callback obtains a handle to the checkbox object and sets its value to 1.
• The NonUi item defined in rtwoptions(8) executes open and close callbacks that are coded inline within the system target file. Each callback simply prints a status message.

We suggest that you study the example code while interacting with the example target options in the Simulation Parameters dialog. To interact with the example target file:

1. Make matlabroot/toolbox/rtw/rtwdemos/rtwoptions_demo your working directory.
2. Open any model of your choice.
3. Open the Real-Time Workshop pane in the Simulation Parameters dialog. Select Target Configuration from the Category menu.
4. Click the Browse button. The System Target File Browser opens. Select Real-Time Workshop Options Example Target. Then click OK.
5. Observe that the Category menu of the Real-Time Workshop pane contains two custom items: userPreferred target options (I) and userPreferred target options (II).
6. As you interact with the options in these two categories and open and close the Simulation Parameters dialog, observe the messages displayed in the MATLAB window. These messages are printed from code in the system target file, or from callbacks invoked from the system target file.

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 pane.

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 documentation for further information on the rtwgensettings structure.

Customizing the Build Process

Adding a Custom Target to the System Target File Browser