| Real-Time Workshop® Embedded Coder™ | |
| On this page… |
|---|
Using the Custom Storage Class Designer Editing Custom Storage Class Properties Using Custom Storage Class References |
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 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.
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 and displays the associated package names in the Select package panel:
The Select package panel contains a menu of 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.
The Custom Storage Class / Memory Section panel lets you select, view, and — if the CSC is writeable — edit CSC or memory section definitions and references. In the picture below, the Custom Storage Class tab is selected.
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.
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.
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.
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:
Properties in the General category are common to all CSCs. These properties are shown in the next figure.
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 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 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.
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 and definitions 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.
The Comments panel lets you specify comments to be generated with definitions and declarations.
Comments must conform to the ANSI[1] C standard (/*...*/). Use \n to specify a new line.
Properties in the Comments panel 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.
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 = {...};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 selected. (See Saving Your Definitions.)
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:
Type cscdesigner to launch the Custom Storage Class Designer. The relevant part of the designer window looks like this:
Select the Custom Storage Class tab.
Use Select Package to select the package in which you want to reference a class or section defined in some other package.
In the Custom storage class definitions pane, select the existing definition below which you want to insert the reference.
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:
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.
Set Refer to custom storage class in package to specify the package that contains the custom storage class you want to reference.
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.
Click OK or Apply to save the changes to memory. See Saving Your Definitions for information about saving changes permanently.
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.
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.
The Memory Section panel lets you view, edit, and verify memory section definitions. Memory section definitions add comments, qualifiers, and #pragma directives to generated symbol declarations. The next figure shows the Memory Section panel with the MemConstVolatile memory section selected:
The Memory section definitions list lets you select a memory section definition to view or edit. The predefined memory section definitions are as follows:
Default: A placeholder definition (read-only).
MemConst: Generates a const declaration.
MemVolatile: Generates a volatile declaration.
MemConstVolatile: Generates a const volatile declaration.
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.
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.
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:
Type cscdesigner to launch the Custom Storage Class Designer.
Select the Memory Section tab. The relevant part of the designer window looks like this:
Use Select Package to select the package in which you want to reference a class or section defined in some other package.
In the Memory section definitions pane, select the existing definition below which you want to insert the reference.
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:
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.
Set Refer to memory section in package to specify the package that contains the memory section you want to reference.
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.
Click OK or Apply to save the changes to memory. See Saving Your Definitions for information about saving changes permanently.
You can use Custom Storage Class Designer capabilities to copy, reorder, validate, and otherwise manage 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.
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.
[1] ANSI is a registered trademark of the American National Standards Institute, Inc.
| Creating Packages with CSC Definitions | Defining Advanced Custom Storage Class Types | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |