Embedded Coder Dictionary

Create code definitions, which control code generation for model data and functions

expand all in page

Description

The Embedded Coder Dictionary is a graphical interface for creating custom code definitions. By applying these definitions in models, you and your users can generate code that conforms to a specific software architecture by default. For example, you can create your own storage class, which you and your users can apply by default to a category of model data, such as root-level inputs, or to individual data elements, such as parameters.

You can create these types of code definitions:

  • Storage classes, which control the code generated for model data.

  • Function customization templates, which control naming of model entry-point functions, such as model_step. The templates also apply memory sections to the entry-point functions.

  • Memory sections, which control the placement of data and functions in memory. The generated code includes custom decorations, such as pragmas, whose syntax you specify.

For general information about creating code generation definitions, see Define Storage Classes, Memory Sections, and Function Templates for Software Architecture.

The Embedded Coder® Dictionary has a tab for each type of code definition. In each tab, you configure the properties of code definitions. Use the table to configure properties and compare definitions side by side. To access properties that do not appear in the table, use the Property Inspector. To verify results as you configure properties, use the pseudocode preview.

You can apply the definitions that you create in the dictionary to model elements by using the Code Mappings editor (see Configure Default C Code Generation for Categories of Data Elements and Functions). To create storage classes and memory sections that you can use outside of the Code Mappings editor, use the Custom Storage Class Designer (see Create Code Definitions for External Data Objects).

Open the Embedded Coder Dictionary

  • To open an Embedded Coder Dictionary, in a model window, on the C Code tab, select Code Interface > Embedded Coder Dictionary.

    The Embedded Coder Dictionary window displays code generation definitions that are stored in the model file. If the model is linked to a data dictionary, the window also displays definitions that are stored in that data dictionary or, if applicable, in a referenced dictionary. The Source column indicates where each definition is stored.

  • To open the Embedded Coder Dictionary in a Simulink® data dictionary, in the Model Explorer Model Hierarchy pane:

    1. Under the dictionary node, select the Embedded Coder node.

      If you do not see the node, right-click the dictionary node and select Show Empty Sections.

    2. In the Dialog pane (the right pane), click Open Embedded Coder Dictionary.

Examples

Create and Verify Storage Class

In a model, create a storage class that aggregates internal model data, including block states, into a structure whose characteristics you can control. Then, verify the storage class by generating code from the model.

  1. Open the example model rtwdemo_roll.

    rtwdemo_roll

  2. If the model does not open in the Embedded Coder app, open the app and click the C Code tab.

  3. On the C Code tab, select Code Interface > Embedded Coder Dictionary. The Embedded Coder Dictionary window displays code generation definitions that are stored in the model file.

  4. In the Embedded Coder Dictionary window, click Add.

  5. Select the new storage class that appears at the bottom of the list, StorageClass1 . In the Property Inspector pane on the right, set the property values listed in this table.

    PropertyValue
    NameInternalStruct
    Header FileinternalData_$R.h
    Definition FileinternalData_$R.c
    Storage TypeStructured
    Structure Properties > Type NameinternalData_T_$M
    Structure Properties > Instance NameinternalData_$M

    After making your changes, in the bottom pane, verify that the pseudocode preview reflects what you expect.

  6. Return to the model editor. To open the Code Mappings editor, below the canvas, double-click Code Mappings. On the Data Defaults tab, expand the Signals section. Select the Signals, states, and internal data row and set Storage Class to InternalStruct.

  7. In the Configuration Parameters dialog box, on the Code Generation > Code Placement pane, set File packaging format to Modular.

  8. Generate code.

  9. In the Simulink Editor Code view, open and inspect the file internalData_rtwdemo_roll.h. The file defines the structure type internalData_T_, whose fields represent block states in the model.

    /* Storage class 'InternalStruct', for system '<Root>' */
typedef struct {
  real32_T FixPtUnitDelay1_DSTATE;     /* '<S7>/FixPt Unit Delay1' */
  real32_T Integrator_DSTATE;          /* '<S1>/Integrator' */
  int8_T Integrator_PrevResetState;    /* '<S1>/Integrator' */
} internalData_T_;

    The file also declares a global structure variable named internalData_.

    /* Storage class 'InternalStruct' */
extern internalData_T_ internalData_;

  10. Open and inspect the file internalData_rtwdemo_roll.c. The file allocates memory for internalData_.

    /* Storage class 'InternalStruct' */
internalData_T_ internalData_;

Create Function Customization Template

With a function template, you can specify a rule that governs the names of generated entry-point functions. This technique helps save time and maintenance effort in a model with many entry-point functions, such as an export-function model or a multirate, multitasking model.

This example shows how to create a function template that specifies the naming rule func_$N_$R. $N is the base name of each generated function and $R is the name of the Simulink model.

  1. Open the example model rtwdemo_mrmtbb.

  2. Update the block diagram. This multitasking model has two execution rates, so the generated code includes two corresponding entry-point functions.

  3. In the model, set model configuration parameter System target file to ert.tlc. To use a function customization template, you must use an ERT-based system target file.

  4. In the Simulink Editor, open the Embedded Coder app and open the Embedded Coder Dictionary.

  5. In the Embedded Coder Dictionary, on the Function Customization Templates tab, click Add.

  6. For the new function template, set these properties:

    • Name to myFunctions.

    • Function Name to func_$N_$R.

    After making your changes, verify that the pseudocode preview reflects what you expect.

  7. In the model window, open the Code Mappings editor. On the Function Defaults tab, for the Initialize/Terminate and Execution rows, set Function Customization Template to myFunctions.

  8. Generate code.

  9. In the Code view, open and inspect the file rtwdemo_mrmtbb.c. The file defines the two execution functions, func_step0_rtwdemo_mrmtbb and func_step1_rtwdemo_mrmtbb, whose names conform to the rule that you specified in the function template.

Create Memory Section

For an example that shows how to create a memory section, see Control Data and Function Placement in Memory by Inserting Pragmas.

Create Storage Class for Use with Statically and Dynamically Initialized Data

This example shows how to create a storage class that places global variable definitions and declarations in files whose names depend on the model name. You create two copies of the storage class so that you can use one copy with parameter data (the data category Model parameters) and one copy with other data.

Typically, the generated code initializes parameter data statically, outside any function, and initializes other data dynamically, in the model initialization function. When you create a storage class by using the Custom Storage Class Designer or an Embedded Coder Dictionary, you set the Data Initialization property to specify the initialization mechanism.

In an Embedded Coder Dictionary, for each storage class, you must select Static or Dynamic initialization. Consider creating one copy of the storage class for parameter data (Static) and one copy for other data (Dynamic).

Create Storage Class

  1. Open example model rtwdemo_roll.

  2. If the C Code tab is not open, open the Embedded Coder app and click the C Code tab.

  3. Select Code Interface > Embedded Coder Dictionary

  4. In the Embedded Coder Dictionary, click Add.

  5. For the new storage class, set these properties:

    • Name to SigsStates

    • Header File to $R_my_data.h

    • Definition File to $R_my_data.c

    By default, the Data Initialization property is set to Dynamic, which means the storage class is suitable for use with signals, states, and data stores.

    After making your changes, verify that the pseudocode preview reflects what you expect.

  6. Click Duplicate. A new storage class, SigsStates_copy, appears.

  7. For the new storage class, set these properties:

    • Name to Params

    • Data Initialization to Static

    After making your changes, verify that the pseudocode preview reflects what you expect.

Apply Storage Class and Generate Code

  1. Return to the model and open the Code Mappings editor. Below the model canvas, double-click Code Mappings - C.

  2. On the Data Defaults tab, for the Parameters > Model Parameters row, in the Storage Class column, select Params.

  3. For the Signals > Signals, states, and internal data row, set Storage Class to SigsStates.

  4. Configure some parameter data elements in the model so that optimizations do not eliminate those elements from the generated code. On the Modeling tab, click Design > Model Workspace.

  5. In the Model Explorer, on the center pane, select the three rows that correspond to the variables dispGain, intGain, and rateGain in the model workspace.

  6. Right-click one of the rows and click Convert to parameter object. The Model Data Editor converts the workspace variables to Simulink.Parameter objects.

  7. In the row for the parameter dispGain, in the Storage Class column, click Configure. The model window highlights the row for the dispGain parameter in the Code Mappings editor.

  8. For each variable, in the Storage Class column, select Model default: Params, which means they acquire the default storage class that you specified for Model parameters.

  9. In the Configuration Parameters dialog box, on the Code Generation > Code Placement pane, set File packaging format to Modular.

  10. Generate code.

  11. In the Code view, open and inspect the files rtwdemo_roll_my_data.c and rtwdemo_roll_my_data.h. These files define and declare global variables that correspond to the parameter objects and some block states, such as the state of the Integrator block in the BasicRollMode subsystem.

    /* Storage class 'SigsStates' */
real32_T rtFixPtUnitDelay1_DSTATE;
real32_T rtIntegrator_DSTATE;
int8_T rtIntegrator_PrevResetState;

/* Storage class 'Params' */
real32_T dispGain = 0.75F;
real32_T intGain = 0.5F;
real32_T rateGain = 2.0F;

Refer to Code Generation Definitions in a Package

You can configure an Embedded Coder Dictionary to refer to code generation definitions that you store in a package (see Create Code Definitions for External Data Objects). Those definitions then appear available for selection in the Code Mappings editor. In this example, you configure the Embedded Coder Dictionary in rtwdemo_roll to refer to definitions stored in the built-in example package ECoderDemos.

  1. Open the Embedded Coder Dictionary for rtwdemo_roll. For instructions, see Create and Verify Storage Class.

  2. In the Embedded Coder Dictionary window, click Manage Packages.

  3. In the Manage Packages dialog box, click Refresh. Wait until more options appear in the Select package drop-down list.

  4. Set Select package to ECoderDemos and click Load.

    In the Embedded Coder Dictionary window, on the Storage Classes tab, the table shows the storage classes defined in the ECoderDemos package. Now, in rtwdemo_roll, you can select these storage classes in the Code Mappings editor on the Data Defaults tab.

  5. To unload the package, in the Manage Packages dialog box, select the package in the Select package drop-down list and click Unload.

Share Code Generation Definitions Between Models by Using Simulink Data Dictionary

For an example that shows how to share code generation definitions between models by using data dictionaries, see Share Embedded Coder Dictionary Definition Between Models.

Configure Default Code Mappings in a Shared Coder Dictionary

For an example that shows how to configure default code mappings in a shared Embedded Coder Dictionary, see Configure Default Code Mapping in a Shared Dictionary.

Related Examples

Parameters

These properties appear in the Property Inspector pane of the Embedded Coder Dictionary window. In the table, some properties appear as columns to facilitate batch editing.

Storage Classes

Name of the storage class. The name must be unique among the storage classes in the dictionary.

For lists of built-in and example storage classes that Simulink provides, see Choose Storage Class for Controlling Data Representation in Generated Code.

Custom text that you can use to describe the purpose and functionality of the storage class.

This property is read-only.

The location of the storage class definition.

Specification to access data associated with the model. Access the data directly (Direct) or through customizable get and set functions (Function). For more information, see Access Data Through Functions by Using Storage Classes in Embedded Coder Dictionary.

Dependencies

  • Setting this property to Function:

    • Sets Data Scope to Imported.

    • Means that you cannot specify multi-instance properties.

    • Enables these properties:

      • Access Mode

      • Allowed Access

      • Name of Getter

      • Name of Setter

    • Disables the Preserve array dimensions property. To preserve dimensions of multidimensional arrays in the generated code, set Data Access to Direct.

Specification that the generated code define the data (Exported) or import (Imported) the data definition from external code. Built-in storage classes and storage classes in packages such as Simulink can use other scope options, such as File.

Dependencies

  • Setting this property to Imported:

    • Disables Definition File. To include your external source code file in the build process, use model configuration parameters. For an example, see Configure Data Interface.

    • Means that you cannot set Header File to $N.h, though you can use the $N token.

  • To set this property to Exported, you must use one of the tokens $N or $R in the value of Header File.

Name of the header file that declares the data, specified as a name or naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$RName of root model
$NName of associated data element
$GName of storage class
$UUser token text, which you specify for a model as described in Identifier Format Control

Dependencies

  • If you set Data Scope to Exported, you must use one of the tokens $R or $N in the value of this property.

  • If you set Data Scope to Imported, you cannot set the value of this property to $N.h, but you can use the $N token.

Name of the source file that defines the data, specified as a name or naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$RName of root model
$NName of associated data element
$GName of storage class
$UUser token text, which you specify for a model as described in Identifier Format Control

Dependencies

Setting Data Scope to Imported disables Definition File. To include your external source code file in the build process, use model configuration parameters. For an example, see Configure Data Interface.

Specification for the storage class to access data associated with the model through functions by using Value or Pointer. For more information, see Access Data Through Functions by Using Storage Classes in Embedded Coder Dictionary.

Dependencies

This property is enabled only when you set Data Access to Function.

Specification for the storage class to allow read and write (Read/Write), read-only (Read Only), or write-only (Write Only) access to the data.

Dependencies

This property is enabled only when you set Data Access to Function.

Name of the get function that fetches the associated data, specified as a name or naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$NName of associated data element (required)
$RName of root model
$MMangle text that ensures uniqueness
$UUser token text. See Identifier Format Control.

Dependencies

This property is enabled only when you set Data Access to Function.

Name of the set function that fetches the modifies data, specified as a name or naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$NName of associated data element (required)
$RName of root model
$MMangle text that ensures uniqueness
$UUser token text. See Identifier Format Control.

Dependencies

This property is enabled only when you set Data Access to Function.

Specification for the storage class to use either the storage settings that you specify in the Single-instance storage section or the storage settings that you specify in the Multi-instance storage section. When you apply the storage class to a data item, the Embedded Coder Dictionary determines if it is a single-instance storage class or a multi-instance storage class by the type of data and by the context of the model within the model reference hierarchy.

Dependencies

Selecting this property enables the sections Single-instance storage and Multi-instance storage. The properties Storage Type, Type Name, and Instance Name appear in both the Single-instance storage and Multi-instance storage sections.

Specification to aggregate the data that uses the storage class into a structure in the generated code. Each data element appears in the code as a field of the structure. To create a structure, use Structured.

Dependencies

Setting this property to Structured enables Type Name and Instance Name.

Name of the structure type in the generated code, specified as a name or a naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$RName of root model
$NBase name of associated function, such as step
$GName of storage class
$UUser token text, which you specify for a model as described in Identifier Format Control
$MName-mangling text inserted, if necessary, to avoid name collisions

Dependencies

Setting Storage Type to Structured enables this property.

Name of the structure variable in the generated code, specified as a name or a naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$RName of root model
$NBase name of associated function, such as step
$GName of storage class
$UUser token text, which you specify for a model as described in Identifier Format Control
$MName-mangling text inserted, if necessary, to avoid name collisions

Dependencies

Setting Storage Type to Structured enables this property.

Specification that the generated code initialize the data.

  • Dynamic — The generated code initializes the data as part of the model initialization entry-point function.

  • Static — The generated code initializes the data in the same statement that defines and allocates memory for the data. The assignment statement appears at the top of a .c or .cpp source file, outside of a function.

  • None — The generated code does not initialize the data.

Dependencies

  • If you select Const, you cannot set this property to Dynamic.

  • Setting this property to Dynamic disables Const.

Location in memory to allocate data, specified as a memory section that exists in the Embedded Coder Dictionary on the Memory Sections tab. For information about memory sections, see Control Data and Function Placement in Memory by Inserting Pragmas.

Specification for the storage class to preserve dimensions of multidimensional arrays in the generated code. For more information, see Preserve Dimensions of Multidimensional Arrays in Generated Code.

Specification to apply the const qualifier to the data.

Dependencies

  • If you select this property, you cannot set Data Initialization to Dynamic.

  • Setting Data Initialization to Dynamic disables this property.

Specification to apply the volatile qualifier to the data.

Specification to apply a custom qualifier to the data. For example, some memory architectures support qualifiers far and huge.

Do not use this property to apply the keyword static. Instead, use the built-in storage class FileScope, which you cannot apply with the Code Mappings editor. See Choose Storage Class for Controlling Data Representation in Generated Code.

Specification indicating whether to allow usage of the storage class with model parameters.

Dependencies

  • Setting Data Initialization to Static enables this property.

  • Setting Data Initialization to Dynamic disables this property.

  • To set the value of this property, set Data Initialization to None.

Specification indicating whether to allow usage of the storage class with model signals.

Dependencies

  • Setting Data Initialization to Dynamic enables this property.

  • Setting Data Initialization to Static disables this property.

  • To set the value of this property, set Data Initialization to None.

Function Customization Templates

Name of the template. The name must be unique among the function templates in the dictionary. Embedded Coder provides the built-in templates listed in this table.

TemplateDescription
ModelFunctionIn the Code Mappings editor, use for entry-point functions for initialization, execution, termination, and reset (see Configure Default Code Generation for Functions)
UtilityFunctionIn the Code Mappings editor, use for shared utility functions (see Configure Default Code Generation for Functions)

Custom text that you can use to describe the purpose and functionality of the function template.

This property is read-only.

The location of the function template definition.

  • Model name — Defined in a Simulink model.

  • Dictionary name — Defined in a Simulink data dictionary (see What Is a Data Dictionary?).

Names of the functions in the generated code, specified as a naming rule. A naming rule includes a combination of text and tokens. Valid tokens are listed in this table.

TokenDescription
$RName of root model
$NBase name of associated function, such as step
$UUser token text, which you specify for a model as described in Identifier Format Control
$CFor shared utility functions, a checksum inserted to avoid name collisions
$MName-mangling text inserted, if necessary, to avoid name collisions

Location in memory to allocate function, specified as a memory section that exists in the Embedded Coder Dictionary on the Memory Sections tab. For information about memory sections, see Control Data and Function Placement in Memory by Inserting Pragmas.

Memory Sections

Name of the memory section. The name must be unique among the memory sections in the dictionary. Embedded Coder provides the built-in memory sections listed in this table.

Memory SectionDescription
MemConstApply the storage type qualifier const to the data.
MemVolatileApply the storage type qualifier volatile to the data.
MemConstVolatileApply the storage type qualifiers const and volatile to the data.

Custom text that you can use to describe the purpose and functionality of the memory section.

This property is read-only.

The location of the memory section definition.

Code comment that the code generator includes with the pragmas or other decorations that you specify with Pre Statement and Post Statement.

Code, such as pragmas, to insert before the definitions and declarations of the data or functions that are in the memory section.

You can use the token $R to represent the name of the model that uses the memory section.

When you set Statements Surround to Each variable, you can use the token $N to represent the name of each variable or function that uses the memory section.

Code, such as pragmas, to insert after the definitions and declarations of the data or functions that are in the memory section.

You can use the token $R to represent the name of the model that uses the memory section.

When you set Statements Surround to Each variable, you can use the token $N to represent the name of each variable or function that uses the memory section.

Specification to insert code statements (Pre Statement and Post Statement):

  • Around each variable and function that uses the memory section. Select Each variable.

  • Once, around the entire memory section. The generated code aggregates the variable and function definitions into a contiguous code block and surrounds the block with the statements. Select Group of variables.

Limitations

  • A storage class or function customization template that you create in an Embedded Coder Dictionary cannot use a memory section that you load from a package (as described in Refer to Code Generation Definitions in a Package). Use a memory section defined in the Embedded Coder Dictionary.

  • You cannot create code generation definitions in a .mdl model file.

  • For additional limitations for code generation definitions in the Embedded Coder Dictionary of a data dictionary (.sldd file), see Deploy Code Generation Definitions.

See Also

Introduced in R2018a

Embedded Coder Documentation

Support