Configure Parameters for C Code Generation
When configuring a model for code generation, you can identify and configure parameters for tunability, for example for calibration. Types of parameters that you can configure are listed in this table.
Type of Parameter | Description |
---|---|
Model parameter argument | Parameter configured as a model argument. Each model instance that includes the model parameter argument can have the argument set to a unique value. |
Model parameter | Parameter defined within a model, such as a parameter in the model workspace. |
External parameter | Parameter defined as an object in the base workspace or in a data dictionary. |
Constant | Constant-value parameters that could not be inlined. |
To configure a parameter for code generation, you must associate the parameter with a data object. For example, before configuring a MATLAB variable for code generation, in the Model Explorer, convert the variable to a parameter object.
When you open a model in the Embedded Coder app, model
parameters, model parameter arguments, and
constants that are associated with data objects appear in the Code Mappings
editor. In the editor, you can configure the parameters for code generation. If a model uses
external parameters, you can add them to the Code Mappings editor by clicking the
Refresh
link to the right of the parameter name. That link initiates
an update diagram and, in the editor view, adds external parameters that are used by the
model.
Configure parameter data to:
Make the data accessible for interaction while the generated code executes.
Minimize the amount of data that is stored in memory.
Control where the code generator places parameter data in memory.
Promote parameter data to the model interface so that other components and systems can access that data.
Improve readability and traceability of the generated code.
To control whether the parameters throughout a model are tunable, you can gain access to
model configuration parameter Default parameter behavior by using the
'Auto' will be tunable/inline
link on the Code Mappings editor
Data Defaults tab. For example, you can use that link to make
parameters tunable in these cases:
Refine parameter settings during rapid prototyping
Calibrate parameters
Optimize parameters for production code
For code generation, examples show how to configure model parameters and model parameter
arguments for the model ConfigurationInterface
. You can configure code mappings by using the Code Mappings Editor – C or code mappings programming interface (coder.mapping.api.CodeMapping
).
Choose Customization Options for Parameters
By default, parameters in a model appear in generated code as fields of global data structures named:
for model parametersmodel
_P
for model parameter argumentsmodel
_InstP
for constant parametersmodel
_ConstP
Based on your code interface requirements, decide whether to customize generation of parameter data. If you do not configure customizations, the code generator determines whether to eliminate or change the representation of parameters in generated code for optimization purposes. If you configure customizations, decide:
Whether to set up a default configuration
If a model includes a significant number of parameters of a category that must be tunable (for example, more than 10), it is more efficient to configure the parameters of that category by using a default setting, and then override that setting for special cases. If the model includes a few parameters of a given category that have unique source, naming, or placement requirements, consider configuring the parameters individually.
How to declare and handle model parameter data in the generated code
As separate global variables
To read model parameter data from global variables defined in external code
As calls to access functions. Requires Embedded Coder®
For more information about these options, see Control Data and Function Interface in Generated Code.
Other considerations for model parameters include whether to:
Name parameters in the generated code by using parameter names in the model or by using unique code identifiers.
Support preprocessor conditionals defined by compiler flags or options. Requires Embedded Coder. See Compile Code Conditionally for Variations of Component Represented Using Variant Block.
Include the
static
type qualifier in global variable definitions and declarations, for example, to prevent name clashes. Requires Embedded Coder. See Prevent Name Clashes by Configuring Data Item as static.Include the
const
,volatile
, orconst
andvolatile
type qualifier in global variable definitions and declarations. Requires Embedded Coder. See Protect Global Data with const and volatile Type Qualifiers.Generate a macro (
#define
) or code that uses a macro defined in an external header file. Requires Embedded Coder. See Macro Definitions (#define).Generate a global data structure with a name that you specify. Requires Embedded Coder. See Organize Data into Structures in Generated Code.
Place parameter data into a specific area of memory. Requires Embedded Coder. See Control Data and Function Placement in Memory by Inserting Pragmas.
For a list of interface requirements that are relevant to parameters that have corresponding storage classes and storage class properties, see Choose Storage Class and Storage Class Properties for Data Stores.
Parameter requirements for example model ConfigurationInterface
are:
By default, retain model parameters in the generated code for tuning. Do not optimize the code by inlining the parameters.
Represent model parameters as separate global variables defined and declared with the
const
andvolatile
type qualifiers.Apply prefix
mp_
to names of variables that represent model parameters.Enable constant parameters
UPPER
andLOWER
to have different values for each instance of the model.For each instance of a model parameter argument, by default, allocate an area of memory represented as a uniquely named field in an exported structure.
Model parameter arguments appear as individual model function arguments in the generated code. Enable the code generator to optimize model parameter arguments that are not used by blocks in the model.
For this example, configure model parameters and model
parameter arguments in ConfigurationInterface
to meet these code generation requirements.
Configure Default Code Generation Settings for Parameters
Default code generation settings for parameters can reduce the effort of preparing a model for code generation, especially if a model has a significant number of parameters with which you need to interact while the generated code executes. Choose configuration settings once, and the code generator applies those settings to parameters across the model. Simulink® stores the default configuration as part of the model.
Consider configuring default code generation settings for model parameters if your model uses multiple parameters for the same category that do not have unique requirements or use a shared Embedded Coder Dictionary.
This example shows how to use the Code Mappings Editor – C to configure default settings
for model parameters and model parameter arguments
for the model ConfigurationInterface
. Configure model parameters so that they are
tunable and are defined and declared in the generated code as separate global
variables that have type qualifiers
const
and volatile
. Configure model parameter arguments to use default settings,
where the code generator allocates an area of memory represented as a uniquely named
field in an exported structure for each argument instance.
Open model
ConfigurationInterface
.openExample("ConfigurationInterface")
Open the Embedded Coder app.
In the C Code tab, select Code Interface > Default Code Mappings.
In the Code Mappings editor, select Model parameter arguments. Leave the storage class set to
Default
. The code generator allocates a separate area of memory for each argument instance.In the Code Mappings editor, under Parameters, select category Model parameters. Link text
'Auto' will be inlined
indicates that the code generator is configured to inline model parameters by default. A requirement for this example is model parameters be tunable. Click'Auto' will be inlined
.In the Model Configuration Parameters dialog box, set model configuration parameter Default parameter behavior to
Tunable
. Save the change and close the dialog box. In the Code Mappings editor, the link text changes to'Auto' will be tunable
.In the Code Mappings, with the Model parameters category still selected, set the storage class to
ConstVolatile
.Save the model.
Configure Code Generation for Individual Parameters
You can configure individual parameters for code generation. For example, if a model has two parameters of the same category that have unique code generation requirements, configure the parameters individually. Or, if you configure default settings for a category of parameters, you can override those settings for specific parameters.
If your model meets at least one of these criteria, consider configuring code generation settings for parameters individually:
Uses multiple parameters of the same category that have unique source, naming, or placement requirements.
Uses a few parameters of the same category.
Has a default configuration for a category of parameters and you need to override the configuration for some specific parameters.
This example shows how to use the Code Mappings editor to apply your default storage
class setting for model parameters to parameters K1
,
Table1
, and Table2
in model ConfigurationInterface
. You configure code identifiers for those
parameters and for model parameter arguments
LOWER
and UPPER
. You can specify
code generation identifiers, for example for integration, without modifying the model
design.
If you have not already done so, complete the steps in Configure Default Code Generation Settings for Parameters.
In the Code Mappings editor, click the Parameters tab. Expand Model Parameter Arguments. By default, the storage class for each model parameter is set to
Auto
, which means that the code generator might eliminate or change the representation of relevant code for optimization purposes. If optimizations are not possible, the code generator applies the model default configuration. For this example, leave the storage class set toAuto
.Expand Model Parameters. By default, the storage class for each parameter is set to
Auto
. Use the model default configuration, which specifies storage classConstVolatile
.To avoid optimizations and force the code generator to use the default configuration, set the storage class to
Model default
.To override the default configuration, specify the storage class that meets the code generation requirements for that parameter.
In the Code Mappings editor, under Model Parameters, select parameters
K1
,Table1
, andTable2
. Set the storage class toModel default: ConstVolatile
.Configure the code identifiers for model parameters with names that include the prefix
mp_
. In the Code Mappings editor, select model parameterK1
. Click the icon and set the storage class property Identifier tomp_K1
. For parametersTable1
andTable2
, set Identifier tomp_Table1
andmp_Table2
.Save the model.
Generate and view the code. For example, find the data definitions for model parameter
mp_K1
inConfigurationInterface.c
.const volatile int8_T mp_K1 = 2;
Find where the parameter is used in the step entry-point function.
if (mode) { output = (real_T)mp_K1 * dout_Table1; } else { output = dstate_X; }
Organize Parameter Data into a Structure by Using Struct
Storage Class
This example shows how to use the Struct
storage class to organize
block parameter values into a structure in the generated code. You apply the storage
class directly to individual data items in a model.
To create a custom structure of parameter data in the generated code, consider creating a corresponding structure in Simulink. See Organize Data into Structures in Generated Code.
Create the Example Model
Create this example model with three Constant blocks and three
Outport blocks. Name the model ex_struct_param
.
Set Up Constant Parameters
Open the Model Data Editor. On the Modeling tab, click Model Data Editor.
In the Model Data Editor, select the Parameters tab.
In the model, select the upper Constant block.
In the Model Data Editor, use the Value column to set the constant value to
p1
. Next top1
, click the action button and select Create.In the Create New Data dialog box, set Value to
Simulink.Parameter(1.0)
and click Create.Simulink adds a
Simulink.Parameter
object namedp1
to the model workspace.In the property dialog box for
p1
, click OK.If you did not have to set up other parameters, you could click the Code Generation tab. Then, click the Configure in Coder App button, which opens the Embedded Coder app and Code Mappings editor.
Use the Model Data Editor to set the other constant values by using parameter objects named
p2
(value2.0
) andp3
(value3.0
).
Configure Constant Parameters for Code Generation
Open the Embedded Coder app.
On the C Code tab, select Code Interface > Individual Element Code Mappings.
In the Code Mappings editor, click the Parameters tab.
Expand Model Parameters.
Set the storage class for parameters
p1
,p2
, andp3
toStruct
.Select parameter
p1
. Click the icon and set property StructName tomy_struct
. For parametersp2
andp3
, set StructName tomy_struct
.Save the model.
Generate and Inspect Code
Generate and inspect the code.
The file ex_struct_param.h
defines structure type,
my_struct_type
.
/* Type definition for custom storage class: Struct */ typedef struct my_struct_tag { real_T p1; real_T p2; real_T p3; } my_struct_type;
The file ex_struct_param.c
defines global variable
my_struct
.
/* Definition for custom storage class: Struct */ my_struct_type my_struct = { /* p1 */ 1.0, /* p2 */ 2.0, /* p3 */ 3.0 };
Configure Code Generation Settings for Parameters Programmatically
To automate configuration of parameters for code generation, use the programming interface for code mappings. For example, when creating custom block libraries or part of an application test environment, use the programming interface to automate data configuration.
This example shows how to configure default settings for model parameters and model parameter arguments for model ConfigurationInterface
. Configure model parameters so that they are tunable
and are defined and declared in the generated code as separate global variables that have type qualifiers const
and
volatile
. Configure
model parameter arguments to use default settings, where the code generator
allocates an area of memory represented as a uniquely named field in an exported
structure for each argument instance. Apply your default storage class
setting for model parameters to parameters K1
,
Table1
, and Table2
. Configure code identifiers
for those parameters.
Open the example model.
openExample("ConfigurationInterface")
Set model configuration parameter Default parameter behavior to
Tunable
.model = "ConfigurationInterface"; set_param(model,"DefaultParameterBehavior","Tunable");
Create object
cm
by calling functioncoder.mapping.api.get
. The object stores the code generation configuration for data elements and functions in modelConfigurationInterface
.cm = coder.mapping.api.get("ConfigurationInterface");
Configure default settings for model parameters by calling function
setDataDefault
. For the arguments, specify these values:The object returned by
coder.mapping.api.get
ModelParameters
for the default categoryProperty name
StorageClass
with property valueConstVolatile
setDataDefault(cm,"ModelParameters","StorageClass","ConstVolatile");
Configure default settings for model parameter arguments. In the call to
setDataDefault
, specify these values for arguments:The object returned by
coder.mapping.api.get
.ModelParameterArguments
for the default category.Property name
StorageClass
with property valueDefault
.
setDataDefault(cm,"ModelParameterArguments","StorageClass","Default");
Verify your default configuration for model parameters and model parameter arguments. Issue calls to
getDataDefault
that specify the object returned bycoder.mapping.api.get
, categoryModelParameters
orModelParameterArguments
, andStorageClass
.getDataDefault(cm,"ModelParameters","StorageClass")
ans = 'ConstVolatile'
getDataDefault(cm,"ModelParameterArguments","StorageClass")
ans = 'Default'
Apply the default configuration for model parameters to parameters
K1
,Table1
, andTable2
.By default, Simulink sets the storage class for individual parameters to
Auto
. When the storage class isAuto
, the code generator:Determines whether to eliminate the data from the generated code for optimization purposes.
If retaining the data, determines how to efficiently represent the data in the generated code, taking into account default configuration settings.
Configure the code generator to apply your default model parameter settings to parameters
K1
,Table1
, andTable2
. For each parameter, call functionsetModelParameter
. Specify the object returned bycoder.mapping.api.get
, the parameter name, property nameStorageClass
, and property valueModel default
.setModelParameter(cm,"K1","StorageClass","Model default"); setModelParameter(cm,"Table1","StorageClass","Model default"); setModelParameter(cm,"Table2","StorageClass","Model default");
Verify your configuration changes for parameters
K1
,Table1
, andTable2
by using calls to functiongetModelParameter
.getModelParameter(cm,"K1","StorageClass")
ans = 'Model default'
getModelParameter(cm,"Table1","StorageClass")
ans = 'Model default'
getModelParameter(cm,"Table2","StorageClass")
ans = 'Model default'
Configure code identifiers for the model parameters. For each parameter, call function
setModelParameter
. Specify the object returned bycoder.mapping.api.get
, the parameter name, property nameIdentifier
, and one of these property values.Model Parameter Code Identifier K1
mp_K1
Table1
mp_Table1
Table2
mp_Table2
setModelParameter(cm,"K1","Identifier","mp_K1"); setModelParameter(cm,"Table1","Identifier","mp_Table1"); setModelParameter(cm,"Table2","Identifier","mp_Table2");
Verify your configuration changes for the model parameters by using calls to function
getModelParameter
.getModelParameter(cm,"K1","Identifier")
ans = 'mp_K1'
getModelParameter(cm,"Table1","Identifier")
ans = 'mp_Table1'
getModelParameter(cm,"Table2","Identifier")
ans = 'mp_Table2'
Save the model.
Generate and view the code. For example, find the data definitions for model parameter
mp_K1
inConfigurationInterface.c
.const volatile int8_T mp_K1 = 2;
Find where the parameter is used in the step entry-point function.
if (mode) { output = (real_T)mp_K1 * dout_Table1; } else { output = dstate_X; }
Choose Storage Class and Storage Class Properties for Model Parameters
Depending on your code generation requirements, choose from the list of available storage classes to configure code generation for model parameters. The list of storage classes is defined in the coder dictionary.
Note
For constants, only the
Default
storage class applies.For model parameter arguments, only the
Auto
,Default
,Model default
,MultiInstance
, andDictionary Default
(when using a shared data dictionary) storage classes apply.Top-level models do not support individual mappings for model parameter arguments. If you select the
Auto
storage class for a model parameter argument in a top-level model, the code generator inlines the argument.
Requirements | Storage Class for Default Mappings | Storage Class for Individual Mappings |
---|---|---|
Enable optimizations, potentially generating more efficient code. | Auto | |
For data elements that cannot be optimized, represent data as a field of a standard data structure. | Default | |
Prevent optimizations from eliminating storage for a data element and use the default mapping for the data element category. | Model Default | |
When using a shared coder dictionary, select the dictionary default for data elements that you do not want the code generator to optimize. | Dictionary Default | |
Generate a structure that stores Boolean, fixed-point, or integer data in named bitfields. | Bitfield | |
Support preprocessor conditionals defined by using a compiler flag or option. | CompilerFlag | CompilerFlag |
Generate a global variable definition and declaration that has the
const , volatile , or
const and volatile type
qualifiers. | Const, Volatile, and ConstVolatile | Const, Volatile, and ConstVolatile |
Generate a macro (#define directive) or code that
uses a macro defined in a header file in your external code. | Define, ImportedDefine | Define, ImportedDefine |
Generate a global variable definition and declaration. | ExportedGlobal | ExportedGlobal |
Generate a global variable definition and declaration to a specified file. | ExportToFile | ExportToFile |
Generate a global variable definition and declaration that has the
static type qualifier. | FileScope (Local and shared local data store mappings only) | FileScope (Local and shared local data store mappings only) |
Generate code that interacts with data by calling your custom accessor functions. | GetSet | GetSet |
Generate code that reads from and writes to a global variable or global variable pointer defined by your external code. | ImportedExtern, ImportedExternPointer | ImportedExtern, ImportedExternPointer |
Generate code that reads from and writes to a global variable defined by your external header file. | ImportFromFile | ImportFromFile |
Generate a global structure that has a name, which you can specify. | Struct | |
Generate variables for single-instance data and generate structures for multi-instance data. | MultiInstance (Not supported for external parameters) | MultiInstance (Not supported for external parameters) |
The list of available storage classes might include other project-specific storage classes defined in an Embedded Coder Dictionary. If you have special requirements that are not met by the listed storage classes and you have Embedded Coder software, you can define a storage class. See Define Service Interfaces, Storage Classes, Memory Sections, and Function Templates for Software Architecture.
For an individual model parameter, use the Identifier storage class property to configure a name for the variable representing the parameter in the generated code. With Embedded Coder, depending on the storage class that you choose, you can also configure these properties.
Property | Description | Storage Classes |
---|---|---|
DefinitionFile | Source definition file that contains definitions for global data, which is read by the parameter and external code | ExportToFile and
Volatile |
GetFunction | Parameter appears in the generated code as a call to a specified
get function | GetSet |
HeaderFile | Source header file that contains declarations for global data, which is read by the parameter and external code | ExportToFile , GetSet ,
ImportFromFile , and
Volatile |
Memory Section (default parameter configuration
only) | Memory section that contains data read by the parameter | Default |
Owner | Code generator places the definition for parameters in the code generated for one of multiple models in a model hierarchy that share definitions. You must select the model configuration parameter Use owner from data object for data definition placement. See Control Placement of Global Data Definitions and Declarations in Generated Files. | ExportToFile and
Volatile |
PreserveDimensions | Code generator preserves dimensions of parameter data that is
represented in generated code as a multidimensional array. You must set
model configuration parameter Array layout to
Row-major . See Preserve Dimensions of Multidimensional Arrays in Generated Code. | ExportToFile , FileScope ,
GetSet , ImportFromFile ,
Localizable and
Volatile |
SetFunction | Parameter appears in the generated code as a call to a specified
set function. | GetSet |
StructName | Name for a structure in the generated code for parameter. | BitField and Struct |
See Also
Code Mappings Editor – C | coder.mapping.api.CodeMapping