Skip to Main Content Skip to Search
Home |   Select Country  Choose Country  |  Contact Us  |  Cart Store 
Create Account | Log In
Products & Services Industries Academia Support User Community Company

 

MATLAB Digest - May 2003

Configuring the Code Generator and Tailoring the Build Process for Embedded Targeting

by Pete Szpak, John Duesenberry, and Tom Erkkinen

This article features a collection of tips and best practices for users of Real-Time Workshop, Real-Time Workshop Embedded Coder, and related embedded targets. These tips address how to configure the code generator for your target and tailor the build process to fit into your development environment:

  • Tip 1: Customize Your Target Build Process via the STF_make_rtw Hook File
  • Tip 2: Specify Target-Specific Information for Your Target
  • Tip 3: Autoconfigure Models for Code Generation
  • Tip 4: Manage Projects Using the Autoconfiguration Utilities and Hook Files

Unless specified, the tips are independent of each other and do not have to be read in numerical order. It is particularly important to follow Tip 2, however, which helps you configure the target-specific parameters so that correct code is generated.

To access the M-file utilities for these tips, download the zip file that accompanies the article, "Real-Time Workshop Targeting Tips and Scripts." Unzip this file and read Abstract.txt, which features instructions and describes the various files and contents in the package.

Tip 1: Customize Your Target Build Process via the STF_make_rtw Hook File

The build process lets you supply optional hook files that are executed at specified points in the code-generation and make process. You can use hook files to add target-specific actions to the build process.

This tip describes an important M-file hook, generically referred to as STF_make_rtw_hook.m. This hook file implements a function that dispatches to a specific action, which is dependent on the passed method argument. The build process automatically calls STF_make_rtw_hook.m and passes the correct method argument into it and other arguments described below. You need to implement only those methods that your build process requires.

To ensure that STF_make_rtw_hook.m is called correctly by the build process, you should:

  • Insert the STF_make_rtw_hook.m file in the MATLAB path.
  • Ensure that the filename is the name of your system target file (STF), appended to the string '_make_rtw_hook.m'. For example, if you were generating code via the default Real-Time Workshop Embedded Coder system target file (ert.tlc), then you would name your STF_make_rtw_hook.m file to ert_make_rtw_hook.m.
  • Confirm that the hook function implemented in the file follows the function prototype described below.

STF_make_rtw_hook.m Function Prototype and Arguments

The function prototype for STF_make_rtw_hook is: function STF_make_rtw_hook(hookMethod, modelName, rtwRoot, templateMakefile, buildOpts, buildArgs)

The arguments are defined as:

  • hookMethod: String specifying the stage of build process from which the STFname_make_rtw_hook function is called. Figure 1 below summarizes the build process and highlights the hook points in red. Possible values are 'entry', 'before_tlc', 'before_make', and 'exit'. The STFname _make_rtw_hook function dispatches to the relevant code via a switch statement.
Build process flowchart
Figure 1: Build process flowchart (hooks indicated in red).

  • rtwRoot: Reserved.
  • modelName: String specifying the name of the model. Valid at all stages of the build process.
  • templateMakefile: Name of template makefile.
  • buildOpts: A MATLAB structure containing the member fields described in the table below. Valid for the 'before_make' and 'exit' stages.
buildOpts Fields
modules Char array specifying a list of generated C files: model.c, model_data.c, etc.
codeFormat Char array containing code format: 'RealTime', 'RealTimeMalloc', 'Embedded-C', and 'S-Function'
noninlinedSFcns Cell array specifying list of noninlined S-Functions
compilerEnvVal String specifying compiler environment variable value, e.g., C:\Applications\Microsoft Visual

buildArgs: Character array containing the argument to make_rtw. When you invoke the build process via the Build button or the direct command rtwbuild ('model'), buildArgs is copied from the argument string (if any) following 'make_rtw' in the Make command edit field of the Real-Time Workshop Target configuration options.

Specifying build options
Figure 2: Specifying build options. Click on image to see enlarged view.

Note that buildArgs (shown in Figure 2) is automatically passed to produce: % make -f ecdemo.mk VAR1=0 VAR2=4

Applications for STF_make_rtw_hook.m

An enumeration of all possible uses for STF_make_rtw_hook.m is beyond the scope of this tip. We can, however, suggest some ways in which you might apply the available hooks.

The 'entry' hook is ideal for autoconfiguring a model, as described in Tip 3. In general, you can use this hook to prepare your target requirements.

The other hook points 'before_tlc', 'before_make', and 'exit', are ideal for interfacing with external tool chains, source control tools, and other environment tools.

The STF_make_rtw_hook.m file can also help you obtain the build directory. You might use this directory to locate generated-code files and check them into your version control system. This directory (most likely in the ‘exit’ stage) can also help you find the generated executable within the build directory and download it to the target hardware via a target-specific utility.

You can obtain the build directory anytime after the 'entry' stage using this function: rtwprivate('rtwattic','getBuildDir')

The build process temporarily changes the MATLAB directory to the build directory for stages 'before_make' and 'exit'.

Using STF_make_rtw_hook.m for Your Build Procedure

Follow these steps to customize your build procedure:
  1. Copy the attached ert_make_rtw_hook.m file to a directory in the MATLAB path. This file works automatically with the Real-Time Workshop Embedded Coder system target file (ert.tlc). If you are using a different target, rename the file in accordance with the naming conventions described above. For example, rename it to grt_make_rtw_hook.m to use it with the default GRT target grt.tlc.
  2. Rename the function within the file to match the filename.
  3. Implement the hooks that you require by adding code to the appropriate case statements within the switch hookMethod statement. Tip 3 and Tip 4 contain code examples.

Tip 2: Specify Target-Specific Information for Your Target

You need to specify word sizes for integer data types (such as short, int, and long), and for the C implementation-specific properties of your target (such as integer overflow behavior) because the C language does not specify this information.

If these settings are wrong, incorrect code may be generated.

The build process lets you specify this information by providing another hook file, generically referred to as STF_rtw_info_hook.m. To ensure that STF_rtw_info_hook.m is called correctly by the build process, the following conditions must be met:

  • The STF_rtw_info_hook.m file is in the MATLAB path.
  • The filename is the name of your system target file (STF), appended to the string "_rtw_info_hook.m". For example, if you were generating code via the default Real-Time Workshop Embedded Coder system target file (ert.tlc), you would name your STF_rtw_info_hook.m file to ert_rtw_info_hook.m.

If STF_rtw_info_hook.m already exists, the build process invokes this file to extract the necessary target-specific information. Otherwise, the word size and C-implementation details default to values appropriate to the host system. The STF_rtw_info_hook.m implements a function that contains a switch Action statement with two cases:

  • The case 'wordlengths' configures the word lengths appropriate for your target.
  • The case 'cImplementation' configures the C-implementation details for your target.

Setting up STF_rtw_info_hook.m

To set up the STF_rtw_info_hook.m file described above for your target:

  1. Access the example hook file, STF_rtw_info_hook.m, from matlabroot\toolbox\rtw\rtwdemos\
    example_rtw_info_hook.m.     and copy example_rtw_info_hook.m to a desired directory.
  2. Rename example_rtw_info_hook.m in accordance with the naming convention above (for example, to ert_rtw_info_hook.m if using ert.tlc).
  3. Add this directory to the MATLAB path if it is not already there.
  4. Change the name of the function defined in the hook file to match your STF (for example, ert_rtw_info_hook).
  5. Configure the word lengths in the case 'wordlengths' of the switch Action statement in the hook file. If your target is the host computer, use the following code: varargout{1} = rtwhostwordlengths(modelName);
    Otherwise, specify the word sizes of your target to read: value.CharNumBits = 8;
    value.ShortNumBits = 16;
    value.IntNumBits = 32;
    value.LongNumBits = 32;
    If you are unfamiliar with these properties, see the "Hook Files for Communicating Target-specific Word Characteristics" section of the Real-Time Workshop documentation.
  6. In the case 'cImplementation' of the switch Action statement, configure the C-implementation details for your target. If your target is the host computer, use the following code: varargout{1} = rtw_host_implementation_props(modelName);
    Otherwise, specify the details for your target to read: value.ShiftRightIntArith = true;
    value.Float2IntSaturates = false;
    value.IntPlusIntSaturates = false;
    value.IntTimesIntSaturates = true;
    If you are unfamiliar with these properties, see the "Hook Files for Communicating Target-Specific Word Characteristics" section of the Real-Time Workshop documentation.

It can be difficult to determine the target-specific information, particularly the C-implementation details. The word size information is contained in your compiler’s limits.h file. Another useful and robust method of determining the correct settings is to use the demo model rtwtargetsettings. The demo will generate code that you can execute on your target to obtain the actual target settings. Simply load this model and type the demo name rtwtargetsettings at the MATLAB command prompt.

You can emulate your target’s execution environment during simulation, rapid prototyping, or for any arbitrary Real-Time Workshop embedded target. To do this, you need to provide target word lengths and implementation details within Simulink: Simulation->Simulation Parameters->Advanced->Production Hardware Characteristics.

When the generated code is planned for execution on the production target, then the Production Hardware Characteristics settings should match those in the STF_rtw_info_hook.m file. Fortunately, a synching mechanism for this is in the EntryConfiguration function in the STF_make_rtw_hook.m file described in Tip 1.

Tip 3: Autoconfigure Models for Code Generation

In the zip file package, we have provided the utility M-Files uset_param.m and uget_param.m. You can use these utilities with ert_make_rtw_hook.m to automate the configuration of a model as part of code generation. The M-files let you configure all code-generation options relevant to Simulink, Stateflow, Real-Time Workshop, and Real-Time Workshop Embedded Coder. This technique helps you avoid manually configuring a model prior to code generation, saving you time and eliminating potential errors.

The example ert_make_rtw_hook.m hook file implements the function: function EntryConfiguration(model)
EntryConfiguration calls uset_param.m to set all parameters of the model. The entire list of options is documented in uset_param.xls (an Excel spreadsheet). You can change any of the settings in the example to suit your target needs.

As shown below, EntryConfiguration is called from the 'entry' stage of the build process. At the 'exit' stage, the previous model settings are restored (see the following code excerpt). Note that the EntryConfiguration call is made within a try/catch block so that in the event of a build error, the model settings will also be restored.

switch hookMethod
case 'entry'
% Called at start of code generation process
% (before anything happens.) disp('Auto configuring model for ERT target.');
uset_param(modelName,'BackupSettings');
try
EntryConfiguration(modelName);
catch
uset_param(modelName,'RestoreSettings');
error(lasterr)
end
case 'exit'
% Called at the end of the RTW build process.
% All arguments are valid at this stage. disp('Restoring model configuration.');
uset_param(modelName,'RestoreSettings');
end

Using the Autoconfiguration Utilities

To use the autoconfiguration utilities during your make process as described above:

  1. Set up the example ert_make_rtw_hook.m as your STF_make_rtw_hook file (see "Using STF_make_rtw_hook.m" above).
  2. Copy uset_param.m and uget_param.m to a directory in the MATLAB path.
  3. Reconfigure the uset_param calls within ert_make_rtw_hook.m to suit your application needs. Tip 4 provides one common usage example.

Tip 4: Manage Projects Using the Autoconfiguration Utilities and Hook Files

Embedded system developers and project managers need to consistently develop and manage large systems of many models. Model style guidelines help address this need as do the establishment of project-wide, code-generation and compiler-configuration settings. This tip demonstrates how to apply the hook files and autoconfiguration utilities described in the previous tips to manage code-generation settings.

Displaying Default Configuration Values within the Model

Code-generation configuration occurs by using the ert_make_rtw_hook.m file as described in Tip 1. These settings are not visible to developers during model inspection or simulation, however. The config_ert_project.m script included in the zip file package addresses this, as shown below, by first loading the model and then applying default embedded real-time target (ERT) code-generation settings so that they can be viewed from within the model.

Loading the model:
try
open_system(modelName);
catch
error(['Unable to access model: ',
modelName]);
end

Applying default settings using ConfigurationDefault function:
stf = deblank(get_param(modelName,
'RTWSystemTargetFile'));
if strmatch('ert', stf)
ConfigurationDefault(modelName);
...
disp(['Configured ', modelName,' using default
ERT project codegen settings.']);
To invoke config_ert_project.m for an existing model:

  • Ensure that the config_ert_project.m file is in your MATLAB path
  • Invoke the script from MATLAB or as shown from your Windows Run command prompt:
    matlab -r config_ert_project(‘modelName’)

This script will work for targets other than ERT, including the generic real-time (GRT) target, but warnings will be issued noting that some parameters could not be set. You can ignore these warnings.

Using the startup.m file is another option for invoking and using scripts that are important for managing projects. We will not discuss this file here because it is covered under MATLAB online help under Development Environment: Starting and Quitting MATLAB: Startup Options.

Establishing Multiple Code-Generation Configuration Options

The settings in the above ConfigurationDefault function match those in the EntryConfiguration function of the ert_make_rtw_hook.m file. However, other configuration variations were created and included with this tip including ConfigurationDebug and ConfigurationOptimized. To use one of these during model load, simply substitute it for ConfigurationDefault in config_ert_project.m.

You can also use these configuration files during code generation by employing a modified version of the make hook file, adv_ert_make_rtw_hook.m. This version of the hook file also supports an override setting that applies the model’s current configuration settings instead of those within a configuration file. buildArgs described in Tip 1 specifies configuration options from the Simulation->Simulation Parameters->Real-Time Workshop build window.

The buildArgs options made available for this example include:
-opt (Configuration based on optimized code efficiency)
-debug (Configuration based on maximum clarity and traceability)
-model (Configuration based on current model settings) If no options are specified, the default configuration in EntryConfiguration is used.

To invoke config_ert_project.m:

  • Ensure that configuration files are in your MATLAB path
  • Save or rename the existing ert_make_rtw_hook.m
  • Rename adv_ert_make_rtw_hook.m to ert_make_rtw_hook.m
  • Set the desired configuration option in the Make command of Simulation->Simulation Parameters->Real-Time Workshop build window
  • Generate code
Specifying build option to use model settings
Figure 3: Specifying build option to use model settings.
Click on image to see enlarged view.

The example above uses the -model option. This causes the current model parameters to be used instead of a configuration file. While useful during development, project managers may want to restrict this capability during later stages of the project to ensure that a consistent configuration is used for the final software build.

Simplifying model configuration and maximizing target optimization is an active area of development at The MathWorks. The targeting tips presented here leverage our work with the Model Assistant Tool, which was presented in the January issue of MATLAB Digest. Contact Tom Erkkinen if you have particular project configuration needs or wish to share a tip.
Contact sales
E-mail this page
Print this page
Subscribe to newsletters