Late-Breaking News for the MATLAB 5.2 Product Family

Chapter 4
Real-Time Workshop 2.2

Summary of Enhancements Introduced in 2.1

If you are upgrading from Real-Time Workshop® 1.1 to 2.2, note the enhancements that were added in Version 2.1 are also included in Version 2.2. These features are documented in the online version of the Real-Time Workshop User's Guide.

Architectural Changes

The structure of Version 2.1 of the Real-Time Workshop differs significantly from Version 1.1. See Chapter 6 of the Real-Time Workshop User's Guide for more information about the architecture of the Real-Time Workshop; read that chapter if you are interested in how the Real-Time Workshop generates C code.

Target Language Compiler

Part of the Real-Time Workshop's new functionality is a reliance on the Target Language Compiler. For information on what this is, how it works, and how to customize it to your needs, refer to the Target Language Compiler Reference Guide.

Generic Real-Time Target

This release works with fixed-step models that are designed to model real-time systems. A generic real-time target is provided for performing high-speed simulations on your workstation. This target is also a useful example of how to target custom hardware.

Additional Changes

Changes from Version 1.1 include:

The user interface now uses appropriate Simulink model settings.
The external mode, ext_comm.mex file provided by The MathWorks for external mode is now based upon a TCP protocol.

Unsupported Features in Version 2.2

Version 2.2 of the Real-Time Workshop does not currently support:

Nonreal-time simulation of variable-step solvers
The Simulink Accelerator

Upgrading External Mode MEX-Files

You must modify existing external mode link MEX-files slightly and rebuild them.

You must replace the structure definition of ExternalSim_tag and #defines for EXT_x names with:

#include "extsim.h"

Note: When you call mdlCommInitiate, Real-Time Workshop automatically follows that call with a call to mdlSetParameters to download the initial set of parameters.

For more information, see matlabroot/rtw/ext_mode/ext_tmpl.c or matlabroot/rtw/ext_mode/ext_comm.c for a TCP socket-based implementation.

The Real-Time Workshop and Stateflow

If you add Stateflow blocks to your Simulink model, the Real-Time Workshop directs Stateflow to generate two additional files. These files are:

model_rtw.c
model_sfun.c

Tornado/VxWorks

When you use the StethoScope Real-Time Graphical Monitoring/Data Collection Utility (STETHOSCOPE=1 in make command arguments), the build procedure now automatically loads the required StethoScope libraries onto the target system. For more information, see the Tornado template makefile, matlab_root/rtw/c/tornado/tornado.tmf.

There are three functions supplied in matlab_root/rtw/c/tornado/rt_main.c that you can call from a Wind Shell (windsh) window to allow the user to dynamically select signals to be monitored by StethoScope while the real-time simulation is running. To install or remove block outputs in StethoScope interactively, use rt_installSignal and rt_removeSignal, respectively. To print a list of block names that consist of a given string, use rt_lkupBlocks. See rt_main.c for arguments required for these functions.

Note About Automatic Downloading

If the target system is rebooted, the Tornado Target Server and the Tornado Registry may need to be restarted. This can be tested by seeing if the Wind Shell (windsh) can still connect to the target when run from the command line.

Target Language Compiler (TLC) Enhancements

This section describes enhancements to the Target Language Compiler that were not documented in the MATLAB 5.2 Product Family New Features guide.

Passing Parameters: mdlRTW and RTWData

The Real-Time Workshop generates a model.rtw file that is a description of the model. There are two additional methods of passing user-specified information into the model.rtw file:

mdlRTW -- Used with Level 2 S-functions
RTWData -- Used with any nonvirtual Simulink block and with empty subsystems

mdlRTW

Level 2 S-functions can use the mdlRTW function to pass information from a C-MEX S-function into the model.rtw file for use during code generation.

The information that the mdlRTW function writes to model.rtw is used by the block target file for that block type. The writer of the block target file can use the additional identifier/value pairs as desired. For all the possible functions that you can use inside mdlRTW to generate information in the model.rtw file, see the file matlabroot/simulink/src/sfuntmpl.doc. See Chapter 8 of Using Simulink (online version) for a discussion of how to write an mdlRTW function.

Example code

This is an example of how to use mdlRTW in a Level 2 S-function:

static void mdlRTW(SimStruct *S)
{
    int_T numElements = mxGetNumberOfElements(TASK_NAME);
    char *buf = NULL;
    
    if ((buf = malloc(numElements +1)) == NULL) {
        ssSetErrorStatus(S,"memory allocation error in mdlRTW");
        return;
    }
    if (mxGetString(TASK_NAME,buf,numElements+1) != 0) {
        ssSetErrorStatus(S,"mxGetString error in mdlRTW");
        free(buf);
        return;
    }
    /* Write out the parameters for this block.*/
    if (!ssWriteRTWParamSettings(S, 3, 
         SSWRITE_VALUE_QSTR,"TaskName", buf,
         SSWRITE_VALUE_NUM,"Priority",
         (real_T) (*(mxGetPr(PRIORITY))),
         SSWRITE_VALUE_NUM,"StackSize",
         (real_T) (*(mxGetPr(STACK_SIZE))))) {
        return; /* An error occurred which will be reported by SL */
    }
    
    /* Write out names for the IWork vectors.*/
    if (!ssWriteRTWWorkVect(S, "IWork", 1, "TaskID", 1)) {
        return; /* An error occurred which will be reported by SL */
    }
    
    /* Write out names for the PWork vectors.*/
    if (!ssWriteRTWWorkVect(S, "PWork", 1, "SemID", 1)) {
        return; /* An error occurred which will be reported by SL */
    }
    
    free(buf);
}

This code contains the resulting model.rtw information:

    Block {
      . . .
      SFcnParamSettings {
    TaskName""
    Priority20
    StackSize1024
      }
      NumIWorkDefines      1
      IWorkDefine {
    Name         "TaskID"
    Width        1
      }
      NumPWorkDefines      1
      PWorkDefine {
    Name         "SemID"
    Width        1
      }
    }

RTWData

RTWData is a parameter that you can set on Simulink blocks using the set_param() command and view with the get_param() command. The parameter/value pair is saved along with the model.

The command syntax is

set_param(gcb,'rtwdata',userdata)

where gcb is the current block pathname. The variable userdata must be a MATLAB data structure where each element is a string. For example:

userdata.a = 'rpm'
userdata.b = '1.25'

When attached to a nonvirtual block, the associated model.rtw information for the block is:

Block {
. . .
  RTWdata {
    a    "rpm"
    b    "1.25"
  }
}

The block target file for that block type can process the information as desired. For example, if RTWData is attached to a S-function, the TLC inlining file for the S-function could process the information in the BlockInstanceSetup function.

Besides nonvirtual blocks, RTWData can be attached to one special case of a virtual block, an empty subsystem. This allows information the be passed into the model.rtw without it being associated with a specific nonvirtual block. This is useful when some block-independent information needs to be passed into model.rtw for use during code generation. For empty subsystems, the RTWData parameter is placed in the System record for the nonvirtual system in which the empty subsystem is contained.

System {
. . .
  EmptySubsysInfo {
    NumRTWdatas    1
    RTWdata {
      a    "rpm"
      b    "1.25"
    }
  }
}

Because the empty subsystem technique is used by the Custom Code block of the RTWLib, there is support built into the system target files to handle RTWData attached to empty subsystems. Specifically, if an EmptySubsysInfo record exists, all RTWdata subrecords are checked for the existence of an identifier named TLCFile. If the identifier exists, the value of TLCFile is used as a block target filename and the TLC function ProcessRTWdata in that file is called using the TLC GENERATE directive. This functionality can also be used by other (user-written) blocks if desired.

TLC Documentation Updates

These changes were not incorporated into the Target Language Compiler Reference Guide distributed with Real-Time Workshop 2.1.

Some model.rtw files, such as the one appearing in Appendix A of the Target Language Compiler Reference Guide, caused difficulty when the signals were very wide. Compilation also took too long and required excessive memory to process adequately. To address these problems, several extensions to the Target Language Compiler were made in the area of vector handling. The Real-Time Workshop files have been modified to take full advantage of these new constructs.

Changes to Target Language Values Table

Several changes to Table 2-2, Target Language Values, in the Target Language Compiler Reference Guide are necessary.

1.: The "Range" value type should specifically say that range values can only appear within vectors. The "Vector" value type is defined as being lists of values. The individual elements of a vector do not need to be the same type, and can be any type except vectors or matrices.

2.: A new value type, "Repeat," repeats the first value the number of times of the second value. For example, [3@10] is equivalent to
[3 3 3 3 3 3 3 3 3 3].

: Note: This can only appear within the context of a vector. See the "Target Language Vectors" section for information on how to interpret vectors containing repeated values.

3.: Another new value type, "Idrange," represents a range of identifier values where the base name is the leading identifier and the numeric range describes the values that it may take on. For example, [B0:B20] represents [B0, B1, B2, ..., B20].

: Note: This can only appear within the context of a vector. See the "Target Language Vectors" section below for information on how these values are interpreted within vectors.

Target Language Vectors

Note: This is a new section, not an update to an existing section in the Target Language Compiler Reference Guide.

Target language vectors can take advantage of several short-hand notations that make vector specification easier. They can also improve performance and memory requirements of the TLC while it generates the code. The special value types "Range," "Idrange," and "Repeat" are interpreted by the Target Language Compiler as follows:


Value Type String	Example	Description
`"Range"`	`[1:5]`	Equivalent to placing all the numeric values within the range in the vector. For example, `[1:5]` is the same as `[1, 2, 3, 4, 5]`. Specifying ranges in this manner reduces the amount of memory required by the TLC and improves the TLC performance when translating the file. The first number in the range must be less than or equal to the second number.
`"Idrange"`	`[B0:B5]`	Equivalent to placing all of the identifiers within the range in the vector. For example, `[B0:B5]` is the same as `[B0, B1, B2, B3, B4, B5]`. Specifying identifier ranges in this manner reduces the amount of memory required by the TLC and improves the performance when translating the file. Both identifiers in the `Idrange` must be identical (e.g., `B` in this example) and the number in the first identifier must be less than or equal to the number in the second identifier.
`"Repeat"`	`[3@5]`	Repeats the specified value the indicated number of times. For example, `[3@5]` is the same as `[3, 3, 3, 3, 3]`. Specifying repeated values in this way reduces the amount of memory required by the TLC and improves the performance when translating the file. The second argument must be a number.

Changes to the SIZE Built-In Function

When calling the SIZE built-in function or specifying the vector size for the Target Language Compiler, you must count all elements expanded out in such a fashion. For example:

%assign x = Vector(5) [1@5]     %% This is correct; there are 5
                                %% elements in the Vector.

The SIZE function returns 5 for the vector x, and 5 must be specified if you use the Vector(#) syntax. When indexing into a vector, likewise, all of the elements are returned as if they had been enumerated.

Changes to Configurable RTW Variables Table

Several new variables have been added to the Configurable RTW Variables table in Chapter 3, "Writing Target Language Files." The variables are:

ForceParamTrailComments
BlockIOSignals
ParameterTuning

ForceParamTrailComments

The trailing comments for each parameter value in model.prm are not generated when the number of parameters in the model is greater than 1000. Setting ForceParamTrailComments to 1 overrides this behavior.

BlockIOSignals

Setting BlockIOSignals to 1 generates the block I/O signals into model.bio. See the Real-Time Workshop User's Guide for details.

ParameterTuning

Use ParameterTuning to generate parameter mapping information when you want to modify parameters separately from Simulink's external mode. Setting this variable to 1 generates the parameter tuning information file, model.pt. For details see the file MATLAB_ROOT/rtw/c/src/pt_readme.txt. Note that this is an undocumented feature provided for your convenience, and that The MathWorks reserves the right to change the parameter tuning information file in subsequent releases.

Changes to Appendix A, model.rtw

Several of the parameters described in the model.rtw file have been modified.

SignalSrc

If needed, SignalSrc uses the Range (:) and/or Repeat (@) values. The SignalSrc parameter can be found in:

Signal record of either the RootSignals or Subsystem record.
DataInputPort record of a Block record.

SigConnected

SigConnected is now written as all, none, or a vector of ones and zeros. This parameter can be found in the BlockOutput records.

BlockOutputsMap

BlockOutputsMap is now a vector that uses the Range (:) and/or Repeat (@) values. For a given index into the block I/O vector (Bi), this gives the index of the BlockOutput record to which Bi maps. The offset within the record is computed by: Bi - SigIdx[0]

ExternalInputsMap

ExternalInputsMap is now a vector that uses the Range (:) and/or Repeat (@) values. For a given index into the external input vector, Ui, this gives the index of the ExternalInput record to which Ui maps. The offset within the record is computed by: Ui - SigIdx[0]

SignalSrcTID

SignalSrcTID uses the Repeat (@) value when possible.

BlockMap

Within the RootSignals or Subsystem records, BlockMap uses the Range (:) value when possible.

Signal Records

In the Signal records, if Block is a string, then it will optionally be followed by the parameter:

SLBlock -- Unmodified Simulink name. This is only written if Block is a string and is not equal to the block name.

Any SigLabel parameter will optionally be followed by:

SLSigLabel -- Unmodified Simulink label. This is only written if SLSigLabel is not equal to SigLabel.

The Signal records also contain the following parameters:

OutportName -- Only written for subsystem blocks. This is the name of the corresponding outport block.

SLOutportName -- Unmodified Simulink outport block name. This is only written if SLOutportName is not equal to OutportName.

ChildSubsystemIndices

ChildSubsystemIndices is now present in the RootSignals and Subsystem records. This is a vector that gives the subsystem record index for any child subsystems.

StatesMap

StatesMap is a matrix of dimension (NumContStates + NumDiscStates, 3).

New Error Messages for Appendix B

The second value in a range must be greater than the first value.

In valid ranges, the first value in the range must be greater than the second value. For example, [1:0] generates this error.

Invalid identifier range, the leading strings "<identifier>" and
"<identifier>" must match.

When specifying an identifier range, the leading identifiers must match for both ends of the range. For example, [B0:U2] generates this error.

Invalid identifier range, the lower bound (<number>) must be less than the upper bound (<number>).

When specifying an identifier range, the lower bound number must be less than or equal to the upper bound number.

[ Previous | Help Desk | Next ]

Chapter 4Real-Time Workshop 2.2

Example code

Chapter 4
Real-Time Workshop 2.2