coder.mapping.api.CodeMapping

Model data and function interface configuration for C code generation

Since R2020b

Description

A code mappings object and related functions enable you to configure C code generation for data and functions of a Simulink^® model. For model data elements, code mappings associate data elements with configurations that consist of a storage class and storage class properties. For functions, code mappings associate entry-point functions with configurations that consist of a function customization template. Reduce the effort of preparing a model for C code generation by specifying default configurations for categories of data elements and functions across a model. Override default configurations by configuring data elements or functions individually. For smaller models, you can choose to configure each data element and function individually. For models with an attached Embedded Coder Dictionary, you can map model elements to service interfaces defined in that dictionary.

Creation

When you select a code generation app from the Apps tab in the Simulink Editor, such as the Simulink Coder or Embedded Coder app, the app creates a coder.mapping.api.CodeMapping object if code mappings do not already exist. The app creates code mappings based on code customization settings stored in the model active configuration set object. The configuration set object can specify memory sections for data and functions.

Create a coder.mapping.api.CodeMapping object programmatically by calling the function coder.mapping.utils.create. Create a mapping based on the active configuration set object or based on the default memory section and shared utility naming rule configurations of another configuration set object.

Object Functions

addSignal	Add block output signal to model code mappings
coder.mapping.api.get	Get code mappings for model
coder.mapping.utils.create	Create code mappings object for configuring data and function interface for C and C++ code generation
find	Get model elements for the category of model code mappings
getDataDefault	Get default storage class or storage class property setting for model data category
getDataStore	Get code and calibration configuration from code mappings for local or shared local data store
getDataTransfer	Get code configuration from code mappings for signal representing data transfer
getDeploymentType	Get deployment type of model
getFunction	Get code configuration from code mappings for model function
getFunctionDefault	Get default function customization template or memory section for model functions category
getInport	Get code and calibration configuration from code mappings for root-level inport
getModelParameter	Get code and calibration configuration from code mappings for model parameters
getOutport	Get code and calibration configuration from code mappings for root-level outport
getSignal	Get code and calibration configuration from code mappings for block output signal
getState	Get code and calibration configuration from code mappings for block state
removeSignal	Remove block output signal from model code mappings
setDataDefault	Set default storage class and storage class property values for model data category
setDataStore	Configure local or shared local data store for code and calibration file (a2l) generation
setDataTransfer	Set code configuration in code mappings for signal representing data transfer
setDeploymentType	Set deployment type of model
setFunction	Set coder mapping information for model function
setFunctionDefault	Set default function customization template and memory section for model functions category
setInport	Configure root-level inports for code and calibration file (a2l) generation
setModelParameter	Configure model parameter for code and calibration file (a2l) generation
setOutport	Configure root-level outport for code and calibration file (a2l) generation
setSignal	Configure block signal data for code and calibration file (a2l) generation
setState	Configure block states for code and calibration file (a2l) generation

Examples

Programmatically Create and Use Code Mappings of Simulink$${}^{\circledR }$$ Models

Use the programmatic interface to create and use code mappings objects of Simulink models.

Load the model NoCoderMapping.

simulinkModel = "NoCoderMapping";
load_system(simulinkModel);

Use a try-catch block to determine whether a code mappings object exists for the model. Inside the try block, attempt to retrieve the existing object by using function coder.mapping.api.get. Inside the catch block, create a new code mappings object by using the function coder.mapping.utils.create. Store the code mappings object in the variable codeMapObj.

Add print messages to show whether the model had an existing code mappings object or not.

try
  codeMapObj = coder.mapping.api.get(simulinkModel);
          fprintf("" + ...
            " ========================================================\n" + ...
            " The model already had code mappings.\n" + ...
            " ========================================================\n");
catch
          fprintf("" + ...
            " ==========================================\n" + ...
            " The model does not have code mappings.\n" + ...
            " Creating new code mappings for the model.\n" + ...
            " ==========================================\n");
  codeMapObj = coder.mapping.utils.create(simulinkModel);
end

 ==========================================
 The model does not have code mappings.
 Creating new code mappings for the model.
 ==========================================

Retrieve the storage class of input port inport_1 of the model.

getInport(codeMapObj,"inport_1","StorageClass")

ans = 
'Auto'

Set the storage class of input port inport_1 to ExportedGlobal.

setInport(codeMapObj,"inport_1",StorageClass="ExportedGlobal")

Use the same try-catch block to see how the function coder.mapping.api.get is now able to retrieve the existing code mappings of the model.

try
  codeMapObj = coder.mapping.api.get(simulinkModel);
          fprintf("" + ...
            " ========================================================\n" + ...
            " The model already had code mappings.\n" + ...
            " ========================================================\n");
catch
          fprintf("" + ...
            " ==========================================\n" + ...
            " The model does not have code mappings.\n" + ... 
            " Creating new code mappings for the model.\n" + ...
            " ==========================================\n");
  codeMapObj = coder.mapping.utils.create(simulinkModel);
end

 ========================================================
 The model already had code mappings.
 ========================================================

Retrieve the storage class of input port inport_1 of the model. Notice that it is the storage class that you set previously.

getInport(codeMapObj,"inport_1","StorageClass")

ans = 
'ExportedGlobal'

Close the model without saving it.

close_system(simulinkModel,false)

Programmatically Get and Use Multiple Code Mapping Types with Simulink$${}^{\circledR }$$ Models

Use the programmatic interface to retrieve and use different types of code mappings objects of a Simulink model.

Load the model CoderMapAPI.

codeMapModel = "CoderMapAPI";
load_system(codeMapModel);

Use the function coder.mapping.api.get to retrieve and store the Simulink$${}^{\circledR }$$ Coder™ and the Embedded Coder$${}^{\circledR }$$ mapping objects of this model.

simCodeMapObj = coder.mapping.api.get(codeMapModel,"SimulinkCoderC");
eCodeMapObj = coder.mapping.api.get(codeMapModel,"EmbeddedCoderC");

Store all root-level input port names.

in_port_names = "in_port_"+(1:4)'

in_port_names = 4x1 string
    "in_port_1"
    "in_port_2"
    "in_port_3"
    "in_port_4"

For each of the code mapping objects, define an inline function that sets the storage class of the input ports. Use the arrayfun function to set the storage class of all root-level input ports of the Simulink code mappings object to ImportedExtern and set the storage class of the root-level input ports of the Embedded Coder mappings object to ImportedExternPointer.

configSimCoderPortStoreClassFcn = @(port_name) setInport(simCodeMapObj,port_name,StorageClass="ImportedExtern");
configECoderPortStoreClassFcn = @(port_name) setInport(eCodeMapObj,port_name,StorageClass="ImportedExternPointer");
arrayfun(configSimCoderPortStoreClassFcn,in_port_names);
arrayfun(configECoderPortStoreClassFcn,in_port_names);

For each of the code mapping objects, define an inline function that displays the storage class of the input ports.

dispSimCoderPortStoreClassFcn = @(port_name) disp(getInport(simCodeMapObj,port_name,"StorageClass"));
dispECoderPortStoreClassFcn = @(port_name) disp(getInport(eCodeMapObj,port_name,"StorageClass"));

Display the storage class of the root-level input ports for each of the code mappings objects.

arrayfun(dispSimCoderPortStoreClassFcn,in_port_names);

ImportedExtern
ImportedExtern
ImportedExtern
ImportedExtern

arrayfun(dispECoderPortStoreClassFcn,in_port_names);

ImportedExternPointer
ImportedExternPointer
ImportedExternPointer
ImportedExternPointer

Root-level input ports with ImportedExtern and ImportedExternPointer storage classes are declared in the generated private header file of the model, in separate sections. Store the header file names of the two system target files so that you can observe these sections in both of header files.

priv_h_simcoder_file = fullfile(codeMapModel+"_grt_rtw",codeMapModel+"_private.h")

priv_h_simcoder_file = 
"CoderMapAPI_grt_rtw/CoderMapAPI_private.h"

priv_h_ecoder_file = fullfile(codeMapModel+"_ert_rtw",codeMapModel+"_private.h")

priv_h_ecoder_file = 
"CoderMapAPI_ert_rtw/CoderMapAPI_private.h"

Set the model target file to grt.tlc and generate code from the model.

set_param(codeMapModel,SystemTargetFile="grt.tlc")
evalc("slbuild(codeMapModel)");

These are the declarations of the root-level input ports in the grt.tlc header file, priv_h_simcoder_file:

/* Imported (extern) block signals */
extern real_T in_port_1;               /* '<Root>/in_port_1' */
extern real_T in_port_2;               /* '<Root>/in_port_2' */
extern real_T in_port_3;               /* '<Root>/in_port_3' */
extern real_T in_port_4;               /* '<Root>/in_port_4' */

The root-level input ports are declared in the ImportedExtern section.

To open the header file, enter this command in the MATLAB$${}^{\circledR }$$ Command Window:

edit(priv_h_simcoder_file)

Now set the model target file to ert.tlc and generate code from the model.

set_param(codeMapModel,SystemTargetFile="ert.tlc")
evalc("slbuild(codeMapModel)");

These are the declarations of the root-level input ports in the ert.tlc header file, priv_h_ecoder_file:

/* Imported (extern) pointer block signals */
extern real_T *in_port_1;              /* '<Root>/in_port_1' */
extern real_T *in_port_2;              /* '<Root>/in_port_2' */
extern real_T *in_port_3;              /* '<Root>/in_port_3' */
extern real_T *in_port_4;              /* '<Root>/in_port_4' */

The root-level input ports in this header file are declared in the ImportedExternPointer section.

To open the header file, enter this command in the MATLAB Command Window:

edit(priv_h_ecoder_file)

Version History

Introduced in R2020b

R2023a: Automatic Code Suggestions and Completions

Starting in R2023a, tab completion is available for function names and arguments and for object properties. After you enter the first few characters of a function, input argument, or object property, press the Tab key to let MATLAB^® automatically complete the typing. MATLAB adds the remaining characters of the function, argument, or parameter. If you did not enter anything or if there are multiple options that begin with the characters you entered, MATLAB opens a list of available alternatives you can choose from. To learn more about tab completion, see Code Suggestions and Completions.