Configure Block States for C Code Generation

Block states, such as the state of a Unit Delay block, retain a state value between execution cycles of an algorithm. When configuring a model for code generation, you can configure state data to:

Minimize the amount of data that is stored in memory.
Control where the code generator places state data in memory.
Promote state data to the model interface so that other components and systems can access that data.
Improve readability and traceability of the generated code.

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

Choose Code Configuration Options for States

Based on your code generation requirements, decide how to represent state data. By default, states in a model appear in generated code as fields of a global data structure named model_DW. If you do not configure customizations, the code generator determines whether to eliminate or change the representation of states in generated code for optimization purposes. If you configure customizations, decide:

Whether to set up a default configuration
If you need to gain access to a significant number of states (for example, more than 10) , it is more efficient to configure the states with default settings and then override those settings for special cases. If you need to gain access to a few states that have unique source, naming, or placement requirements, consider configuring the states individually.
How to declare and handle state data in the generated code
- As separate global variables
- To read input data from global variables defined in external code
- As calls to access functions. Requires Embedded Coder^®
For more information about these options, see Control Data and Function Interface in Generated Code.

Other considerations include whether to:

Name states in the generated code by using state 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 state data 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 states with corresponding storage classes and storage class properties, see Choose Storage Class and Storage Class Properties for Data Stores.

State requirements for example model ConfigurationInterface are:

Retain the state data of the Unit Delay block for accessibility while the generated code executes.
Represent the state as a separate global variable.
Apply prefix dtemp_ to the name of the variable that represents the state.

For this example, you set the default representation of the state in the generated code as a global variable with the static type qualifier. Then, you configure the state of the Unit Delay block to use the default storage class and a unique code identifier that includes the required prefix dtemp_. The code identifier capability enables you to specify code generation identifiers without having to modify the model design.

Configure Default Code Generation Settings for States

A default code generation setting for states can reduce the effort of preparing a model for code generation, especially if a model has a significant number of states that you want to gain access to while the generated code executes. Choose configuration settings once, and the code generator applies those settings to states across the model. Simulink^® stores the default configuration as part of the model.

Consider configuring default code generation settings for model states if your model uses multiple states 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 states. Use the Code Mappings editor to set the default storage class for states in model ConfigurationInterface to FileScope. With that storage class setting, the code generator represents state data in the generated code as global variables that have the static type qualifier.

Open model ConfigurationInterface.
```
openExample("ConfigurationInterface")
```
Open the Embedded Coder app.
In the C Code tab, select Code Interface > Default Code Mappings.
In the Code Mappings editor, under Signals, select category Signals, states, and internal data. Set the default storage class to FileScope.
Save the model.

Configure Code Generation Settings for Individual States

You can configure individual states for code generation. For example, if a model has two states that have unique code generation requirements, configure the states individually. Or, if you configure default settings for states, you can override those settings for specific states.

If your model meets at least one of these criteria, consider configuring code generation settings for states individually:

Uses multiple states that have unique source, naming, or placement requirements.
Uses a few states.
Has a default configuration for states and you need to override the configuration for some specific states.

This example shows how to use the Code Mappings editor to apply your default storage class setting to the Unit Delay block state X in model ConfigurationInterface.

The example also shows how to configure a code identifier for that state. 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 States.
In the Code Mappings editor, click the Signals/States tab. Expand States. The storage class for the state 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 FileScope.
- 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 state.
In the Code Mappings editor, select state X. Set the storage class to Model default: FileScope.
Configure the code identifier for the state with a name that includes the prefix dstate_. In the Code Mappings editor, select state X. Click the icon and set the storage class property Identifier to dstate_X.
Save the model.
Generate and view the code. For example, in ConfigurationInterface.c, find the data definitions for the state data.
```
static MYTYPE dstate_X;
```
Find where the state data is used in the step entry-point function.
```
.
.
.
  if (mode) {
    output = (real_T)mp_K1 * dout_Table1;  
  } else {
    output = dstate_X;
  }
.
.
.
   dstate_X = dout_Table2;
}
```

Configure Code Generation Settings for States Programmatically

To automate configuration of states for code generation, use the programming interface for code mappings. For example, when creating custom block libraries or as part of creating an application test environment, use the programming interface to automate data configuration.

This example shows how to use the programming interface to configure states for model ConfigurationInterface. Set the default representation of states in the generated code as global variables that have the static type qualifier. Then, configure state X of the Unit Delay block to use the default storage class and unique code identifier that includes the required prefix dstate_.

Open the example model.
```
openExample("ConfigurationInterface")
```
Create object cm by calling function coder.mapping.api.get. The object stores the code generation configuration for data and functions for model ConfigurationInterface.
```
cm = coder.mapping.api.get("ConfigurationInterface");
```
Configure default settings for states by calling function setDataDefault. For the arguments, specify these values:
- The object returned by coder.mapping.api.get
- InternalData for the default category
- Property name StorageClass with property value FileScope
```
setDataDefault(cm,"InternalData","StorageClass","FileScope");
```
Verify your default configuration for states. Issue a call to getDataDefault that specifies the object returned by coder.mapping.api.get and category InternalData. Specify the third argument as property StorageClass.
```
getDataDefault(cm,"InternalData","StorageClass")
```
```
ans =

    'FileScope'
```
Apply the default configuration for states to state X.
By default, Simulink sets the storage class for individual states to 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 configuration for a state, call function setState.
Issue a call to setState that specifies:
- Object returned by coder.mapping.api.get
- State name X
- Default storage class previously set for states by using property StorageClass and property value Model default.
- Property Identifier and property value dstate_X
```
setState(cm,"X","StorageClass","Model default","Identifier","dstate_X");
```
Verify your configuration changes by calling function getState. Specify the object returned by coder.mapping.api.get, name of the state, and property StorageClass or Identifier.
```
getState(cm,"X","StorageClass")
```
```
ans =

    'Model default'
```
```
getState(cm,"X","Identifier")
```
```
ans =

    'dstate_X'
```
Save the model.
Generate and view the code. For example, in ConfigurationInterface.c, find the data definitions for state data.
```
static MYTYPE dstate_X;
```
Find where the state data is used in the step entry-point function.
```
.
.
.
  if (mode) {
    output = (real_T)mp_K1 * dout_Table1;  
  } else {
    output = dstate_X;
  }
.
.
.
   dstate_X = dout_Table2;
}
```

Choose Storage Class and Storage Class Properties for States

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

Tip

In the default mappings, states are configured in the section Signals, states, and internal data.

Requirements	Storage Class for Default Mappings	Storage Class for Individual Mappings
Let the code generator handle how to represent the state in the generated code. For example, for optimization purposes, the code generator might eliminate or change the representation of data.		Auto
For data elements that cannot be optimized, represent data as a field of a standard data structure.	Default
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 a structure that stores Boolean, fixed-point, or integer data in named bitfields.		Bitfield
Generate a global variable definition and declaration that has the `volatile` type qualifier.	`Volatile` (See Const, Volatile, and ConstVolatile)	`Volatile` (See Const, Volatile, and ConstVolatile)
Generate a global variable definition and declaration.	ExportedGlobal	ExportedGlobal
Generate a global variable definition and declaration to a specified file.	ExportToFile	ExportToFile
Generate a global variable definition and declaration that has the `static` type qualifier.	FileScope (Local and shared local data store mappings only)	FileScope (Local and shared local data store mappings only)
Generate code that interacts with data by calling your custom accessor functions.	GetSet	GetSet
Generate code that reads from and writes to a global variable or global variable pointer defined by your external code.	ImportedExtern, ImportedExternPointer	ImportedExtern, ImportedExternPointer
ExportToFile	ImportFromFile	ImportFromFile
Generate variables that are local to functions.	Localizable	Localizable
Generate a global structure that has a name, which you can specify.		Struct
Generate a global variable that enables 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 state, use the Identifier storage class property to configure a name for the variable representing the state in the generated code. If you leave the Identifier property blank, the code generator uses the State name parameter of the block that has the state. If this parameter is empty, the code generator uses the name of the 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 state and external code	`ExportToFile` and `Volatile`
`GetFunction`	State 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 state and external code	`ExportToFile`, `GetSet`, `ImportFromFile`, and `Volatile`
`Memory Section` (default state configuration only)	Memory section that contains data read by the state	`Default`
`Owner`	Code generator places the definition for states in the code generated for one of multiple models in a model hierarchy that share definitions. You must select 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` and `Volatile`
`PreserveDimensions`	Code generator preserves dimensions of state data that is represented in generated code as a multidimensional array. You must set model configuration parameter Array layout to `Row-major`. See Preserve Dimensions of Multidimensional Arrays in Generated Code.	`ExportToFile`, `FileScope`, `GetSet`, `ImportFromFile`, `Localizable` and `Volatile`
`SetFunction`	State appears in the generated code as a call to a specified `set` function.	`GetSet`
`StructName`	Name for a structure in the generated code for state.	`BitField` and `Struct`