Learn more about Real-Time Workshop Embedded Coder

Designing Custom Storage Classes and Memory Sections

On this page…
Using the Custom Storage Class Designer Editing Custom Storage Class Properties Using Custom Storage Class References Creating and Editing Memory Section Definitions Using Memory Section References

Using the Custom Storage Class Designer

The Custom Storage Class Designer (cscdesigner) is a tool for creating and managing custom storage classes and memory sections. You can use the Custom Storage Class Designer to:

• Load existing custom storage classes and memory sections and view and edit their properties

• Create new custom storage classes and memory sections

• Create references to custom storage classes and memory sections defined in other packages

• Copy and modify existing custom storage class and memory section definitions

• Verify the correctness and consistency of custom storage class and memory section definitions

• Preview pseudocode generated from custom storage class and memory section definitions

• Save custom storage class and memory section definitions

To open the Custom Storage Class Designer, type the following command at the MATLAB prompt:

cscdesigner

When first opened, the Custom Storage Class Designer scans all data class packages on the MATLAB path to detect packages that have a CSC registration file. A message is displayed while scanning proceeds. When the scan is complete, the Custom Storage Class Designer window appears:

The Custom Storage Class Designer window is divided into several panels:

• Select package: Lets you select from a menu of data class packages that have CSC definitions associated with them. See Selecting a Data Class Package for details.

• Custom Storage Class / Memory Section properties: Lets you select, view, edit, copy, verify, and perform other operations on CSC definitions or memory section definitions. The common controls in the Custom Storage Class / Memory Section properties panel are described in Selecting and Editing CSCs, Memory Sections, and References.

  • When the Custom Storage Class tab is selected, you can select a CSC definition or reference from a list and edit its properties. See Editing Custom Storage Class Properties for details.

  • When the Memory Section tab is selected, you can select a memory section definition or reference from a list and edit its properties. See Creating and Editing Memory Section Definitions for details.

• Filename: Displays the filename and location of the current CSC registration file, and lets you save your CSC definition to that file. See Saving Your Definitions for details.

• Pseudocode preview: Displays a preview of code that is generated from objects of the given class. The preview is pseudocode, since the actual symbolic representation of data objects is not available until code generation time. See Previewing Generated Code for details.

• Validation result: Displays any errors encountered when the currently selected CSC definition is validated. See Validating CSC Definitions for details.

Selecting a Data Class Package

A CSC or memory section definition or reference is uniquely associated with a Simulink data class package. The link between the definition/reference and the package is formed when a CSC registration file (csc_registration.m) is located in the package directory.

You never need to search for or edit a CSC registration file directly: the Custom Storage Class Designer locates all available CSC registration files. The Select package menu contains names of all data class packages that have a CSC registration file on the MATLAB search path. At least one such package, the Simulink package, is always present.

When you select a package, the CSCs and memory section definitions belonging to the package are loaded into memory and their names are displayed in the scrolling list in the Custom storage class panel. The name and location of the CSC registration file for the package is displayed in the Filename panel.

If you select a user-defined package, by default you can use the Custom Storage Class Designer to edit its custom storage classes and memory sections. If you select a built-in package, by default you cannot edit its custom storage classes or memory sections. See Custom Storage Class Implementation for more information.

Selecting and Editing CSCs, Memory Sections, and References

The Custom Storage Class / Memory Section panel lets you select, view, and (if the CSC is writable) edit CSC and memory section definitions and references. In the next figure and the subsequent examples, the selected package is mypkg. Instructions for creating a user-defined package like mypkg appear in Creating Packages that Support CSC Definitions.

The list at the top of the panel displays the definitions/references for the currently selected package. To select a definition/reference for viewing and editing, click on the desired list entry. The properties of the selected definition/reference appear in the area below the list. The number and type of properties vary for different types of CSC and memory section definitions. See:

• Editing Custom Storage Class Properties for information about the properties of the predefined CSCs.

• Creating and Editing Memory Section Definitions for information about the properties of the predefined memory section definitions.

The buttons to the right of the list perform these functions, which are common to both custom storage classes and memory definitions:

• New: Creates a new CSC or memory section with default values.

• New Reference: Creates a reference to a CSC or memory section definition in another package. The default initially has a default name and properties. See Using Custom Storage Class References and Using Memory Section References.

• Copy: Creates a copy of the selected definition / reference. Copies are given a default name using the convention:

  definition_name_n

  where definition_name is the name of the original definition, and n is an integer indicating successive copy numbers (for example: BitField_1, BitField_2, ...)

• Up: Moves the selected definition one position up in the list.

• Down: Moves the selected definition one position down in the list

• Remove: Removes the selected definition from the list.

• Validate: Performs a consistency check on the currently selected definition. Errors are reported in the Validation result panel.

For example, if you click New, a new custom storage class is created with a default name:

You can now rename the new class by typing the desired name into the Name field, and set other fields as needed. The changes take effect when you click Apply or OK. For example, you could set values for the new custom storage class as follows:

Saving Your Definitions

After you have created or edited a CSC or memory section definition or reference, you must save the changes to the CSC registration file. To do this, click Save in the Filename panel. When you click Save, the current CSC and memory section definitions that are in memory are validated, and the definitions are written out.

If errors occur, they are reported in the Validation result panel. The definitions are saved whether or not errors exist. However, you should correct any validation errors and resave your definitions. Trying to use definitions that were saved with validation errors can cause additional errors. Such problems can occur even it you do not try to use the specific parts of the definition that contain the validation errors, making the problems difficult to diagnose.

Restarting MATLAB After Changing Definitions

If you add, change, or delete custom storage class or memory section definitions for any user-defined class, and objects of that class already exist, you must restart MATLAB to put the changed definitions into effect and eliminate obsolete objects. A message warning you to restart MATLAB appears when you save the changed definitions. This warning message does not affect the success of the save operation itself.

Back to Top

Editing Custom Storage Class Properties

To view and edit the properties of a CSC, click the Custom Storage Class tab in the Custom Storage Class / Memory Section panel. Then, select a CSC name from the Custom storage class definitions list.

The CSC properties are divided into several categories, selected by tabs. Selecting a class, and setting property values for that class, can change the available tabs, properties, and values. As you change property values, the effect on the generated code is immediately displayed in the Pseudocode preview panel. In most cases, you can define your CSCs quickly and easily by selecting the Pseudocode preview panel and using the Validate button frequently.

The property categories and corresponding tabs are as follows:

General

Properties in the General category are common to all CSCs. In the next figure and the subsequent examples, the selected custom storage class is ByteField. Instructions for creating a user-defined custom storage class like ByteField appear in Selecting and Editing CSCs, Memory Sections, and References.

Properties in the General category, and the possible values for each property, are as follows:

• Name: The CSC name, selected from the Custom storage class definitions list. The name cannot be any TLC keyword. Violating this rule causes an error.

• Type: Specifies how objects of this class are stored. Values:

  • Unstructured: Objects of this class generate unstructured storage declarations (for example, scalar or array variables), for example:

    datatype dataname[dimension];

  • FlatStructure: Objects of this class are stored as members of a struct. A Structure Attributes tab is also displayed, allowing you to specify additional properties such as the struct name. See Structure Attributes.

  • Other: Used for certain data layouts, such as nested structures, that cannot be generated using the standard Unstructured and FlatStructure custom storage class types. If you want to generate other types of data, you can create a new custom storage class from scratch by writing the necessary TLC code. See Defining Advanced Custom Storage Class Types for more information.

• For parameters and For signals: These options let you enable a CSC for use with only certain classes of data objects. For example, it does not make sense to assign storage class Const to a Simulink.Signal object. Accordingly, the For signals option for the Const class is deselected, while the For parameters is selected.

• Memory section: Selects one of the memory sections defined in the Memory Section panel. See Creating and Editing Memory Section Definitions.

• Data scope: Controls the scope of symbols generated for data objects of this class. Values:

  • Auto: Symbol scope is determined internally by the Real-Time Workshop software. If possible, symbols have File scope. Otherwise, they have Exported scope.

  • Exported: Symbols are exported to external code in the header file specified by the Header File field. If no Header File is specified, symbols are exported to external code in model.h.

  • Imported: Symbols are imported from external code in the header file specified by the Header File field. If you do not specify a header file, an extern directive is generated in model_private.h. For imported data, if the Data initialization value is Macro, a header file must be specified.

  • File: The scope of each symbol is the file that defines it. File scope requires each symbol to be used in a single file. If the same symbol is referenced in multiple files, an error occurs at code generation time.

  • Instance specific: Symbol scope is defined by the Data scope field of the RTWInfo.CustomAttributes property of each data object.

• Data initialization: Controls how storage is initialized in generated code. Values:

  • Auto: Storage initialization is determined internally by the Real-Time Workshop software. Parameters have Static initialization, and signals have Dynamic initialization.

  • None: No initialization code is generated.

  • Static: A static initializer of the following form is generated:

    datatype dataname[dimension] = {...};

  • Dynamic: Variable storage is initialized at runtime, in the model_initialize function.

  • Macro: A macro definition of the following form is generated:

     #define data numeric_value

    The Macro initialization option is available only for use with unstructured parameters. It is not available when the class is configured for generation of structured data, or for signals. If the Data scope value is Imported, a header file must be specified.

  • Instance specific: Initialization is defined by the Data initialization property of each data object.

  Note   When necessary, the Real-Time Workshop Embedded Coder software generates dynamic initialization code for signals and states even if the CSC has Data initialization set to None or Static.

• Data access: Controls whether imported symbols are declared as variables or pointers. This field is enabled only when Data scope is set to Imported or Instance-specific. Values:

  • Direct: Symbols are declared as simple variables, such as

    extern myType myVariable;

  • Pointer: Symbols are declared as pointer variables, such as

    extern myType *myVariable;

  • Instance specific: Data access is defined by the Data access property of each data object.

• Header file: Defines the name of a header file that contains exported or imported variable declarations for objects of this class. Values:

  • Specify: An edit field is displayed to the right of the property. This lets you specify a header file for exported or imported storage declarations. Specify the full filename, including the filename extension (such as .h). Use quotes or brackets as in C code to specify the location of the header file. Leave the edit field empty to specify no header file.

  • Instance specific: The header file for each data object is defined by the Header file property of the object. Leave the property undefined to specify no header file for that object.

  If the Data scope is Exported, specifying a header file is optional. If you specify a header file name, the custom storage class generates a header file containing the storage declarations to be exported. Otherwise, the storage declarations are exported in model.h.

  If the Data scope of the class is Imported, and Data initialization is Macro, you must specify a header file name. A #include directive for the header file is generated.

Comments.   The Comments panel lets you specify comments to be generated with definitions and declarations.

Comments must conform to the ANSI C standard (/*...*/). Use \n to specify a new line.

Properties in the Comments tab are as follows:

• Comment rules: If Specify is selected, edit fields allowing you to enter comments are displayed. If Default is selected, comments are generated under control of the Real-Time Workshop software.

• Type comment: The comment entered in this field precedes the typedef or struct definition for structured data.

• Declaration comment: Comment that precedes the storage declaration.

• Definition comment: Comment that precedes the storage definition.

Structure Attributes

The Structure Attributes panel gives you detailed control over code generation for structs (including bitfields). The Structure Attributes tab is displayed for CSCs whose Type parameter is set to FlatStructure. The following figure shows the Structure Attributes panel.

Structure Attributes Panel

The Structure Attributes properties are as follows:

• Struct name: If you select Instance specific, specify the struct name when configuring each instance of the class.

  If you select Specify, an edit field appears (as shown in Structure Attributes Panel) for entry of the name of the structure to be used in the struct definition. Edit fields Type tag, Type token, and Type name are also displayed.

• Is typedef: When this option is selected a typedef is generated for the struct definition, for example:

  typedef struct {
     ...
  } SignalDataStruct;

  Otherwise, a simple struct definition is generated.

• Bit-pack booleans: When this option is selected, signals and/or parameters that have Boolean data type are packed into bit fields in the generated struct.

• Type tag: Specifies a tag to be generated after the struct keyword in the struct definition.

• Type token: Some compilers support an additional token (which is simply another string) after the type tag. To generate such a token, enter the string in this field.

• Type name: Specifies the string to be used in typedef definitions. This field is visible if Is typedef is selected.

The following listing is the pseudocode preview corresponding to the Structure Attributes properties displayed in Structure Attributes Panel.

Header file:

No header file is specified. By default, data is
exported with the generated model.h file.


Type definition:

/* CSC type comment generated by default */

typedef struct aToken myTag {
   :
} myType;


Declaration:

/* CSC declaration comment generated by default */

extern myType MyStruct;


Definition:

/* CSC definition comment generated by default */

myType MyStruct = {...};

Validating CSC Definitions

To validate a CSC definition, select the definition on the Custom Storage Class panel and click Validate. The Custom Storage Class Designer then checks the definition for consistency. The Validation result panel displays any errors encountered when the selected CSC definition is validated. The next figure shows the Validation result panel with a typical error message:

Validation is also performed whenever CSC definitions are saved. In this case, all CSC definitions are validated. (See Saving Your Definitions.)

Back to Top

Using Custom Storage Class References

Any package can access and use custom storage classes that are defined in any other package, including both user-defined packages and predefined packages such as Simulink and mpt. Only one copy of the storage class exists, in the package that first defined it. Other packages refer to it by pointing to it in its original location. Thus any changes to the class, including changes to a predefined class in later MathWorks™ product releases, are immediately available in every referencing package.

To configure a package to use a custom storage class that is defined in another package:

1. Type cscdesigner to launch the Custom Storage Class Designer. The relevant part of the designer window initially looks like this:

   

2. Select the Custom Storage Class tab.

3. Use Select Package to select the package in which you want to reference a class or section defined in some other package. The selected package must be writable.

4. In the Custom storage class definitions pane, select the existing definition below which you want to insert the reference. For example:

   

5. Click New Reference.

   A new reference with a default name and properties appears below the previously selected definition. The new reference is selected, and a Reference tab appears that shows the reference's initial properties. A typical appearance is:

   

6. Use the Name field to enter a name for the new reference. The name must be unique in the importing package, but can duplicate the name in the source package. The name cannot be any TLC keyword. Violating this rule causes an error.

7. Set Refer to custom storage class in package to specify the package that contains the custom storage class you want to reference.

8. Set Custom storage class to reference to specify the custom storage class to be referenced. Trying to create a circular reference generates an error and leaves the package unchanged.

9. Click OK or Apply to save the changes to memory. See Saving Your Definitions for information about saving changes permanently.

For example, the next figure shows the custom storage class ConstVolatile imported from the Simulink package into mypkg, and given the same name that it has in the source package. Any other name could have been used without affecting the properties of the storage class.

You can use Custom Storage Class Designer capabilities to copy, reorder, validate, and otherwise manage classes that have been added to a class by reference. However, you cannot change the underlying definitions. You can change a custom storage class only in the package where it was originally defined.

Changing Existing CSC References

To change an existing CSC reference, select it in the Custom storage class definitions pane. The Reference tab appears, showing the current properties of the reference. Make any needed changes, then click OK or Apply to save the changes to memory. See Saving Your Definitions for information about saving changes permanently.

Back to Top

Creating and Editing Memory Section Definitions

Memory section definitions add comments, qualifiers, and #pragma directives to generated symbol declarations. The Memory Section tab lets you create, view, edit, and verify memory section definitions. The steps for creating a memory section definition are essentially the same as for creating a custom storage class definition:

1. Select a writable package in the Select package field.

2. Select the Memory Section tab. In a new package, only a Default memory section initially appears.

3. Select the existing memory section below which you want to create a new memory section.

4. Click New.

   A new memory section definition with a default name appears below the selected memory section.

5. Set the name and other properties of the memory section as needed.

6. Click OK or Apply.

The next figure shows mypkg with a memory section called MyMemSect:

The Memory section definitions list lets you select a memory section definition to view or edit. The available memory section definitions also appear in the Memory section name menu in the Custom Storage Class panel. The properties of a memory section definition are as follows:

• Memory section name: Name of the memory section (displayed in Memory section definitions list).

• Is const: If selected, a const qualifier is added to the symbol declarations.

• Is volatile: If selected, a volatile qualifier is added to the symbol declarations.

• Qualifier: The string entered into this field is added to the symbol declarations as a further qualifier. Note that no verification is performed on this qualifier.

• Memory section comment: Comment inserted before declarations belonging to this memory section. Comments must conform to the ANSI C standard (/*...*/). Use \n to specify a new line.

• Pragma surrounds: Specifies whether the pragma should surround All variables or Each variable. When Pragma surrounds is set to Each variable, the %<identifier> token is allowed in pragmas and will be replaced by the variable or function name.

• Pre-memory section pragma: pragma directive that precedes the storage definition of data belonging to this memory section. The directive must begin with #pragma.

• Post-memory section pragma: pragma directive that follows the storage definition of data belonging to this memory section. The directive must begin with #pragma.

Previewing Generated Code

If you click Validate on the Memory Section panel, the Pseudocode preview panel displays a preview of code that is generated from objects of the given class. The panel also displays messages (in blue) to highlight changes as they are made. The code preview changes dynamically as you edit the class properties. The next figure shows a code preview for the MemConstVolatile memory section.

Back to Top

Using Memory Section References

Any package can access and use memory sections that are defined in any other package, including both user-defined packages and predefined packages such as Simulink and mpt. Only one copy of the section exists, in the package that first defined it; other packages refer to it by pointing to it in its original location. Thus any changes to the section, including changes to a predefined section in later MathWorks product releases, are immediately available in every referencing package.

To configure a package to use a memory section that is defined in another package:

1. Type cscdesigner to launch the Custom Storage Class Designer.

2. Select the Memory Section tab.

3. Use Select Package to select the package in which you want to reference a class or section defined in some other package.

4. In the Memory section definitions pane, select the existing definition below which you want to insert the reference.

5. Click New Reference.

   A new reference with a default name and properties appears below the previously selected definition. The new reference is selected, and a Reference tab appears that shows the reference's initial properties.

6. Use the Name field to enter a name for the new reference. The name must be unique in the importing package, but can duplicate the name in the source package.

7. Set Refer to memory section in package to specify the package that contains the memory section you want to reference.

8. Set Memory section to reference to specify the memory section to be referenced. Trying to create a circular reference generates an error and leaves the package unchanged.

9. Click OK or Apply to save the changes to memory. See Saving Your Definitions for information about saving changes permanently.

For example, the next figure shows the memory section MemConstVolatile imported from the Simulink package into mypkg, and given the same name that it has in the source package. Any other name could have been used without affecting the properties of the memory section.

You can use Custom Storage Class Designer capabilities to copy, reorder, validate, and otherwise manage memory sections that have been added to a class by reference. However, you cannot change the underlying definitions. You can change a memory section only in the package where it was originally defined.

Changing Existing Memory Section References

To change an existing memory section reference, select it in the Memory section definitions pane. The Reference tab appears, showing the current properties of the reference. Make any needed changes, then click OK or Apply to save the changes to memory. See Saving Your Definitions for information about saving changes permanently.

Back to Top

Creating Packages that Support CSC Definitions

Applying CSCs to Parameters and Signals

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS