Real-Time Workshop Embedded Coder Release Notes

Chapter 1
Real-Time Workshop Embedded Coder 3.0 Release Notes

New Features

This section summarizes the new features and enhancements introduced in the Real-Time Workshop Embedded Coder 3.0.

If you are upgrading from a release earlier than Release 12.1, then you should see the Real-Time Workshop Embedded Coder 2.0 Release Summary. For an introduction to the Real-Time Workshop Embedded Coder and for information about demos for the product, see the "Product Overview" section of the Real-Time Workshop Embedded Coder User's Guide.

New User's Guide

The Real-Time Workshop Embedded Coder is now documented in a separate manual, the Real-Time Workshop Embedded Coder User's Guide. The new manual includes and updates the information about the Real-Time Workshop Embedded Coder that was formerly included in the Real-Time Workshop User's Guide.

The new manual also includes an appendix on generating ASAP2 files.

Auto-generated Main Program

The new Generate an example main program option lets you generate a fully commented, model-specific example main program module, ert_main.c. The code requires minimal modification for deployment in your environment. You can generate the example main program as either:

• A bare-board program designed to run under control of a real-time clock, without a real-time operating system
• An example showing how to deploy the code under the VxWorks real-time operating system

By default, Generate an example main program is on. Note that once you have generated and customized the main program, you should take care to avoid overwriting your customized version.

See the "Data Structures and Program Execution" section of the section of the Real-Time Workshop Embedded Coder User's Guide for further information about the operation of the main program module.

The Real-Time Workshop Embedded Coder continues to provide a static (non-generated) version of ert_main.c as a template example for developing embedded applications. To use the static version of ert_main.c (or continue using a customized version):

• Turn Generate an example main program off.
• Read the next section, Modifying the Static Main Program Module and make changes to ert_main.c as required by your application.

Modifying the Static Main Program Module

This section describes modifications you may need to make to use the static version of ert_main.c (or continue using a customized version).

• The multi-rate scheduling code that was in ert_main.c is now generated with the model code. Therefore, if your model has multiple rates, note that multi-rate systems will not operate correctly unless:
• The multirate scheduling code is removed. The relevant code is tagged with the keyword REMOVE in comments. (see also the Version 3.0 comments in ert_main.c)
• Use the MODEL_SETEVENTS macro (defined in ert_main.c) to set the event flags instead of accessing the flags directly. The relevant code is tagged with the keyword REPLACE in comments.
• Remove #include ertformat.h directives. ertformat.h is no longer required. The following macros, formerly defined in ertformat.h, are now defined within ert_main.c:

• EXPAND_CONCAT
  CONCAT
  MODEL_INITIALIZE
  MODEL_STEP
  MODEL_TERMINATE
  MODEL_SETEVENTS
  RT_OBJ
  

• If applicable, follow comments in the code regarding where to add code for reading/writing model I/O and saving/restoring FPU context.
• When the Generate an example main program option is off, the Real-Time Workshop Embedded Coder generates the file autobuild.h to provide an interface between the main module and generated model code. If you create your own static main program module, you would normally include autobuild.h.

• Alternatively, you can suppress generation of autobuild.h, and include model.h directly in your main module. To suppress generation of autobuild.h, use the following statement in your system target file:

  • %assign AutoBuildProcedure = 0
    

• If you have cleared the Terminate function required option, remove or comment out the following in your production version of ert_main.c:
• The #if TERMFCN... compile-time error check
• The call to MODEL_TERMINATE
• If you do not want to combine output and update functions, clear the Single output/update function option and make the following changes in your production version of ert_main.c:
• Replace calls to MODEL_STEP with calls to MODEL_OUTPUT and MODEL_UPDATE.
• Remove the #if ONESTEPFCN... error check.
• The static ert_main.c module does not support the Generate Reusable Code option. Use this option only if you are generating a main program. The following error check will raise a compile-time error if Generate Reusable Code is used illegally.

• #if MULTI_INSTANCE_CODE==1
  

• The static ert_main.c module does not support the External Mode option. Use this option only if you are generating a main program. The following error check will raise a compile-time error if External Mode is used illegally.

• #ifdef EXT_MODE
  

Code Generation Options

This section describes new Real-Time Workshop Embedded Coder code generation options. These options are available via the ERT code generation options menus of the Real-Time Workshop page of the Simulation Parameters dialog box.

External Mode

Select this option to generate external mode communications support code in the target program. See also External Mode Support.

Generate an Example Main Program

This option lets you generate a model-specific example main program module. See Auto-generated Main Program.

Generate Reusable Code

When this option is selected, the Real-Time Workshop Embedded Coder generates reusable, reentrant code for the model. See Reusable Code Generation.

Include Model Name in Global Data Structures

This option is available via the ERT code generation options (2) menu item of the Real-Time Workshop page of the Simulation Parameters dialog box.

When this option is selected (the default), the name of the model (model_) is prefixed to the symbolic names of generated global data structures. This option is useful in cases where you want to compile and link code from two or more models into a single executable. Turning Include model name in global data structures on in such cases will avoid name clashes.

Parameter Structure

See Hierarchical Parameter Structures

Suppress Error Status in Real-Time Model Data Structure

If you do not need to log or monitor error status in your application, select this option.

By default, the real-time model data structure (rtM) includes an error status field (data type string). This field lets you log and monitor error messages via macros provided for this purpose (see model.h). The error status field is initialized to NULL. If Suppress error status in real-time model data structure is selected, the error status field is not included in rtM. Selecting this option may also cause the real-time model data structure to disappear completely from the generated code.

Target Floating Point Math Environment

This popup menu provides two options. If you select the ANSI_C option (the default), the Real-Time Workshop Embedded Coder generates calls to the ANSI C (ANSI X3.159-1989) math library for floating point functions. If you select the ISO_C option, Real-Time Workshop Embedded Coder generates calls to the ISO C (ISO/IEC 9899:1999) math library wherever possible.

If your target compiler supports the ISO C (ISO/IEC 9899:1999) math library, we recommend selecting the ISO_C option and setting your compiler's ISO C option. This will generate calls to the ISO C functions wherever possible (for example, sqrtf() instead of sqrt() for single precision data) and ensure that you obtain the best performance your target compiler offers.

If your target compiler does not support ISO C math library functions, use the ANSI_C option.

ECRobot Target Example

The ECRobot (Embedded Coder Robot) target is a simple example of a custom target based on the Real-Time Workshop Embedded Coder. The ECRobot target was originally developed as a training example for use in classes offered to Real-Time Workshop Embedded Coder users. In this release, the ECRobot target is available to all Real-Time Workshop Embedded Coder users as an example and demonstration.

The ECRobot target files are automatically installed with the Real-Time Workshop Embedded Coder. Source code files, control files, demonstration models, and documentation for the target are installed in the directory

• matlabroot/toolbox/rtw/targets/ECRobot
  

Note    The ECRobot target requires an operating system kernel, a cross-compiler and support utilities that are available on the Web. For instructions on how to obtain and install these utilities, see the file ECRobot_ReadMe.txt in the ECRobot/documentation directory.

Note that the ECRobot target uses a Windows-based cross-compiler and other utilities; it is therefore hosted on Windows 2000 or Windows XP. A UNIX configuration is not planned.

Programs generated by the ECRobot target run on the Command System (RCX^TM) module of the LEGO® MINDSTORMS^TM Robotics Invention System2.0^TM. This platform affords an inexpensive and simple way to study concepts and techniques essential to developing a custom embedded target, and to develop, run and observe generated programs.

The files included with the target illustrate typical approaches to problems encountered in custom target development, including:

• Interfacing a Real-Time Workshop Embedded Coder generated program to an external real-time operating system (RTOS) or kernel.
• Implementing device drivers, via wrapper S-functions, for use in simulation and inlined code generation.
• Customizing a system target file by adding code generation options and adding the target to the System Target File Browser.
• Customizing a template makefile to use a target specific cross compiler and download generated code to the target hardware.

Note    The Robot Car: An Embedded Target Example document does not cover all current features of the ECRobot target. The document will be updated for the final r13 release.

External Mode Support

The Real-Time Workshop Embedded Coder now includes full support for all features of Simulink external mode. External mode lets you use your Simulink block diagram as a front end for a target program that runs on external hardware or in a separate process on your host computer. External mode allows you to tune parameters and view or log signals as the target program executes.

The External mode option is available via the ERT code generation options (2) menu item of the Real-Time Workshop page of the Simulation Parameters dialog box.

See the External Mode section of the Real-Time Workshop User's Guide for further information.

GetSet Custom Storage Class
for Data Store Memory

A new custom storage class, GetSet, has been added to provide acessor methods for memory associated with Data Store Memory blocks. This custom storage class is used in conjunction with Data Store Memory blocks. The properties of the GetSet class are:

• GetFunction (string)
• SetFunction (string)
• HeaderFile (string)
• IncludeDelimeter (enumerated property, same as in the ImportFromFile class)

This class supports signals of non-complex data types. Its purpose is to generate code that reads (gets) and writes (sets) data via functions. For example, if the GetFunction for signal x is specified as "get_x" then the generated code will call get_x() wherever the value of x is used. If the SetFunction for signal x is specified as "set_x" then the generated code will call set_x(value) wherever the value of x is assigned.

For wide signals, an additional index argument is passed, as in:

• get_x(idx)
  set_x(value, idx)
  

See also the "Custom Storage Classes" section of the Real-Time Workshop Embedded Coder User's Guide.

Hierarchical Parameter Structures

The Parameter structure menu lets you control how parameter data is generated for reusable subsystems. (If you are not familiar with reusable subsystem code generation, see "Nonvirtual Subsystem Code Generation Options" in the Real-Time Workshop User's Guide for further information.)

The Parameter structure menu is available via the ERT code generation options (3) menu item of the Real-Time Workshop page of the Simulation Parameters dialog box.

The Parameter structure menu is enabled when the Inline parameters option is on. The menu lets you select the following options:

• Hierarchical: This option is the default. When the Hierarchical option is selected, the Real-Time Workshop Embedded Coder generates a separate header file, defining an independent parameter structure, for each subsystem that meets the following conditions:
• The Reusable function option is selected in the subsystem's RTW system code pop-up menu, and the subsystem meets all conditions for generation of reusable subsystem code.
• The subsystem does not access any parameters other than its own (such as parameters of the root-level model).

• When the Hierarchical option is selected, each generated subsystem parameter structure is referenced as a substructure of the root-level parameter data structure, which is therefore called a hierarchical data structure.

• Non-hierarchical: When this option is selected, the Real-Time Workshop Embedded Coder generates a single parameter data structure. This is a flat data structure; subsystem parameters are defined as fields within this structure.

Real-Time Model Structure Replaces
Real-Time Object and Logging Object

The Real-Time Workshop Embedded Coder now encapsulates information about the root model in the real-time model data structure. We will refer to the real-time model data structure as rtM.

rtM replaces the real-time object (RT_OBJ) and the logging object, which were used in previous releases. If your code accesses these objects through the macros provided with previous releases, it will continue to work.

See the "Data Structures and Program Execution" section of the Real-Time Workshop Embedded Coder User's Guide for further information.

Reusable Code Generation

The Generate reusable code option lets you generate reusable, reentrant code from a model or subsystem. When this option is selected, data structures such as block states, parameters, external outputs, etc. are passed in (by reference) as arguments to model_step and other generated model functions. These data structures are also exported via model.h.

In some cases, the Real-Time Workshop Embedded Coder may generate code that will compile but is not reentrant (although it may still be acceptable for your application). For example, if a signal or parameter has a storage class other than Auto, the generated code is not reentrant, because the code must access the global data directly. To handle such cases, the Reusable code error diagnostic menu is enabled when Generate reusable code is selected. This menu offers a choice of three severity levels for diagnostics to be displayed in such cases:

• None: build proceeds without displaying a diagnostic message.
• Warn: build proceeds after displaying a warning message.
• Error: build aborts after displaying an error message.

In some cases, the Real-Time Workshop Embedded Coder is unable to generate valid and compilable code. For example, if the model contains an S-Function that is not code-reuse compliant, or a subsystem triggered by a wide function call trigger, the code generated would be invalid. In these cases, the build will abort unconditionally.

When Generate reusable code option is not selected (the default), model data structures are statically allocated and accessed directly in the model code. Therefore the model code is neither reusable nor reentrant.

Revised Packaging of Generated Code Files

The packaging of generated code into.c and.h files has changed. The following table summarizes the structure of source code generated by the Real-Time Workshop Embedded Coder. All code modules described are written to the build directory.

Note    The file packaging of the Real-Time Workshop Embedded Coder differs slightly (but significantly) from the file packaging employed by the GRT, GRT malloc, and other non-embedded targets. See the Real-Time Workshop User's Guide for further information.

Table 1-1: Real-Time Workshop Embedded Coder File Packaging

File	Description
model.c	Contains entry points for all code implementing the model algorithm (model_step, model_initialize, model_terminate, model_SetEventsForThisBaseStep).
model_private.h	Contains local defines and local data that are required by the model and subsystems. This file is included by subsystem .c files in the model. You do not need to include model_private.h when interfacing hand-written code to a model. Note that model_private.h is sub-included by model.h.
model.h	Defines model data structures and a public interface to the model entry points and data structures. Also provides an interface to the real-time model data structure (model_rtM) via accessor macros. model.h is included by subsystem .c files in the model. If you are interfacing your hand-written code to generated code for one or more models, you should include model.h for each model to which you want to interface.
model_data.c (conditional)	model_data.c is conditionally generated. It contains the declarations for the parameters data structure and the constant block I/O data structure. If these data structures are not used in the model, model_data.c is not generated. Note that these structures are declared extern in model.h.
model_types.h	Provides forward declarations for the real-time model data structure and the paramters data structure. These may be needed by function declarations of reusable functions. model_types.h is included by all subsystem .h files in the model.
ert_main.c (optional)	This file is generated only if the Generate an example main program option is on. (This option is on by default). See Auto-generated Main Program.
autobuild.h (optional)	This file is generated only if the Generate an example main program option is off. See Auto-generated Main Program. autobuild.h contains #include directives required by the static version of the ert_main.c main program module. Since the static ert_main.c is not created at code generation time, it includes autobuild.h to access model-specific data structures and entry points.

If you have interfaced hand-written code to code generated by previous releases of the Real-Time Workshop Embedded Coder, you may need to remove dependencies on header files that are no longer generated. Use #include model.h directives, and remove #include directives referencing any of the following:

• model_common.h (replaced by model_types.h and model_private.h)
• model_export.h (replaced by model.h)
• model_prm.h (replaced by model_data.c)
• model_reg.h (subsumed by model_.c

Template Makefile for Tornado

We have provided a simplified version of the Tornado target template makefile support deployment of Real-Time Workshop Embedded Coder code on the VxWorks operating system. See matlabroot/rtw/c/ert/ert_tornado.tmf for details.

Real-Time Workshop Embedded Coder Release Notes

Upgrading from an Earlier Release