Configure Root-Level Inport Blocks for C Code Generation - MATLAB & Simulink (original) (raw)

To use code that you generate from a model, you call generated entry-point functions. The calling environment and generated functions exchange input and output data, for example, as global variables or function arguments. Root-level Inport blocks (inports) constitute the input data of the interface. To integrate and deploy the generated code into applications, you can customize how the code generator produces the interface code, including how input data is declared and handled. Customizations can:

• Minimize the modifications that you must make to existing code.
• Generate stable interfaces that do not change or minimally change when you make changes to your model.
• Generate code that exchanges data more efficiently (for example, by using pointers and pass-by-reference arguments for nonscalar data).

Enable and Trigger blocks (function-call inports) also load data into a system from outside the system. From a code generation perspective, these modeling elements are exported functions. For an exported function, the code generator produces an entry-point function, which you can configure. SeeConfigure Generated C Function Interface for Model Entry-Point Functions.

For code generation, examples show how to customize the inport interface for model ConfigurationInterface. You can configure code mappings by using the Code Mappings Editor – C or code mappings API (coder.mapping.api.CodeMapping).

Choose Customization Options for Inport Interface

By default, root-level inports in a model appear in generated code as fields of a global data structure named _`model`__ExtU. Based on your code interface requirements, decide whether to customize generation of root-level inport data. If you do not configure customizations, the code generator determines whether to eliminate or change the representation of inports 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 (for example, more than 10) of root-level inports, it is more efficient to configure the inports with a default setting, and then override that setting for special cases. If the model includes a few root-level inports that have unique source, naming, or placement requirements, consider configuring the inports individually.
• How to declare and handle root-level inport data in the generated interface
  • As separate global variables
  • To read input data from global variables defined in external code
  • For referenced model inports, as global variables (void-void)
  • As calls to access functions. Requires Embedded Coder®
  • As entry-point function arguments. Requires Embedded Coder
    For more information about these options, see Control Data and Function Interface in Generated Code.

Other considerations include whether to:

• Name inports in the generated code by using Inport block labels that appear in the model or by using unique code identifiers.
• Include the volatile type qualifier in global variable definitions and declarations. Requires Embedded Coder. See Protect Global Data with const and volatile Type Qualifiers.
• Place data read 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 inports with corresponding storage classes and storage class properties, see Choose Storage Class for Controlling Data Representation in Generated Code.

For example model ConfigurationInterface, inport interface requirements are:

• Use project type definition DBL_FLOAT defined in header file exDblFloat.h.
• Get data for inport In1 from header fileexInDataMem.h. The data is used for computing a value that is stored in memory, and then used in an if-else condition of code generated for the Switch block.
• Get data elements for inports In2, In3, and In4 from header file exInDataLut.h. The data is used in lookup tables Table1 andTable2.
• Variables representing the inports in the generated code must be named input1, input2,input3, and input4.

For this example, configure inports in ConfigurationInterface to meet these code generation requirements.

Configure Default Code Generation Settings for Root-Level Inports

A default code generation setting for root-level inports can reduce the effort of preparing a model for code generation, especially if a model has a significant number of inports. Choose configuration settings once, and the code generator applies those settings to the inports across the model. Simulink® stores the default configuration as part of the model.

Consider configuring default code generation settings for model root-level inports if your model uses multiple root-level inports that do not have unique requirements or uses a shared Embedded Coder Dictionary.

This example shows how to use the Code Mappings Editor – C to configure default settings for root-level inports for model ConfigurationInterface. Specify an external header file that declares input data. Three of the four root inports read input from variables declared in header file exInDataLut.h. Set that header file as the default input source for inports.

1. Open example model ConfigurationInterface. Save a copy of the model to a writable location.
   
2. Open the Embedded Coder app.
3. In the C Code tab, select > .
4. In the Code Mappings editor, under Inports and Outports, select category Inports. Set the default storage class toImportFromFile.
5. Click the icon, set Header File to exInDataLut.h.
   
6. Save the model.

Configure Code Generation Settings for Individual Root-Level Inports

You can configure individual root-level inports for code generation. For example, if a model has two root-level inports that have unique code generation requirements, configure the inports individually. Or, if you configure default settings for inports, configure individual inports to use the default settings or unique settings.

If your model meets at least one of these criteria, consider configuring code generation settings for root-level inports individually:

• Uses multiple inports that have unique requirements.
• Uses few inports.
• Has a default configuration for inports and you need to override the configuration for some specific inports.

This example shows how to use the Code Mappings editor to override the default code generation configuration for one of the inports in model ConfigurationInterface. In the preceding example, you set the default storage class for inports to ImportFromFile. The model requires that inport In1 read input data from a global variable instead of a global variable pointer.

The example also shows how to configure identifiers that the code generator uses for naming the four inports in the generated code. You can specify code generation identifiers, for example for integration, without having to modify the model design.

1. If you have not already done so, complete the steps in Configure Default Code Generation Settings for Root-Level Inports.
2. In the Code Mappings editor, click the Inports tab. The editor lists the names of Inport blocks and bus elements that are in the model. If a port resolves to a signal object, a resolve-to-signal-object icon appears to the right of the element name. 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 model default configuration. For this example, the model default configuration specifies storage class ImportedFromFile.
   • 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 inport.
3. Configure the code generator to apply the default storage class setting to inports In2, In3, andIn4. Select the rows for the three inports. Then, for one of the selected inports, set the storage class to Model default: ImportFromFile.
   
   The storage class for the three selected inports changes to Model default: ImportFromFile.
4. For inport In1, override the default storage class setting. Set the storage class to ImportFromFile. Click the icon and set Header File to exInDataMem.h.
   
5. Configure code identifiers for the inports so that the interface argument names in the generated code match the interface names in the external header and definition files. In the Code Mappings editor, select the row for each inport. Click the icon and set theIdentifier property to these values.

   Inport	Code Identifier
   In1	input1
   In2	input2
   In3	input3
   In4	input4

6. Save the model.
7. Generate and view the code. For example, in ConfigurationInterface.c find where variables input1, input2,input3, and input4 are used in the step entry-point function.
   void ConfigurationInterface_step(void)
   {
   mode = ((input1 > 10.0) || (input1 < -10.0));
   if (mode) {
   output = (real_T)K1 * look1_binlc(input2, (const MYTYPE *)&Table1.BP[0], (
   const MYTYPE *)&Table1.Table[0], 10U);
   } else {
   output = ConfigurationInterface_DW.X;
   }
   ConfigurationInterface_DW.X = look2_binlc(input3, input4, (const MYTYPE *)
   &Table2.BP1[0], (const MYTYPE *)&Table2.BP2[0], (const MYTYPE *)
   &Table2.Table[0], rtCP_Table2_maxIndex, 3U);
   }

Configure Code Generation Settings for Root-Level Inports Programmatically

To automate configuration of root-level inports 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 use the programming interface to configure default settings for root-level inports for model ConfigurationInterface. Specify an external header file that declares input data. Three of the four root-level inports read input from variables declared in header file exInDataLut.h. You set that file as the default header file. Then, you override the default code generation configuration forIn1, which requires that input data be read from header fileexInDataMem.h.

In addition, you configure code identifiers for the inports so that global variable names in the generated code match the variable names defined in an external file.

1. Open the example model.
   openExample("ConfigurationInterface")
2. Create object cm by calling functioncoder.mapping.api.get. The object stores the dataand function code generation configuration for model ConfigurationInterface.
   cm = coder.mapping.api.get("ConfigurationInterface");
3. Configure default settings for inports by calling functionsetDataDefault. For the arguments, specify these values:
   • The object returned bycoder.mapping.api.get
   • Inports for the default category
   • Property name StorageClass with property valueImportFromFile
   • Property name HeaderFile with property valueexInDataLut.h, the name of the external file that contains the input data
     setDataDefault(cm,"Inports","StorageClass","ImportFromFile","HeaderFile","exInDataLut.h")
4. Verify your default configuration for inports. Issue two calls to getDataDefault that specify the object returned by coder.mapping.api.get and categoryInports. In the first call, specify the third argument as property StorageClass. In the second call, for the third argument, specifyHeaderFile.
   getDataDefault(cm,"Inports","StorageClass")
   getDataDefault(cm,"Inports","HeaderFile")
5. Override the default inport configuration for inport In1. The requirements for that inport differ from requirements of the other three inports.
   By default, Simulink sets the storage class for individual inports 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.
     To control the storage class and header file configuration for an inport, configure settings for the inport with functionsetInport. Configure code generated for inportIn1 to read input data from global variables defined in external header file exInDataMem.h, as specified in the requirements. Issue two calls to function setInport that specify the object returned by coder.mapping.api.get andInport block named In1. In the first call, also specify property name StorageClass and property valueImportFromFile. In the second call, specify property nameHeaderFile and property valueexInDataMem.h.
     setInport(cm,"In1","StorageClass","ImportFromFile")
     setInport(cm,"In1","HeaderFile","exInDataMem.h")
6. Verify your configuration for inport In1 by calling function getInport.
   getInport(cm,"In1","StorageClass")
   getInport(cm,"In1","HeaderFile")
7. Configure the code generator to apply your default inport settings to inportsIn2, In3, and In4. For each inport, call function setInport. Specify the object returned by coder.mapping.api.get, theInport block name, property nameStorageClass, and property value Model default.
   setInport(cm,"In2","StorageClass","Model default")
   setInport(cm,"In3","StorageClass","Model default")
   setInport(cm,"In4","StorageClass","Model default")
8. Verify your configuration changes for inports In2,In3, and In4 with calls to functiongetInport.
   getInport(cm,"In2","StorageClass")
   getInport(cm,"In3","StorageClass")
   getInport(cm,"In4","StorageClass")
9. Configure code identifiers for the inports so that the global variables that represent inports in the generated code match the variable names in the external definition file. For each inport, call function setInport. Specify the object returned by coder.mapping.api.get, theInport block name, property nameIdentifier, and one of these property values.

   Inport	Code Identifier
   In1	input1
   In2	input2
   In3	input3
   In4	input4
   setInport(cm,"In1","Identifier","input1");
   setInport(cm,"In2","Identifier","input2");
   setInport(cm,"In3","Identifier","input3");
   setInport(cm,"In4","Identifier","input4");

10. Verify your configuration changes for the inports by using calls to functiongetInport.
    getInport(cm,"In1","Identifier")
    getInport(cm,"In2","Identifier")
    getInport(cm,"In3","Identifier")
    getInport(cm,"In4","Identifier")
11. Save the model.
12. Generate and view the code. For example, in ConfigurationInterface.c find where variables input1, input2,input3, and input4 are used in the step entry-point function.
    void ConfigurationInterface_step(void)
    {
    mode = ((input1 > 10.0) || (input1 < -10.0));
    if (mode) {
    output = (real_T)K1 * look1_binlc(input2, (const MYTYPE *)&Table1.BP[0], (
    const MYTYPE *)&Table1.Table[0], 10U);
    } else {
    output = ConfigurationInterface_DW.X;
    }
    ConfigurationInterface_DW.X = look2_binlc(input3, input4, (const MYTYPE *)
    &Table2.BP1[0], (const MYTYPE *)&Table2.BP2[0], (const MYTYPE *)
    &Table2.Table[0], rtCP_Table2_maxIndex, 3U);
    }

Choose Storage Class and Storage Class Properties for Root-Level Inports

Depending on your code generation requirements, choose from these storage classes to configure code generation for root-level inports. The list of storage classes is defined in the coder dictionary.

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 inport, use the Identifier storage class property to configure a name for the variable representing the inport in the generated code. If you leave the Identifier property blank, the code generator uses the name of the signal attached to the Inport block. If the signal label is empty, the code generator uses the name of the Inport block.

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

Topics

• C Data Code Interface Configuration for Model Interface Elements
• Choose Storage Class for Controlling Data Representation in Generated Code
• Use Built-In and Predefined Storage Classes to Represent Data in Generated Code
• Configure Default C Code Generation for Categories of Data Elements and Functions
• Control Data and Function Interface in Generated Code
• Configure Model Data Elements for ASAP2 File Generation