Variable-Size Signals in Generated Code

Simulink^® models can use signals with fixed or variable-dimension sizes to transmit data between model components. If the size of a dimension is known at compile time and does not change at run time, then the dimension is fixed-size. When the dimensions of a signal are fixed-size, the signal is called a fixed-size signal.

If the size of a dimension is unknown at compile time or the size can change at run time, then the dimension is variable-size. If at least one of the signal dimensions is variable-size, that signal is called a variable-size signal.

A variable-size dimension is either bounded or unbounded. A bounded dimension has a fixed finite upper size where an unbounded dimension does not have one. Unbounded dimensions are specified by setting the dimension sizes to Inf or inf. Signals with bounded variable-size dimensions are bounded variable-size signals and signals with at least one unbounded variable-size dimension are called unbounded variable-size signals. For more information, see Unbounded Variable-Size Signals.

The following configured Inport block outputs a variable-size signal of two dimensions. The variable-size signal is bounded because the dimensions have finite upper bounds of 6 and 5.

Inport block configured for passing variable-size signals with finite upper bound

The following configured Inport block outputs an unbounded variable-size signal of two dimensions because Inf is set as the upper bound for the second dimension.

Inport block configured for passing an unbounded variable-size signals

Bounded variable-size signals are supported for C and C++ code generation. However, unbounded variable-size signals are supported only for C++ code generation. If you try to generate C code from models that contain unbounded variable-size signals, the code generator issues an error.

Memory Allocation for Bounded Variable-Size Signals

For fixed-size signals and bounded variable-size signals, the code generator allocates memory statically on the stack during compile time. Using these types of signals is beneficial if you want to deploy the generated code to embedded targets with fixed memory.

Limitations of Code Generation for Bounded Variable-Size Signals

Bounded variable-size signals are not supported for row-major code generation.
Bounded variable-size signals with custom storage classes, function prototype control, and the AUTOSAR model interface are not supported.
Bounded variable-size signals are not supported when the Code interface packaging parameter is set to C++ class or Reusable function.

Memory Allocation For Unbounded Variable-Size Signals

For unbounded variable-size signals, the code generator can allocate memory dynamically on the heap at run-time. This is beneficial when:

You do not have a mechanism to know the upper bounds of a signal.
The estimated upper bounds might be a deficit or surplus to the actual upper bounds. Overestimating an upper bound results in a portion of the allocated memory going unused and underestimating can cause a stack overflow.
If you want to interface the generate code with external libraries or APIs that operate on arrays that change size dynamically.

Dynamic memory allocation is also beneficial for larger variable-size signals when you have limited stack space. If your model uses larger variable-size signals, you can leverage the benefits of dynamic memory allocation by specifying the signals as unbounded. However, allocating memory dynamically and freeing that memory at run time can increase the code execution time.

Configuring Models to Use Dynamic Memory Allocation For Unbounded Signals

To use unbounded variable-size signals in your model, you must use the blocks that support unbounded variable-size signals. To see the list of the supported blocks, see Supported Blocks and Features for Simulation. For more information on how you can configure a supported block to create unbounded variable-size signals, see Unbounded Variable-Size Signal Basic Operations.

To use dynamic memory allocation for a model containing unbounded variable-size signals, in the Model Configuration Parameters dialog box, you must set these parameters:

On the Solver pane, use the default auto option for Solver or select the discrete (no continuous states) option.
On the Data Import/Export pane, set Format to Dataset.
On the Code Generation pane, set Language to C++.
On the Interface pane, select Support: variable-size signals.
Select the Dynamic memory allocation in MATLAB functions parameter.

If your model contains MATLAB Function blocks that accept or output unbounded variable-size signals from or to other blocks, on the Simulation Target pane, select Dynamic memory allocation in MATLAB functions.

In the generated C++ code, the code generator represents dynamically allocated data as an instance of a container class. For grt-based targets, the code generator uses the coder::array class and generates a coder_array.h file. The file contains the definition of the class template coder::array and the implementation of the set_size() method, which uses the new and delete operators to allocate and free memory dynamically.

For ert-based targets, the code generator uses the std::vector container class by default. You can use the Dynamic array container type (Embedded Coder) model configuration parameter to generate coder::array containers instead.

For more information about dynamic array allocation in generated C++ code, see Use Dynamic Memory Allocation for Unbounded Variable-Size Signals in C++ Code Generation (Embedded Coder).

Limitations of Code Generation for Unbounded Variable-Size Signals

Unbounded variable-size signals are not supported for row-major code generation.
Unbounded variable-size signals with custom storage classes, function prototype control, and the AUTOSAR model interface are not supported.
Unbounded variable-size signals are not supported for C code generation.
Unbounded variable-size signals are not supported if you enable the Use dynamic memory allocation for model initialization (Embedded Coder) optimization.
Unbounded variable-size signals with these built-in storage classes are only supported:
- Auto
- ExportedGlobal
- ImportedExtern
- ImportedExternPointer
These user-defined functions with unbounded variable-size signals are not supported:
- C-Mex S-Functions
- Legacy Code Tool-generated S-Functions

Memory Allocation for Variable-Size Arrays Inside MATLAB Function Blocks

For variable-size arrays inside MATLAB Function blocks, the code generator can use dynamic memory allocation for C/C++ code generation. For a MATLAB Function block, you cannot use dynamic memory allocation for:

Parameters, which must be fixed size.
Discrete state properties of System objects associated with a MATLAB System block.
Input and output signals, if you configure the model to generate C code. Variable-size input and output signals must have finite upper bounds.

To enable dynamic memory allocation for variable-size arrays in MATLAB Function blocks:

Select Dynamic memory allocation in MATLAB functions.
Set an appropriate threshold in Dynamic memory allocation threshold in MATLAB functions.

For unbounded variable-size arrays, the code generator uses dynamic memory allocation. For a bounded variable-size array, the code generator uses dynamic memory allocation if the array size, in bytes, is greater than or equal to the specified threshold. By controlling the threshold, you can control the use of dynamic memory allocation for variable-size arrays. For more information, see Control Memory Allocation for Variable-Size Arrays in a MATLAB Function Block.

If you generate C code, the code generator represents dynamically allocated data as a structure type called emxArray and generates utility functions to interact with the emxArray structures. If you generate C++ code, the code generator represents dynamically allocated data as class template called coder::array. The code generator also generates a coder_array.h header file that contains the definition of the class template coder::array and methods to interact with the defined class templates. For more information, see Use Dynamic Memory Allocation for Variable-Size Arrays in a MATLAB Function Block.