Simulink® Enabled
Ginmake version 1.74+
This section details the use of Ginmake for Simulink® Enabled GEMS electronic controllers. It includes information on the build process, command line options, and how to use the Simulink® related features.
Ginmake version 1.74+
This section details the use of Ginmake for Simulink® Enabled GEMS electronic controllers. It includes information on the build process, command line options, and how to use the Simulink® related features.
ginmake –simulink-options=options-file –simulink-base-gin=some.gin –simulink-output=dir
The options file can specify both the output directory (dir) and/or the base gin. The command line options will override the options file.
The base GIN file describes the base-level un-extended functionality, protocols etc for the ECU and is strictly required.
The generated model source code and the user workspace file should be provided in the model_sources section of the options file. These are necessary for code/data generation.
Ginmake will generate an externs file in such a way to allow the firmware to convert virtual gemscom addresses to real addresses. The externs file is also processed to add the items to the base gin file and generate a merged gin.
The generated model code is parsed to check which main processor signals are used and generate the
Simulink export will generate a number of files:
The Simulink options file controls what files are input and output.
The file is in a permissive JSON format that supports c-style comments and allows key names to be specified without quotation marks. The entire file must be a JSON object.
Use target: "CDX" to select CDX export. Like target: "XCU8", this defaults to
A2L output, does not require a base GIN, and enables direct calibration access.
Alternatively, set uses_cdx_api: true to select the CDX API independently of the
target’s other defaults. This takes precedence over uses_xcu_api.
CDX uses CDX_ API symbols and cdx_*.h API headers. CAN transmit entry points
take no execution deadline: CDX_STATUS CDX_auto_can_tx(void) and
CDX_STATUS CDX_auto_can_<port>_tx(void).
Periodic scheduling, offsets, and start delays are retained, but transmit frames
have no timeout. Transmit timeout and notification options, including their DBC
attributes, have no effect in CDX mode. No *_can_tx_time.c or *_tx_notify
functions are generated, and notification-dependent transmit timestamps and
error counters are omitted. Receive timeouts are unchanged.
Existing XCU8 and uses_xcu_api configurations are unchanged unless CDX is enabled.
For both CDX and XCU, generated CAN runtime pack/copy calls use internal
start-LSB offsets. Ginmake converts Motorola DBC start-MSB positions during
import, including signals crossing CAN-FD chunk boundaries. This applies to
TX setters, RX/TX start values, multiplexor IDs and common-signal copies.
Keep the original DBC layout; no application offset adapter is required.
Regenerate CAN code with the corrected Ginmake executable to pick up this fix.
Legacy canfuncs code generation retains its own offset convention.
Use urgent_tx inside a can entry to select imported TX frames for urgent
transmission on a physical CAN bus. This option is currently only supported by the CDX API.
Selected frames are excluded from normal transmit rate groups and un-selected frames are processed normally.
For example, add something along the following lines to your Simulink options file, replacing the DBC filename and frame names with those from your application:
{
target: "CDX",
can: [
{
port: "IPC1",
tx: ["physical_can_tx.dbc"],
urgent_tx: [
{frame: "TorqueRequest", port: 0, policy: "step", lifetime_us: 2000},
{frame: "Heartbeat", port: 1, policy: "periodic", period_us: 1000, lifetime_us: 3000},
{frame: "ShiftRequest", port: 0, policy: "triggered", lifetime_us: 2000}
]
}
]
}Each urgent_tx entry accepts these fields:
| Field | Meaning |
|---|---|
frame |
Exact name of a unique TX frame imported into this can entry. Each frame may be selected only once, must be nonmultiplexed, and must have 1..64 payload bytes. |
port |
Physical destination: 0 = CAN1, 1 = CAN2. This is independent of the containing can.port, including named ports such as IPC1. |
policy |
"step", "periodic", or "triggered", as described below. |
lifetime_us |
Urgent enqueue lifetime in microseconds, from 1 to 1000000. |
period_us |
Required for "periodic", from 1 to 1000000 microseconds. For other policies, omit it or set it to zero. |
Use the actual physical-bus DBC IDs and payload layouts, not an IPC-specific representation. The generated enqueue call uses the imported frame’s CAN ID, payload length, and standard/extended, CAN FD and BRS flags.
Sending policies
step: attempts one enqueue on every call to CDX_auto_can_tx_urgent().periodic: attempts an enqueue on the first call, then when at least
period_us has elapsed since the last attempt. Each attempt rearms from the
current time; missed releases are skipped, not sent in a burst. The actual
timing is limited by how often your application calls the function.triggered: attempts one enqueue when the model sets its generated
CDX_<frame-prefix>urgent_request data store to a nonzero value. The request
is cleared before enqueueing, even if the queue rejects the frame. Multiple
writes before the next call represent a single request, not a queue.Application integration
Call CDX_auto_can_tx_init() during initialization. It also initializes urgent
scheduling, clears requests and counters, and sets per-frame status to
CDX_STATUS_NO_DATA. In each foreground model cycle, use this order:
CDX_auto_can_tx_urgent() to enqueue due urgent frames.CDX_auto_can_tx() for ordinary transmission.Urgent calls are foreground-only and nonblocking. Do not call them from an
interrupt handler. To reset only urgent scheduling, requests and diagnostics,
call CDX_auto_can_tx_urgent_init() from the foreground.
For triggered frames, the generated TX MATLAB workspace file supplies the
request signal as ImportedExtern when generate.can_tx_workspace is enabled.
Use that generated signal as the model’s data store; the C request variable is
uint8_t. Refer to the generated CAN TX header for the exact frame-prefixed
symbol names.
Enqueue results
CDX_auto_can_tx_urgent() returns CDX_STATUS_NO_DATA when no frame is due,
CDX_STATUS_OK when all attempted enqueues are accepted, or the first enqueue
error. Each selected frame also exposes:
| Generated symbol | Meaning |
|---|---|
CDX_<frame-prefix>urgent_status |
Result of the most recent enqueue attempt; unchanged when the frame is not due. |
CDX_<frame-prefix>urgent_accepted |
Number of accepted enqueues (uint32_t). |
CDX_<frame-prefix>urgent_rejected |
Number of rejected enqueues (uint32_t). |
Message delivery is not guaranteed - the accepted count only counts messages that have been successfully enqueued. The counters wrap on overflow.
The cdx-runtime provides cdx_fast_io.h and CDX_can_tx_urgent_enqueue.
Each can entry accepts either a numeric port from 1 to 64 or a port name.
For XCU and CDX, port: "IPC1" and port: "ipc1" both generate
XCU_CAN_BUS_ID_IPC1 or CDX_CAN_BUS_ID_IPC1. Names are converted to uppercase
and must start with a letter or underscore, followed by letters, digits or
underscores. Numeric ports retain their existing behavior: port: 2 generates
XCU_CAN_BUS_ID_CAN2 or CDX_CAN_BUS_ID_CAN2.
Entries with the same normalized name share a bus. Named ports also use their
uppercase name in generated per-port identifiers and segment semantics, for
example canrxIPC1 and cantxIPC1. The usual canrx, cantx, can and model
RAM segment fallbacks still apply.
A2L Simulink builds generate CDX_IPC_INTERFACE_HASH for the CDX API (including
CD6 builds), or XCU_IPC_INTERFACE_HASH for the XCU API, alongside EPK_VALUE
in <file_prefix>epk.h. These are string macros that may be overridden with an
existing definition.
EPK_VALUE remains the build identity. The IPC interface hash is a 40-character
SHA-1 hex string depending only on the contents of the DBC files imported through
can.rx and can.tx. File paths, import order, repeated identical files, CAN
ports, model versions and other build inputs do not affect it. Any DBC content
change, including comments, affects the hash.
The hash is SHA-1 of the concatenated, lexicographically sorted, unique SHA-1 hex
digests of the DBC files. With no DBC files, it is the SHA-1 of an empty input:
da39a3ee5e6b4b0d3255bfef95601890afd80709.
Example:
1// Options for ginmake simulink code generation / build steps
2// All paths/filenames are relative to this file unless specified as absolute paths
3{
4 include:["common.opt"], // Optional list of options files to process before this one.
5 target:"EM80-M", // May be blank for legacy behaviour. Use "XCU8" for the XCU8 ECU. V2.51+
6 base_gin:"EM80_M-00x06.gin", // Not required for XCU8 target – do not specify.
7 // a2l: true/false – generate A2L instead of GIN, implicitly defined by target option. V2.51+
8 file_prefix:"auto_EM80_M-", // "" == generate from ECU name loaded from base_gin (i.e. not on XCU8).
9 out_dir:"./BuildEnv/src/Simulink",
10 out_dir_can:"./BuildEnv/src/Simulink/can",
11 out_dir_gin:".",
12 out_dir_workspace:".",
13 temp_dir:"",
14 direct_cal_access: true, // On XCU8, use fast direct calibration variable access for get/set functions.
15 use_temp_files: true, // Write code to temporary files and only overwrite if contents changed.
16 compiler_packing: 4, // Packing affects addressing of externs that would be aligned by compiler.
17 compiler_array_alignment: 1, // Minimum alignment for arrays of values.
18 categories:[], // list of category names if filtering required.
19 // Terse options for placement. Using regions is more flexible.
20 // ram_address: 0xE000, // virtual 'gemscom' address of volatile items (gems parameters)
21 // nvm_address: 0xF000, // virtual 'gemscom' address of non-volatile items (gems options/tables/maps)
22 // ram_size: 0x1000, // max size (bytes) reserved for RAM segment
23 // nvm_size: 0x1000, // max size (bytes) reserved for NVM (non volatile memory) segment
24 asm_gcc_prefix_underscore: false, // GCC: set this if underscore is added to function names by compiler
25 asm_iar_prefix_underscore: false, // IAR: set this if underscore is added to function names by compiler
26 canrx_data_size: 16, // Usually best not to specify these
27 cantx_data_size: 12,
28 canrx_frame_timeout_multiplier: 10, // defaults for these
29 canrx_frame_timeout_default: 10000,
30 cantx_frame_timeout_multiplier: 0, // TX: multiplied by GenMsgCycleTime, added to fixed value (XCU). v2.75+
31 cantx_frame_timeout: 1000, // TX fixed timeout value (XCU). v2.75+
32 cantx_frame_timeout_enable: true, // Enable CAN Tx timeouts (XCU) v2.75+
33 virtual_version: "$(BaseVersion)-XYZ-$(ModelVersion)", // Generate virtual version to disambiguate ECU names. Currently, Name, BaseVersion and ModelVersion are recognised. As are environment variables.
34 output_filename: "$(FilePrefix)$(Name)-$(BaseVersion)-XYZ-$(ModelVersion)",
35 model_sources:[
36 "em80m_generation.c",
37 "em80m_generation.h",
38 "user_workspace.m",
39 "model_sources.grh" // includes multiple files recursively, with C preprocessor support (ginmake 2.51+)
40 ],
41 // Files to use in ginmake 2.51+ build
42 // (in addition to generated externs.h)
43 // Not typically used for EM80-M target.
44 inputs:[
45 "app_version.h",
46 "xcu_cal.h",
47 "multiple_headers.grh" // includes multiple files recursively, with C preprocessor support.
48 ],
49 can: [
50 {
51 port:2,
52 speed:1000000,
53 rx_prefix: "CRX_",
54 tx_prefix: "CTX_",
55 rx_name_prefix, "CAN2 RX ",
56 tx_name_prefix, "CAN2 TX ",
57 rx_gin_category, "CAN2.Signals", // Semicolon separated list Category names to add RX signals to.
58 rx_raw_gin_category, " CAN2.Raw",// Semicolon separated list Category names to add raw RX signals to (e.g. frame data & bytes).
59 rx_time_gin_category, " CAN2.Time",// Semicolon separated list Category names to add time RX signals to (time / delta time).
60 rx_frame_time_prefix: "CRX_Time_",
61 rx_frame_elapsed_prefix: "CRX_Elapsed_",
62 rx_real_only: false, // If true, export all rx signals from can as real32_T
63 rx_use_start_values: true, // CDX/XCU: initialize RX signals from DBC GenSigStartValue. Set false for zero-filled RX buffers.
64 tx_use_start_values: true, // CDX/XCU: initialize TX signals from DBC GenSigStartValue. Multiplexor group IDs are always initialized.
65 keep_duplicates: true,
66 warn_duplicates: true,
67 prefix_frame_name: false,
68 default_tx_rate: 10,
69 disable_demultiplex: false,
70 disable_tx_multiplex: false,
71 disable_tx_notify: false, // XCU: flag tx frames as not requiring completion notification. Overridden by DBC attribute GemsEnableNotify. v2.75+
72 tx_timeout: 0, // If nonzero, overrides global cantx_frame_timeout (XCU). Overridden **by DBC attribute GemsMsgTimeoutOffset. OR: GemsMsgTimeout - which is an absolute value that also overrides timeout multiplier.** v2.75+
73 tx_timeout_multiplier: 0, // If nonzero, overrides global cantx_frame_timeout_multiplier (XCU). Overridden by DBC attribute GemsMsgTimeoutMultiplier. v2.75+
74 // tx_timeout_enable: true, // Overrides global cantx_frame_timeout_enable. Overidden by DBC attribute GemsMsgTimeoutEnable v2.75+
75 disable_demultiplex: false, // Disable de-multiplex of CAN frames.
76 disable_tx_multiplex: false,
77 rx: ["can_rx.dbc"],
78 tx: ["can_tx.dbc"],
79 rx_nodes: "VDM", // optional: Only import VDM frames for RX. Do not specify to import all
80 tx_nodes: ["LCM1","BCS"], // optional: Only import LCM or BCS frames for RX.
81 filter_rx_nodes_on_signals: true // set to false to filter based upon frame TX node.
82 }
83 ],
84 segments: [
85 {
86 name: "MODEL_NVM",
87 address: 0xF000,
88 size: 0x1000,
89 physical_address: 0x0800F000, // Optional physical address (if known).
90 semantic: "model_nvm",
91 identifier: "seg_nvm",
92 gcc_section: ".modelDataNVM",
93 memory_type: "nvm",
94 address_define: "GEMS_SECTION_ADDRESS_NVM",
95 endian: "MSB_FIRST",
96 attributes:{ // [ATTRIBUTES] to add to segment
97 // ADDRESS_MAPPING:"{APP_SEG_NVM_DEFAULT_ADDR};{APP_SEG_NVM_ADDR};{APP_SEG_NVM_SIZE}",
98 PrgType:"DATA",
99 MemoryType:"FLASH",
100 Attribute:"INTERN",
101 SECTOR:0,
102 NUM_PAGES:1,
103 ADDRESS_EXTENSION:0x00,
104 COMPRESSION_METHOD:0x00,
105 ENCRYPTION_METHOD:0x00,
106 }
107 },
108 {
109 name: "MODEL_RAM",
110 address: 0xE000,
111 size: 0x1000,
112 semantic: "model_ram",
113 identifier: "seg_ram",
114 gcc_section: ".modelData",
115 memory_type: "ram",
116 address_define: "GEMS_SECTION_ADDRESS_RAM"
117 },
118 {
119 name: "CANRX2",
120 address: 0xB800,
121 size: 0x800,
122 semantic: "canrx2", // can use can, canrx, canrxN, cantx, cantxN
123 identifier: "seg_crx2",
124 gcc_section: ".modelDataCRx2",
125 memory_type: "ram",
126 address_define: "GEMS_SECTION_ADDRESS_CANRX2",
127 endian: "LSB_FIRST"
128 },
129 ],
130 generate: {
131 date_comment:false, // Include date/time in source file comment.
132 // Turn off to prevent otherwise identical files from being touched.
133 get_set:true,
134 get_set_real_only:false, // Make all get/set values real32_T as per old behaviour.
135 utility_functions:true,
136 workspace:true,
137 workspace_descriptions:true,
138 workspace_optimize:true, // use signal factory functions to reduce workspace file size
139 in_signals:true,
140 externs:true,
141 externs_addresses:true, // generate #defines for the virtual address of each variable, for on-target testing purposes.
142 externs_segment_size:true, // generate #defines for segment used sizes / first identifier.
143 externs_asm_placement:true, // Generate ASM files to place extern variables (avoids compiler re-ordering). Also generates a .c file.
144 asm_gcc_comment_start: "@", // GCC Assembler uses different comment char depending upon target!
145 unused_externs:false, // generate externs for simulink objects even if not used by model
146 gin:true,
147 gin_code:true,
148 ecudef_code:true,
149 gin_append_model_version:true,
150 units:false,
151 identity:true, // Generate identity.c
152 can_rx_h: true,
153 can_rx_c: true,
154 can_rx_workspace: true,
155 can_rx_frame_time: true,
156 can_rx_frame_elapsed: true,
157 can_rx_frame_timeout: true,
158 can_tx_h: true,
159 can_tx_c: true,
160 can_tx_workspace: true,
161 can_tx_frame_time: true,
162 can_tx_frame_error_counters: true,
163 can_frame_bytes: true,
164 can_signal_size_optimization: true, // 2.20.0: RX avoid raw value using all bytes in the CAN frame.
165 can_integer_frame_times: true, // 2.34.0: Use uint32_T for frame times instead of real32_T.
166 simulink_categories: true, // Link objects to categories based upon Simulink.Type. Default true.
167 m_file_per_function: true // Use separate .m file for workspace optimization functions.
168 }
169}If not provided, the model_nvm and model_ram segments will be automatically generated based upon nvm_address/size and ram_address/size respectively. Ginmake uses the ‘semantic’ field to look up sections so these must match correctly.
With workspace_optimize enabled, each enabled workspace script uses its own signal factory:
GemsSignal for workspace, GemsGetSetCanRx for can_rx_workspace, and
GemsGetSetCanTx for can_tx_workspace. With m_file_per_function: true, these
functions are written once per export to separate .m files alongside their workspace
scripts in out_dir_workspace (or out_dir if not specified). Otherwise, each function
is included in its workspace script. Disabling workspace also disables GemsSignal
generation; CAN workspace generation is controlled independently.
The identifier field is used to define a symbol for section placement of global variables and will also be used by ginmake to locate items into calibration regions. Items are expected to be packed according to the compiler_packing value.
Warning: the segment identifier will be converted to lower case internally due to the way segment lookups are performed by ginmake (for legacy reasons), so segment lookups will effectively be case insensitive and name collisions with alternatively cased identifiers should be avoided.
The Simulink code generation can be supplied with a user workspace file that identifies objects used by the Simulink model and should be available to the calibration software.
Enumerations and other ginmake directives can appear in this file. These should be specified in comments that begin with %+.
e.g.
Items may have ginmake style comments preceding them. These will be added to the generated externs file (possibly with some translations).
Such comments must begin with %$.
Empty fields in such ginmake comments (e.g. the item name) may be filled in by ginmake using the details in the MATLAB object definition before writing to the externs file.
Items in the user workspace should use the ImportedExtern CoderInfo.StorageClass.
e.g.
1%$ [,speed:rpm,,,r,,,,#.##,]
2MySignal = Simulink.Signal;
3MySignal.CoderInfo.StorageClass = 'ImportedExtern';
4MySignal.DataType = 'single';
5MySignal.Complexity = 'real';
6MySignal.InitialValue = '0.0';It is also possible to specify the fields of an object definition in a more readable way. For example:
1%$ units: speed:rpm
2%$ readonly: true
3%$ axis_param: Flyspd
4%$ scalar: 1
5%$ offset: 0
6%$ reciprocal: false
7%$ category: breakpoints
8%$ format: #.##
9Bpx = Simulink.Breakpoint;
10Bpx.SupportTunableSize = false;
11Bpx.Breakpoints.DataType = 'single';
12Bpx.Breakpoints.Min = [];
13Bpx.Breakpoints.Max = [];
14Bpx.Breakpoints.Unit = '';
15Bpx.Breakpoints.FieldName = 'Bpx';
16Bpx.Breakpoints.Description = '';
17Bpx.Breakpoints.Value = [1 2 3 4 5];
18Bpx.Breakpoints.TunableSizeName = 'N';
19Bpx.CoderInfo.StorageClass = 'ImportedExtern';
20Bpx.CoderInfo.Alias = '';
21Bpx.CoderInfo.Alignment = -1;
22Bpx.StructTypeInfo.Name = '';
23Bpx.StructTypeInfo.DataScope = 'Auto';
24Bpx.StructTypeInfo.HeaderFileName = '';The full list of available fields is as follows:
Unless stated otherwise, these fields follow those in the parameter/option/table/map definitions. Remember that to create the desired object, you must use the correct number of fields required for that object (unused fields can be left blank).
Examples of how to use limits on raw and real values can be found in VIEWRANGE, LIMITS and HARDLIMITS sections. Note: In Ginmake 2.21+, floating-point objects without limits set will generate a warning. To remove this warning, one of the following needs to be set for the object: Valid range, View range, Limits, Hard Limits.
By Default, Simulink.Signal objects will be placed in RAM (the segment with semantic:“model_ram”).
All other objects will go into NVM (model_nvm).
It is possible in ginmake 1.91+ to specify the segment NAME in the preceding comment to override this behaviour.
e.g.
Items in functions whose names end with _GEMS_Initialize will be added to initialization lists in generated firmware code.