Real-Time Workshop®

Block State Storage and Interfacing

Introduction

For certain block types, the Real-Time Workshop^® product lets you control how block states in your model are stored and represented in the generated code. Using the State properties tab of a block dialog box, you can

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

• Assign symbolic names to block states in generated code.

Back to Top

Block State Storage

The discussion of block state storage in this section applies to the following block types:

• Discrete Filter

• Discrete State-Space

• Discrete-Time Integrator

• Discrete Transfer Function

• Discrete Zero-Pole

• Memory

• Unit Delay

These block types require persistent memory to store values representing the state of the block between consecutive time intervals. By default, such values are stored in a data type work vector. This vector is usually referred to as the DWork vector. It is represented in generated code as model_DWork, a global data structure. For more information on the DWork vector, see the Target Language Compiler documentation.

If you want to interface a block state to your hand-written code, you can specify that the state is to be stored in a location other than the DWork vector. You do this by assigning a storage class to the block state.

You can also define a symbolic name, to be used in code generation, for a block state.

Back to Top

Block State Storage Classes

The storage class property of a block state specifies how the Real-Time Workshop product declares and stores the state in a variable. Storage class options for block states are similar to those for signals. The available storage classes are

• Auto

• ExportedGlobal

• ImportedExtern

• ImportedExternPointer

Default Storage Class

Auto is the default storage class. Auto is the appropriate storage class for states that you do not need to interface to external code. States with Auto storage class are stored as members of the Dwork vector.

You can assign a symbolic name to states with Auto storage class. If you do not supply a name, the Real-Time Workshop product generates one, as described in Symbolic Names for Block States.

Explicitly Assigned Storage Classes

Block states with storage classes other than Auto are stored in unstructured global variables, independent of the Dwork vector. These storage classes are appropriate for states that you want to interface to external code. The following storage classes are available for states:

• ExportedGlobal: The state is stored in a global variable. model.h exports the variable. States with ExportedGlobal storage class must have unique names.

• ImportedExtern: model_private.h declares the state as an extern variable. Your code must supply the proper variable definition. States with ImportedExtern storage class must have unique names.

• ImportedExternPointer: model_private.h declares the state as an extern pointer. Your code must supply the proper pointer variable definition. States with ImportedExternPointer storage class must have unique names.

The table in Summary of Signal Storage Class Options gives examples of variable declarations and the code generated for block states with each type of storage class.

Note   Assign a symbolic name to states to specify a storage class other than auto. If you do not supply a name for auto states, the Real-Time Workshop product generates one, as described in Symbolic Names for Block States.

The next section explains how to use the State Properties dialog box to assign storage classes to block states.

Back to Top

Using the State Properties Dialog Box to Interface States to External Code

The State Properties tab of the relevant blocks' parameter dialog boxes lets you interface a block's state to external code by assigning the state a storage class other than Auto (that is, ExportedGlobal, ImportedExtern, or ImportedExternPointer).

Set the storage class as follows:

1. In your block diagram, double-click the desired block. This opens the block dialog box containing two or more tabs, one of which is State properties. Alternatively, you can right-click the block and select Block properties from the context menu.

2. Click the State Properties tab. The State Properties dialog appears.

   

3. Enter a name for the variable to be used to store block state in the State name field.

   The State name field turns yellow to indicate that you changed it.

4. Click Apply to register the variable name.

   The first two fields beneath the State name, State name must resolve to Simulink signal object and RTW storage class, become enabled.

5. If the state is to be stored in a Simulink^® signal object in the base or model workspace, select State name must resolve to Simulink signal object.

   If you choose this option, you cannot declare a storage class for the state in the block, and the fields below becomes disabled.

6. Select the desired storage class (ExportedGlobal, ImportedExtern, or ImportedExternPointer) from the RTW storage class menu.

7. 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.

8. Click OK or Apply and close the dialog box.

Back to Top

Symbolic Names for Block States

To determine the variable or field name generated for a block's state, you can either

• Use a default name generated by the Real-Time Workshop product

• Define a symbolic name by using the State Name field of the State Properties dialog box

Default Block State Naming Convention

If you do not define a symbolic name for a block state, the Real-Time Workshop product uses the following default naming convention:

BlockType#_DSTATE

where

• BlockType is the name of the block type (for example, Discrete_Filter).

• # is a unique ID number (#) assigned by the Real-Time Workshop product if multiple instances of the same block type appear in the model. The ID number is appended to BlockType.

• _DSTATE is a string that is always appended to the block type and ID number.

For example, consider the model shown in the next figure.

Model with Two Discrete Filter Block States

Examine the code generated for the states of the two Discrete Filter blocks. Assume that:

• Neither block's state has a user-defined name.

• The upper Discrete Filter block has Auto storage class (and is therefore stored in the DWork vector).

• The lower Discrete Filter block has ExportedGlobal storage class.

The states of the two Discrete Filter blocks are stored in DWork vectors, initialized as shown in the code below:

/* data type work */
disc_filt_states_M->Work.dwork = ((void *) 
&disc_filt_states_DWork);
    (void)memset((char_T *) &disc_filt_states_DWork, 0,
     sizeof(D_Work_disc_filt_states));
    {
      int_T i;
      real_T *dwork_ptr = (real_T *) 
&disc_filt_states_DWork.DiscFilt_DSTATE;

      for (i = 0; i < 2; i++) {
        dwork_ptr[i] = 0.0;
      }
    }

User-Defined Block State Names

Using the State Properties dialog box, you can define your own symbolic name for a block state. To do this,

1. In your block diagram, double-click the desired block. This opens the block dialog box, containing two or more tabs, one of which is State properties.

   Alternatively, you can right-click the block and select Block properties from the context menu.

2. Click the State properties tab.

3. Enter the symbolic name in the State name field of the State Properties dialog box. For example, enter the state name Top_filter.

4. Click Apply. The dialog box now looks like this:

   

5. Click OK or Cancel to dismiss the block dialog box.

The following state initialization code was generated from the example model shown in figure ???, under the following conditions:

• The upper Discrete Filter block has the state name Top_filter, and Auto storage class (and is therefore stored in the DWork vector).

• The lower Discrete Filter block has the state name Lower_filter, and storage class ExportedGlobal.

Top_filter is placed in the Dwork vector.

/* data type work */
    disc_filt_states_M->Work.dwork = ((void *)
&disc_filt_states_DWork);
    (void)memset((char_T *) &disc_filt_states_DWork, 0,
    sizeof(D_Work_disc_filt_states));
    disc_filt_states_DWork.Top_filter = 0.0;

    /* exported global states */
    Lower_filter = 0.0;

Back to Top

Block States and Simulink^® Signal Objects

If you are not familiar with Simulink data objects and signal objects, you should read Simulink^® Data Objects and Code Generation before reading this section.

You can associate a block state with a signal object, and control code generation for the block state through the signal object. To do this,

1. Instantiate the desired signal object, and set its RTWInfo.StorageClass property as you require.

2. Open the State Properties dialog box for the block whose state you want to associate with the signal object.

3. Enter the name of the signal object in the State name field.

4. Select State name must resolve to Simulink signal object.

   The Simulink product disables the RTW storage class and RTW storage type qualifier options in the State Properties dialog box, because the signal object specifies these settings.

5. Click Apply and close the dialog box.

   Note   When a block state is associated with a signal object, the mapping between the block state and the signal object must be one to one. If two or more identically named entities, such as a block state and a signal, map to the same signal object, the name conflict is flagged as an error at code generation time.

Back to Top

Summary of State Storage Class Options

Here is a simple model, unit_delay.mdl, which contains a Unit Delay block:

The following table shows, for each state storage class option, the variable declaration and initialization code generated for a Unit Delay block state. The block state has the user-defined state name udx.

typedef struct 
D_Work_unit_delay_tag 
{
  real_T udx;
 }
D_Work_unit_delay;

unit_delay_DWork.udx = 0.0;

real_T udx;

extern real_T udx; 

udx = 0.0;

extern real_T udx; 

udx = 
  unit_delay_P.UnitDelay_X0; 

extern real_T *udx; 

(*udx) = 
  unit_delay_P.UnitDelay_X0; 

Back to Top

Simulink® Data Objects and Code Generation

Storage Classes for Data Store Memory Blocks