Configuring the Hardware Implementation :: Configuring the Target Environment (Real-Time Workshop®)

Configuring the Hardware Implementation

When you use Simulink software to create and execute a model, and Real-Time Workshop software to generate code, you may need to consider up to three platforms, often called hardware targets:

MATLAB Host — The platform that runs MathWorks software during application development
Embedded Target — The platform on which an application will be deployed when it is put into production
Emulation Target — The platform on which an application under development is tested before deployment

The same platform might serve in two or possibly all three capacities, but they remain conceptually distinct. Often the MATLAB host and the emulation target are the same. The embedded target is usually different from, and less powerful than, the MATLAB host or the emulation target; often it can do little more than run a downloaded executable file.

When you use Simulink software to execute a model for which you will later generate code, or use Real-Time Workshop software to generate code for deployment on an embedded target, you must provide information about the embedded target hardware and the compiler that you will use with it. The Simulink software uses this information to guarantee bit-true agreement for the results of integer and fixed-point operations performed in simulation and in code generated for the embedded target. The Real-Time Workshop code generator uses the information to create code that executes with maximum efficiency.

When you generate code for testing on an emulation target, you must additionally provide information about the emulation target hardware and the compiler that you will use with it. The code generator uses this information to create code that provides bit-true agreement for the results of integer and fixed-point operations performed in simulation, in code generated for the embedded target, and in code generated for the emulation target. The agreement is guaranteed even though the embedded target and emulation target may use very different hardware, and the compilers for the two targets may use different defaults where the C standard does not completely define behavior.

Describing the Emulation and Embedded Targets

The Configuration Parameters dialog Hardware Implementation pane provides options that you can use to describe hardware properties, such as data size and byte ordering, and compiler behavior details that may vary with the compiler, such as integer rounding. The Hardware Implementation pane contains two subpanes:

Embedded Hardware — Describes the embedded target hardware and the compiler that you will use with it. This information affects both simulation and code generation.
Emulation Hardware — Describes the emulation target hardware and the compiler that you will use with it. This information affects only code generation.

The two subpanes provide identical options and value choices. By default, the Hardware Implementation subpane initially look like this:

The default assumption is that the embedded target and emulation target are the same, so the Emulation Hardware subpane by default does not need to specify anything and contains only a checked option labeled None. Code generated under this configuration will be suitable for production use, or for testing in an environment identical to the production environment.

If you clear the check box, the Emulation Hardware subpane appears, initially showing the same values as the Emulation Hardware subpane. If you change any of these values, then generate code, the code will be able to execute in the environment specified by the Emulation Hardware subpane, but will behave as if it were executing in the environment specified by the Embedded Hardware subpane. See Describing Emulation Hardware Characteristics for details.

If you have used the Real-Time Workshop pane General tab to specify a System target file, and the target file specifies a default microprocessor and its hardware properties, the default and properties appear as initial values in the Hardware Implementation pane.

Options with only one possible value cannot be changed. Any option that has more than one possible value provides a list of legal values. If you specify any hardware properties manually, check carefully that their values are consistent with the system target file. Otherwise, the generated code may fail to compile or execute, or may execute but give incorrect results.

Note Hardware Implementation pane options do not control hardware or compiler behavior in any way. Their purpose is solely to describe hardware and compiler properties to MATLAB software, which uses the information to generate code that is correct for the platform, runs as efficiently as possible, and gives bit-true agreement for the results of integer and fixed-point operations in simulation, production code, and test code.

The rest of this section describes the options in the Embedded Hardware and Emulation Hardware subpanes. Subsequent sections describe considerations that apply only to one or the other subpane. For more about Hardware Implementation options, see Hardware Implementation Pane. To see an example of Hardware Implementation pane capabilities, run the rtwdemo_targetsettings demo.

Describing the Device Vendor

The Device vendor option gives the name of the device vendor. To set the option, select a vendor name from the Device vendor menu. Your selection of vendor will determine the available device values in the Device type list. If the desired vendor name does not appear in the menu, select Generic and then use the Device type option to further specify the device.

Note

For complete lists of Device vendor and Device type values, see Device vendor and Device type in the Simulink reference documentation.
To add Device vendor and Device type values to the default set that is displayed on the Hardware Implementation pane, see Registering Additional Device Vendor and Device Type Values.

Describing the Device Type

The Device type option selects a hardware device among the supported devices listed for your Device vendor selection. To set the option, select a microprocessor name from the Device type menu. If the desired microprocessor does not appear in the menu, change the Device vendor to Generic.

If you specified the Device vendor as Generic, examine the listed device descriptions and select the device type that matches your hardware. If no available device type is appropriate, select Custom.

If you select a device type for which the target file specifies default hardware properties, the properties appear as initial values in the subpane. Options with only one possible value cannot be changed. Any option that has more than one possible value provides a list of legal values. Select values appropriate to your hardware. If the device type is Custom, all options can be set, and each option has a list of all possible values.

Registering Additional Device Vendor and Device Type Values

To add Device vendor and Device type values to the default set that is displayed on the Hardware Implementation pane, you can use a hardware device registration API provided by the Real-Time Workshop software.

To use this API, you create an sl_customization.m file, located in your MATLAB path, that invokes the registerTargetInfo function and fills in a hardware device registry entry with device information. The device information will be registered with Simulink software for each subsequent Simulink session. (To register your device information without restarting MATLAB, issue the MATLAB command sl_refresh_customizations.)

For example, the following sl_customization.m file adds device vendor MyDevVendor and device type MyDevType to the Simulink device lists.

function sl_customization(cm)
  cm.registerTargetInfo(@loc_register_device);
end

function thisDev = loc_register_device
  thisDev = RTW.HWDeviceRegistry;
  thisDev.Vendor = 'MyDevVendor';
  thisDev.Type = 'MyDevType';
  thisDev.Alias = {};
  thisDev.Platform = {'Prod', 'Target'};
  thisDev.setWordSizes([8 16 32 32 32]);
  thisDev.Endianess = 'Unspecified';
  thisDev.IntDivRoundTo = 'Undefined';
  thisDev.ShiftRightIntArith = true;
  thisDev.setEnabled({'IntDivRoundTo'});
end

If you subsequently select the device in the Hardware Implementation pane, it is displayed as follows:

To register multiple devices, you can specify an array of RTW.HWDeviceRegistry objects in your sl_customization.m file. For example,

function sl_customization(cm)
  cm.registerTargetInfo(@loc_register_device);
end

function thisDev = loc_register_device

  thisDev(1) = RTW.HWDeviceRegistry;
  thisDev(1).Vendor = 'MyDevVendor';
  thisDev(1).Type = 'MyDevType1';
  ...

  thisDev(4) = RTW.HWDeviceRegistry;
  thisDev(4).Vendor = 'MyDevVendor';
  thisDev(4).Type = 'MyDevType4';
  ...

end

The following table lists the RTW.HWDeviceRegistry properties that you can specify in the registerTargetInfo function call in your sl_customization.m file.

Property	Description
`Vendor`	String specifying the Device vendor value for your hardware device.
`Type`	String specifying the Device type value for your hardware device.
`Alias`	Cell array of strings specifying any aliases or legacy names that users might specify that should resolve to this device. Specify each alias or legacy name in the format `'Vendor->Type'`. (Real-Time Workshop Embedded Coder software provides the utility functions `RTW.isHWDeviceTypeEq` and `RTW.resolveHWDeviceType` for detecting and resolving alias values or legacy values when testing user-specified values for the target device type.)
`Platform`	Cell array of enumerated string values specifying whether this device should be listed in the Embedded hardware subpane (`{'Prod'}`), the Emulation hardware subpane (`{'Target'}`), or both (`{'Prod', 'Target'}`).
`setWordSizes`	Array of integer sizes to associate with the Number of bits parameters char, short, int, long, and native word size, respectively.
`Endianess`	String specifying an enumerated value for the Byte ordering parameter: `'Unspecified'`, `'Little'` for little Endian, or `'Big'` for big Endian.
`IntDivRoundTo`	String specifying an enumerated value for the Signed integer division rounds to parameter: `'Zero'`, `'Floor'`, or `'Undefined'`.
`ShiftRightIntArith`	Boolean value specifying whether your compiler implements a signed integer right shift as an arithmetic right shift (`true`) or not (`false`).
`setEnabled`	Cell array of strings specifying which device properties should be enabled (modifiable) in the Hardware Implementation pane when this device type is selected. In addition to the `'Endianess'`, `'IntDivRoundTo'`, and `'ShiftRightIntArith'` properties listed above, you can enable individual Number of bits parameters using the property names `'BitPerChar'`, `'BitPerShort'`, `'BitPerInt'`, `'BitPerLong'`, and `'NativeWordSize'`.

Describing the Number of Bits

The Number of bits options 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.
All bit lengths must be multiples of 8, with a maximum of 32.
The bit length for long data must not be less than 32.

Real-Time Workshop integer type names are defined in the file rtwtypes.h. The values that you provide must be consistent with the word sizes as defined in the compiler's limits.h header file. The following table lists the standard Real-Time Workshop integer type names and maps them to the corresponding Simulink names.

Real-Time Workshop Integer Type	Simulink Integer Type
`boolean_T`	`boolean`
`int8_T`	`int8`
`uint8_T`	`uint8`
`int16_T`	`int16`
`uint16_T`	`uint16`
`int32_T`	`int32`
`uint32_T`	`uint32`

If no ANSI C type with a matching word size is available, but a larger ANSI C type is available, the Real-Time Workshop code generator uses the larger type for int8_T, uint8_T, int16_T, uint16_T, int32_T, and uint32_T.

An application can use integer data of any length from 1 (unsigned) or 2 (signed) bits up 32 bits. If the integer length matches the length of an available type, the Real-Time Workshop code generator uses that type. If no matching type is available, the code generator uses the smallest available type that can hold the data, generating code that never uses unnecessary higher-order bits. For example, on a target that provided 8-bit, 16-bit, and 32-bit integers, a signal specified as 24 bits would be implemented as an int32_T or uint32_T.

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

Describing the Byte Ordering

The Byte ordering option specifies whether the target hardware uses Big Endian (most significant byte first) or Little Endian (least significant byte first) byte ordering. If left as Unspecified, the Real-Time Workshop software generates code that determines the endianness of the target; this is the least efficient option.

Describing Quotient Rounding for Signed Integer Division

ANSI C does not completely define the rounding technique to be used 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 tells the Real-Time Workshop code generator how the compiler rounds the result of signed integer division. Providing this information does not affect 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 options 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 — Choose this option if neither Zero nor Floor describes the compiler's behavior, or if that behavior is unknown.

The following table illustrates the compiler behavior that corresponds to each of these three options:

N	D	Ideal N/D	Zero	Floor	Undefined
`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`

Note Select Undefined only as a last resort. When the Real-Time Workshop code generator does not know the signed integer division rounding behavior of the compiler, it must generate fairly costly code in order to guarantee correct results.

The compiler's implementation for signed integer division rounding can be obtained from the compiler documentation, or by experiment if no documentation is available.

Describing Arithmetic Right Shifts on Signed Integers

ANSI C does not define the behavior of right shifts on negative integers, so the behavior is implementation-dependent. The Shift right on a signed integer as arithmetic shift parameter tells the Real-Time Workshop code generator how the compiler implements right shifts on negative integers. Providing this information does not affect 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.

Select the option if the C compiler implements a signed integer right shift as an arithmetic right shift, and clear the option otherwise. 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 twos complement notation. The option is selected by default. If your compiler handles right shifts as arithmetic shifts, this is the preferred setting.

When the option is selected, the Real-Time Workshop software generates simple efficient code whenever the Simulink model performs arithmetic shifts on signed integers.
When the option is cleared, the Real-Time Workshop software generates fully portable but less efficient code to implement right arithmetic shifts.

The compiler's implementation for arithmetic right shifts can be obtained from the compiler documentation, or by experiment if no documentation is available.

Describing Embedded Hardware Characteristics

Describing the Emulation and Embedded Targets documents the options available on the Hardware Implementation subpanes. This section describes considerations that apply only to the Embedded Hardware subpane. When you use this subpane, keep the following in mind:

Code generation targets can have word sizes and other hardware characteristics that differ from the MATLAB host. Furthermore, code can be prototyped on hardware that is different from either the deployment target or the MATLAB host. The Real-Time Workshop code generator takes these differences into account when generating code.
The Simulink product uses some of the information in the Embedded Hardware subpane to ensure that simulation without code generation gives the same results as executing generated code, including detecting error conditions that could arise on the target hardware, such as hardware overflow.
The Real-Time Workshop software generates code that guarantees bit-true agreement with Simulink results for integer and fixed-point operations. Generated code that emulates unavailable data lengths runs less efficiently than it would without emulation, but the emulation does not affect bit-true agreement with Simulink for integer and fixed-point results.
To ensure correctness and efficiency, if you change targets at any point during application development you must reconfigure the hardware implementation parameters for the new target before generating or regenerating code. Bit-true agreement for the results of integer and fixed-point operations in simulation, production code, and test code is not guaranteed when code executes on hardware for which it was not generated.
Use the Integer rounding mode parameter on your model's blocks to simulate the rounding behavior of the C compiler that you intend to use to compile code generated from the model. This setting appears on the Signal Attributes pane of the parameter dialog boxes of blocks that can perform signed integer arithmetic, such as the Product and Lookup Table (n-D) 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 Rounding in the Simulink Fixed Point User's Guide.
When models contain Model blocks, all models that they reference must be configured to use identical hardware settings.

Describing Emulation Hardware Characteristics

Note (If the Emulation Hardware subpane contains a button labeled Configure current execution hardware device, see Updating from Earlier Versions, then continue from this point.)

The default assumption is that the embedded target and emulation target are the same, so the Emulation Hardware subpane by default does not need to specify anything and contains only a selected check box labeled None. Code generated under this configuration will be suitable for production use, or for testing in an environment identical to the production environment.

To generate code that runs on an emulation target for test purposes, but behaves as if it were running on an embedded target in a production application, you must specify the properties of both targets in the Hardware Implementation pane. The Embedded Hardware subpane specifies embedded target hardware properties, as described previously. To specify emulation target properties:

Clear the None option in the Emulation Hardware subpane.
By default, the Hardware Implementation pane now looks like this:
In the Emulation Hardware subpane, specify the properties of the emulation target, using the instructions in Describing the Emulation and Embedded Targets

If you do not display the Emulation Hardware subpane, the Simulink and Real-Time Workshop software defaults every Emulation Hardware option to have the same value as the corresponding Embedded Hardware option. If you hide the Emulation Hardware subpane after setting its values, the values that you specified will be lost. The underlying configuration parameters immediately revert to the values that they had when you exposed the subpane, and these values, rather than the values that you specified, will appear if you re-expose the subpane.

Updating from Earlier Versions

If your model was created before Release 14 and has not been updated, by default the Hardware Implementation pane initially looks like this:

Click Configure current execution hardware device. The Configure current execution hardware device button disappears. The subpane then appears as shown in the first figure in this section. Save your model at this point to avoid redoing Configure current execution hardware device next time you access the Hardware Implementation pane.

Configuring the Target Environment

Configuring the Target Hardware Environment

Related Products & Applications

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit