MPT Data Object Properties

The following table describes the properties and property values for mpt.Parameter and mpt.Signal data objects that appear in the Model Explorer.

Note

You can create mpt.Signal and mpt.Parameter objects in the base MATLAB^® or model workspace. However, if you create a signal object in a model workspace, the object's storage class must be set to Auto.

The figure below shows an example of the Model Explorer. When you select an mpt.Parameter or mpt.Signal data object in the middle pane, its properties and property values display in the rightmost pane.

In the Properties column, the table lists the properties in the order in which they appear on the Model Explorer.

Parameter and Signal Property Values

Class: Parameter, Signal, or Both	Property	Available Property Values (* Indicates Default)	Description
Both	User object type	*`auto`	Prenamed and predefined property sets that are registered in the `sl_customization.m` file. (See Register mpt User Object Types.) This field is active when a user object type is registered. Select `auto` if this field is available but you do not want to apply the properties of a user object type to a selected data object. The fields on the Model Explorer are populated with default values.
		Listed user object type name	Select a user object type name to apply the properties and values that you associated with this name in the `sl_customization.m` file. The fields on the Model Explorer are automatically populated with those values.
Parameter	`Value`	`*0`	The data type and numeric value of the data object. For example, `int8(5)`. The numeric value is used as an initial parameter value in the generated code.
Both	Data type		Used to specify the data type for an `mpt.Signal` data object, but not for an `mpt.Parameter` data object. The data type for an `mpt.Parameter` data object is specified in the Value field above. See About Data Types in Simulink.
Both	Unit	*`null`	Units of measurement of the signal or parameter. (Enter text in this field.)
Both	Dimensions	`*-1`	The dimension of the signal or parameter. For a parameter, the dimension is derived from its value.
Both	Complexity	`*auto` `real` `complex`	Complexity specifies whether the signal or parameter is a real or complex number. Select `auto` for the code generator to decide. For a parameter, the complexity is derived from its value.
Signal	Sample time	`*-1`	Model or block execution rate.
Signal	Sample mode	`*auto`	Determines how the signal propagates through the model. Select `auto` for the code generator to decide.
		`Sample based`	The signal propagates through the model one sample at a time.
		`Frame based`	The signal propagates through the model in batches of samples.
Both	Minimum	*`0.0`	The minimum value to which the parameter or signal is expected to be bound.
		Number within the minimum range of the parameter or signal. (Based on the data type and resolution of the parameter or signal.)
Both	Maximum	*`0.0`	Maximum value to which the parameter or signal is expected to be bound. (Enter information using a dialog box.)
	Code generation options
	Storage class		Note that an `auto` selection for a storage class tells the build process to decide how to declare and store the selected parameter or signal.
Both	Global (Custom)	`Global` is the default storage class for `mpt` data objects.	Specifies that a code generator not place a qualifier in the data object's declaration.
Both	Memory section	`*Default`	Memory section allows you to specify storage directives for the data object. `Default` specifies that the code generator not place a type qualifier and `pragma` statement with the data object's declaration.
Parameter		`MemConst`	Places the `const` type qualifier in the declaration.
Both		`MemVolatile`	Places the `volatile` type qualifier in the declaration.
Parameter		`MemConstVolatile`	Places the `const volatile` type qualifier in the declaration.
Both	Header file		Name of the file used to import or export the data object. This file contains the declaration (`extern`) to the data object. Also, you can specify this header filename between the double-quotation or angle-bracket delimiter. You can specify the delimiter with or without the `.h` extension. For example, specify `"object.h"` or `"object"`. For the selected data object, this overrides the general delimiter selection in the #include file delimiter field on the Configuration Parameters dialog box.
Both	Owner	*Blank	The name of the module that owns this signal or parameter. This is used to help determine the ownership of a definition. For details, see Control Placement of Global Data Definitions and Declarations in Generated Files.
Both	Definition file	*Blank	Name of the file that defines the data object.
		Valid character vector
Both	Persistence level		The number you specify is relative to Signal display level or Parameter tune level on the Code Placement pane of the Configuration Parameters dialog box. For a signal, allows you to specify whether or not the code generator declares the data object as global data. For a parameter, allows you to specify whether or not the code generator declares the data object as tunable global data. See Signal display level and Parameter tune level in Model Configuration Parameters: Code Generation Code Placement.
Both	Bitfield (Custom)		Embeds Boolean data in a named bit field.
	Struct name		Name of the `struct` into which the object's data will be packed.
Parameter	Const (Custom)		Places the `const` type qualifier in the declaration.
Parameter	Header file		See above.
Parameter	Owner		See above.
Parameter	Definition file		See above.
Parameter	Persistence level		See above.
Both	Volatile (Custom)		Places the `volatile` type qualifier in the declaration.
Both	Header file		See above.
Both	Owner		See above.
Both	Definition file		See above.
Both	Persistence level		See above.
Parameter	ConstVolatile (Custom)		Places the `const volatile` type qualifier in declaration.
Parameter	Header file		See above.
Parameter	Owner		See above.
Parameter	Definition file		See above.
Parameter	Persistence level		See above.
Parameter	Define (Custom)		Represents parameters with a `#define` macro.
Parameter	Header file		See above.
Both	ExportToFile (Custom)		Generates global variable definition, and generates a user-specified header (`.h`) file that contains the declaration (`extern`) to that variable.
Both	Memory section		See above.
Both	Header file		See above.
Both	Definition file		See above.
Both	ImportFromFile (Custom)		Includes predefined header files containing global variable declarations, and places the `#include` in a corresponding file. Assumes external code defines (allocates memory) for the global variable.
Both	Data access	*`Direct`	Allows you to specify whether the identifier that corresponds to the selected data object stores data of a data type (`Direct`) or stores the address of the data (a pointer).
Both		`Pointer`	If you select `Pointer`, the code generator places `*` before the identifier in the generated code.
	Header file		See above.
Both	Struct (Custom)		Embeds data in a named `struct` to encapsulate sets of data.
Both	Struct name		See above.
Signal	GetSet (Custom)		Reads (gets) and writes (sets) data using functions.
Signal	Header file		See above.
Signal	Get function		Specify the Get function.
Signal	Set function		Specify the Set function.
Both	Alias	*`null`	As explained in detail in Override Data Object Naming Rules, for a Simulink^® or `mpt` data object (identifier), specifying a name in the Identifier field overrides the global naming rule selection you make on the Configuration Parameters dialog box.
		Valid ANSI^®^[a] C/C++ variable name
Both	`Description`	*`null`	Text description of the parameter or signal. Appears as a comment beside the signal or parameter's identifier in the generated code.
		Character vector
Signal	Reusable		Allows the code generator to reuse a pair of root I/O signals when you specify the same name and the same storage class for both. The storage class is either `Reusable` or derived from `Reusable`.
Signal	Data Scope	`*Auto`	You can specify the scope of symbols code generation generates for a data object of this class by selecting a value for DataScope. When you take the default of `Auto`, code generation determines the symbol scope internally. If possible, symbols have `File` scope. Otherwise, they have `Exported` scope.
		`File`	Code generation defines the scope of each symbol as 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, code generation reports an error.
		`Exported`	Code generation exports symbols to external code in the header file specified by the HeaderFile field. If a HeaderFile is not specified, symbols are exported to external code in `model.h`.
		`Imported`	Code generation imports symbols from external code in the header file specified by the HeaderFile field. If you do not specify a header file, code generation generates an `extern` directive in `model`_private.h.
Signal	Header file		See above.
Signal	Owner		See above.
Signal	Definition file		See above.
^[a] ANSI is a registered trademark of the American National Standards Institute, Inc.

mpt Package Storage Classes

CSC Name	Purpose	Signals?	Parameters?
`BitField`	Generate a `struct` declaration that embeds Boolean data in named bit fields.	Y	Y
`CompilerFlag`	Supports preprocessor conditionals defined via compiler flag. See Generate Preprocessor Conditionals for Variant Systems.	N	Y
`Const`	Generate a constant declaration with the `const` type qualifier.	N	Y
`ConstVolatile`	Generate declaration of volatile constant with the `const volatile` type qualifier.	N	Y
`Define`	Generate `#define` directive.	Y	Y
`ExportToFile`	Generate header (`.h`) file, with user-specified name, containing global variable declarations.	Y	Y
`FileScope`	Generate a static qualifier suffix for a variable declaration so that the scope of the variable is limited to the current file.	Y	Y
`GetSet`	Supports specialized function calls to read and write the memory associated with a Data Store Memory block. See Access Data Through Functions with Storage Class GetSet.	Y	Y
`Global`	The default storage class for the `mpt` package. Generate the declaration and definition of a data object in specified files, and use the specified memory section.	Y	Y
`ImportedDefine`	Supports preprocessor conditionals defined via legacy header file. See Generate Preprocessor Conditionals for Variant Systems.	N	Y
`ImportFromFile`	Generate directives to include predefined header files containing global variable declarations.	Y	Y
`Reusable`	Allows the code generator to reuse a pair of root I/O signals when you specify the same name and the same storage class for both. The storage class is either `Reusable` or derived from `Reusable`.	Y	N
`Struct`	Generate a `struct` declaration encapsulating parameter or signal object data.	Y	Y
`StructConst`	Generate a `struct` declaration, with a `const` type qualifier, encapsulating parameter object data.	N	Y
`StructVolatile`	Generate a `struct` declaration, with a `volatile` type qualifier, encapsulating parameter or signal object data.	Y	Y
`Volatile`	Use `volatile` type qualifier in declaration.	Y	Y

Examples of Property Value Changes on Generated Code

What I noticed when inspecting the .c/.cpp file	Change I made to property value settings	What I noticed after regenerating and reinspecting the file
Example 1: Parameter data objects can be declared or defined as constants. I know that the data object `GAIN` is a parameter. I want this to be declared or defined in the `.c` file as a variable. But I notice that `GAIN` is declared as a constant by the statement `const real_T GAIN = 5.0;`. Also, this statement is in the constant section of the file.	In the Model Explorer, I clicked the data object `GAIN`. I noticed that the property value for its Memory section property is set at `MemConst`. I changed this to `Default`.	I notice two differences. One is that now `GAIN` is declared as a variable with the statement `real_T GAIN = 5.0;`. The second difference is that the declaration now is located in the `MemConst` memory section in the `.c` or `.cpp` file.
Example 2: I notice again the declaration of `GAIN` in the `.c` file mentioned in Example 1. It appears as `real_T GAIN = 5.0;`. But I have changed my mind. I want data object `GAIN` to be `#define`.	I changed the Storage class selection to `Define`.	`GAIN` is not declared in the `.c` file as a `MemConst` parameter. Rather, it is defined as a `#define` macro by the code `#define GAIN 5.0`, and this is located near the top of the `.c` file with the other preprocessor directives.
Example 3: I changed my mind again after doing Example 2. I do want `GAIN` defined using the `#define` preprocessor directive. But I do not want to include the `#define` in this file. I know it exists in another file and I want to reference that file.	On the Model Explorer, I notice that the property value for the Header file property is blank. I changed this to `filename.h`. (I chose the ANSI C/C++ double quote mechanism for the `#include`, but could have chosen the angle bracket mechanism.) Also, I must make the user-defined `filename.h` available to the compiler, placing it either in the system path or local directory.	`#define GAIN 5.0` is not present in this `.c` file. Instead, the `#include filename.h` code appears as a preprocessor directive at the top of the file.
Example 4: I have one more change I want to make. Let us say that we have declared the data object `data_in`, and that its declaration statement in the `.c` file reads `real_T data_in = 0.0;`. I want to replace this statement with an alias in the `.c` file.	In the Model Explorer, I selected the data object `data_in`. I noticed that the Identifier field is blank. I changed this to `data_in_alias`, which I know is a valid ANSI C/C++ variable name.	The identifier `data_in_alias` now appears in the `.c` file everywhere `data_in` appeared.

Specify Persistence Level for Signals and Parameters

With this procedure, you can control the persistence level of signal and parameter objects associated with a model. Persistence level allows you to make intermediate variables or parameters global during initial development. At the later stages of development, you can use this procedure to remove these signals and parameters for efficiency. Use the Persistence Level property of mpt.Signal and mpt.Parameter data objects. For descriptions of the properties on the Model Explorer, see MPT Data Object Properties.

Notice also the Signal display level and Parameter tune level fields on the Code Placement pane of the Configuration Parameters dialog box, as illustrated in the next figure.

The Signal display level field allows you to specify whether or not the code generator defines a signal data object as global data in the generated code. The number you specify in this field is relative to the number you specify in the Persistence level field. The Signal display level number is for mpt (module packaging tool) signal data objects in the model. The Persistence level number is for a particular mpt signal data object. If the data object's Persistence level is equal to or less than the Signal display level, the signal appears in the generated code as global data with the custom attributes that you specified. For example, this would occur if Persistence level is 2 and Signal display level is 5.

Otherwise, the code generator automatically determines how the particular signal data object appears in the generated code. Depending on the settings on the Optimization pane of the Configuration Parameters dialog box, the signal data object could appear in the code as local data without the custom attributes you specified for that data object. Or, based on expression folding, the code generator could remove the data object so that it does not appear in the code.

The Parameter tune level field allows you to specify whether or not the code generator declares a parameter data object as tunable global data in the generated code.

The number you specify in this field is relative to the number you specify in the Persistence level field. The Parameter tune level number is for mpt parameter data objects in the model. The Persistence level number is for a particular mpt parameter data object. If the data object's Persistence level is equal to or less than the Parameter tune level, the parameter appears tunable in the generated code with the custom attributes that you specified. For example, this would occur if Persistence level is 2 and Parameter tune level is 5.

Otherwise, the parameter is inlined in the generated code, and the code generation settings determine its exact form.

Note that, in the initial stages of development, you might be more concerned about debugging than code size. Or, you might want one or more particular data objects to appear in the code so that you can analyze intermediate calculations of an equation. In this case, you might want to specify the Parameter tune level (Signal display level for signals) to be higher than Persistence level for some mpt parameter (or signal) data objects. This results in larger code size, because the code generator defines the parameter (or signal) data objects as global data, which have the custom properties you specified. As you approach production code generation, however, you might have more concern about reducing the size of the code and less need for debugging or intermediate analyses. In this stage of the tradeoff, you could make the Parameter tune level (Signal display level for signals) greater than Persistence level for one or more data objects, generate code and observe the results. Repeat until satisfied.

With the model open, in the Configuration Parameters dialog box, select Code Generation > Code Placement.
Type the desired number in the Signal display level or Parameter tune level field, and click Apply.
In the Model Explorer, type the desired number in the Persistence field for the selected signal or parameter, and click Apply.
Save the model and generate code.

Register mpt User Object Types

Introduction
Register mpt User Object Types Using sl_customization.m
mpt User Object Type Customization Using sl_customization.m

Introduction

Embedded Coder^® allows you to create custom mpt object types and specify properties and property values to be associated with them. Once created, a user object type can be applied to data objects displayed in Model Explorer. When you apply a user object type to a data object, by selecting a type name in the User object type pull-down list in Model Explorer, the data object is automatically populated with the properties and property values that you specified for the user object type.

To register mpt user object type customizations, use the Simulink customization file sl_customization.m. This file is a mechanism that allows you to use MATLAB code to perform customizations of the standard Simulink user interface. The Simulink software reads the sl_customization.m file, if present on the MATLAB path, when it starts and the customizations specified in the file are applied to the Simulink session. For more information on the sl_customization.m customization file, see Registering Customizations.

Register mpt User Object Types Using sl_customization.m

To register mpt user object type customizations, you create an instance of sl_customization.m and include it on the MATLAB path of the Simulink installation that you want to customize. The sl_customization function accepts one argument: a handle to a customization manager object. For example,

function sl_customization(cm)

As a starting point for your customizations, the sl_customization function must first get the default (factory) customizations, using the following assignment statement:

hObj = cm.slDataObjectCustomizer;

You then invoke methods to register your customizations. The customization manager object includes the following methods for registering mpt user object type customizations:

addMPTObjectType(hObj, objectTypeName, classtype, propName1, propValue1, propName2, propValue2, ...)
addMPTObjectType(hObj, objectTypeName, classtype, {propName1, propName2, ...}, {propValue1, propValue2, ...})
Registers the specified user object type, along with specified values for object properties, and adds the object type to the top of the user object type list, as displayed in the User object type pull-down list in the Model Explorer.
- objectTypeName — Name of the user object type
- classType — Class to which the user object type applies: 'Signal', 'Parameter', or 'Both'
- propName — Name of a property of an mpt or mpt-derived data object to be populated with a corresponding propValue when the registered user object type is selected
- propValue — Specifies the value for a corresponding propName
moveMPTObjectTypeToTop(hObj, objectTypeName)
Moves the specified user object type to the top of the user object type list, as displayed in the User object type pull-down list in the Model Explorer.
moveMPTObjectTypeToEnd(hObj, objectTypeName)
Moves the specified user object type to the end of the user object type list, as displayed in the User object type pull-down list in the Model Explorer.
removeMPTObjectType(hObj, objectTypeName)
Removes the specified user object type from the user object type list.

Your instance of the sl_customization function should use these methods to register mpt object type customizations for your Simulink installation.

The Simulink software reads the sl_customization.m file when it starts. If you subsequently change the file, to use the changes, you must restart your MATLAB session.

mpt User Object Type Customization Using sl_customization.m

The sl_customization.m file shown in mpt User Object Type Customization Using sl_customization.m uses the addMPTObjectType method to register the user signal types EngineType and FuelType for mpt objects.

Example 1. sl_customization.m for mpt Object Type Customizations

function sl_customization(cm)
% Register user customizations

% Get default (factory) customizations
hObj = cm.slDataObjectCustomizer;

% Add commonly used signal types
hObj.addMPTObjectType(...
    'EngineType','Signal',...
    'DataType', 'uint8',...
    'Min', 0,...
    'Max', 255,...
    'Unit','m/s');  

hObj.addMPTObjectType(...
    'FuelType','Signal',...
    'DataType', 'int16',...
    'Min', -12,...
    'Max', 3000,...
    'Unit','mg/hr');  

end

If you include the above file on the MATLAB path of the Simulink installation that you want to customize, the specified customizations will appear in Model Explorer. For example, you could view the customizations as follows:

Start a MATLAB session.
Open Model Explorer, for example, by entering the MATLAB command daexplr.
Select Base Workspace.
Add an mpt signal, for example, by selecting Add > Add Custom.
In the right-hand pane display for the added mpt signal, examine the User object type drop-down list, noting the impact of the changes specified in mpt User Object Type Customization Using sl_customization.m.
From the User object type drop-down list, select one of the registered user signal types, for example, FuelType, and verify that the displayed settings are consistent with the arguments specified to the addMPTObjectType method in sl_customization.m.

Documentation