Simulink Options File

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.

CDX API

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.

CDX Urgent CAN Generation

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:

  1. Run the model step to update the TX payloads and any trigger requests.
  2. Call CDX_auto_can_tx_urgent() to enqueue due urgent frames.
  3. Call 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.

CAN Port Names

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.

IPC Hash

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.