Main Content

Configure Run-Time Environment Options

When you use Simulink® software to create and execute a model and use the code generator to produce C or C++ code, consider your configuration for up to three run-time environments:

  • The MATLAB® development computer run-time environment that runs MathWorks® software during application development.

  • The production hardware run-time environment in which you deploy an application when it is put into production.

  • The test hardware run-time environment in which you test an application under development before deployment.

One run-time environment can serve in multiple capacities, but the run-time environments remain conceptually distinct. Often, the MATLAB development computer is the test hardware. Typically, the production hardware is different from, and less powerful than, the MATLAB development or the test hardware. Many types of production hardware can do little more than run a downloaded executable file.

Provide information about the production hardware board and the compiler that you use with it when:

  • You use Simulink software to simulate a model for which you later generate code

  • You use the code generator to produce code for deployment on production hardware

The software uses the board and compiler information to get bit-true agreement for the results of integer and fixed-point operations performed in simulation and in code generated for the production hardware. The code generator uses the information to create code that executes with maximum efficiency.

When you generate code for testing on test hardware, provide information about the test hardware board and the compiler that you use. The code generator uses this information to create code that provides bit-true agreement between results from:

  • Integer and fixed-point operations performed in simulation

  • Generated code run on the production hardware

  • Generated code run on the test hardware

You can achieve bit-true agreement for results even if the production and test hardware are different. Where the C standard does not completely define behavior, the compilers for the two types of hardware can use different defaults.

Configure Production and Test Hardware

You can specify model simulation or code generation for a specific hardware board and its device type. For example, you can set the data size, byte ordering, and compiler behavior, such as integer rounding. You can configure:

Configure production hardware by selecting Configuration Parameters > Hardware Implementation. By default, the Hardware Implementation pane lists Hardware board, Device vendor, and Device type parameter fields only. Unless you have installed hardware support packages, Hardware board lists values None or Determine by Code Generation system target file, and Get Hardware Support Packages. After installing a hardware support package, the list also includes the corresponding hardware board name. If you select a hardware board name, parameters for that board appear. To set device details, such as data size and byte ordering, click Device details.

Configure test hardware on the Configuration Parameters > Hardware Implementation > Advanced parameters pane. To enable parameters for configuring test hardware details, disable the Configuration Parameters > Hardware Implementation > Advanced parameters > Test hardware is the same as production hardware parameter. Code generated for test hardware executes in the environment specified by the test hardware parameters. The code behaves as if it were executing in the environment specified for the production hardware. For more information, see Test Hardware Considerations.

Default values and properties appear as initial values in the Hardware Implementation pane when:

  • You specify a System target file in the Code Generation pane.

  • The system target file specifies a default microprocessor and its hardware properties.

You cannot change parameters that have only one possible value. Parameters that have more than one possible value provide a list of valid values. If you specify hardware properties manually in Hardware Implementation pane, verify that these values are consistent with the system target file. Otherwise, the generated code can fail to compile or execute, or can execute but produce incorrect results.

Hardware implementation parameters describe hardware and compiler properties to MATLAB software. The code generator uses the information to produce code for the run-time environment that runs as efficiently as possible. The generated code gives bit-true agreement for the results of integer and fixed-point operations in simulation, production code, and test code.

For details about specific parameters, see Hardware Implementation Pane. To see an example of Hardware Implementation pane capabilities, open the TargetSettings example model.

openExample("TargetSettings");

For details related to configuring a hardware implementation, see:

Specify Hardware Board

Specify the hardware board that runs the code generated from your model. Select a value for Configuration Parameters > Hardware Implementation > Hardware board.

The Hardware Implementation pane identifies the system target file selected on Configuration Parameters > Code Generation.

To configure test hardware, use the Configuration Parameters > Hardware Implementation > Advanced parameters pane.

To enable parameters for configuring test hardware details, set ProdEqTarget to off.

Ways to Specify the Hardware Board

IfSelect

The menu includes the name of the hardware board that you want to use.

The name of that hardware board.

If you select a hardware board name, parameters for that board appear.

The menu does not include the name of the hardware board that you want to use.

Get Hardware Support Packages.

That value opens the Support Package Installer. Install the support package that you want. After you install the support package, the menu includes relevant hardware board names.

The model configuration uses system target file ert.tlc, realtime.tlc, or autosar.tlc.

None.

No hardware board is specified for the hardware implementation.

The model configuration does not use system target file ert.tlc, realtime.tlc, or autosar.tlc.

Determine by Code Generation system target file.

The code generator uses the specified system target file to determine the hardware implementation.

Specify Device Vendor

To specify the vendor of the microprocessor of the hardware device, use the Device vendor parameter. Your selection determines the available microprocessors in the Device type menu. If the vendor name does not appear, select Custom Processor. Then, use the Device type parameter to specify the microprocessor.

Specify the Device Type

To specify the microprocessor name from the supported devices listed for your Device vendor selection, use the Device type parameter. If the microprocessor does not appear in the menu, change Device vendor to Custom Processor. Then, specify device details for your custom device.

If you select a device type for which the system target file specifies default hardware properties, the properties appear as initial values. You cannot change the value of parameters with only one possible selection. Parameters that have more than one possible value provide a menu. Select values for your hardware.

Set Bit Lengths for Device Data Types

The Number of bits parameters describe the native word size of the microprocessor and the bit lengths of char, short, int, and long data. For code generation to succeed:

  • The bit lengths must be such that char <= short <= int <= long.

  • Bit lengths must be multiples of 8, with a maximum of 32.

  • The bit length for long data must not be less than 32.

The rtwtypes.h file defines integer type names. The values that you provide must be consistent with the word sizes as defined in the compiler limits.h header file. The code generator maps its integer type names to the corresponding Simulink integer type names.

If no ANSI® C type with a matching word size is available, but a larger ANSI C type is available, the code generator uses the larger type for int8_T, uint8_T, int16_T, uint16_T, int32_T, and uint32_T. When the code generator uses a larger type, the resulting logged values (for example, MAT-file logging) can have different data types than logged values for simulation.

An application can use an integer data of length from 1 (unsigned) or 2 (signed) bits up 32 bits. If the integer length matches the length of an available type, the code generator uses that type. If a matching type is not available, the code generator uses the smallest available type that can hold the data, generating code that does not use unnecessary higher-order bits. For example, on hardware that supports 8-bit, 16-bit, and 32-bit integers, for a signal specified as 24 bits, the code generator implements the data as an int32_T or uint32_T.

Code that uses emulated integer data is not maximally efficient. This code can be useful during application development for emulating integer lengths that are available only on production hardware. Emulation does not affect the results of execution.

During code generation, the software checks the compatibility of model data types with the data types that you specify for production hardware.

  • If none of the lengths that you specify for production hardware integers is 32 bits, the software generates an error.

  • If the lengths of data types that the model uses are smaller than the available production hardware integer lengths, the software generates a warning.

Mapping of Integer Types from Code Generator to Simulink

Code Generator Integer TypeSimulink Integer Type
boolean_Tboolean
int8_Tint8
uint8_Tuint8
int16_Tint16
uint16_Tuint16
int32_Tint32
uint32_Tuint32

Set Byte Ordering for Device

The Byte ordering parameter specifies whether the hardware uses Big Endian (most significant byte first) or Little Endian (least significant byte first) byte ordering. If left as Unspecified, the code generator produces code that determines the endianness of the hardware. This setting is the least efficient.

Set Quotient Rounding Behavior for Signed Integer Division

ANSI C does not completely define the quotient rounding technique for compilers to use when dividing one signed integer by another. So, the behavior is implementation-dependent. If both integers are positive, or both are negative, the quotient must round down. If either integer is positive and the other is negative, the quotient can round up or down.

The Signed integer division rounds to parameter instructs the code generator about how the compiler rounds the result of signed integer division. Providing this information does not change the operation of the compiler. It only describes that behavior to the code generator, which uses the information to optimize code generated for signed integer division. The parameter values are:

  • Zero — If the quotient is between two integers, the compiler chooses the integer that is closer to zero as the result.

  • Floor — If the quotient is between two integers, the compiler chooses the integer that is closer to negative infinity.

  • Undefined — If Zero or Floor do not describe the compiler behavior or if that behavior is unknown, choose this value.

Avoid selecting Undefined. When the code generator does not know the signed integer division rounding behavior of the compiler, the model build generates extra code.

The compiler quotient rounding behavior varies according to these values.

You can obtain the compiler implementation for signed integer division rounding from the compiler documentation. If documentation is not available, you can determine this behavior by experiment.

Example Quotient Rounding for Zero, Floor, and Undefined

NDIdeal N/DZeroFloorUndefined

33

4

8.25

8

8

8

-33

4

-8.25

-8

-9

-8 or -9

33

-4

-8.25

-8

-9

-8 or -9

-33

-4

8.25

8

8

8 or 9

Set Arithmetic Right Shift Behavior for Signed Integers

ANSI C does not define the behavior of right shifts on negative integers for compilers. So, the behavior is implementation-dependent. The Shift right on a signed integer as arithmetic shift option instructs the code generator about how the compiler implements right shifts on negative integers. Providing this information does not change the operation of the compiler. It only describes that behavior to the code generator, which uses the information to optimize the code generated for arithmetic right shifts.

If the C compiler implements a signed integer right shift as an arithmetic right shift, select the option. Otherwise, clear the option. An arithmetic right shift fills bits vacated by the right shift with the value of the most significant bit, which indicates the sign of the number in two’s-complement notation. The option is selected by default. If your compiler handles right shifts as arithmetic shifts, this setting is preferred.

  • When you select the option, the code generator produces efficient code whenever the Simulink model performs arithmetic shifts on signed integers.

  • When the option is cleared, the code generator produces fully portable but less efficient code to implement right arithmetic shifts.

You can obtain the compiler implementation for arithmetic right shifts from the compiler documentation. If documentation is not available, you can determine this behavior by experiment.

Update Release 14 Hardware Configuration

If your model was created before Release 14 and you have not updated the model, the Configure current execution hardware device parameter (TargetUnknown) value is 'on' by default.

To update your model, clear the box for Configuration Parameters > Hardware Implementation > Advanced parameters > Test hardware > Configure test hardware.Or in the Command Window, type:

cs = getActiveConfigSet('your_model_name');
set_param(cs,'TargetUnknown','off');

This update to your model:

  • Enables the Test Hardware is the same as production hardware parameter (ProdEqTarget), setting the parameter to 'on'.

  • Copies the Production device vendor and type parameter (ProdHWDeviceType) value to the Test device vendor and type parameter (TargetHWDeviceType).

To complete the update:

  1. Clear the box for Configuration Parameters > Hardware Implementation > Advanced parameters > Test hardware > Test Hardware is the same as production hardware. Apply this step only if your production and test hardware are different.

  2. Set the parameters in Configuration Parameters > Hardware implementation > Advanced parameters to match your production and test systems.

  3. Save the model.

Production Hardware Considerations

When you configure production hardware, consider these points:

  • Production hardware can have word sizes and other hardware characteristics that differ from the MATLAB development computer. You can prototype code on hardware that is different from the production hardware or the MATLAB development computer. When producing code, the code generator accounts for these differences.

  • The Simulink product uses some of the information in the production hardware configuration. That information enables simulations without code generation to give the same results as executing generated code. For example, the results can detect error conditions that arise on the production hardware, such as hardware overflow.

  • The code generator produces code that provides bit-true agreement with Simulink results for integer and fixed-point operations. Generated code that emulates unavailable data lengths runs less efficiently than without emulation. The emulation does not affect bit-true agreement with Simulink for integer and fixed-point results.

  • If you change run-time environments during application development, before generating or regenerating code, reconfigure the hardware implementation parameters for the new run-time environment. When code executes on hardware for which it was not generated, bit-true agreement is not always achieved for results of integer and fixed-point operations in simulation, production code, and test code.

  • To compile code generated from the model, use the Integer rounding mode parameter on model blocks to simulate the rounding behavior of the C compiler that you intend. This setting appears on the Signal Attributes pane in the parameter dialog boxes of blocks that can perform signed integer arithmetic, such as the Product, Matrix Multiply and n-D Lookup Table blocks.

  • For most blocks, the value of Integer rounding mode completely defines rounding behavior. For blocks that support fixed-point data and the simplest rounding mode, the value of Signed integer division rounds to also affects rounding. For details, see Precision (Fixed-Point Designer).

  • When models contain Model blocks, configure models that they reference to use identical hardware settings.

Test Hardware Considerations

By default, the test hardware configuration is the same as the configuration for the production hardware. You can use the generated code for testing in an environment that is identical to the production environment.

If the test and production environments differ, you can generate code that runs on test hardware as if it were running on production hardware:

  1. To enable test hardware parameters, clear the box for Configuration Parameters > Hardware Implementation > Advanced parameters > Test hardware > Test hardware is the same as production hardware. Or, in the Command Window type:

    cs = getActiveConfigSet('your_model_name');
set_param(cs,'ProdEqTarget','off');

  2. Specify device type details through the test hardware (Target*) parameters.

If you select a system target file that specifies a default microprocessor and its hardware properties, these default values and properties appear as initial values.

Parameters with only one possible value cannot be changed. If you modify hardware properties, check that their values are consistent with the system target file. Otherwise, the generated code can fail to compile or execute, or can execute but produce incorrect results.

Example Production Hardware Setting That Affects Normal Mode Simulation

Changing some production hardware settings, for example, ProdLongLongMode and ProdIntDivRoundTo, can affect normal mode simulation results. The following example simulates an adder with four inputs. In the first simulation, ProdLongLongMode is disabled. In the second simulation, ProdLongLongMode is enabled. In the plot of simulation outputs, you observe small differences between output values in the time step range 125–175.

  1. Create the adder model.

    model = 'hwSettingEffect';
new_system(model) 
open_system(model)

pos = [140   140   200   340];
add_block('simulink/Math Operations/Add', ...
          [model '/sum_int32'], ...
          'Inputs','++++', ...
          'SaturateOnIntegerOverflow', ...
          'on', ...
          'Position', ...
          pos)

pos = [75   155   105   175];
add_block('built-in/Inport',[model '/In1'],'Position',pos)
set_param([model '/In1'], 'OutDataTypeStr', ...
          'int32','PortDimensions','1','SampleTime','1');
add_line(model, 'In1/1','sum_int32/1')

pos = [75   205   105   225];
add_block('built-in/Inport',[model '/In2'],'Position',pos)
set_param([model '/In2'], 'OutDataTypeStr', ...
           'int32','PortDimensions','1','SampleTime','1');
add_line(model, 'In2/1','sum_int32/2')

pos = [75   255   105   275];
add_block('built-in/Inport',[model '/In3'],'Position',pos)
set_param([model '/In3'], 'OutDataTypeStr', ...
          'int32','PortDimensions','1','SampleTime','1');
add_line(model, 'In3/1','sum_int32/3')

pos = [75   305   105   325];
add_block('built-in/Inport',[model '/In4'],'Position',pos)
set_param([model '/In4'], 'OutDataTypeStr', ...
           'int32','PortDimensions','1','SampleTime','1');
add_line(model, 'In4/1','sum_int32/4')

pos = [275   230   305   250];
add_block('built-in/Outport',[model '/Out1'],'Position',pos)
add_line(model, 'sum_int32/1','Out1/1')

  2. Specify the input data, simulation time, and simulation output format.

    t = 0:200;
peakValue = 1.5e9;
in1 = peakValue * sin(t*2*pi/100);
in2 = peakValue * cos(t*2*pi/70);
in3 = -peakValue * sin(t*2*pi/40);
in4 = -peakValue * cos(t*2*pi/30);
set = Simulink.SimulationData.Dataset;
set = set.addElement(1, timeseries(int32(in1),t,'Name','sig1'));
set = set.addElement(2, timeseries(int32(in2),t,'Name','sig2'));
set = set.addElement(3, timeseries(int32(in3),t,'Name','sig3'));
set = set.addElement(4, timeseries(int32(in4),t,'Name','sig4'));

set_param(model, 'LoadExternalInput', 'on');
set_param(model, 'ExternalInput', 'set');

set_param(model, 'StopTime', '50');

set_param(model, 'ReturnWorkspaceOutputs', 'off');

  3. Disable the production hardware setting and run the first simulation.

    set_param(model, 'ProdLongLongMode', 'off');
[~, ~, y1] = sim(model, 200);

  4. Enable the production hardware setting and run the second simulation.

    set_param(model, 'ProdLongLongMode', 'on');
[~, ~, y2] = sim(model, 200);

  5. Plot the simulation outputs.

    plot([y1 y2]);
figure(gcf);

The difference in behavior is due to the accumulator data type in the Sum block. The Accumulator data type block parameter is set to Inherit: Inherit via internal rule. For this example, the resulting accumulator data type is 64 bits wide if the use of the C long long data type is enabled. Otherwise, it is 32 bits wide. Depending on the input values for the sum block, the 32-bit accumulator can saturate when the 64-bit accumulator does not. Therefore, normal mode behavior can depend on the ProdLongLongMode setting. In both cases, the normal mode behavior and production hardware behavior matches bitwise.

Related Topics