Real-Time Workshop®

Signal Storage, Optimization, and Interfacing

Introduction

The Real-Time Workshop product offers a number of options that let you control how signals in your model are stored and represented in the generated code. This section discusses how you can use these options to

• Control whether signal storage is declared in global memory space or locally in functions (that is, in stack variables).

• Control the allocation of stack space when using local storage.

• Ensure that particular signals are stored in unique memory locations by declaring them as test points.

• Reduce memory usage by instructing the Real-Time Workshop product to store signals in reusable buffers.

• Control whether or not signals declared in generated code are interfaceable (visible) to externally written code. You can also specify that signals are to be stored in locations declared by externally written code.

• Preserve the symbolic names of signals in generated code by using signal labels.

The discussion in the following sections refers to code generated from signal_examp, the model shown in the next figure.

Signal_examp Model

Back to Top

Signal Storage Concepts

This section discusses structures and concepts you must understand to choose the best signal storage options for your application:

• The global block I/O data structure model_B

• The concept of signal storage classes as used in the Real-Time Workshop product

The Global Block I/O Structure

By default, the Real-Time Workshop product attempts to optimize memory usage by sharing signal memory and using local variables.

However, there are a number of circumstances in which it is desirable or necessary to place signals in global memory. For example,

• You might want a signal to be stored in a structure that is visible to externally written code.

• The number and/or size of signals in your model might exceed the stack space available for local variables.

In such cases, it is possible to override the default behavior and store selected (or all) signals in a model-specific global block I/O data structure. The global block I/O structure is called model_B (in earlier versions this was called rtB).

The following code shows how model_B is defined and declared in code generated (with signal storage optimizations off) from the signal_examp model shown in the Signal_examp Model figure.

(in signal_examp.h)
/* Block signals (auto storage) */
extern BlockIO_signal_examp signal_examp_B;

(in signal_examp.c)
/* Block signals (auto storage) */
BlockIO_signal_examp signal_examp_B;

Field names for signals stored in model_B are generated according to the rules described in Symbolic Naming Conventions for Signals in Generated Code.

Signals Storage Classes

In the Real-Time Workshop product, the storage class property of a signal specifies how the product declares and stores the signal. In some cases this specification is qualified by more options.

In the context of the Real-Time Workshop product, the term "storage class" is not synonymous with the term storage class specifier, as used in the C language.

Default Storage Class.   Auto is the default storage class. Auto is the appropriate storage class for signals that you do not need to interface to external code. Signals with Auto storage class can be stored in local and/or shared variables or in a global data structure. The form of storage depends on the Signal storage reuse, Reuse block outputs, Enable local block outputs, and Minimize data copies between local and global variables options, and on available stack space. See Signals with Auto Storage Class for a full description of code generation options for signals with Auto storage class.

Explicitly Assigned Storage Classes.   Signals with storage classes other than Auto are stored either as members of model_B, or in unstructured global variables, independent of model_B. These storage classes are appropriate for signals that you want to monitor and/or interface to external code.

The Signal storage reuse, Enable local block outputs, Reuse block outputs, Eliminate superfluous local variables (Expression folding), and Minimize data copies between local and global variables optimizations do not apply to signals with storage classes other than Auto.

Use the Signal Properties dialog box to assign these storage classes to signals:

• SimulinkGlobal(Test Point): Test points are stored as fields of the model_B structure that are not shared or reused by any other signal. See Signals with Test Points for more information.

• ExportedGlobal: The signal is stored in a global variable, independent of the model_B data structure. model.h exports the variable. Signals with ExportedGlobal storage class must have unique signal names. See Interfacing Signals to External Code for more information.

• ImportedExtern: model_private.h declares the signal as an extern variable. Your code must supply the proper variable definition. Signals with ImportedExtern storage class must have unique signal names. See Interfacing Signals to External Code for more information.

• ImportedExternPointer: model_private.h declares the signal as an extern pointer. Your code must define a valid pointer variable. Signals with ImportedExtern storage class must have unique signal names. See Interfacing Signals to External Code for more information.

Back to Top

Signals with Auto Storage Class

Options are available for signals with Auto storage class:

• Signal storage reuse

• Enable local block outputs

• Reuse block outputs

• Eliminate superfluous local variables (Expression folding)

• Minimize data copies between local and global variables

Use these options to control signal memory reuse and choose local or global (model_B) storage for signals. The Signal storage reuse option is on the Optimization pane of the Configuration Parameters dialog box, as shown in the next figure.

When you select Signal storage reuse, the Enable local block outputs, Reuse block outputs, Eliminate superfluous local variables (Expression folding), and Minimize data copies between local and global variables options in the Code Generation section of the dialog box are enabled.

These options interact. When the Signal storage reuse option is selected,

• The Reuse block outputs option is enabled and selected, and signal memory is reused whenever possible.

• The Enable Local block outputs option is enabled and selected. This lets you choose whether reusable signal variables are declared as local variables in functions or as members of model_B.

• The Eliminate superfluous local variables (Expression folding) is enabled and selected, and block computations collapse into single expressions.

• The Minimize data copies between local and global variables is enabled and cleared, and global memory is not reused.

The following code examples illustrate the effects of the Signal storage reuse, Enable Local block outputs, Reuse block outputs, Eliminate superfluous local variables (Expression folding) and Minimize data copies between local and global variables options. The examples were generated from the signal_examp model (see figure Signal_examp Model).

The first example illustrates signal storage optimization, with Signal storage reuse, Enable Local block outputs, Reuse block outputs, and Minimize data copies between local and global variables selected. (For clarity in showing the individual Gain and Sum block computation, expression folding is off in this example.) The output signal from the Sum block reuses signal_examp_Y.Out1, a variable local to the model output function.

/* Model output function */
static void signal_examp_output(int_T tid)
{
  /* Sum: '<Root>Sum' incorporates:
   *  Constant: '<Root>/Constant'
   *  Inport: '<Root>>/In1'
   */
  signal_examp_Y.Out1 = signal_examp_U.In1 + signal_examp_P.Constant_Value;
  
  /* Gain: '<Root>/Gain' */
  signal_examp_Y.Out1 = signal_examp_P.Gain_Gain * signal_examp_Y.Out1;

  /* tid is required for a uniform function interface.
   * Argument tid is not used in the function. */
  UNUSED_PARAMETER(tid);
}

If you are constrained by limited stack space, you can turn Enable local block outputs off and still benefit from memory reuse. The following example was generated with Enable local block outputs cleared and Signal storage reuse, Reuse block outputs, and Minimize data copies between local and global variables selected. The output signals from the Sum and Gain blocks use global structure signal_examp_B rather than declaring local variables and in both cases the signal name is gainSig.

/* Model output function */
static void signal_examp_output(int_T tid)
{
  /* Sum: '<Root>/Add' incorporates:
   *  Constant: '<Root>/Constant'
   *  Inport: '<Root>/In1'
   */
  signal_examp_B.gainSig = signal_examp_U.In1 + 
    signal_examp_P.Constant_Value;

  /* Gain: '<Root>/Gain' */
  signal_examp_B.gainSig = signal_examp_P.Gain_Gain * 
    signal_examp_B.gainSig;

  /* Outport: '<Root>/Out1' */
  signal_examp_Y.Out1 = signal_examp_B.gainSig;
  
  /* tid is required for a uniform function interface.
   * Argument tid is not used in the function. */
  UNUSED_PARAMETER(tid);
}

When the Signal storage reuse option is cleared, Reuse block outputs, Enable local block outputs, and Minimize data copies between local and global variables are disabled. This makes the block output signals global and unique, signal_examp_B.sumSig and signal_examp_B.gainSig, as shown in the following code.

/* Model output function */
static void signal_examp_output(int_T tid)
{
  /* Sum: '<Root>/Add' incorporates:
   *  Constant: '<Root>/Constant'
   *  Inport: '<Root>/In1'
   */
  signal_examp_B.sumSig = signal_examp_U.In1 + 
    signal_examp_P.Constant_Value;

  /* Gain: '<Root>/Gain' */
  signal_examp_B.gainSig = signal_examp_P.Gain_Gain * 
    signal_examp_B.sumSig;

  /* Outport: '<Root>/Out1' */
  signal_examp_Y.Out1 = signal_examp_B.gainSig;

  /* tid is required for a uniform function interface.
   * Argument tid is not used in the function. */
  UNUSED_PARAMETER(tid);
}

In large models, disabling Signal storage reuse can significantly increase RAM and ROM usage. Therefore, this approach is not recommended for code deployment; however it can be useful in rapid prototyping environments.

The following table summarizes the possible combinations of the Signal storage reuse / Reuse block outputs and Enable local block outputs options.

Controlling Stack Space Allocation

When the Enable local block outputs option is on, the following TLC variables constrain the use of stack space by local block output variables:

• MaxStackSize: The maximum number of bytes the Real-Time Workshop product allocates for local variables declared by all block outputs in a model. MaxStackSize can be any positive integer. If the total size of local block output variables exceeds this maximum, the product allocates the remaining block output variables in global, rather than local, memory. The default value for MaxStackSize is Inf, that is, unlimited stack size.

  Note   Local variables in the generated code from sources other than local block outputs and stack usage from sources such as function calls and context switching are not included in the MaxStackSize calculation. For overall executable stack usage metrics, you should do a target-specific measurement, such as using run-time (empirical) analysis or static (code path) analysis with object code.

• MaxStackVariableSize: The maximum number of bytes n, where n is greater than zero, the Real-Time Workshop product allocates for any local block output variable declared in the code. The product allocates any variable with a size that exceeds MaxStackVariableSize in global, rather than local, memory. The default is 4096 bytes.

You may need to adjust the settings of these variables when working with models that contain large signals. When a variable exceeds MaxStackVariableSize, the Real-Time Workshop product places the variable in global memory space. Similarly, if the accumulated size of variables in local memory exceeds MaxStackSize, the product places subsequent local variables in global memory space. The Real-Time Workshop product analyzes the accumulated size of local variables based on a worst-case scenario without taking into account that local variables are released after functions return.

Consider the following options for your specific model:

• Is it important that you maximize potential for signal storage optimization? If so, set MaxStackSize appropriately to accommodate the size and number of signals in your model. This minimizes overflow into global memory space and maximizes use of local memory. Local variables offer more optimization potential through mechanisms such as expression folding and buffer reuse.

• Is the accumulated size of local variables exceeding the MaxStackSize setting? If so, consider setting MaxStackVariableSize to a value that forces large local variables into the global memory space and helps retain smaller local variables in local storage.

See Setting Target Language Compiler Options for more information.

Back to Top

Signals with Test Points

A test point is a signal that is stored in a unique location no other signals share or reuse. See Working with Test Points in the Simulink documentation for information about including test points in your model.

When you generate code for models that include test points, the Real-Time Workshop build process allocates a separate memory buffer for each test point. Test points are stored as members of the model_B structure.

Declaring a signal as a test point disables the following options for that signal. This can lead to increased code and data size. You do not lose the benefits of optimized storage for any other signals in your model.

• Signal storage reuse

• Enable local block outputs

• Reuse block outputs

• Eliminate superfluous local variables (Expression folding)

• Minimize data copies between local and global variables

For an example of storage declarations and code generated for a test point, see Summary of Signal Storage Class Options.

Back to Top

Interfacing Signals to External Code

The Simulink Signal Properties dialog box lets you interface selected signals to externally written code. In this way, your hand-written code has access to such signals for monitoring or other purposes. To interface a signal to external code, use the Real-Time Workshop tab of the Signal Properties dialog box to assign one of the following storage classes to the signal:

• ExportedGlobal

• ImportedExtern

• ImportedExternPointer

Set the storage class as follows:

1. In your Simulink block diagram, select the line that carries the signal. Then select Signal Properties from the Edit menu of your model. This opens the Signal Properties dialog box. Alternatively, right-click the line that carries the signal, and select Signal properties from the menu.

2. Select the Real-Time Workshop tab of the Signal Properties dialog box.

3. Select the desired storage class (Auto, ExportedGlobal, ImportedExtern, or ImportedExternPointer) from the RTW storage class menu. The next figure shows ExportedGlobal selected.

   

4. Optional: For storage classes other than Auto, you can enter a storage type qualifier such as const or volatile in the RTW storage type qualifier field. The Real-Time Workshop product does not check this string for errors; whatever you enter is included in the variable declaration.

5. Click Apply.

   Note   You can also interface test points and other signals that are stored as members of model_B to your code. To do this, your code must know the address of the model_B structure where the data is stored, and other information. This information is not automatically exported. The Real-Time Workshop product provides C/C++ and Target Language Compiler APIs that give your code access to model_B and other data structures. See C API for Interfacing with Signals and Parameters for more information.

Back to Top

Symbolic Naming Conventions for Signals in Generated Code

When signals have a storage class other than Auto, the Real-Time Workshop product preserves symbolic information about the signals or their originating blocks in the generated code.

For labeled signals, field names in model_B derive from the signal names. In the following example, the field names model_B.sumSig and model_B.gainSig are derived from the corresponding labeled signals in the signal_examp model (shown in figure Signal_examp Model).

/* Block signals (auto storage) */
typedef struct _BlockIO_signal_examp {
    real_T sumSig;                        /* '<Root>/Add' */
    real_T gainSig;                       /* '<Root>/Gain' */
} BlockIO_signal_examp;

When you clear the Signal Storage Reuse optimization, sumSig is not part of model_B, and a local variable is used for it instead. For unlabeled signals, model_B field names are derived from the name of the source block or subsystem.

The components of a generated signal label are

• The root model name, followed by

• The name of the generating signal object, followed by

• A unique name mangling string (if required)

The number of characters that a signal label can have is limited by the Maximum identifier length parameter specified on the Symbols pane of the Configuration Parameters dialog box. See Configuring Generated Identifiers for more detail.

When a signal has Auto storage class, the Real-Time Workshop build process controls generation of variable or field names without regard to signal labels.

Back to Top

Summary of Signal Storage Class Options

The next table shows, for each signal storage class option, the variable declaration and the code generated for Sum (sumSig) and Gain (gainSig) block outputs of the model shown in figure Signal_examp Model.

real_T rtb_sumSig;

rtb_sumSig = signal_examp_U.In1 +
  signal_examp_P.Constant_Value;
rtb_sumSig *=
  signal_examp_P.Gain_Gain;
signal_examp_Y.Out1 = rtb_sumSig;

typedef struct
_BlockIO_signal_examp 
{
  real_T sumSig;
}
BlockIO_signal_examp;

BlockIO_signal_examp
signal_examp_B; 
real_T rtb_gainSig;

signal_examp_B.sumSig =
  signal_examp_U.In1 +
  signal_examp_P.Constant_Value;
rtb_gainSig = 
  signal_examp_B.sumSig * 
  signal_examp_P.Gain_Gain;
signal_examp_Y.Out1 = rtb_gainSig;

extern real_T sumSig;

real_T sumSig; 
real_T rtb_gainSig; 

sumSig = signal_examp_U.In1 +
signal_examp_P.Constant_Value;
rtb_gainSig = sumSig *
  signal_examp_P.Gain_Gain;
signal_examp_Y.Out1 = rtb_gainSig;

extern real_T sumSig;

real_T rtb_gainSig;

sumSig = signal_examp_U.In1 +
signal_examp_P.Constant_Value;
rtb_gainSig = sumSig *
  signal_examp_P.Gain_Gain;
signal_examp_Y.Out1 = rtb_gainSig;

extern real_T *sumSig;

real_T rtb_gainSig;

(*sumSig) = signal_examp_U.In1 +
  signal_examp_P.Constant_Value;
rtb_gainSig = (*sumSig) *
  signal_examp_P.Gain_Gain;
signal_examp_Y.Out1 = rtb_gainSig;

Back to Top

Parameter Storage, Interfacing, and Tuning

Parameter Tuning and Signal Monitoring