coder.mapping.api.get

Get code mappings for model

Since R2020b

Syntax

coderMapObj = coder.mapping.api.get(simulinkModel)

coderMapObj = coder.mapping.api.get(simulinkModel,codeMappingType)

coderDataDictObj = coder.mapping.api.get(coderDictionary)

Description

coderMapObj = coder.mapping.api.get(simulinkModel) returns the active code mappings for the specified model as object coderMapObj. Code mappings associate model data elements and functions with configurations for C or C++ code generation. If a model has multiple code mappings, the active code mappings are the mappings associated with the active system target file.

If code mappings do not exist, an error is generated. Simulink^® creates a code mappings object when you open a coder app for the model. If you have not opened a coder app for the model, you can invoke the coder.mapping.utils.create function to create a code mappings object.

coderMapObj = coder.mapping.api.get(simulinkModel,codeMappingType) returns the code mappings for your model that correspond to the specified code mapping type as object coderMapObj.

coderDataDictObj = coder.mapping.api.get(coderDictionary) returns the object coderDataDictObj that you can use to get and set data and function defaults in the shared dictionary specified by coderDictionary.

Note

• To save changes you make in the dictionary with the object coderMapObj, create and use a general dictionary object Simulink.data.Dictionary for the same dictionary.

• This syntax of the function is only supported for data interface dictionaries.

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 Code Mappings Objects with Coder Dictionaries

Programmatically get and use a code mappings object with an Embedded Coder$${}^{\circledR }$$ Dictionary.

To interactively observe how your commands are reflected in the Code Mappings editor and the model dictionary, make sure the Code Mappings editor is open with the Data Defaults tab selected, and the model dictionary is open with the Data Defaults section selected. To learn how to open the Code Mappings editor, see Open the Code Mappings Editor – C. To learn how to open the model dictionary, see Open the Embedded Coder Dictionary.

Store the model and dictionary filenames, and then open the model ECoderMapAPI.

simulinkModel = "ECoderMapAPI";
dict_name = "ECoderDataDict.sldd";
load_system(simulinkModel);

To use code mappings in a shared dictionary, configure the model to use the shared dictionary.

set_param(simulinkModel,EmbeddedCoderDictionary="ECoderDataDict.sldd");

Get to get the code mappings object of the model and use it to:

• Specify Model default as the storage class of all root-level ports of the model.

• Specify Dictionary default as the default storage class of root-level ports.

modelCodeMapObj = coder.mapping.api.get(simulinkModel);
setInport(modelCodeMapObj,find(modelCodeMapObj,"Inports"),StorageClass="Model default")
setOutport(modelCodeMapObj,find(modelCodeMapObj,"Outports"),StorageClass="Model default")
setDataDefault(modelCodeMapObj,"Inports",StorageClass="Dictionary default")
setDataDefault(modelCodeMapObj,"Outports",StorageClass="Dictionary default")

A coder dictionary contains, among other things, definitions that can be used by the code mappings of the model. You can use the code mapping API to retrieve and control the data and function defaults in shared coder dictionaries.

Get the code mappings object of the dictionary, ECoderDataDict.sldd. You use this object to view and control the data and function defaults of the dictionary.

coderMapDictObj = coder.mapping.api.get(dict_name);

Get a general dictionary object for the same shared dictionary. You use this object to control general elements of the dictionary, that are not related to code mappings. In this example, you need this general dictionary object to save the dictionary after you make changes to it with the code mapping object of the dictionary.

dictObj = Simulink.data.dictionary.open(dict_name);

Use the code mappings object of the dictionary to set the default storage class of input ports to Localizable and the default storage class of output ports to Volatile.

setDataDefault(coderMapDictObj,"Inports",StorageClass="Localizable");
setDataDefault(coderMapDictObj,"Outports",StorageClass="Volatile");

Verify that the default storage classes are set as you intended.

getDataDefault(coderMapDictObj,"Inports","StorageClass")

ans = 
'Localizable'

getDataDefault(coderMapDictObj,"Outports","StorageClass")

ans = 
'Volatile'

Localizable and Volatile variables are declared in separate sections of the generated model header file. Store the header file name in the variable model_h_file.

model_h_file = fullfile(simulinkModel+"_ert_rtw",simulinkModel+".h")

model_h_file = 
"ECoderMapAPI_ert_rtw/ECoderMapAPI.h"

Generate code from the model.

evalc("slbuild(simulinkModel)");

These are the declarations of the root-level input and output ports in the header file:

/* Declaration for custom storage class: Localizable */
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' */

/* Declaration for custom storage class: Volatile */
extern volatile real_T out_port_1;     /* '<Root>/out_port_1' */
extern volatile real_T out_port_2;     /* '<Root>/out_port_2' */
extern volatile real_T out_port_3;     /* '<Root>/out_port_3' */
extern volatile real_T out_port_4;     /* '<Root>/out_port_4' */

Ports are of the storage classes set in the data defaults of the dictionary.

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

edit(model_h_file)

Use the setDataDefault function with the code mapping object of the dictionary to switch between the default storage classes of the input and output ports in the dictionary.

setDataDefault(coderMapDictObj,"Inports",StorageClass="Volatile");
setDataDefault(coderMapDictObj,"Outports",StorageClass="Localizable");

Verify that the default storage classes are set as you intended.

getDataDefault(coderMapDictObj,"Inports","StorageClass")

ans = 
'Volatile'

getDataDefault(coderMapDictObj,"Outports","StorageClass")

ans = 
'Localizable'

Generate code from the model again.

evalc("slbuild(simulinkModel)");

The declarations of the input and output ports have been updated in the header file with the storage classes you configured them to be.

/* Declaration for custom storage class: Localizable */
extern real_T out_port_1;              /* '<Root>/out_port_1' */
extern real_T out_port_2;              /* '<Root>/out_port_2' */
extern real_T out_port_3;              /* '<Root>/out_port_3' */
extern real_T out_port_4;              /* '<Root>/out_port_4' */

/* Declaration for custom storage class: Volatile */
extern volatile real_T in_port_1;      /* '<Root>/in_port_1' */
extern volatile real_T in_port_2;      /* '<Root>/in_port_2' */
extern volatile real_T in_port_3;      /* '<Root>/in_port_3' */
extern volatile real_T in_port_4;      /* '<Root>/in_port_4' */

Use the general dictionary object, dictObj, to save the changes you made to the dictionary and to close it.

saveChanges(dictObj);
close(dictObj);

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)

Input Arguments

simulinkModel — Simulink model

handle | character vector | string scalar

Simulink model for which to return the code mapping object, specified as a handle, or a character vector or string scalar with the model name (without the .slx file extension), or the relative or absolute path of the model file (including the .slx file extension).

Note

The model must be loaded (for example, by using load_system).

Example: "configModel"

Data Types: char | string | handle

coderDictionary — Coder data interface dictionary

character vector | string scalar | Simulink.data.Dictionary

Data interface dictionary for which to return the code mappings object, specified as a Simulink.data.Dictionary object, or a character vector or string scalar with the relative or full path of the dictionary file (including the .sldd file extension).

Example: "exCodeDefs.sldd"

Data Types: char | string | Simulink.data.Dictionary

codeMappingType — Type of code mapping

"SimulinkCoderC" | "EmbeddedCoderC" | "EmbeddedCoderCPP"

The type of code mappings to return for the specified model or dictionary, specified as one of the values in the table. Code mappings enable you to associate the model with code generation configuration suitable for your platform. If the specified mappings type does not exist, an error is generated.

Code Mappings Type	Code Generation Configuration	Details
"SimulinkCoderC"	C language rapid prototyping platform	Simulink Coder™ and C language
"EmbeddedCoderC"	C language production platform	Embedded Coder® and C language
"EmbeddedCoderCPP"	C ++ language production platform	Embedded Coder and C++ language

Output Arguments

coderMapObj — Code mappings

CodeMapping object | CodeMappingCPP object

The code mappings object for the model, returned as a CodeMapping object or a CodeMappingCPP.

Output	Input Object	Code Mapping Type
coder.mapping.api.CodeMapping	Simulink model	"SimulinkCoderC" or "EmbeddedCoderC"
coder.mapping.api.CodeMappingCPP	Simulink model	"EmbeddedCoderCPP"

coderDataDictObj — Embedded Coder data dictionary

CoderDictionary object

The Embedded Coder data dictionary, returned as a coder.mapping.api.CoderDictionary object.

Version History

Introduced in R2020b