Configure Root-Level Outport 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 Outport blocks (outports) constitute the output data of the interface. To integrate and deploy the generated code into larger applications, you can customize how the code generator produces the interface code, including how output data is declared and handled. Customizations can:
- Minimize the modifications that you 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).
For code generation, examples show how to customize the outport interface for the modelConfigurationInterface
. You can configure code mappings by using the Code Mappings Editor – C or code mappings API (coder.mapping.api.CodeMapping).
Choose Customization Options for Outport Interface
By default, root-level outports in a model appear in generated code as fields of a global data structure named _`model`__ExtY
. Based on your code interface requirements, decide whether to customize generation of outport data. If you do not configure customizations, the code generator determines whether to eliminate or change the representation of outports 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 outports, it is more efficient to configure the outports with a default setting, and override that setting for special cases. If the model includes a few outports that have unique source, naming, or placement requirements, consider configuring the outports individually. - How to declare and handle outport data in the generated interface
- As separate global variables
- To write output data to global variables defined in external code
- For referenced model outports, 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 outports in the generated code by using Outport 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. - Write data from a specific area of memory. Requires Embedded Coder. See Control Data and Function Placement in Memory by Inserting Pragmas.
For a list of lists interface requirements that are relevant to outports with corresponding storage classes and storage class properties, see Choose Storage Class for Controlling Data Representation in Generated Code.
Outport interface requirements for example model ConfigurationInterface
are:
- Use project type definition
MYTYPE
defined inConfigurationInterface_data.m
. - Declare a variable for outport
Out1
in generated external header fileexOutSys.h
and define the variable in source definition fileexOutSys.c
. The data written toOut1
is the output of code generated for the Switch block. - The variable representing the outport in the generated code must be named
output1
. That name is the variable name that the external code interface uses to access the output data.
For this example, configure the outport in ConfigurationInterface
to meet these code generation requirements.
Configure Default Code Generation Settings for Root-Level Outports
A default code generation setting for root-level outports can reduce the effort of preparing a model for code generation, especially if a model has a significant number of outports. Choose configuration settings once, and the code generator applies those settings to outports across the model. Simulink® stores the default configuration as part of the model.
Consider configuring default code generation settings for model outports if your model uses multiple root-level outports that do not have unique requirements or uses a shared Embedded Coder Dictionary.
The example model ConfigurationInterface
includes one root-level outport. This example shows how to use the Code Mappings Editor – C to configure default settings for root-level outports. Specify that the code generator declare and define variables to represent root outports in generated external header and definition files. Name the generated default external header fileexOutSys.h
and the generated definition fileexOutSys.c
.
- Open example model
ConfigurationInterface
. Save a copy of the model to a writable location. - Open the Embedded Coder app.
- In the C Code tab, select > .
- In the Code Mappings editor, under Inports and Outports, select category Outports. Set the default storage class to
ExportToFile
. - Click the
icon and set Header File to
exOutSys.h
and Definition File toexOutSys.c
. - Save the model.
Configure Code Generation Settings for Individual Root-Level Outports
You can configure individual root-level outports for code generation. For example, if a model has two root-level outports that have unique code generation requirements, configure the outports individually. Or, if you configure default settings for outports, configure individual outports to use the default settings or unique settings.
If your model meets at least one of these criteria, consider configuring code generation settings for outports individually:
- Uses multiple outports that have unique requirements.
- Uses few outports.
- Has a default configuration for outports and you need to override the configuration for some specific outports.
This example shows how to use the Code Mappings editor to apply the default code generation configuration for outports in model ConfigurationInterface
. In the preceding example, you set the default storage class for outports to ExportToFile
. A requirement specifies that outport Out1
write output data to a global variable declared and defined in generated header and definition files accessible to external code.
The example also shows how to configure an identifier that the code generator uses for naming the outport in the generated code. You can specify code generation identifiers, for example for integration, without modifying the model design.
- If you have not already done so, complete the steps in Configure Default Code Generation Settings for Root-Level Outports.
- In the Code Mappings editor, click the Outports tab. The editor lists the names of Outport 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 the outport in the example model 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 classExportToFile
.- 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 outport.
- To avoid optimizations and force the code generator to use the default configuration, set the storage class to
- Configure the code generator to apply the default storage class setting to outport
Out1
. Select the row for the outport. Set the storage class toModel default: ExportToFile
.
The storage class for the selected outport changes toModel default: ExportToFile
. - Configure the code identifier for the outport so that the interface argument name in the generated code matches the interface name used by the external code. In the Code Mappings editor, select the row for the outport. Click the
icon and set theIdentifier property to
output
. - Save the model.
- Generate and view the code. For example, in the file
ConfigurationInterface.c
, find where variableoutput
is used in the step entry-point function.
if (mode) {
output = (real_T)mp_K1 * dout_Table1;
} else {
output = dstate_X;
}
Configure Code Generation Settings for Root-Level Outports Programmatically
To automate configuration of root-level outports 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 outports for model ConfigurationInterface
.
Configure code an identifier for the outport so that global variable name in the generated code matches the variable name in the external code interface.
- Open the example model.
openExample("ConfigurationInterface") - Create object
cm
by calling functioncoder.mapping.api.get
. The object stores the code generation configuration for data elements and functions in modelConfigurationInterface
.
cm = coder.mapping.api.get("ConfigurationInterface"); - Configure default settings for outports by calling function
setDataDefault
. For the arguments, specify these values.- The object returned by
coder.mapping.api.get
Outports
for the default category- Property name
StorageClass
that has property valueExportToFile
- Property name
HeaderFile
that has property valueexOutSys.h
and property nameDefinitionFile
that has property valueexOutSys.c
, the names for the generated files that declare and define the output data
setDataDefault(cm,"Outports","StorageClass","ExportToFile","HeaderFile","exOutSys.h",...
"DefinitionFile","exOutSys.c")
- The object returned by
- Verify your default configuration for outports. Issue three calls to
getDataDefault
that specify the object returned bycoder.mapping.api.get
and categoryOutports
.- In the first call, specify the third argument as property
StorageClass
. - In the second call, for the third argument, specify
HeaderFile
. - In the third call, for the third argument, specify
DefinitionFile
.
getDataDefault(cm,"Outports","StorageClass")
getDataDefault(cm,"Outports","HeaderFile")
getDataDefault(cm,"Outports","DefinitionFile")
- In the first call, specify the third argument as property
- Apply the default outport configuration for outport
Out1
.
By default, Simulink sets the storage class for individual outports toAuto
. When the storage class isAuto
, 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 configuration for an outport, call functionsetOutport
.
Issue a call tosetOutport
that specifies: - Object returned by
coder.mapping.api.get
- Outport block name
Out1
- Default storage class previously set for the outport by using property
StorageClass
and property valueModel default
- Property
Identifier
and property valueoutput
setOutport(cm,"Out1","StorageClass","Model default","Identifier","output");
- Verify your configuration changes by calling function
getOutport
. Specify the object returned bycoder.mapping.api.get
, name of the outport block, and propertyStorageClass
orIdentifier
.
getOutport(cm,"Out1","StorageClass")
ans =
'Model default'
getOutport(cm,"Out1","Identifier")
ans =
'output' - Save the model.
- Generate and view the code. For example, in the file
ConfigurationInterface.c
, find where variableoutput
is used in the step entry-point function.
if (mode) {
output = (real_T)mp_K1 * dout_Table1;
} else {
output = dstate_X;
}
Choose Storage Class and Storage Class Properties for Root-Level Outports
Depending on your code generation requirements, choose from these storage classes to configure code generation for root-level outports. The list of storage classes is defined in the coder dictionary.
Requirements | Storage Class for Default Mappings | Storage Class for Individual Mappings |
---|---|---|
For data elements that cannot be optimized, represent data as a field of a standard data structure. | Default | |
Enable optimizations, potentially generating more efficient code. | Auto | |
Prevent optimizations from eliminating storage for a data element and use the default mapping for the data element category. | Model Default | |
When using a shared coder dictionary, select the dictionary default for data elements that you do not want the code generator to optimize. | Dictionary Default | |
Generate standalone global variables. Generated code contains the variable declaration and definition. | ExportedGlobal | ExportedGlobal |
Generate standalone global variables or global variable pointers. Generated code contains the variable or pointer declaration. Your external code provides the definition. | ImportedExtern, ImportedExternPointer | ImportedExtern, ImportedExternPointer |
Generate standalone global variables with thevolatile qualifier. | Volatile (See Const, Volatile, and ConstVolatile) | Volatile (See Const, Volatile, and ConstVolatile) |
Generate standalone global variables. You can specify the external files that contain the variable declaration and definition. | ExportToFile | ExportToFile |
Generate standalone global variables. You can specify the external file that contains the variable declaration. Your external code provides the definition. | ImportFromFile | ImportFromFile |
Generate standalone variables whose scope is defined by their usage. Attempt to minimize the use of global scope by using variables localized to a function or file where possible. | Localizable | Localizable |
Generate variables as fields of a structure. | Struct | |
Generate variables as fields of a structure that stores Boolean, fixed-point, or integer data in named bitfields. | Bitfield | |
Generate variables that you access through a function call. | GetSet | GetSet |
Generate standalone global variables that enable buffer reuse. | Reusable | |
Generate variables for single-instance data and generate structures for multi-instance data. | MultiInstance | MultiInstance |
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 outport, use the Identifier storage class property to configure a name for the variable representing the outport in the generated code. If you leave the Identifier property blank, the code generator uses the Signal name parameter of theOutport block. If this parameter is empty, the code generator uses the name of the Outport block.
With Embedded Coder, depending on the storage class that you choose, you can also configure these properties.
Property | Description | Storage Classes |
---|---|---|
DefinitionFile | Source definition file that contains definitions for global data, which is read by the outport and external code | ExportToFile andVolatile |
GetFunction | Data element that appears in the generated code as a call to a specified get function | GetSet |
HeaderFile | Source header file that contains declarations for global data, which is read by the outport and external code | ExportToFile, GetSet,ImportFromFile, andVolatile |
Memory Section (default outport configuration only) | Memory section that contains data read by the outport | Default |
Owner | A component in the model hierarchy where the code generator places a global data definition instead of placing it in the top component of the hierarchy. To use this property, you must set the model configuration parameter Use owner from data object for data definition placement.. See Control Placement of Global Data Definitions and Declarations in Generated Files. | ExportToFile andVolatile |
PreserveDimensions | Flag that indicates whether to declare multidimensional data as multidimensional arrays in the generated code. To use this flag, you must set the model configuration parameter Array layout to Row-major. See Preserve Dimensions of Multidimensional Arrays in Generated Code. | ExportToFile, GetSet,ImportFromFile, Localizable and Volatile |
SetFunction | Data element that appears in the generated code as a call to a specified set function | GetSet |
StructName | Name for a structure in the generated code for outport | BitField and Struct |
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