Applying CSCs to Parameters and Signals :: Creating and Using Custom Storage Classes (Real-Time Workshop® Embedded Coder™)

Learn more about Real-Time Workshop Embedded Coder

Applying CSCs to Parameters and Signals

On this page…
About Applying Custom Storage Classes Applying a Custom Storage Class to a Parameter Applying a Custom Storage Class to a Signal Applying a CSC Using a Base Workspace Signal Object Applying a CSC Using an Embedded Signal Object Specifying a Custom Storage Class Using the GUI Specifying a Custom Storage Class Using the API

On this page…

About Applying Custom Storage Classes

Applying a Custom Storage Class to a Parameter

Applying a Custom Storage Class to a Signal

Applying a CSC Using a Base Workspace Signal Object

Applying a CSC Using an Embedded Signal Object

Specifying a Custom Storage Class Using the GUI

Specifying a Custom Storage Class Using the API

About Applying Custom Storage Classes

You can apply a custom storage class to a parameter or a signal using the GUI or the API.

To apply a custom storage class to a parameter, you specify the storage class in the Simulink.Parameter object that defines the parameter in the base workspace.
To apply a custom storage class to a signal, you specify the storage class in a Simulink.Signal object that is bound to the signal. You can provide this object in two ways:
- Create the object in the base workspace, then bind it to the signal as described in Resolving Symbols. When you save the model, you must save the object in a separate file, as with any base workspace object.
- Use the Signal Properties dialog box to embed the object in the model on the port where the signal originates. When you save the model, Simulink automatically saves the embedded signal object as part of the model file.

Most of the GUI techniques, and most of the API techniques, are the same for parameter and signal objects, and for base workspace and embedded signal objects. Only the initial steps differ, after which you apply the same GUI or API instructions within the context that you established in the initial steps.

The following instructions assume that you have already created any needed packages, custom storage classes, and memory sections, as described in Creating Packages that Support CSC Definitions and Designing Custom Storage Classes and Memory Sections.

Applying a Custom Storage Class to a Parameter

To apply a custom storage class to a parameter, you specify the storage class in the Simulink.Parameter object that defines the parameter in the base workspace. The instructions that begin in this section show you how to create that object using the GUI or API. Later instructions show you how to specify a custom storage class and custom attributes.

For information about using parameter objects to specify block parameter values, see Working with Block Parameters in the Simulink documentation. For information about parameter storage in generated code, see Parameter Considerations in the Real-Time Workshop documentation.

Providing a Parameter Object Using the GUI

In the Model window, choose View > Model Explorer.
In the Model Hierarchy pane, select the Base Workspace.
Click the Add Parameter tool or choose Add > Simulink Parameter.
Simulink creates a Simulink.Parameter object with a default name:
Change the parameter name as needed by editing it in the Contents pane. Example: MyParam.
Set parameter attributes other than Code generation options in the Dialog pane.
Follow the instructions in Specifying a Custom Storage Class Using the GUI.

Providing a Parameter Object Using the API

In the MATLAB Command Window, enter:
```
ParamName=ParamClass
```
where ParamClass is Simulink.Parameter or any subclass of it that you have defined.

Simulink creates a ParamClass object with the specified name:

MyParam =
 
Simulink.Parameter (handle)
          Value: []
        RTWInfo: [1x1 Simulink.ParamRTWInfo]
    Description: ''
       DataType: 'auto'
            Min: -Inf
            Max: Inf
       DocUnits: ''
     Complexity: 'real'
     Dimensions: [0 0]

Set parameter attributes other than RTWInfo, which controls custom storage classes.
Follow the instructions in Specifying a Custom Storage Class Using the API.

Applying a Custom Storage Class to a Signal

To apply a custom storage class to a signal, you specify the storage class in a Simulink.Signal object. This object can exist in either of two locations:

In the MATLAB base workspace
On the port where the signal originates

The object itself is the same in either case; only its location and some of the techniques for managing it differ. The instructions that begin in this section show you how to create a signal object in either location using the GUI or API. Later instructions show you how to specify the custom storage class and custom attributes.

A given signal can be associated with at most one signal object under any circumstances. The signal can refer to the object more that once, but every reference must resolve to exactly the same object. A different signal object that has exactly the same properties will not meet the requirement for uniqueness. A compile-time error occurs if a model associates more than one signal object with any signal.

Assigning a signal to any non-Auto storage class automatically makes the signal a test point, overriding the setting of Signal Properties > Logging and accessibility > Test point. See Working with Test Pointsfor more information.

For information about using signal objects to specify signal attributes, see Working with Signals in the Simulink documentation. For information about signal storage in generated code, see Signal Considerations in the Real-Time Workshop documentation.

Applying a CSC Using a Base Workspace Signal Object

The first step is to create the signal object in the base workspace, after which you specify any needed signal attributes and the custom storage class and attributes.

Providing a Base Workspace Signal Object Using the GUI

In the Model window, choose View > Model Explorer.
In the Model Hierarchy pane, select the Base Workspace.
Click the Add Signal tool or choose Add > Simulink Signal.
Simulink creates a Simulink.Signal object with a default name:
Change the signal name as needed by editing it in the Contents pane. Example: MySig.
Set signal attributes other than Code generation options in the Dialog pane.
Give the signal the same name as the signal object, as described in Naming Signals.
Arrange for the signal to resolve to the object, as described in Resolving Symbols.
Follow the instructions in Specifying a Custom Storage Class Using the GUI.

Providing a Base Workspace Signal Object Using the API

In the MATLAB Command Window, enter:
```
SignalName=SignalClass
```
where SignalClass is Simulink.Signal or any subclass of it that you have defined.

Simulink creates a SignalClass object with the specified name:

MySig =
 
Simulink.Signal (handle)
         RTWInfo: [1x1 Simulink.SignalRTWInfo]
     Description: ''
        DataType: 'auto'
             Min: -Inf
             Max: Inf
        DocUnits: ''
      Dimensions: -1
      Complexity: 'auto'
      SampleTime: -1
    SamplingMode: 'auto'
    InitialValue: ''

Set parameter attributes other than RTWInfo, which controls custom storage classes.
Give the signal the same name as the signal object, as described in Naming Signals.
Arrange for the signal to resolve to the object, as described in Resolving Symbols.
Follow the instructions in Specifying a Custom Storage Class Using the API.

Applying a CSC Using an Embedded Signal Object

You can use the GUI or the API to apply a CSC using an embedded signal object.

If you use the GUI, you use the Signal Properties dialog box to specify the attributes you want. The software then creates a Simulink.Signal object and assigns it to the output port where the signal originates.
If you use the API, you instantiate Simulink.Signal or a subclass of it, set the attribute values that you want, and assign the object to the output port where the signal originates.

In either case, the effect on code generation is the same as if you had created a base workspace signal object that specified the same name, CSC, and custom attributes as the embedded signal object. See Applying a CSC Using a Base Workspace Signal Object for details.

The advantages of using embedded signal objects are that they do not clutter the base workspace, and they do not need to be saved separately from the model, as base workspace objects do. When you save a model, Simulink saves any embedded signal objects in the model file, and reloads the objects when you later reload the model.

The disadvantage of embedded signal objects is that you can use such an object only to specify a custom storage class, custom attributes, and an alias; you must accept the default values for all other signal attributes. You cannot work around this restriction by providing additional information in a base workspace signal object on the same signal, because a signal object can have at most one associated signal object, as described in Multiple Signal Objects.

Providing an Embedded Signal Object using the GUI

Give the signal a name, which must be a valid ANSI C identifier. Example: MySig.
Right-click the signal and choose Signal Properties from the context menu.
The Signal Properties dialog box opens:
Do not select Signal name must resolve to Simulink signal object. Selecting it would require a base workspace signal object, which would conflict with the embedded signal object.
Click the Real-Time Workshop tab:
The Package is initially ---None---. When no package is specified, only the non-custom built-in storage classes defined for both GRT and ERT targets are available:

Applying a storage class when the package is ---None--- sets internal storage class attributes rather than creating an embedded signal object. For more information, see Signal Considerations and Simulink Data Object Considerations in the Real-Time Workshop documentation.
To apply a custom storage class, you must first specify the package where it is defined. Initially, viewing the Package menu displays only the built-in Simulink and mpt packages:
Click Refresh to load any other available packages, including user-defined packages, available on the MATLAB path. After a brief delay, a timer box tracks the progress of the package search. After the search completes, viewing the Package menu displays all available packages:

Once you have used Refresh in any Signal Properties dialog, Simulink saves the information for later use, so you do not have to click Refresh again during the current MATLAB session.
Select the package that contains the custom storage class you want to apply, e.g. Simulink:
Follow the instructions in Specifying a Custom Storage Class Using the GUI.

Deleting an Embedded Signal Object Using the GUI

To delete an embedded signal object with the GUI, delete the name of the signal to which the object applies, by editing the name in the graphical model or in the Signal Properties dialog box. Simulink automatically deletes the embedded signal object as soon as its signal has no name.

Providing an Embedded Signal Object using the API

To provide an embedded signal object using the API, you create the object, set its custom storage class and any custom attributes, then assign the object to the output port on which it will be embedded.

Name the signal if it does not already have a name. The name must be a valid ANSI C identifier.
In the MATLAB Command Window, enter:
```
SignalName=SignalClass
```
where SignalClass is Simulink.Signal or any subclass of it that you have defined. The name of the signal object does not need to match the name of the signal to which the object will be applied.

Simulink creates a SignalClass object with the specified name. Example:

MySig =
 
Simulink.Signal (handle)
         RTWInfo: [1x1 Simulink.SignalRTWInfo]
     Description: ''
        DataType: 'auto'
             Min: -Inf
             Max: Inf
        DocUnits: ''
      Dimensions: -1
      Complexity: 'auto'
      SampleTime: -1
    SamplingMode: 'auto'
    InitialValue: ''

Do not set any attributes. An embedded signal object can specify only custom storage class information.
Follow the instructions in Specifying a Custom Storage Class Using the API. After specifying the custom storage class, be sure to assign the signal object to its output port, as described under Assigning an Embedded Signal Object to an Output Port.

Changing an Embedded Signal Object Using the API

To change an embedded signal object using the API, you obtain a copy of the object from the output port on which it is embedded, change the object as needed, then assign the changed object back to the port.

Obtain a copy of the signal object using a handle to the output port. Example:

hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
MySig=get_param(hp,'SignalObject')

Change the signal object using the techniques described in Specifying a Custom Storage Class Using the API. After making the changes, be sure to copy the signal object to its output port, as described in Assigning an Embedded Signal Object to an Output Port.

Deleting an Embedded Signal Object Using the API

To delete an embedded signal object with the API, obtain a handle to the output port where the signal object is embedded, then set the port's SignalObject parameter to []:

hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
set_param(hp,'SignalObject',[])

Specifying a Custom Storage Class Using the GUI

The initial steps for applying a CSC with the GUI differ depending on whether you are applying the CSC to a parameter using a base workspace object, to a signal using a base workspace object, or to a signal using an embedded object. The initial steps for each of these three cases appear in:

After the initial steps, applying a CSC with the GUI is the same in all three cases. The following instructions show you how to finish applying a CSC with the GUI. The instructions assume that you have completed one of the previous sets of instructions, and that the dialog you used to execute those instructions is still open. If necessary, return to the relevant section and restore the situation that existed at its end, then return to this section.

The dialog that you used to begin the process of applying a CSC with the GUI by providing an object contains two fields: one for specifying a custom storage class and one for optionally specifying an alias. These fields are the same in all three of the dialogs that you might use:

Storage class is Auto because that is the default storage class in the Simulink package. Other packages may have different defaults. You can specify an Alias whenever the Storage class is not Auto. If Storage class is Auto, Simulink deletes any alias you try to specify, leaving the field blank. If you specify an alias, it appears in generated code instead of the name of the object.

To specify a custom storage class and its custom attributes:

View the Storage Class menu, which looks like this for the Simulink package:

Each custom storage class has (custom) suffixed to its name. The storage classes SimulinkGlobal, ExportedGlobal, ImportedExtern, and ImportedExternPointer are the built-in non-custom storage classes described in Signal Considerations and Simulink Data Object Considerations in the Real-Time Workshop documentation.
Choose the desired custom storage class from Storage class, for example, Struct.
If the storage class defines any custom attributes, fields for defining them appear:
Provide values for any custom attributes. Struct has only one, Struct name. For example, set Struct name to MyStruct:
Click Apply.

In generated code, all data whose storage is controlled by this custom storage class specification will appear in a structure named MyStruct. See Generating Code with Custom Storage Classes for an example.

Specifying a Custom Storage Class Using the API

The initial steps for applying a CSC with the API differ depending on whether you are applying the CSC to a parameter using a base workspace object, to a signal using a base workspace object, or to a signal using an embedded object. The initial steps for each of these three cases appear in:

After the initial steps, applying a CSC with the API is the same in all three cases, except for an assignment needed only by an embedded signal object. The following instructions show you how to finish applying a CSC with the API. The instructions assume that you have completed one of the previous sets of instructions, and that the resulting objects an attributes are unchanged. If necessary, return to the relevant section and restore the situation that existed at its end, then return to this section.

The instructions given in this section apply to all packages, but the available custom storage classes and custom attributes depend on the package that you select. The examples in this section assume that you are using the Simulink package. The examples also assume that the object for which you want to specify a custom storage class is named MyObj, which is a parameter or signal object that exists in the base workspace, or a signal object that will be assigned to an output port.

The rest of this section provides information that is specific to custom storage classes in Real-Time Workshop Embedded Coder. See Simulink Package Custom Storage Classes for a list of the custom storage classes that are built into the Simulink package for use by Real-Time Workshop Embedded Coder software.

RTWInfo Properties

Each Simulink parameter object or signal object defines properties called RTWInfo properties. Real-Time Workshop uses these properties to control storage class assignment in generated code. The RTWInfo properties and their default values are:

          StorageClass: 'Auto'
                 Alias: ''
    CustomStorageClass: 'Default'
      CustomAttributes: [1x1 SimulinkCSC.AttribClass_Simulink_Default]

For more information about RTWInfo properties, see Signal Considerations and Simulink Data Object Considerations in the Real-Time Workshop documentation.

Specifying a Custom Storage Class

To specify a custom storage class using RTWInfo properties:

Set StorageClass to 'Custom'.
Set CustomStorageClass to the name of the storage class.

For example, to specify the Struct custom storage class:

MyObj.RTWInfo.StorageClass='Custom'
MyObj.RTWInfo.CustomStorageClass='Struct'

Whenever you have specified a custom storage class other than Auto, you can specify an alias by setting the Alias attribute. If you specify an alias, it appears in generated code instead of the name of the object.

Specifying Instance-Specific Attributes

A custom storage class can have properties that define attributes that are specific to that CSC. Such properties are called instance-specific attributes. For example, if you specify the Struct custom storage class, you must specify the name of the C language structure that will store the data. That name is an instance-specific attribute of the Struct CSC.

Instance-specific attributes are stored in the RTWInfo property CustomAttributes. This property is initially defined as follows:

SimulinkCSC.AttribClass_Simulink_Default
1x1 struct array with no fields

When you specify a custom storage class, Simulink automatically populates RTWInfo.CustomAttributes with the fields necessary to represent any instance-specific attributes of that CSC. For example, if you set the MySig CSC to Struct, as described in Specifying a Custom Storage Class, then enter:

MyObj.RTWInfo.CustomAttributes

MATLAB displays:

SimulinkCSC.AttribClass_Simulink_Struct
    StructName: ''

To specify that StructName is MyStruct, enter:

MyObj.RTWInfo.CustomAttributes.StructName='MyStruct'

MATLAB displays:

SimulinkCSC.AttribClass_Simulink_Struct
    StructName: 'MyStruct'

Simulink Package CSC Instance-Specific Properties

Class Name	Instance-Specific Property	Purpose
`BitField`	`CustomAttributes.StructName`	Name of the bitfield `struct` into which the code generator packs the object's Boolean data.
`ExportToFile`	`CustomAttributes.HeaderFile`	Name of header (`.h`) file that contains exported variable declarations and export directives for the object.
`GetSet`	`CustomAttributes.HeaderFile`	Name of header (`.h`) file to `#include` in the generated code. See GetSet Custom Storage Class for Data Store Memory.
	`CustomAttributes.GetFunction`	String that specifies the name of a function call to read data.
	`CustomAttributes.SetFunction`	String that specifies the name of a function call to write data.
`ImportedDefine`	`CustomAttributes.HeaderFile`	The header file that defines the values of code variant preprocessor conditionals. See Generating Code Variants for Variant Models.
`ImportFromFile`	`CustomAttributes.HeaderFile`	Name of header (`.h`) file containing global variable declarations the code generator imports for the object.
`Struct`	`CustomAttributes.StructName`	Name of the `struct` into which the code generator packs the object's data.

Assigning an Embedded Signal Object to an Output Port

If you are operating on an embedded signal object with the API, you must copy the object to the port after providing or changing its RTWInfo properties. For example, if MyObj is a signal object that you want to copy to the output port, enter:

hps=get_param(gcb,'PortHandles')
hp=hps.Outport(1)
set_param(hp,'SignalObject','MyObj')

Subsequent changes to the source object in the base workspace have no effect on the output port copy, and you can delete the source object if you have no further use for it:

clear ('MyObj')

Designing Custom Storage Classes and Memory Sections

Generating Code with Custom Storage Classes

Related Products & Applications

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit