Main Content

Code Mappings Editor

Associate model elements with code definitions

Description

The Code Mappings editor is a graphical interface where you can configure data elements and entry-point functions in a model, excluding referenced models, for code generation. Each model in a model reference hierarchy has its own code mappings. Associate each category of model data element with a specific storage class and each category of model entry-point function with a specific function customization template throughout a model. Then, override those settings, as needed, for specific data elements and functions.

A storage class defines properties such as appearance and location, which the code generator uses when producing code for associated data. Function customization templates define how the code generator produces code for associated functions. If you leave the storage class or function customization template set to Default, you can configure a memory section for that data or function category.

To configure data elements and functions for code generation, use the tables in the Code Mappings editor display:

  • Data Defaults

  • Function Defaults

  • Functions

  • Inports

  • Outports

  • Parameters

  • Data Stores

  • Signals/States

When you select a row in the active table, the Code section of the Property Inspector displays storage class or function customization template property settings for the selected data element or function.

Before you can configure a signal for code generation, add the signal to the model code mappings. Add and remove signals from the code mappings by pausing on the ellipsis that appears above or below a signal line to open the action bar. Click the Add Signal or Remove Signal button. These buttons are also available in the Code Mappings editor on the Signals/States tab.

Open the Code Mappings Editor

Do one of the following:

  • Open the Embedded Coder® app. On the C Code tab, select Code Interface > Default Code Mappings or Code Interface > Individual Element Code Mappings.

  • Open the Embedded Coder app. On the C Code tab, in the bottom left corner of the Simulink® Editor window, click the Code Mappings - C tab.

  • In the model canvas of the Simulink Editor window, click the perspective control in the lower-right corner and select Code. Then, click the Code Mappings - C tab.

Examples

Configure Code Generation for Root Inport and Outport Blocks

Configure code generation for the root Inport and Outport blocks throughout a model. Applying default configurations can save time, especially for large-scale models that use a significant amount of data. After applying default mappings, you can adjust mappings for individual data elements.

Set Up Example Environment
  1. Copy external code files into a writable folder.

    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_input_data.c'));
    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_input_data.h'));
    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_heading_mode.c'));
    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_heading_mode.h'));
  2. Open model rtwdemo_roll. Save a copy of the model in the folder where you copied the external code files.

  3. Open the Embedded Coder app.

Configure Default Mappings

Configure the code generator to:

  • Use header file roll_input_data.h to declare the variables representing model Inport blocks.

  • Represent variables for model Outport blocks as separate global variables.

  • Define output variables in roll_output_data.c and declare them in roll_output_data.h.

  • Configure names that the code generator uses for variables it produces in the code for Inport blocks.

  1. In the C Code tab, select Code Interface > Default Code Mappings.

  2. In the Data Defaults tab, under Inports and Outports, select the row for Inports. Then, set the storage class to ImportFromFile.

  3. In the Property Inspector, set Header File to roll_input_data.h.

  4. Set the storage class for model element category Outports to ExportToFile.

  5. Set Header File to roll_output_data.h and Definition File to roll_output_data.c.

Configure Individual Inports for Default Configuration
  1. In the Code Mappings editor, click the Inports tab. The storage class for each inport 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 default configuration for inports.

  2. Force the code generator to use the default configuration for inports, storage class ImportFromFile with external header file roll_input_data.h. Press the Ctrl key and select the inports. For one of the selected inports, set the storage class to Model default: ImportFromFile. The editor updates the storage class setting for the selected inports.

Override Default Mappings

Override the default source location for inport variable HDG_Mode. That variable is declared in the external file roll_heading_mode.h.

  1. In the Code Mappings editor, click the Inports tab.

  2. Select the HDG_Mode row.

  3. Set Storage Class to ImportFromFile.

  4. In the Property Inspector, under the Code section, set Header File to roll_heading_mode.h.

  5. Configure the code generator to produce variable names in the code for the Inport blocks that match the variable names in external files roll_input_data.h and roll_heading_mode.h. On the Inports tab, select each Inport block and in the Property Inspector set Identifier to the block name. When the storage class is set to a value other than Auto, you must specify a value for the Identifier storage class property.

Include External Source Files In Code Generation and Build Process

Include external source files roll_input_data.c and roll_heading_mode.c in the code generation and build process. Set the model configuration parameter Source files to roll_input_data.c roll_heading_mode.c.

Save the model.

Generate and Verify Code

Generate code and verify that the code generated for the Inport and Output blocks appears as you expect.

  • rtwdemo_roll.h includes these header files associated with storage classes:

    #include "roll_output_data.h"
    #include "roll_input_data.h"
    #include "roll_heading_mode.h"
    
  • roll_heading_mode.c includes roll_heading_mode.h and defines variable HDG_Mode.

    #include "roll_heading_mode.h"
    
    boolean_T HDG_Mode;
  • roll_input_data.c defines the variables declared in roll_input_data.h.

    #include "roll_input_data.h"
    
    boolean_T AP_Eng;
    real32_T HDG_Ref;
    real32_T Rate_FB;
    real32_T Phi;
    real32_T Psi;
    real32_T TAS;
    real32_T Turn_Knob;
  • roll_output_data.c includes this exported data definition:

    real32_T Ail_Cmd;
  • roll_output_data.h includes this exported data declaration:

    extern real32_T Ail_Cmd;

Configure Default Function Names for Entry-Point Functions

By default, the code generator uses the identifier naming rule $R$N to name entry-point functions. $R is the name of the root model. $N is the name of the function, for example, initialize, step, and terminate. To integrate generated code with existing external code or to comply with naming standards or guidelines, you can adjust the default naming rule. This example shows how to add the text string myproj_ as a prefix to $R$. Adjusting the default naming rule can save time, especially for multirate models for which the code generator produces a unique step function for each rate.

Set Up Example Environment
  1. Open model rtwdemo_multirate_multitasking. Save a copy to a writable folder.

  2. Open the Embedded Coder app. The C Code tab opens, which includes the Code Mappings editor.

Define Function Naming Rule

Create a function customization template that defines the naming rule myproj_$R$N.

  1. Open the Embedded Coder Dictionary. In the C Code tab, select Code Interface > Embedded Coder Dictionary.

  2. Click the Function Customization Templates tab.

  3. Click Add.

  4. In the Name column of the new table row, name the new template myproj_FunctionTemplate.

  5. In the Function Name column, enter the naming rule myproj_$R$N.

  6. Close the Embedded Coder Dictionary.

Configure Default Mappings
  1. In the C Code tab, select Code Interface > Default Code Mappings.

  2. Click the Function Defaults tab.

  3. For the Initialize/Terminate and Execution function categories, change the default function customization template from Default to myproj_FunctionTemplate.

  4. Save the model.

Generate and Review Code

Generate code and verify the entry-point function names.

void myproj_rtwdemo_multirate_multitasking_step0(void) /* Sample time: [1.0s, 0.0s] */
{
  (rtM->Timing.RateInteraction.TID0_1)++;
  if ((rtM->Timing.RateInteraction.TID0_1) > 1) {
       rtM->Timing.RateInteraction.TID0_1 = 0;
  }

  if (rtM->Timing.RateInteraction.TID0_1 == 1) {
      rtDW.RateTransition = rtDW.RateTransition_Buffer0;
  }
      rtY.Out2 = 2.0 * rtDW.RateTransition + rtU.In1_1s;
      rtY.Out1 = (3.0 * rtDW.RateTransition + rtU.In1_1s) * 5.0 + rtY.Out2;
}

/* Model step function for TID1 */
void myproj_rtwdemo_multirate_multitasking_step1(void) /* Sample time: [2.0s, 0.0s] */
{
  rtDW.RateTransition_Buffer0 = rtDW.Integrator_DSTATE;
  rtDW.Integrator_DSTATE += 2.0 * rtU.In2_2s;
}

void myproj_rtwdemo_multirate_multitasking_initialize(void)
{
  /* (no initialization code required) */
}

void myproj_rtwdemo_multirate_multitasking_terminate(void)
{
  /* (no terminate code required) */
}

Customize Individual Entry-Point Functions

For your model, you can customize the names of most entry-point functions and the arguments of execution functions, such as step functions and Simulink functions. This example shows how to customize the entry-point functions for the model rtwdemo_roll.

Set Up the Environment
  1. Copy external code files into a writable folder.

    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_input_data.c'));
    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_input_data.h'));
    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_heading_mode.c'));
    copyfile(fullfile(matlabroot,'toolbox','rtw','rtwdemos','roll_heading_mode.h'));
  2. Open model rtwdemo_roll. Save a copy of the model in the folder where you copied the external code files.

  3. Open the Embedded Coder app. The C Code tab opens, which includes the Code Mappings editor.

Customize Entry-Point Functions
  1. In the C Code tab, select Code Interface > Individual Element Code Mappings.

  2. Click the Functions tab.

  3. Customize the name of the step (execution) function. In the Function Name column, enter the name roll_run.

  4. Customize arguments of the step function. Open the configuration dialog box for the step function by clicking the prototype hyperlink in the Function Preview column.

  5. Select Configure arguments for Step function prototype.

  6. To open a table that displays the default configurations for the arguments, click Get Default.

  7. Customize the arguments:

    • From the C return argument drop-down list, select Ail_Cmd.

    • For each port, in the C Identifier Name field, remove the arg_ prefix from their default names.

    • For the HDG_Mode Inport, from the C Type Qualifier drop-down list, select Pointer. In the C Identifier Name field change the name to HDG_Mode_Ptr

  8. Click Apply and verify that the function prototype reflects the changes.

  9. Validate the changes by clicking Validate.

  10. Click OK.

Generate and Verify Code
  1. Generate code.

  2. Verify the updates in the generated C file rtwdemo_roll.c. To find the updated step function (roll_run), use the Search field.

  3. Select the step function to verify its prototype.

    real32_T roll_run(real32_T Phi, real32_T Psi, real32_T Rate_FB, real32_T TAS,
                      boolean_T AP_Eng, boolean_T *HDG_Mode_Ptr, real32_T HDG_Ref,
                      real32_T Turn_Knob)

Related Examples

Parameters

Data Defaults

Names a category of Simulink model data elements. The storage class that you set for a category applies to elements in that category throughout the model.

Model Element CategoryDescription
InportsRoot-level input ports of a model, such as Inport and In Bus Element blocks.
OutportsRoot-level output ports of a model, such as Outport and Out Bus Element blocks.
Signals, states, and internal dataData elements that are internal to the model, such as block output signals, discrete block states, data stores, and zero-crossing signals.
Shared local data storesData Store Memory blocks that have the block parameter Share across model instances set. These data stores are accessible only in the model where they are defined. The data store value is shared across instances of the model.
Global data storesData stores that are defined by a signal object in the base workspace or in a data dictionary. Multiple models in an application can use these data stores. To view and configure these data stores in the Code Mappings editor, click the Refresh link to the right of the category name. Clicking this link updates the model diagram.
Model parameter argumentsParameters in the model workspace that you configure as model arguments. These parameters are exposed at the model block to enable each model instance to provide its own value. To specify a parameter as a model argument, select the Model Data Editor > Parameters > Argument check box.
Model parametersParameters that are defined within a model, such as parameters in the model workspace. Excludes model arguments.
External parametersParameters that you define as objects in the base workspace or in a data dictionary. Multiple models in an application can use these parameters. To view and configure these parameters in the Code Mappings editor, click the Refresh link to the right of the category name. Clicking this link updates the model diagram.
ConstantsConstant-value block output and constant parameters in a model.

The Code Mappings editor presents valid storage class options for a given category. The options can include:

  • Unspecified storage class (Default). The code generator places the code for the category of data elements in standard structures, such as B_, ExtY_, ExtU_, DW_, and P_. See Standard Data Structures in the Generated Code.

  • Relevant predefined storage classes, such as ExportedGlobal.

  • Relevant storage classes in an available package, such as ImportFromFile .

  • Storage class defined in an Embedded Coder Dictionary .

Definition (specification) that the code generator uses to determine properties, such as appearance and location, for code that it produces for model data elements. See Choose Storage Class for Controlling Data Representation in Generated Code.

Function Defaults

Names a category of Simulink model functions. The function customization template that you set for a category applies to functions in that category throughout the model.

Model Function CategoryDescription
Initialize/TerminateEntry-point functions for initialization and termination
ExecutionEntry-point functions for initiating execution and resets
Shared utilityShared utility functions

Definition (specification) that the code generator uses to determine properties, such as appearance and location, for code that it produces for model functions. Templates are not available by default. You might need to define a function customization template in the Embedded Coder Dictionary.

Functions

Identifies the type of entry-point function. For rate-based models, this property provides the sample rate of step functions.

Definition (specification) that the code generator uses to determine properties, such as appearance and location, for code that it produces for a model function.

Name that the code generator gives a model function.

Preview of the entry-point function prototype. To verify a prototype, review the prototype preview. To open a dialog box where you can customize the prototype, click the preview hyperlink. For more information, see Configure Default Settings for Functions.

Inports

Identifies a root Inport block or an element of an In Bus Element block (for example, InBus1.signal1) in the model. If the element resolves to a data object, the Code Mappings editor displays a resolve-to-signal-object icon to the right of the source name and resolves the configuration based on whether the storage class setting for the element is Auto. If the storage class is Auto, the data element assumes the code configuration that the data object specifies. The editor changes the display text in the Storage Class column to From signal object: followed by the name of the storage class of the data object. If the storage class is not Auto, the data element assumes the configuration that you specify in the Code Mappings editor.

Definition that the code generator uses to determine properties, such as appearance and location, for code that it produces for the root inport. See Choose Storage Class for Controlling Data Representation in Generated Code.

Outports

Identifies a root-level Outport block or an element of an Out Bus Element block (for example, OutBus1.signal1) in the model. If the element resolves to a data object, the Code Mappings editor displays a resolve-to-signal-object icon to the right of the source name and resolves the configuration based on whether the storage class setting for the element is Auto. If the storage class is Auto, the data element assumes the code configuration that the data object specifies. The editor changes the display text in the Storage Class column to From signal object: followed by the name of the storage class of the data object. If the storage class is not Auto, the data element assumes the configuration that you specify in the Code Mappings editor.

Definition that the code generator uses to determine properties, such as appearance and location, for code that it produces for the root outport. See Choose Storage Class for Controlling Data Representation in Generated Code.

Parameters

Identifies a parameter in the model. If the element resolves to a data object, the Code Mappings editor displays a resolve-to-parameter-object icon to the right of the source name and resolves the configuration based on whether the storage class setting for the element is Auto. If the storage class is Auto, the data element assumes the code configuration that the data object specifies. The editor changes the display text in the Storage Class column to From parameter object: followed by the name of the storage class of the data object. If the storage class is not Auto, the data element assumes the configuration that you specify in the code mappings.

Types of parameter elements are listed in this table.

Type of Parameter ElementDescription
Model parameter argumentBlock parameter in the model workspace that you configure as a model argument. The parameter is exposed at the model block to enable each model instance to provide its own value. To specify a parameter as a model argument, select the Model Data Editor > Parameters > Argument check box.
Model parameterParameter that is defined within a model, such as a parameter in the model workspace. Excludes model arguments.
External parameterParameter that you define as an object in the base workspace or in a data dictionary. Multiple models in an application can use these parameters. This grouping of parameters appears in the editor only if the model uses such an element. To view and configure these parameters in the Code Mappings editor, click the Refresh link to the right of the category name. Clicking this link updates the model diagram.

Definition that the code generator uses to determine properties, such as appearance and location, for code that it produces for the parameter. For external parameters, after you click the Refresh link to the right of the category name, the compiled storage class (for example, the storage class configured for an external parameter) appears on the right side of the Storage Class column. See Choose Storage Class for Controlling Data Representation in Generated Code.

Data Stores

Identifies a data store in the model. If the element resolves to a data object, the Code Mappings editor displays a resolve-to-signal-object icon to the right of the source name and resolves the configuration based on whether the storage class setting for the element is Auto. If the storage class is Auto, the data element assumes the code configuration that the data object specifies. The editor changes the display text in the Storage Class column to From signal object: followed by the name of the storage class of the data object. If the storage class is not Auto, the data element assumes the configuration that you specify in the code mappings.

Types of data store elements are listed in this table.

Type of Data Store ElementDescription
Local data storeData store that is accessible from anywhere in the model hierarchy that is at or below the level at which you define the data store. You can define a local data store graphically in a model by including a Data Store Memory block or by creating a signal object (synthesized data store) in the model workspace.
Shared local data storeData Store Memory block that has the block parameter Share across model instances set. These data stores are accessible only in the model where they are defined. The data store value is shared across instances of the model. This grouping of data stores appears in the editor only if such an element exists in the model.
Global data storeData store that is defined by a signal object in the base workspace or in a data dictionary. Multiple models in an application can use these data stores. These data stores are not configurable in the code mappings. After you click the refresh button, they appear in the Code Mappings editor in a read-only state for viewing or accounting purposes. This grouping of data stores appears in the editor only if the model uses such an element. To view and configure these data stores in the Code Mappings editor, click the Refresh link to the right of the category name. Clicking this link updates the model diagram.

Names of local and shared local data stores appear in the format block-name: data-store-name.

Depending on how the data store element is represented and configured in the model, local and shared local data stores can resolve to a signal object in the model workspace, based workspace, or a data dictionary. Global data stores resolve to a signal object in the base workspace or a data dictionary.

Definition that the code generator uses to determine properties, such as appearance and location, for code that it produces for the data store. For global data stores, after you click the Refresh link to the right of the category name, the compiled storage class (for example, the storage class configured for a global data store) appears on the right side of the Storage Class column. See Choose Storage Class for Controlling Data Representation in Generated Code.

Link that you can click to highlight the data store in the model diagram.

Signals/States

Identifies a signal line or state in the model. If the element resolves to a data object, the Code Mappings editor displays a resolve -to-signal-object icon to the right of the source name and resolves the configuration based on whether the storage class setting for the element is Auto. If the storage class is Auto, the data element assumes the code configuration that the data object specifies. The editor changes the display text in the Storage Class column to From signal object: followed by the name of the storage class of the data object. If the storage class is not Auto, the data element assumes the configuration that you specify in the Code Mappings editor.

The Code Mappings editor lists:

  • Named signals and states by using the data element name

  • Unnamed signals by using the format source-block: port-number

  • States used in multiple blocks by using the format block-name: state-name

To configure an individual signal line in the Code Mappings editor for a model, first you must add the signal to the mappings. See Configure Signal Data for C Code Generation.

Definition that the code generator uses to determine properties, such as appearance and location, for code that it produces for the signal line or state. See Choose Storage Class for Controlling Data Representation in Generated Code.

Link that you can click to highlight the signal line or block that uses the state in the model diagram.

Introduced in R2018a