Configure Parameters for C Code Generation - MATLAB & Simulink (original) (raw)

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.

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 theRefresh 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 editorData 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:

• _`model`__P for model parameters
• _`model`__InstP for model parameter arguments
• _`model`__ConstP for constant parameters

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 and volatile 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 and volatile 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 argumentsfor 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 qualifiersconst 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.

1. Open model ConfigurationInterface.
   openExample("ConfigurationInterface")
   
2. Open the Embedded Coder app.
3. In the C Code tab, select > .
4. In the Code Mappings editor, select Model parameter arguments. Leave the storage class set toDefault. The code generator allocates a separate area of memory for each argument instance.
5. 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.
6. In the Model Configuration Parameters dialog box, set model configuration parameter Default parameter behavior toTunable. Save the change and close the dialog box. In the Code Mappings editor, the link text changes to 'Auto' will be tunable.
7. In the Code Mappings, with the Model parameters category still selected, set the storage class to ConstVolatile.
   
8. 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 argumentsLOWER and UPPER. You can specify code generation identifiers, for example for integration, without modifying the model design.

1. If you have not already done so, complete the steps in Configure Default Code Generation Settings for Parameters.
2. 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 to Auto.
3. Expand Model Parameters. By default, the storage class for each parameter is set to Auto. Use the model default configuration, which specifies storage class ConstVolatile.
   • 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.
4. In the Code Mappings editor, under Model Parameters, select parameters K1, Table1, andTable2. Set the storage class to Model default: ConstVolatile.
   
5. Configure the code identifiers for model parameters with names that include the prefix mp_. In the Code Mappings editor, select model parameter K1. Click the icon and set the storage class propertyIdentifier to mp_K1. For parametersTable1 and Table2, setIdentifier to mp_Table1 andmp_Table2.
   
6. Save the model.
7. Generate and view the code. For example, find the data definitions for model parameter mp_K1 in ConfigurationInterface.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 threeOutport blocks. Name the model ex_struct_param.

Set Up Constant Parameters

1. Open the Model Data Editor. On the Modeling tab, click Model Data Editor.
2. In the Model Data Editor, select the Parameters tab.
3. In the model, select the upper Constant block.
4. In the Model Data Editor, use the Value column to set the constant value to p1. Next to p1, click the action button and select .
5. In the Create New Data dialog box, set Value toSimulink.Parameter(1.0) and clickCreate.
   Simulink adds a Simulink.Parameter object namedp1 to the model workspace.
6. In the property dialog box for p1, clickOK.
   If you did not have to set up other parameters, you could click theCode Generation tab. Then, click theConfigure in Coder App button, which opens theEmbedded Coder app and Code Mappings editor.
7. Use the Model Data Editor to set the other constant values by using parameter objects named p2 (value 2.0) and p3 (value 3.0).

Configure Constant Parameters for Code Generation

1. Open the Embedded Coder app.
2. On the C Code tab, select > .
3. In the Code Mappings editor, click the Parameters tab.
4. Expand Model Parameters.
5. Set the storage class for parameters p1,p2, and p3 toStruct.
6. Select parameter p1. Click the icon and set propertyStructName to my_struct. For parameters p2 and p3, setStructName to my_struct.
7. 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 variablemy_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 andvolatile. 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.

1. Open the example model.
   openExample("ConfigurationInterface")
2. Set model configuration parameter Default parameter behavior to Tunable.
   model = "ConfigurationInterface";
   set_param(model,"DefaultParameterBehavior","Tunable");
3. Create object cm by calling functioncoder.mapping.api.get. The object stores the code generation configuration for data elements and functions in model ConfigurationInterface.
   cm = coder.mapping.api.get("ConfigurationInterface");
4. Configure default settings for model parameters by calling functionsetDataDefault. For the arguments, specify these values:
   • The object returned bycoder.mapping.api.get
   • ModelParameters for the default category
   • Property name StorageClass with property valueConstVolatile
     setDataDefault(cm,"ModelParameters","StorageClass","ConstVolatile");
5. Configure default settings for model parameter arguments. In the call tosetDataDefault, specify these values for arguments:
   • The object returned bycoder.mapping.api.get.
   • ModelParameterArguments for the default category.
   • Property name StorageClass with property valueDefault.
     setDataDefault(cm,"ModelParameterArguments","StorageClass","Default");
6. Verify your default configuration for model parameters and model parameter arguments. Issue calls to getDataDefault that specify the object returned by coder.mapping.api.get, categoryModelParameters orModelParameterArguments, andStorageClass.
   getDataDefault(cm,"ModelParameters","StorageClass")
   getDataDefault(cm,"ModelParameterArguments","StorageClass")
7. Apply the default configuration for model parameters to parameters K1, Table1, and Table2.
   By default, Simulink sets the storage class for individual parameters toAuto. When the storage class is Auto, 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 name StorageClass, and property value Model default.
     setModelParameter(cm,"K1","StorageClass","Model default");
     setModelParameter(cm,"Table1","StorageClass","Model default");
     setModelParameter(cm,"Table2","StorageClass","Model default");
8. Verify your configuration changes for parameters K1,Table1, and Table2 by using calls to function getModelParameter.
   getModelParameter(cm,"K1","StorageClass")
   getModelParameter(cm,"Table1","StorageClass")
   getModelParameter(cm,"Table2","StorageClass")
9. 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 name Identifier, 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");

10. Verify your configuration changes for the model parameters by using calls to function getModelParameter.
    getModelParameter(cm,"K1","Identifier")
    getModelParameter(cm,"Table1","Identifier")
    getModelParameter(cm,"Table2","Identifier")
11. Save the model.
12. Generate and view the code. For example, find the data definitions for model parameter mp_K1 in ConfigurationInterface.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 theAuto, 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.

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.

See Also

Code Mappings Editor – C | coder.mapping.api.CodeMapping

Related Topics

• C Data Code Interface Configuration for Model Interface Elements
• Choose Storage Class for Controlling Data Representation in Generated Code
• Configure Model Data Elements for ASAP2 File Generation
• Configure Default C Code Generation for Categories of Data Elements and Functions