Real-Time Workshop®

Choosing and Configuring Your Target

Introduction

The first step to setting up a file for code generation is to choose and configure a system target. The process of generating target-specific code is controlled by the following:

• A system target file

• A template makefile

• A make command

You can specify this configuration information for a specific type of target in one step by using the System Target File Browser. The browser lists a variety of ready-to-run configurations.

When you select a target, the Real-Time Workshop^® software changes settings in the current configuration set to be compatible with the corresponding system target file. For example, many hardware emulation target settings, such as word size and byte ordering, are set automatically according to device type requirements. After selecting a system target, you can modify other model configuration settings to meet model or system requirements.

If you want to apply different system target files to a given model, you can do so by creating multiple configuration sets for that model. At any given time, you choose one configuration set to be the active configuration set. This is the preferred practice over simply changing the model's system target file.

Back to Top

Selecting a System Target File

To select a target configuration using the System Target File Browser,

1. Click Real-Time Workshop on the Configuration Parameters dialog box. The Real-Time Workshop pane appears.

2. Click the Browse button next to the System target file field. This opens the System Target File Browser. The browser displays a list of all currently available target configurations, including customizations. When you select a target configuration, the Real-Time Workshop software automatically chooses the appropriate system target file, template makefile, and make command.

   Selecting a System Target File shows the System Target File Browser with the generic real-time target selected.

3. Click the desired entry in the list of available configurations. The background of the list box turns yellow to indicate an unapplied choice has been made. To apply it, click Apply or OK.

   System Target File Browser

   

   When you choose a target configuration, the Real-Time Workshop software automatically chooses the appropriate system target file, template makefile, and make command for the selected target, and displays them in the System target file field. The description of the target file from the browser is placed below its name in the general Real-Time Workshop pane.

Back to Top

Selecting a System Target File Programmatically

Simulink^® models store model-wide parameters and target-specific data in configuration sets. Every configuration set contains a component that defines the structure of a particular target and the current values of target options. Some of this information is loaded from a system target file when you select a target using the System Target File Browser. You can configure models to generate alternative target code by copying and modifying old or adding new configuration sets and browsing to select a new target. Subsequently, you can interactively select an active configuration from among these sets (only one configuration set can be active at a given time).

Scripts that automate target selection need to emulate this process.

To program target selection

1. Obtain a handle to the active configuration set with a call to the getActiveConfigSet function.

2. Define string variables that correspond to the required Real-Time Workshop system target file, template makefile, and make command settings. For example, for the ERT target, you would define variables for the strings 'ert.tlc', 'ert_default_tmf', and 'make_rtw'.

3. Select the system target file with a call to the switchTarget function. In the function call, specify the handle for the active configuration set and the system target file.

4. Set the TemplateMakefile and MakeCommand configuration parameters to the corresponding variables created in step 2.

For example:

cs = getActiveConfigSet(model);
stf = 'ert.tlc';
tmf = 'ert_default_tmf';
mc  = 'make_rtw';
switchTarget(cs,stf,[]);
set_param(cs,'TemplateMakefile',tmf);
set_param(cs,'MakeCommand',mc);

Back to Top

Available Targets

The following table lists supported system target files and their associated code formats. The table also gives references to relevant manuals or chapters in this book. All of these targets are built using the make_rtw make command.

Note   You can select any target of interest using the System Target File Browser. This allows you to experiment with configuration options and save your model with different configurations. However, you cannot build or generate code for non-GRT targets unless you have the appropriate license on your system (Real-Time Workshop® Embedded Coder™ license for ERT, Real-Time Windows Target™ license for RTWIN, and so on).

Each system target file invokes one or more template makefiles. The template makefile that is invoked activates a particular compiler (for example, Lcc, gcc, or Watcom compilers). This is specified for you by MEXOPTS, which is determined when you run mex -setup to select a compiler for mex. One exception is the Microsoft^® Visual C++^® project target, which has separate System Target File Browser entries.

Targets Available from the System Target File Browser

Targets Supporting Nonzero Start Time

When you try to build models with a nonzero start time, if the selected target does not support a nonzero start time, the Real-Time Workshop software does not generate code and displays an error message. The Rapid Simulation (RSim) target supports a nonzero start time when the Configuration Parameters > RSim Target > Solver selection parameter is set to Use Simulink solver module. All other targets do not support a nonzero start time.

Back to Top

Creating Custom Targets

You can create your own system target files to build custom targets that interface with external code or operating environments. If you have in the past created system target files, note that the form of callbacks has changed between Versions 5 and 6 of the Real-Time Workshop product. See the Real-Time Workshop Embedded Coder documentation for details, including how to make your custom targets appear in the System Target File Browser and display appropriate controls in panes of the Configuration Parameters dialog box.

Back to Top

Template Makefiles and Make Options

The Real-Time Workshop product includes a set of built-in template makefiles that are designed to build programs for specific targets.

There are two types of template makefiles:

• Compiler-specific template makefiles are designed for use with a particular compiler or development system.

  By convention, compiler-specific template makefiles are named according to the target and compiler (or development system). For example, grt_vc.tmf is the template makefile for building a generic real-time program under the Visual C++ compiler; ert_lcc.tmf is the template makefile for building a Real-Time Workshop Embedded Coder program under the Lcc compiler.

• Default template makefiles make your model designs more portable, by choosing the correct compiler-specific makefile and compiler for your installation. Choosing and Configuring a Compiler describes the operation of default template makefiles in detail.

  Default template makefiles are named target_default_tmf. They are M-files that, when run, select the appropriate TMF. For example, grt_default_tmf is the default template makefile for building a generic real-time program; ert_default_tmf is the default template makefile for building a Real-Time Workshop Embedded Coder program.

You can supply options to makefiles by using arguments to the Make command field in the general Real-Time Workshop pane of the Configuration Parameters dialog box. Append the arguments after make_rtw (or make_xpc or other make command), as in the following example:

make_rtw OPTS="-DMYDEFINE=1"

The syntax for make command options differs slightly for different compilers.

Complete details on the structure of template makefiles are provided in the Real-Time Workshop Embedded Coder documentation. This information is provided for those who want to customize template makefiles. This section describes compiler-specific template makefiles and common options you can use with each.

Note   To control compiler optimizations for your Real-Time Workshop makefile build at the Simulink GUI level, use the Compiler optimization level option on the Real-Time Workshop pane of the Configuration Parameters dialog box. The Compiler optimization level option provides Target-independent values Optimizations on (faster runs) and Optimizations off (faster builds), which allow you to easily toggle compiler optimizations on and off during code development The value Custom for entering custom compiler optimization flags at Simulink GUI level (rather than at other levels of the build process) If you specify compiler options for your Real-Time Workshop makefile build using OPT_OPTS, MEX_OPTS (except MEX_OPTS="-v"), or MEX_OPT_FILE, the value of Compiler optimization level is ignored and a warning is issued about the ignored parameter.

Template Makefiles for UNIX^® Platforms

The template makefiles for UNIX platforms are designed to be used with the Free Software Foundation's GNU^® Make. These makefile are set up to conform to the guidelines specified in the IEEE^®[4] Std 1003.2-1992 (POSIX) standard.

• ert_unix.tmf

• grt_malloc_unix.tmf

• grt_unix.tmf

• rsim_unix.tmf

• rtwsfcn_unix.tmf

You can supply options by using arguments to the make command.

• OPTS — User-specific options, for example,

  make_rtw OPTS="-DMYDEFINE=1"

• OPT_OPTS— Optimization options. Default is -O. To enable debugging specify as OPT_OPTS=-g. Because of optimization problems in IBM_RS, the default is no optimization.

• CPP_OPTS — C++ compiler options.

• USER_SRCS — Additional user sources, such as files needed by S-functions.

• USER_INCLUDES — Additional include paths, for example,

  USER_INCLUDES="-Iwhere-ever -Iwhere-ever2"

These options are also documented in the comments at the head of the respective template makefiles.

Template Makefiles for the Microsoft^® Visual C++^® Compiler

The Real-Time Workshop product offers two sets of template makefiles designed for use with the Visual C++ compiler.

To build an executable within the Real-Time Workshop build process, use one of the target_vc.tmf template makefiles:

• ert_vc.tmf

• grt_malloc_vc.tmf

• grt_vc.tmf

• rsim_vc.tmf

• rtwsfcn_vc.tmf

You can supply options by using arguments to the make command.

• OPT_OPTS — Optimization option. Default is -O2. To enable debugging specify as OPT_OPTS=-Zd.

• OPTS — User-specific options.

• CPP_OPTS — C++ compiler options.

• USER_SRCS — Additional user sources, such as files needed by S-functions.

• USER_INCLUDES — Additional include paths, for example,

  USER_INCLUDES="-Iwhere-ever -Iwhere-ever2"

These options are also documented in the comments at the head of the respective template makefiles.

Visual C++^® Code Generation Only.   To create a Visual C++ project makefile (model.mak) without building an executable, use one of the target_msvc.tmf template makefiles:

• ert_msvc.tmf

• grt_malloc_msvc.tmf

• grt_msvc.tmf

These template makefiles are designed to be used with nmake, which is bundled with the Visual C++ compiler.

You can supply the following options by using arguments to the nmake command:

• OPTS — User-specific options, for example,

  make_rtw OPTS="/D MYDEFINE=1"

• USER_SRCS — Additional user sources, such as files needed by S-functions.

• USER_INCLUDES — Additional include paths, for example,

  USER_INCLUDES="-Iwhere-ever -Iwhere-ever2"

These options are also documented in the comments at the head of the respective template makefiles.

Template Makefiles for the Watcom C/C++ Compiler

The Real-Time Workshop product provides template makefiles to create an executable for the Microsoft^® Windows^® platform using Watcom C/C++. These template makefiles are designed to be used with wmake, which is bundled with Watcom C/C++.

Note   The Watcom C compiler is no longer available from the manufacturer. However, the Real-Time Workshop product continues to ship with Watcom-related template makefiles.

• ert_watc.tmf

• grt_malloc_watc.tmf

• grt_watc.tmf

• rsim_watc.tmf

• rtwsfcn_watc.tmf

You can supply options by using arguments to the make command. Note that the location of the quotes is different from the other compilers and make utilities discussed in this chapter.

• OPTS — User-specific options, for example,

  make_rtw "OPTS=-DMYDEFINE=1"

• OPT_OPTS — Optimization options. The default optimization option is -oxat. To turn off optimization and add debugging symbols, specify the -d2 compiler switch in the make command, for example,

  make_rtw "OPT_OPTS=-d2"

• CPP_OPTS — C++ compiler options.

• USER_OBJS — Additional user objects, such as files needed by S-functions.

• USER_PATH — The directory path to the source (.c or .cpp) files that are used to create any .obj files specified in USER_OBJS. Multiple paths must be separated with a semicolon. For example,

  USER_PATH="path1;path2"

• USER_INCLUDES — Additional include paths, for example,

  USER_INCLUDES="-Iinclude-path1 -Iinclude-path2"

These options are also documented in the comments at the head of the respective template makefiles.

Template Makefiles for the LCC Compiler

The Real-Time Workshop product provides template makefiles to create an executable for the Windows platform using Lcc compiler Version 2.4 and GNU Make (gmake).

• ert_lcc.tmf

• grt_lcc.tmf

• grt_malloc_lcc.tmf

• rsim_lcc.tmf

• rtwsfcn_lcc.tmf

You can supply options by using arguments to the make command:

• OPTS — User-specific options, for example,

  make_rtw OPTS="-DMYDEFINE=1"

• OPT_OPTS — Optimization options. Default is none. To enable debugging, specify -g4 in the make command:

  make_rtw OPT_OPTS="-g4"

• CPP_OPTS — C++ compiler options.

• USER_SRCS — Additional user sources, such as files needed by S-functions.

• USER_INCLUDES — Additional include paths, for example,

  USER_INCLUDES="-Iwhere-ever -Iwhere-ever2"

  For Lcc, have a / as file separator before the filename instead of a \, for example, d:\work\proj1/myfile.c.

These options are also documented in the comments at the head of the respective template makefiles.

Enabling the Real-Time Workshop^® Software to Build When Path Names Contain Spaces

The Real-Time Workshop software is able to handle path names that include spaces. Spaces might appear in the path from several sources:

• Your MATLAB^® installation directory

• The current MATLAB directory in which you initiate a build

• A compiler you are using for a Real-Time Workshop build

If your work environment includes one or more of the preceding scenarios, use the following support mechanisms, as necessary and appropriate:

• Add the following code to your template makefile (.tmf):

  ALT_MATLAB_ROOT         = |>ALT_MATLAB_ROOT<|
  ALT_MATLAB_BIN          = |>ALT_MATLAB_BIN<|
  !if "$(MATLAB_ROOT)" != "$(ALT_MATLAB_ROOT)"
  MATLAB_ROOT = $(ALT_MATLAB_ROOT)
  !endif
  !if "$(MATLAB_BIN)" != "$(ALT_MATLAB_BIN)"
  MATLAB_BIN = $(ALT_MATLAB_BIN)
  !endif

  This code replaces MATLAB_ROOT with ALT_MATLAB_ROOT when the values of the two tokens are not equal, indicating the path for your MATLAB installation directory includes spaces. Likewise, ALT_MATLAB_BIN replaces MATLAB_BIN.

  Note the preceding code is specific to nmake. See the supplied Real-Time Workshop template make files for platform-specific examples.

• Use the MATLAB command rtw_alt_pathname to translate fully qualified path into standard DOS 8.3 style names. Specify the command with the path you want to translate.

  For example, to translate the path D:\Applications\Common Files, specify the following:

  rtw_alt_pathname('D:\Applications\Common Files')
  ans =
      D:\APPLIC~1\COMMON~1

• When using operating system commands, such as system or dos, enclose path that specify executables or command parameters in double quotes (" "). For example,

  system('dir "D:\Applications\Common Files"')

^[a] UNIX is a registered trademark of The Open Group in the United States and other countries.

^[b] Visual C++ is a registered trademark of Microsoft Corporation.

^[c] Tornado and VxWorks are registered trademarks of Wind River Systems, Inc.

^[4] IEEE is a registered trademark of The Institute of Electrical and Electronics Engineers, Inc.

Back to Top

Code Generation and the Build Process

Choosing and Configuring a Compiler