Data Definitions
Reference for Ginmake data definition directives and related syntax.
Reference for Ginmake data definition directives and related syntax.
Definitions for these kinds of objects are based upon the number of fields in the definition & do not have a directive name.
Channels were formerly called ‘parameters’ in older versions of Ginmake. They were renamed to avoid confusion with the concept of ‘parameters’ in Simulink and also to better reflect their purpose as a channel for the value of a parameter (or other variable) that is used in the ECU’s memory.
The first 9 fields of each of these types hold the same information.
For tables and maps fields 10 to 14 hold information about the axis or x axis respectively. For maps fields 15 to 19 hold information about the y axis.
For channels field 10 is not currently used and should be left blank.
The following table shows how each field is used:
| Field | Field Name | Description |
|---|---|---|
| 1 | Name | The name of the type. If left blank the associated variable name is used. For Gin versions 3.17+: If the field is preceded with a tilde character ( |
| 2 | Units | The units for the type. If this field contains text in brackets, it indicates a user scalar. For information on user scalars see below. See also section on units: Error! Bookmark not defined. |
| 3 | Scalar | IFF the whole field matches a pre-processor symbol then it shall be replaced (Ginmake 2.35+). This field and the offset field define how the raw value is scaled to the given units. The scalar (m) and offset (c) (obtained from field 4) are applied to the raw value using m*raw + c. If this field is left blank, m is set to 1. If the field is a value, m is set to value/256. For example, if the value is 100, m is set to 0.39. If the field is a value preceded by a ‘*’ character, m is the real value following the ‘*’. The field may alternatively use a type specifier, to provide a multiplier of a specific type. If a type specified field is used, this may be followed by a ‘/’ and an additional type specified value to be used as a divisor. If the field is a value preceded by the ‘/’ character, m is the real value following the ‘/’ but the real value is calculated as m / (raw + c). For example, /5859 would result in real=5859/(raw [+ offset]). If the resulting denominator is zero, then GWv4 will display ‘Error’ in parameter/enumerations. If this field is defined enum(x), x refers to the name of an enumeration (see ENUM). It can also be used in conjunction with a multiplier (allowing enumerations to be used on mask-shifted values). e.g. …,64 ol(PullUpList),… Legacy: instead of ’enum’, the field may also use ‘ol’ for backwards compatibility. Additionally, this field may be defined as OLx where x is the index of the enumeration in the GIN file, starting at 1. Index based enumeration lookup is easily broken and therefore discouraged. A text string in brackets indicates a function table. See below for details on function tables. If this field is ‘c’, the type is a parameter comm code. |
| 4 | Offset | IFF the whole field matches a pre-processor symbol then it shall be replaced (Ginmake 2.35+). The value of this field defines c and is an integer value. If the field is blank, c is set to 0. If the field is a value preceded by a ‘*’ character c is the real value following the ‘*’. Alternatively, this may be a value with a type specifier. |
| 5 | Read/write | IFF the whole field matches a pre-processor symbol then it shall be replaced (Ginmake 2.35+). If this field is set to w or W the type can be written as well as read through the serial port. If the type is an option and the field is set to o or O the option is also writeable. If the field is r, R or left blank the type is read only. If the type is a parameter, a value of ’m’ or ‘M’ followed by either a numerical index or a name reference in brackets indicates a multiplicative programmable parameter. If an ‘a’ or ‘A’ is used instead of ’m’, then it is an additive programmable parameter. e.g. ‘m5’ indicates that the parameter modifies the fifth map. ’m(Fuel)’ indicates that the parameter modifies the map named ‘Fuel’. Gin versions 3.17+: This field may additionally contain a profile reference (see below about Profiles). The format for this is a ‘p’ character followed by the name of the profile in brackets. This can be added in addition to one of the above values and should be separated with a space. It can feature before or after the r/w value. It is possible to assign the object to multiple profiles if required. This is accomplished by separating the profile names by ‘;’ characters: e.g. [..,m(Fuel) p(Engine),,,…] or [..,r p(Engine;Fuel),,,…] Gin versions 3.22+: This field may additionally contain a category reference (see below about Categories). The format for this is a ‘c’ character followed by the unique identifier of the category in brackets. This can be added in addition to one of the above values and should be separated with a space. It can feature before or after the r/w value. It is possible to assign the object to multiple categories if required. This is accomplished by separating the category identifiers by ‘;’ characters: e.g. [..,m(Fuel) c(fuel),,,…] or [..,r c(fuel;accel),,,…] |
| 6 | 2’s complement | If a ‘2’ or a ‘-’, the location holds a 2’s complement value. If a ‘+’ or empty, the location holds a positive value. Alternatively, the field can contain a type specifier to indicate/override the underlying raw type (e.g. @4u:) |
| 7 | Floating-point | If an ‘f’ character is specified, the scaled value is displayed as a floating-point value. If ‘i’ or empty, the scaled value is displayed as an integer. |
| 8 | Bitmask | IFF the whole field matches a pre-processor symbol then it shall be replaced (Ginmake 2.35+). If this field is empty, all bits of the location are used to calculate the value. A value indicates a bit mask showing which bits should be used in calculating the value. Any bits used must be adjacent. A single bit is displayed as either ON or OFF. Note that the bit mask may be defined using a shift expression if desired: e.g. 1 « 2 1 shl 4 If the value is signed, then the mask will sign extend the top bit. Gin version 3.32+ May define a shift to be applied to the value before the mask and before any scaling. This is part of the conversion from ‘EcuRaw’ => Native ‘Raw’ (in conjunction with Endian Mode + Mask). e.g. SHL(10) SHR(4) May define a Bit Extraction similar to DBC: BIT(offset|count) BIT(offset) BIT(offset) is equivalent to BIT(offset|1) Bit extraction is performed after any endian swapping and is therefore relative to the Least Significant Bit (LSB). e.g. BIT(8|4) will extract 4 bits that are 8 bits offset from the LSB. The result will be shifted down. i.e. ((EcuRaw » 8) & 0x0F) |
| 9 | Base/Format | IFF the whole field matches a pre-processor symbol then it shall be replaced (Ginmake 2.35+). If ‘b’ the scaled value is displayed in binary notation (0bxxxxxxxx). If ‘h’ or ‘x’ the scaled value is displayed in hexadecimal notation (0xXXXX). If ’d’ or blank, the scaled value is displayed in decimal. Note that binary and hexadecimal do not display to floating-point. This field may also be a format string to control the display of decimal places. See Value Formatting. To specify formatters for axes, this field can be a semi-colon delimited list of formats. The first item being the format for the map/table itself, and subsequent fields being for the x and y axes, respectively. |
| 10 | Axis Channel | This is the name of the parameter used for the axis of a table (or x axis of a map). In some tables (e.g. battery compensation table) the parameter is used to determine the current position in the table. In others (e.g. speed table) the parameter is used by the maps that use the table as their axis. This name may also be the name of a table used for the axis of a table or map (as referred to in the speed table example). Note tables take precedence over channels. You should avoid duplicating names of channels, options and tables for values that are referenced by this field. If such a conflict exists, Ginmake will warn you. If the field is encapsulated in P[…], then this corresponds to an option that defines the PARAMETER to use (i.e. a dynamic, ‘indirect parameter’). The option may be an enumeration containing parameter names or it may be a comcode option. e.g. P[Channel Selector X] If the field is encapsulated in T[…], then this corresponds to an option that defines the TABLE for the axis. The option may be an Enumeration style option that contains the name of the tables that can be used. Of the field is an indirect table/parameter and it refers to an Option with an Enumeration, the enumeration names will be checked for matching table/parameter names. If there is an entry for an unknown item, Ginmake will issue an error. |
| 11 | Axis Units | The units for the axis (or x axis of the map). (May also be user scalar units as per field 2.). Defaults to an empty string. |
| 12 | Steps | The number of steps in the table (or x axis of the map). Defaults to 1. Alternatively, this may be the name of an option if a table has not been used for the axis parameter. The name may optionally be placed in brackets. |
| 13 | Start | The axis value of the first step. This is an integer value. If preceded by a ‘*’ the subsequent real value is the first step value. Defaults to 0. Alternatively, this may be the name of an option if a table has not been used for the axis parameter. The name may optionally be placed in brackets. |
| 14 | Offset | The offset of each subsequent axis site from the start axis value. This is an integer value. If preceded by a ‘*’ the subsequent real value is the offset. Defaults to 1. Alternatively, this may be the name of an option if a table has not been used for the axis parameter. The name may optionally be placed in brackets. |
| 15 | Y Axis Channel | As field 10 for maps. |
| 16 | Y Axis Units | As field 11 for maps. |
| 17 | Y Steps | As field 12 for maps. |
| 18 | Y Start | As field 13 for maps. |
| 19 | Y Offset | As field 14 for maps. |
To create the desired object, you must use the correct number of fields required for that object. There should be a minimum of 9 commas for a parameter and up to 18 commas for maps. Unused fields can be left blank like the two channels and a map example below:
1FMOD DS.B 1 ;[Fuel mod,%,100,,W,2,f,,,]
2SPEED DS.W 1 ;[Engine Spd,rpm,100,0,r,+,i,,]
3FMAP DS.B MAPSIZE ;[Fuel,VE,,,o,+,i,,,
4 ; Throttle,,MAPLSTP,0,10,
5 ; Engine Spd,rpm,MAPSSTP,800,400]
6
7; Note that 'Throttle' and 'Engine Spd' must be defined as channels.Options may be defined as ‘parameter comm codes’. Such options are always words, and their value defines the comm code of a parameter. The appropriate parameter is looked up and its name displayed as the value. Such objects must be large enough to hold a comm code value.
An option displaying a parameter comm code is defined by setting ‘c’ in the scalar field.
Many objects can use a value format in order to control how values are displayed (decimal places, hex etc).
The following table shows the standard formatting characters that can be used:
| Character | Description | Notes |
| X or x | Display in hexadecimal | Must be first character in format |
| B or b | Display in binary | Must be first character in format |
| - | Force leading sign character | e.g. +5.3 is displayed instead of 5.3 |
| # | Indicates an optional digit | e.g. ### gives 93 |
| 9 | Indicates a required digit | e.g. 999 gives 093 |
| 5 | Round to nearest 5 | e.g. ##5# gives 2450 instead of 2448 |
| 0 | Round to nearest 10 | e.g. ##0# gives 2400 instead of 2448 |
| . | Indicates position of decimal | e.g. #.## rounds to 2 decimal places. |
Supported by Ginmake v1.74 and later.
[_DEFINE,name]
[_DEFINE,name,value]
Define pre-processor symbols via ginmake comments instead of in the source code itself.
e.g.
Supported by Ginmake 1.32 and later
These are used for comment-based conditionals. If the statement is false, then the rest of the comment line is not parsed.
e.g.
This will only include Inj Advance Mod if the OMEX symbol has a value of ‘2’ or equates to hat value. Any arithmetic or relational operators may be used in the expression.
_IFDEF evaluates to TRUE if the symbol in the following field is defined.
_IFNDEF evaluates to TRUE if the symbol in the following field is NOT defined.
Supported by Ginmake 1.42 and later
Has the same effect as _IF, _IFDEF and _IFNDEF. The difference is that it only applies to the next object definition (excluding any more pre-processor definitions and/or _WARN directives).
Supported by Ginmake 1.41 and later
Supress output of a warning for the next object definition.
e.g.
1// [_WARN,4017][expression generating warning 4017...]
[ADDROFF,n]
Similar to [SIZEOF]
Causes the base address of the next defined object to be adjusted.
For example, if there is a word value defined:
1USERMSG1 DS.W 1 ;[User Message,,,,r,,,,H,]A 8bit alias of the 2nd byte may be added:
Following use of the ADDROFF override to create an object, the override is reset. The override also does not survive until the next source code definition (e.g. the next DS.B).
Ginmake 2.62+
[ALIAS,name,alias_name]
[ALIAS,name,alias_name,type]
Clone object named ’name’ of type ’type’ with new name ‘alias_name’. Type field is optional.
Note that for more control, the following is now also possible in ginmake 2.62+, to create a new object at the same location as the EXTEND item:
1// [EXTEND,TIC 01 Time][TC1,,,,r,+,i,,,]
Supported by Ginmake 1.24 and later, Gin file version 3.21
[ATTRIBUTES,attribute1,attribute2=value2,...]
Allows the object to be tagged with various strings. These will be used to convey additional information about the object.
One such attribute is ‘fuel’. This allows maps that are not called ‘fuel’ to be interpreted as fuel maps and provide the user with additional fuel map specific options.
Example:
1// [Fuel1,VE,,,o,+,i,,,rpm Breakpoints,rpm,MAPSSTP,800,400,Load Breakpoints,(Load),MAPLSTP,0,10]
2// [ATTRIBUTES,fuel,another one,another two]
Extension in Ginmake 1.33 and later, Gin file version 3.23
Attributes can now be given values using assignment:
// [ATTRIBUTES,ChannelName = Vehicle CAN]
In-line expression evaluation is also possible by enclosing the expression in {…} symbols. This includes expansion of pre-processor symbols and function-like macros:
1#define CAN_CHANNEL(x) CAN x + 1If a ‘{’ character is required in the evaluated text, enter it twice:
Note: can channel names should be defined using the ‘META’ tag, along with ‘CAN_CHANNEL_NAME’.
Small increment and large increment
A problem when using 16bit tables, maps, options etc is that incrementing the value can have a very small effect on the object. You can specify the large/small increment used by Gwv4 by using the large_inc and small_inc attributes:
1[ATTRIBUTES,small_inc=16,large_inc=256]The default supplied by gw is a small_inc of 1 and a large_inc of 16.
| Attribute | Meaning |
|---|---|
| _equ | EQU name preceding the definition, automatically generated by ginmake from injected EQU_ANNOTATION directives. |
| _f | Filename index and line reference, automatically generated by ginmake. |
| _v | Variable name, automatically generated by ginmake for display in descriptions view for GEMS staff. |
| analog_index | Indicates that an option specifies an analog input channel number. |
| axis_x_param_cc | The value of this attribute is given the name of an option that holds a comcode for looking up the X axis parameter. Currently only for tables (note that tables can be used as map axes though). |
| adjust_by_percentage | For log maps, this is the default value for the ‘Adjust by Percentage’ setting in the ‘Apply Corrections’ dialog. |
| bool | Object represents a Boolean value (zero or non-zero) |
| can_id | Indicates that this value is a CAN ID and GW should present a CAN ID editor for the field. The Extended bit is represented by 0x20000000. The ID itself is right justified. This is only available in GW version 4.03.36+ so it is recommended to set the field to display in hex for prior versions. |
| convert_lerp | During calibration conversion, does a real->real interpolated site conversion (the default). |
| convert_raw | During calibration conversion, does a copy of raw values as-is, with no interpolation. empty sizes will be set to zero. |
| convert_static | During calibration conversion, does a real->real (scaled) site conversion, with no interpolation. empty sizes will be set to zero (raw). |
| correction_mul | For log maps, this is the default value for the ‘Multiplier’ setting in the ‘Apply Corrections’ dialog. |
| error_as_percentage | For log maps, this is the default value for the ‘Error as Percentage’ setting in the ‘Apply Corrections’ dialog. |
| direct_cal_disable | Simulink builds: disables ‘direct calibration access’ for this object or memory segment. If set to -1 then the setting is inherited from the parent segment (allows EXTEND to effectively un-set the attribute). |
| enable_error_as_percentage | Enables error_as_percentage property in Apply Corrections. |
| fuel | Indicates that the associated object is a fuel map. |
| input_name | Name of an input. E.g. for Analog 08 this may specify “Air Intake Temperature”. |
| inputs | List of object names that are inputs to this object for the purposes of generating an audit graph |
| invert_lookup | Inverts the parameter position lookup on table objects. The parameter position is based upon the values in the table as opposed to the values in the axis. For tables that are used as table axes, this is done automatically. This may specify a Boolean value (0, 1, true, false) to override the automatic value. |
| large_inc | Value of this attribute defines the large raw increment in Gwv4 when the SHIFT+/- keys are used. |
| pullup | Pullup value, in ohms. This must be an integer value – i.e. use 4700 instead of 4K7. Used for analog inputs. If specified, when using Sensor Calibration view with conversion from Ohms to table input voltage, the pullup field can be auto-populated. |
| outputs | List of object names that are outputs of this object for the purposes of generating an audit graph |
| sl_prefix | Equivalent to [SL_PREFIX] directive. |
| small_inc | Value of this attribute defines the small raw increment in Gwv4 when the +/- keys are used. |
| stress_test_override | When running a calibration stress test, this value is not randomised and is instead written with its default value (see VALUES tag). GEMSEC is automatically handled in stress tests. |
| target_map | For log maps, specifies a physical map that should be used for the target. |
| swt_in | Indicates that this option should present a switch selector (or not) – specify 1 or 0, with the default being 1. |
Conversion directives will be applied if either source OR destination have the attribute. convert_static will take preference over convert_raw. convert_lerp will take preference over convert_static.
For some conversions, these hints will be ignored (Enumeration or ComCode targets).
Categories are supported in version 3.22 Gin files.
[CATEGORY,<identifier>,<display_name>,[<parent>]]
| identifier | Unique identifier referring to the category |
| display_name | Name to be displayed in GWv4 |
| Parent (optional) | Identifier of the parent category. This allows tree structures of categories to be defined. |
A category generates a tag that is referenced by other objects in the GIN file. In Gwv4 objects are added to categories in the views tree to make the user interface more logical.
Categories can be applied to options, tables, parameters and maps in the read/write field with a ‘c(
See also: Option, Parameter, Table and Map definitions, Read/Write field
Example
1[CATEGORY,fuel,Fuel]
2[CATEGORY,fuel_accel,Accel,Fuel]
3[CATEGORY,ign,Ignition]
4[CATEGORY,ign_accel,Accel,Ignition]
5[CATEGORY,another,Another]
6[CATEGORY,yet_another,Yet Another]…
1[Fuel,VE,,,o **c(fuel;another;yet_another)**,+,i,,,Throttle,,MAPLSTP,0,10,Engine Spd,rpm,MAPSSTP,800,400]Supported by Ginmake 1.33 and later, GIN file version 3.23.
[CONNECTION,type[,param1,param2,...]]
Connection definitions give GW a hint as to how the ECU should be connected to. The idea is to be able to provide a better user interface if it appears that the user is having trouble connecting to the ECU. It is mandatory to have at least one connection defined in GIN files of version 3.23 or later.
The connections will be checked when connecting to the ECU in Gwv4. If there is not a connection in the GIN that matches, then GW will warn you.
For now, these are the definable connection types. The third parameter of the COM connection definition is the baud rate (mandatory for COM connections only).
1// [CONNECTION,COM,38400]
2// [CONNECTION,FTDI]
3// [CONNECTION,LIBUSB]
4// [CONNECTION,HID]
5// [CONNECTION,MASS] // Mass storage device
The CONNECTION definition is just a list of strings and there is no checking on the actual values performed by ginmake. This is to make it easily extensible in the future.
Notice that only the COM port connection type requires a baud rate. In the future the other connection objects may acquire additional parameters.
Supported by Ginmake 2.38 and later.
[DELETE,name]
[DELETE,name,type]
Extend an existing item of the given name and, optionally, type in case of ambiguity.
e.g.
Supported by Ginmake 1.33 and later, GIN file version 3.23.
[{object}][DESCRIPTION,text]
Tags a description to the preceding object. This will be used in Gwv4 for extended information (e.g. tool tips for options).
See also XMLDESCRIPTIONS.
1// [Fuel,....] // fuel map
2// [DESCRIPTION,Configures the amount of fuel injected at different load and speed values]
In ginmake 2.37 this can be used in conjunction with EXTEND to place descriptions in a separate file.
1// [EXTEND,Fuel,map] // fuel map
2// [DESCRIPTION,Configures the amount of fuel injected at different load and speed values]
Text may include ginmake style character entities (see Appendix A).
HTML is supported in this field so must be appropriately escaped.
If this field is being generated from Simulink object properties or DBC, prefix with to prevent automatic escaping.
Ginmake 2.62+
[{object}][DIRECT_CAL_DISABLE]
For Simulink builds, if direct_cal_access is enabled, this post-fix directive disables direct access for the associated object.
The controls the way in which get/set functions are generated for the object. If direct_cal_access is enabled, then by default get/set functions will be generated that access the calibration memory / variable directly. This directive forces the use of XCU_memory_xx functions instead for the associated object.
In some cases, it may be preferred for some items to be read/written via the XCU_memory_xx functions instead on a case-by-case basis, even when direct_cal_access is enabled. This directive allows this to be done without having to disable direct_cal_access for the whole build.
e.g.
1uint16_t object; // [My Thing,…][DIRECT_CAL_DISABLE]
This is a shorthand equivalent to:
1uint16_t object; // [My Thing,…][ATTRIBUTES,direct_cal_disable=1]
Supported by Ginmake 2.37 and later, Gin file version 3.22
[{object}][DISPLAY_IDENTIFIER,identifier]
Sets the ‘display identifier’ value on the prior object (as in Asam A2L DISPLAY_IDENTIFIER)
Supported by Ginmake 1.53 and later, Gin file version 3.26
[ECU_STRING,identifier]
Adds an array of bytes that is readable from the ECU as a string.
e.g.
1example ds.b 6 ; [ECU_STRING,Example]Adds a string that is 6 characters long and identified by the name ‘Example’.
Ginmake version 1.48.0+ supports ~ and ! characters as a name prefix, as for options, tables, maps etc for ignoring in conversions / hiding from the user.
e.g.
1example ds.b 6 ; [ECU_STRING,!Example][ENUM=name,string1,value1,string2,value2...]
[ENUM,string1,value1,string2,value2...]
[OPTLIST=name,string1,value1...]
An enumeration (formerly ‘Option List’) allows a value to be represented by a string of text. Within GW the type (typically an option) can be modified by selecting a string from a pull-down list of strings within a combo box.
An enumeration is typically defined at the beginning of a file after a comment. A square bracket followed by the text ‘ENUM’ (or, for backwards compatibility, ‘OPTLIST’), any number of subsequent value/string pairs and a terminating close square bracket define an enumeration. For example:
If an enumeration has no entries, anything defined to use it will not use it. This allows an enumeration definition to be undefined (typically for debugging) by placing the ‘]’ after the ENUM:
1;[ENUM], 0,OFF,1,ON,2,UNDEFINEDThis creates an empty enumeration definition in the GIN file in order to maintain the index numbering. This is useful if you are using the legacy index based “ol
Enumerations may be tagged with an identifier to allow name-based lookup by other types. This is highly recommended because it reduces hard coding and eases code maintenance:
1;[ENUM=Troolean,0,OFF,1,ON,2,MAYBE]Type specifiers may be used. Useful if the value cannot be reasonably represented using a 32bit signed integer.
GIN file versions 3.32+:
Normally if the underlying value does not map to a value in the enumeration definition, then the Calibration software will display “-”. It is possible to define this ‘default’ text by including “?” in one of the value entries or as its own entry:
[EQU_ANNOTATION,name,value]
Causes the next item to be given an “_equ” attribute for display of this metadata in the GWv4 descriptions view.
Manual addition of these directives is not recommended – ginmake will automatically insert them during the pre-processing pass of ASM sources. See ticket #1526.
Supported by Ginmake 2.37 and later
[EXTEND,name]
[EXTEND,name,type]
Extend an existing item of the given name and, optionally, type in case of ambiguity.
e.g.
1// [EXTEND,Engine RPM,channel][RENAME,Engine Speed]
Function Tables are supported in v1.12+.
[FUNCTBL, FUEL, <oorlowreal>, <oorhighreal>, <oorlowraw>, <oorhighraw>, <count>, <raw0>, <real0>, <raw1>, <real1>, ...., <rawcount-1>, <realcount-1>]
When defining a parameter, option, table or map, the scalar function is defined as a function table by specifying a name in brackets in the scalar field. For example:
1uint16_t FUELLVL; // [Fuel level,l,(FUEL),,r,+,i,,]
The first label is always FUNCTBL and the name of the function table follows.
The raw (integer) value to which a real value is converted if it is lower than the lowest value in the table (oor meaning Out Of Range).
The raw (integer) value to which a real value is converted if it is higher than the highest value in the table (oor meaning Out Of Range).
The real value to which a raw value is converted when it is lower than any raw value in the table.
The real value to which a raw value is converted when it is higher than any raw value in the table.
The number of entries in the function table and is succeeded by the raw and real values of each entry.
Note that function tables must be continuously increasing or decreasing.
Type specifiers may be used. Useful if the value cannot be reasonably represented using a 32bit signed integer.
Supported by Ginmake 2.04 and later, Gin file version 3.21
This is the same as VALIDRANGE except that values are specified in real (physical) values instead of RAW internal values. Values will be converted to RAW by ginmake and stored in the GIN archive in the same way as VALIDRANGE.
e.g.
1// [Rad Fan 1,,OL3,,o,2,i,,][HARDLIMITS,0,150]
LIMITS and HARDLIMITS can be combined:
1// [LSB_FIRST][PT3,,,,,,f,,,][LIMITS,0.0,100.0][HARDLIMITS,0.0,100.0]
For A2L output, HARDLIMITS sets EXTENDED_LIMITS on calibration objects
(CHARACTERISTIC, AXIS_PTS and AXIS_DESCR). An omitted bound uses the
corresponding data type limit after scaling. VIEWRANGE or LIMITS can independently
set the normal display limits.
A2L does not support EXTENDED_LIMITS on MEASUREMENT objects. Use VIEWRANGE
or LIMITS to set their display limits. Applying HARDLIMITS or VALIDRANGE to a
measurement when generating A2L issues warning W4038. Suppress this warning
independently with -u4038.
Supported by Ginmake 2.37 and later, Gin file version 3.22
[{object}][IDENTIFIER,identifier]
Sets the ‘identifier’ value on the prior object (as in Asam A2L IDENTIFIER)
Supported by Ginmake 2.27.
[IDENTITY,name[,value[,nameN,valueN]]]
Adds additional fields to the ECU identity JSON that is embedded in the GIN file. Multiple key-value pairs can be specified.
Multiple IDENTITY directives may be specified.
e.g.
1// [IDENTITY,GlsVersion,"01V00"]
Indicates the supported GLS (GEMS Logger Setup) version (see GEMS doc 104172)
The JSON is output to a file ‘ginmake.identity.json’.
Ginmake 2.39+
[INCLUDE_A2L,<filename>]
Filename is absolute or relative to the file being processed.
When exporting A2L files, this command shall parse the supplied file (syntactically, not semantically) and then load that DOM directly into the MODULE node being exported.
At present, this will result in loss of formatting / comments from the source file.
There is some possibility that this could result in unwanted conflicts, so some care is needed to avoid that.
Supported by Ginmake 1.75.
[INPUTS,name1[,nameN]]
[OUTPUTS,name1[,nameN]]
List inputs and outputs of this object (e.g. a parameter name that represents the output of a map). This may in future enable automatic Audit graph generation and may also be useful for A2L export. These definitions generate inputs/outputs ATTRIBUTES.
Supported by Ginmake 1.92 and later, Gin file version 3.21
This is the same as VIEWRANGE except that values are specified in real (physical) values instead of RAW internal values. Values will be converted to RAW by ginmake and stored in the GIN archive in the same way as VIEWRANGE – i.e. they will not take into account any dynamic scaling.
e.g.
1// [Rad Fan 1,,OL3,,o,2,i,,][LIMITS,0,150]
or
1// [LSB_FIRST][PT3,,,,,,f,,,][LIMITS,0.0,100.0]
[LITTLEENDIAN]
By default, ECUs are assumed to be big endian. To define an ECU as little endian simply add the line:
..anywhere in the code to be processed. ECUs are always little or big endian and cannot be mixed.
The logging memory size can be specified for gin files of version 3.18 and greater. Often the ECU defines this in a parameter (“Log Size”) which is not available off-line. In the past it has been assumed that the logging memory size is 512*1024 (originally hard coded for AEM) when calculating the run time in GW.
The size can be defined as follows:
1// [LOGGINGSIZE=1024 * 1024]
The value is specified in bytes.
Values can be defined in hex, decimal or binary with appropriate prefixes (0x or $ for hex, 0b or % for binary and no prefix for decimal).
The value may be an expression containing pre-processor symbols (#defines and equates) and can use mathematical symbols (see the “expression evaluation” section for more details).
The value and expression arguments use 64bit integer arithmetic with the final value stored as a 64bit value in the gin file.
Log Maps monitor and store a pre-defined parameter into the map at sites corresponding to those of a base map. For example, a Lambda log map would log the lambda parameter, based upon the fuel map. As the load and speed approach a particular site in the fuel map, the value of lambda is logged into the lambda log map at the corresponding site. As more values of lambda are collected for that site, the site value is averaged out. As engine load and speed changes, the log map is built up to show how lambda changes across the entire load and speed map.
The weight of a site is the number of data points collected to produce the average value. Setting the weighting to a low value (such as zero) will give higher priority to new data coming in. Setting it to a higher value will reduce the priority of new data coming in. This can also be used to initiate auto mapping for selected sites as auto mapping will not start for a site until the weighting has exceeded a certain value.
| Field Name | Definition |
|---|---|
| LOGMAP | This is entered as is, and defines the values as a log map. |
| Name | Name of the log map. |
| Reserved | Leave blank. |
| Map Base | Map Name Reference – This must be provided, and indicates the base map May be left blank |
| Log Parameter | Parameter Name Reference |
| Remove Time (ms) | Integer – Time that a site must be located for before values are logged. |
| Weight Time (ms) | Integer – Time over which a linear significance value is applied to a recorded value. |
| Filter Limit (%) | Integer – Readings that deviate from the most significant recorded value exceeding this percentage will be dropped. |
| Create Mod Map | Boolean – may be 0, 1, ’true’ or ‘false’. Generates an additional map that can be used to enter a desired value for the parameter being logged at a particular map site. This map is used to perform auto mapping. |
| Site Accuracy (%) | Integer – affects the weighting given to recorded values depending upon how close to the centre of a site the current axis positions are. |
| 100% weighting (%) | Integer – affects the shape of the site accuracy filtering. |
| Filter Type | “bell” or “proportional”, defaults to “proportional” |
| Secondary Filter Parameter | (Parameter Name, blank for no secondary filtering) |
| Secondary Filter Minimum | Real – cutoff point for the secondary parameter, below which logging will not take place. |
| Secondary Filter Maximum | real– cutoff point for the secondary parameter, above which logging will not take place. |
| Tertiary Filter Parameter | (Parameter Name, blank for no tertiary filtering) Pls note that this feature is not yet supported in GW and is not stored in v3.15 GIN files. |
| Tertiary Filter Minimum | Real – cutoff point for the tertiary parameter, below which logging will not take place. Pls note that this feature is not yet supported in GW and is not stored in v3.15 GIN files. |
| Tertiary Filter Maximum | real– cutoff point for the tertiary parameter, above which logging will not take place. Pls note that this feature is not yet supported in GW and is not stored in v3.15 GIN files. |
| Max absolute change (+) | specifies the constraints imposed on the change value. When auto mapping is started, GW takes a copy of the base map in its original state. The base map is not changed by more than the absolute or percentage change from its original state. |
| Max % Change (+) | |
| Max absolute change (-) | |
| Max % Change (-) |
Example:
1[LOGMAP,Lambda,,Fuel,Lambda,200,400,10,true,75,25,proportional,,,,,,,10,50,10,50]Generates a Lambda log map. This has the Fuel map as a base, logging against the Lambda parameter. There is no secondary/tertiary parameter filtering in this example.
Supported by Ginmake 2.37 and later, Gin file version 3.22
Sets the ’long identifier’ value on the prior object (as in Asam A2L LONG_IDENTIFIER)
Supported by Ginmake 1.33 and later, GIN file version 3.23.
Used to define additional, arbitrary ‘meta’ information in the GIN file.
Ideally, this should take the format:
[META,name,other stuff..n]
Valid definitions:
Gives a human readable name for the CAN channel
[META,CAN_CHANNEL_NAME,1,Vehicle CAN]
[META,CAN_CHANNEL_NAME,2,Engine CAN]
Identifies pages in the page table that can be read even when the ECU is secured.
This allows users access to some ECU areas whilst keeping other areas of the calibration locked.
[META,UNSECURE_PAGES,0]
[META,UNSECURE_PAGES,1,3,4]
Page numbers start at ZERO.
Indicates the type of internal logging format. See GEMSCOM protocol specification for more details on the types of logs. This meta tag will affect the internal logging setup dialog.
[META,LOG_TYPE,linear]
[META,LOG_TYPE,normal]
[META,LOG_TYPE,v0.06]
[META,linear_log] - equivalent to [META,LOG_TYPE,linear]
[META,HAS_CAN_TELE_FIXED_VALS]
[META,HAS_SERIAL_TELE_FIXED_VALS]
These flags indicate that CAN telemetry and Serial Telemetry, respectively, can have ‘fixed’ values in the list of options. Fixed values insert fixed byte values into the output stream. Fixed values are identified by comcodes with the top byte set to 0x7F.
e.g. 0x7F23 instead of an actual parameter comcode would output 0x23 at the specified telemetry stream position.
By specifying these flags, GWv4 will identify fixed values and will additionally add a method for entering fixed values.
[META,BLOB,<type>,<index>,<max_size>];
Identifies that there is a blob (binary large object) of a particular type. Each blob must have a unique index number (used by the protocol for reading & writing blobs) and a maximum size, in bytes. Type names prefixed ‘gems_’ are reserved and must be specified in this document.
e.g.
[META,BLOB,gems_log_setup,0,262144];
Note that blobs are required to contain the size of the data as a 4-byte little-endian integer at the start of the blob. If this value is 0 or FFFFFFFF then the blob is considered as being empty.
gems_log_setup Setup file for ‘full featured’ internal data logger setups.
[META,BLOB_RW_SIZE,<[connection]>,<max_read_size>,<max_write_size>];
Indicates the maximum size that may be read/written in a single blob read/write gemscom command (see GEMSCOM protocol specification document).
The size identified is the maximum number of bytes that may be in the data portion of the command, excluding the command header/checksum overhead.
The
Indicates that coprocessor firmware can be uploaded to this ECU.
Note that the coprocessor .bin file must contain a string that says:
“GEMS FIRMWARE”, followed by the name/version of the firmware which will be presented to the user.
Indicates that this GIN file is for a CoPro bootloader firmware image.
Alternatively, if the ECU name ends with ‘CPB’ then the GIN is considered as being CoPro bootloader.
Indicates that this product has a minimum CoPro firmware version recommendation. This is not a hard requirement but GW may indicate to the user that an upgrade of the CoPro firmware is recommended.
Set to ‘1’ to explicitly enable comms read/write optimizations. Set to ‘0’ to disable them.
Some ECUs have bugs that mean that joining adjacent reads together to reduce bandwidth can result in incorrect data being read from the ECU due to the CoPro using internal byte-swapping.
This was fixed in EM80_M but there are many versions of EM80/GDI80 CoPro etc in the field that have this bug.
GWv4 will automatically disable read optimizations on EM80, GDI80 unless the CoPro version is >= 02x01.
Affected ECUs:
For new ECUs that use lower versioned CoPro that does not have this issue, explicitly set COMMS_READ_OPTIMIZE / COMMS_WRITE_OPTIMIZE to ‘1’ in the GIN file.
Ginmake 2.39+. When exporting A2L format ECU definition file, this inserts ECU_ CALIBRATION_OFFSET into the MOD_PAR section.
Ginmake 2.39+. When exporting A2L format ECU definition file, this inserts EPK into the MOD_PAR section.
e.g.
[META,EPK,{REV_NAME}{REV_VERSION}]
Ginmake 2.39+. When exporting A2L format ECU definition file, this inserts ADDR_EPK into the MOD_PAR section.
There is an alternative to using this META string and that is to define an EPK ECU_STRING. If defined, the address of the EPK ECU_STRING object shall be used.
If defined, causes GEMS Reflash tool to disable the ‘clear’ calibration option for this ECU & not perform a pre-clear.
Indicates that a reflash of the firmware will reset the calibration to default values. May simplify the user-interface flow when reflashing + reprogramming ECUs.
A2L: Populates Version field of MOD_PAR section in A2L file.
A2L: Populates name of MODULE in A2L file. If not specified the ECU name is used (i.e. REV_NAME).
A2L: Populates long identifier field of MODULE in A2L file. If not specified, the generated ECU Identity display name / version (REV_VERSION or Virtual Version) is used.
Supported by Ginmake 1.41 and later, GIN file version 3.23.
Adds meta data from a file. This is generally used for output pin configuration files:
[METAFILE,pin_config,aem25_pin_config.xml]
See the X25 source code for an example XML file. This enables ‘Configure Outputs’ on GWv4.
Endian Directives cause the next item to have the given endian mode applied.
[MSB_FIRST] (big endian)
[LSB_FIRST] (little endian)
e.g.
1uint16_t value; // [MSB_FIRST][Value,,,,,,,,,]
[MIN_VERSION,<version>]
Specify a minimum ginmake version to interpret this file, e.g. [MIN_VERSION, 2.22.0.0]. If minor revisions are not specified, they will be assumed to be 0, e.g. 2.22 = 2.22.0.0. An error will be issued if the current ginmake version is lower than the minimum.
Note: This feature was only added in version 2.22 so the directive will not be recognised for earlier versions of Ginmake. Instead, you can use the pre-processor code below to enforce a minimum Ginmake version.
Added in version 2.24
[PACK_PUSH,align]
...
[PACK_POP]
Pushes the current alignment (default is 4) onto a stack and sets ‘align’ as the current packing / alignment value.
Pushes the prior alignment value from the stack and sets it as the current packing / alignment value.
Note: in ginmake 2.19+. page tables can be avoided through using a combination of SEGMENT and SEGMENT_ADDRESS definitions.
A file containing a page table may be referenced in a header file using either PAGETBL or PAGETBLV2:
[PAGETBL=COMS.ASM]
[PAGETBLV2=COMS.ASM]
PAGETBL indicates an old-style page table and is present in most existing code. This is now restricted to 32 entries (to catch errors when upgrading to the extended comms protocol) and should have contiguous a EEROM segment. This version of page table allows ROMBS to be used as EEROM in ASM code if it directly follows the EEROM data.
PAGETBLV2 indicates that the page table should be handled differently by Ginmake and is intended for use with the extended comms protocol. PAGETBLV2 does NOT allow ROMBS to be used for calibration data. With PAGETBLV2 it is possible to have breaks in the EEROM data so that parameters and/or ROMBS may be inserted in the middle of the EEROM data without being a part of the calibration. This is generally required when using the extended protocol because the header information must still reside in page 0x1F (i.e. a read of 0xDF 00 using the 13 bit protocol). If splits exist in EEROM, multiple regions will be added to the calibration data with a single checksum added at the location of CHKLOC or CRCLOC. All regions are summed up to the location of the checksum.
Objects such as maps and tables are not allowed to span region boundaries. Ginmake will emit errors in such situations and suggest padding values.
Also see section on SEGMENT definitions for multi-region calibrations / parameter spaces.
Parameter tables are similar to tables but use live parameter data to fill the table.
A parameter table is defined with a name, axis start and offset labels, an optional axis parameter to determine the current site and a list of parameters defining the value at each site.
A parameter table is defined as follows:
| Field Name | Definition |
|---|---|
| PARAMTBL | This is entered as is and defines the values as a parameter table. |
| Name | Defines the name of the parameter table. This is displayed in selection menus and at the top of the table when displayed. |
| Axis Parameter | This is the name of the parameter used for the axis of a table (or x axis of a map). In some tables (e.g. battery compensation table) the parameter is used to determine the current position in the table. In others (e.g. speed table) the parameter is used by the maps that use the table as their axis. This name may also be the name of a table used for the axis of a table or map (as referred to in the speed table example). Note tables take precedence over parameters. You should avoid duplicating names of parameters, options and tables for values that are referenced by this field. If such a conflict exists, Ginmake will warn you. |
| Axis Units | The units for the axis (or x axis of the map). (May also be user scalar units as per field 2.). Defaults to an empty string. |
| Start | The axis value of the first step. This is an integer value. If preceded by a ‘*’ the subsequent real value is the first step value. Defaults to 0. Alternatively, this may be the name of an option if a table has not been used for the axis parameter. The name may optionally be placed in brackets. |
| Offset | The offset of each subsequent axis site from the start axis value. This is an integer value. If preceded by a ‘*’ the subsequent real value is the offset. Defaults to 1. Alternatively, this may be the name of an option if a table has not been used for the axis parameter. The name may optionally be placed in brackets. |
| Parameter[1] | Defines the parameter used to determine the value of the first site. This is followed by the names of the parameters defining the subsequent site values. Ginmake 1.78+ May also use a range expression here. There are 2 possible formats 1) A range of parameters separated by an ellipsis, which will include all parameters in declaration order between (and including) the start and end values given. <param[1]>…<param[N]> e.g. TPER00…TPER31 2) A printf style format expression, preceeded by an ellipsis, the bounds for the expanded range are placed in the next two fields following this field. e.g. [PARAMTBL, |
| Parameter[2] | [Optional] Second parameter in the table. |
| Parameter[n] | [Optional] Nth parameter in the table. |
Profiles are supported in version 3.17 Gin files.
Syntax:
1[PROFILE,<profile name>]A profile generates a tag that is referenced by other objects in the GIN file. The profile can be used to hide various objects from the user.
The objects may be shown to the user by toggling an option in GW. The option will be labelled with the name provided in the PROFILE definition.
Profiles can be applied to options, tables, parameters and maps in the read/write field.
See also: Option, Parameter, Table and Map definitions, Read/Write field
Supported by Ginmake 1.44 and later, GIN file version 3.24 or later.
[PROTOCOL, <type> {,<MAX_READ> {,<MAX_WRITE>}} ][PROTOCOL:<conn>, <type> {,<MAX_READ> {,<MAX_WRITE>}} ]
1#define MAX_READ_USB 256
2#define MAX_WRITE_USB 4
3
4// [PROTOCOL GemsExtended, 2, 2]
5// [PROTOCOL:LIBUSB, GemsExtended, MAX_READ_USB, MAX_WRITE_USB]
‘conn’ refers to the connection type to which to associate the protocol. If this field is not supplied, then the default protocol is defined. See [CONNECTION].
’type’ may be one of: Gems13bit [Existing protocol] GemsExtended [Extended address/size protocol]
‘MAX_READ’[optional]: Maximum number of data bytes that can be requested from the ECU in a single read command. Default is 2.
‘MAX_WRITE’[optional]: Maximum number of data bytes that can be written to the ECU in a single write command. Default is 2 for connection specific protocols and 1 for the default protocol (can be set directly or overridden with [WORDWRITES] which sets this to ‘2’).
See the Gemscom Protocol Specification for more details on the protocol implementations.
It is perfectly legal to specify different protocol types for different connections which aids the development process - the code in the ECU can be more gradually converted over to use newer protocols. Additionally, there may be different hardware buffering constraints for different connection types.
Supported by Ginmake 2.37 and later.
[RENAME,new_name]
Renames the prior definition. If appropriate, the existing name will be added to the front of the old names list.
Supported by Ginmake 1.61
[SEGMENT,<mem_type>,<name>,<symbol_name>{,<checksum_name>,<checksum_type>}]
Defines segments that should be used by the page table and address assignment.
Segment definitions must precede the page table (PAGTBL or PAGETBLv2). Additionally, the definitions must precede the checksum locations.
Parameter Description
| <mem_type> | Describes the type of memory. One of: nvm: Non volatile memory (i.e. Calibration memory – options/maps). ram: Parameter memory (e.g. parameters, parameter tables). rom: Readonly memory (e.g. ECU header at DF00). |
| Name of the segment. There should be a #define that equates to its address that is used during page table processing. e.g. EEROM, RAMBS etc. | |
| <symbol_name> | Name of the symbol used for the storage attribute to in the C source code. For ASM compilations, this field is for segment lookups e.g. EEROM. The symbol name is case insensitive for historical reasons. e.g. idata, near (legacy names from X25 code). uint16_t near option_variable; // [Option X, …] This may use a #define that is not visible to ginmake code: e.g. #ifndef GINMAKE #define GXGRAM #endif uint16_t GXGRAM option_variable; // [Option X, …] |
| <checksum_name> | Name of region checksum variable. Optional. |
| <checksum_type> | Type of region checksum. Possible values: additive crc16 next_region [default] none |
Defaults
Unless specified, segments are defined by default that are equivalent to the following:
Tip
For unused pages in the page table, you can create an unused area:
// [SEGMENT,rom,NOT_USED,__not_used]
The page table file should define the physical addresses of the various segments using #define statements.
e.g.
1const uint16_t near wpagetbl[32] = {
2RAMBS, // $00 Parameters start here (0x2000)
3RAMBS + 0x100, // $01
4RAMBS + 0x200, // $02
5RAMBS + 0x300, // $03
6RAMBS + 0x400, // $04
7RAMBS + 0x500, // $05
8RAMBS + 0x600, // $06
9RAMBS + 0x700, // $07 Parameters end here (0x27FF)
10RAMBS + 0x800, // $08
11RAMBS + 0x900, // $09
12RAMBS + 0xA00, // $0A
13RAMBS + 0xB00, // $0B
14RAMBS + 0xC00, // $0C
15RAMBS + 0xD00, // $0D
16EEROM, // $0E Options start here (0x3000)
17EEROM + 0x100, // $0F
18EEROM + 0x200, // $10
19EEROM + 0x300, // $11
20EEROM + 0x400, // $12
21// etc..
In ASM code, the page table is similar to that in C compilation. In ginmake versions prior to 2.07.00, it was not possible to define custom segments that were larger than a single page and additionally all EEROM based sections would be merged into a single Region in the GIN file.
The situation has now changed in 2.07.00 and [SEGMENT] definitions are handled.
There are defaults applied in the absence of any SEGMENT definitions:
If the EQU name starts with EEROM then interpreted as NVM. Checksums will be set to ‘InNextRegion’ until chkloc or crcloc is seen.
ROMBS will be a ROM section and must start at page 0x1F.
Anything else will be RAM by default unless a SEGMENT definition overrides that.
e.g.
1;[LSB_FIRST][SEGMENT,nvm,COPROPT2,COPROPT2,,none]
2COPROPT2 EQU $7800
3ifdef __GINMAKE__
4segment 'COPROPT2'
5endif
6// data in segment 'COPROPT2'pagetbl.asm entries parse the labels and discard the value after the ‘+’. It is expected that entries are contiguous for a given segment name.
Ginmake 2.39+
Since version 2.39, segments may have ATTRIBUTES specified. These attributes allow fine-tuning of the output when generating A2L files.
| Attribute | Meaning |
| NO_A2L | Do not export the segment in the A2L file |
| PrgType | Set the PrgType field of A2L MEMORY_SEGMENT. Possible values: CALIBRATION_VARIABLES, CODE, DATA, EXCLUDE_FROM_FLASH, OFFLINE_DATA, RESERVED, SERAM, VARIABLES, |
| MemoryType | Set the MemoryType field of the A2L MEMORY_SEGMENT. Possible values: EEPROM, EPROM, FLASH, RAM, ROM, REGISTER, NOT_IN_ECU, |
| Attribute | Set the Attribute field for the A2L MEMORY_SEGMENT. Possible values: INTERN, EXTERN, |
| XCP_CHECKSUM | Set the CHECKSUM field of the XCP IF_DATA on the MEMORY_SEGMENT. |
| ADDRESS_MAPPING | Set the ADDRESS_MAPPING block of the XCP IF_DATA on the MEMORY_SEGMENT. This attribute is a semicolon separated list of integer values source, dest, size for the address re-mapping values. |
| SECTOR | Sector number (XCP IF_DATA of MEMORY_SEGMENT) |
| NUM_PAGES | Number of Pages (XCP IF_DATA of MEMORY_SEGMENT) |
| ADDRESS_EXTENSION | Memory address extension value (XCP IF_DATA of MEMORY_SEGMENT) |
| COMPRESSION_METHOD | Compression Method, relates to PGM commands (XCP IF_DATA of MEMORY_SEGMENT). This is an 8 bit unsigned integer, the host does not do anything with this value. |
| ENCRYPTION_METHOD | Encryption Method, relates to PGM commands (XCP IF_DATA of MEMORY_SEGMENT). This is an 8 bit unsigned integer, the host does not do anything with this value. |
Supported by Ginmake 2.19+
[SEGMENT_ADDRESS,<segment_name>,<gemscom_address>,<size>[,<physical_address>[,gcc_section]]]
Defines address / size of a segment previously defined by a SEGMENT definition. This removes the need for PAGETBL / PAGETBLv2 – memory segments can be defined purely with SEGMENT and SEGMENT_ADDRESS since ginmake 2.19. This is preferable for code that does not use a page table for gemscom address translation.
Parameter Description
| <segment_name> | Name of the segment to match that in its SEGMENT definition |
| <gemscom_address> | Address of the segment used over the gemscom protocol. This is a virtual address and is remapped by the ECU to a physical address. |
| Size of the segment, in bytes. At time of writing, GWv4 will read/write entire calibration (NVM) segments. | |
| <physical_address> | Optional physical address of the segment from the perspective of the target computer (the ECU). This may be useful for diagnostic purposes in future. |
| <gcc_section> | Section name used by linker for this segment that will appear in the GNU linker map file. |
Example
An example of using SEGMENT and SEGMENT_ADDRESS to define memory segments without needing a page table (PAGETBL / PAGETBLv2).
1// [LSB_FIRST][SEGMENT,ram,Measurements,SEG_RAM,,none]
2// [LSB_FIRST][SEGMENT,nvm,Calibration,SEG_NVM,,none]
3// [LSB_FIRST][SEGMENT,rom,Identity,SEG_ROM,,none]
4// [SEGMENT_ADDRESS,Measurements,0x0000,0x0100,.modelData]
5// [SEGMENT_ADDRESS,Calibration,0x0100,0x1E00,0x20009000,.modelDataNVM]
6// [SEGMENT_ADDRESS,Identity,0x1F00,0x0100,0x2000F000]
Supported by Ginmake 2.19+
[SEGMENT_BEGIN,<segment_name>]
Start a segment section. This allows C code to avoid placing a segment location on variables defined between SEGMENT_BEGIN and SEGMENT_END. Or particular use if C style structs are used to define the memory of a region.
Segments may not be nested.
Parameter Description
| <segment_name> | Name / symbol of the segment to match that in its SEGMENT definition |
Example
Supported by Ginmake 2.19+
[SEGMENT_END,<segment_name>]
Closes segment opened with SEGMENT_BEGIN.
Parameter Description
| <segment_name> | Name / symbol of the segment to match that in its SEGMENT definition |
Example
[SIZEOF,n]
Causes the base size of the next defined object to be reinterpreted.
For example, if there is a byte value defined:
1USERMSG1 DS.B 1 ;[User Message1,,,,r,,,,H,]A 16bit alias may be added that also spans the next byte:
Following use of the sizeof override to create an object, the override is reset. The override also does not survive until the next source code definition (e.g. the next DS.B).
Added in version 2.65.
Add / change the prefix used for generated Simulink signal name. For builds using XCU API, signals are prefixed with XCU_ by default. Specifying [SL_PREFIX,] overrides the default, removing the prefix, which can be useful for legacy name mappings (e.g. EM80M compatibility layer).
This is a post-fix directive and may be used on any object that may be used to generate a signal.
Additionally, the directive may be used as a post-fix on [SEGMENT] to apply the prefix to an entire memory segment.
Added in version 2.24
Instantiate a struct. The struct being instantiated must currently be included within a STRUCT_BEGIN / STRUCT_END block.
[STRUCT,name]
As of ginmake 2.24, simple struct typedefs are parsed.
As of ginmake 2.41, if the name ends with a ‘#’ character, it shall synthesize names in the format ’name #NNn member’, instead of using array syntax ’name[N].member’. If the name ends with ‘#.’, then the format will be dotted, e.g. ’name_#NNn.member’.
As of ginmake 2.45, struct identifier numbering syntax was extended to allow starting at indices other than 0 by specifying a number before the #.
e.g.
[STRUCT,MyStruct1#] will start numbering at 1
[STRUCT,MyStruct2#] will start numbering at 2.
Currently, it is necessary to use the typedef name of the struct as the data type in other structures – the ginmake C parser is currently quite limited.
Structs that you intend to instantiate through the STRUCT directive should not have their definition within a SEGMENT_BEGIN / SEGMENT_END section.
Structs can contain members that do not have ginmake comments. These are not accessible via the GIN file but their size and alignment will be taken into account when computing the structure size and alignment. Alignment can be controlled with PACK_PUSH / PACK_POP.
The ’name’ field is used as a prefix for the names within the struct. The struct member names are appended to the prefix and separated by a dot character.
Arrays are also supported. The array will be un-rolled and the names will include the array index, starting at zero.
typedef struct CAL_track_struct
{
1int32_t lon; // [Longitude,(GPS Coord Units),,,o,-,f,,]
2int32_t lat; // [Latitude,(GPS Coord Units),,,o,-,f,,]
3uint16_t course; // [Course,(GPS Course Units),,,o,,f,,]
4uint16_t width; // [Width,(Track Width Units),,,o,,f,,][DESCRIPTION,If this value is zero then the track entry is disabled.]
5} CAL_track;
6typedef struct CAL_data_nvm_struct{
1// [SEGMENT_BEGIN,CAL_SEG_NVM]
2CAL_track tracks[CAL_TRACK_COUNT]; // [STRUCT,Track][ATTRIBUTES,gps_start_line]
3// crcloc must be at the end!
4uint16_t crcloc; // specially handled by ginmake - region checksum
5// [SEGMENT_END,CAL_SEG_NVM]
6} CAL_data_nvm;This would produce items in the calibration along the following lines:
Track[0].Longitude Track[0].Latitude Track[0].Course Track[0].Width
Track[1].Longitude Track[1].Latitude Track[1].Course Track[1].Width
Track[2].Longitude Track[2].Latitude Track[2].Course Track[2].Width …
[TYPEDEF_SIZE,name,size,[align]]
Introduces a type name to the C parser. Used for e.g. structs to declare their size for ginmake.
‘align’ is optional as of Ginmake 2.24.0 and is the alignment value of the structure. If elided then the default alignment value is used (see PACK_PUSH / PACK_POP).
Unit definitions allow additional units to be specified by this ECU definition file that are not in the list of predefined units (See Units and Quantities).
| Field Name | Definition |
|---|---|
| UNIT | This is entered as is and defines the values as a unit definition. |
| Name | Defines the name of the unit. If blank, this is the same as the unit ID’s unit name. |
| Unit ID | Defines the unit ID of this unit. e.g. afr:AFR Ammonia for Air Fuel Ratio This MUST include the quantity ID of the unit and the unit identifier. |
| Display Unit | The display unit. If blank, this is the same as the unit IDs unit name |
| Aliases | Semicolon separated list of aliases used for lookups. E.g. km/h might have an alias ‘kph’. |
| M | Defines the default scalar. Defaults to 1. This value indicates the linear conversion from the relative unit to convert from a value in the relative unit to this one. For example, if defining kilograms relative to grams, then the scaling factor would be 0.001. |
| C | Defines the default offset. Defaults to 0. As with ‘M’ this is the offset from the relative unit being derived from. |
| Relative To | Unit ID of the unit that this unit is derived from. If not given, the scaling is relative to the reference ‘unity scaled’ (root) unit for the given quantity. A quantity must always have a ‘root’ unit. The quantity does not need to be provided here – derived units may only belong to the same quantity as the unit they are relative to. If the quantity is given it will be checked. |
Example:
1// [UNITQUANTITY,CPU Power,cpu_power][DESCRIPTION,CPU Processing Power]
2// [UNIT,FLOPS,cpu_power:flops,FLOPS,,,,][DESCRIPTION,Floating Point Ops / Second]
3// [UNIT,Kilo FLOPS,cpu_power:kflops,KFLOPS,kiloflops,0.001,0,cpu_power:flops]
4// [UNIT,Mega FLOPS,cpu_power:mflops,MFLOPS,megaflops,0.001,0,cpu_power:kflops]
5// [UNIT,Giga FLOPS,cpu_power:gflops,GFLOPS,gigaflops,0.001,0,cpu_power:mflops]
6// [UNIT,Tera FLOPS,cpu_power:tflops,TFLOPS,teraflops,0.001,0,cpu_power:gflops]
7// [UNIT,Peta FLOPS,cpu_power:pflops,PFLOPS,petaflops,0.001,0,cpu_power:tflops]
8// [UNIT,Exa FLOPS,cpu_power:eflops,EFLOPS,exaflops,0.001,0,cpu_power:pflops]
Defines a custom unit quantity to be added to the set of predefined units for this GIN file (See Units and Quantities). If a unit quantity is defined and there is a predefined quantity of the same ID then the defined quantity will replace the predefined one.
Unit quantities must always include a ‘root’ unit; root units are those that have unity (‘identity’) scaling where m = 1 and c = 0 in the linear scaling function f(x) = m.x + c.
| Field Name | Definition |
|---|---|
| UNITQUANTITY | This is entered as is and defines the values as a unit quantity definition. |
| Name | Defines the name of the unit. |
| Identifier | Defines the ID of this quantity as used in unit IDs. |
User scalars allow the units, scalar and offset to be defined by the user within GW. By specifying the units (including table axis units and map x and y axis units) as a name in brackets (e.g. ‘(load)’) a user scalar is created with the appropriate name (if necessary) and assigned to the type.
Since GIN version 3.33, DELETE
Supported by Ginmake 2.38 and later.
1[DELETE,name[,type]]Extend an existing item of the given name and, optionally, type in case of ambiguity.
e.g.
DESCRIPTION, ALIAS
Ginmake 2.62+
1[ALIAS,name,alias_name[,type]]Clone object named ’name’ of type ’type’ with new name ‘alias_name’. Type field is optional.
Note that for more control, the following is now also possible in ginmake 2.62+, to create a new object at the same location as the EXTEND item:
// [EXTEND,TIC 01 Time][TC1,,,,r,+,i,,,]
ATTRIBUTES are supported on USERSCALAR / OPTUSERSCALAR.
The actual parameters of the user scalar are defined using the following methods for fixed value scalars and offsets and option user scalars:
1;[USERSCALAR,<name>,<units>,<FP?>,<format>,<m>,<c>]
2;[OPTUSERSCALAR,<name>,<units>,<FP?>,<format>,
3; <scalaroptname>,<sm>,<sc>,<s\*or/>, <offsetoptname>,<om>,<oc>,<o\*or/>, <chainoptname>]If a value uses a user scalar, the scaled value is calculated using the function:
scaled = raw value * m + c
Scaled values of option user scalars are detailed below the table.
For the user scalar definition, the fields are defined as follows:
| Field Name | Definition |
|---|---|
| USERSCALAR | This is entered as is and defines the values as a user scalar. |
| Name | Defines the name of the user scalar as seen in the user selectable units in GW and AEMPro. Must be specified and match an existing user scalar. If the name is prefixed with ‘!’ then the user scalar will be hidden from units configuration. Supported in GIN version 3.33, GWv4.03.45. |
| Units | Defines the default units used by values assigned with the user scalar. Defaults to an empty string. A unit quantity may also be specified by using a colon ‘:’ character with the quantity before the colon and unit afterwards. See 9 The quantity should be the ‘script name’ for the quantity. Also, the script name for the unit can be used when a quantity is specified. e.g. afr:LA for Air Fuel Ratio : λ If the unit’s field is encapsulated in O[…], this refers to an option that has an enumeration defining the units. The enumeration must only contain the names of user scalars that will become a dynamic chained user scalar. |
| FP? | Defines whether the default scaled value uses floating-point. A ‘y’ or ‘Y’ indicates floating-point. Defaults to integer. |
| Format | Defines the default format used by the default user scalar. Defaults to an empty string. |
| M | Defines the default scalar. Defaults to 1. |
| C | Defines the default offset. Defaults to 0. |
For the option user scalar definition, the fields are defined as follows:
| Field Name | Definition |
|---|---|
| OPTUSERSCALAR | This is entered as is and defines the values as an option user scalar. |
| Name | Defines the name of the option user scalar as seen in the user selectable units in GW and AEMPro. Must be specified and match an existing user scalar. If the name is prefixed with ‘!’ then the user scalar will be hidden from units configuration. Supported in GIN version 3.33, GWv4.03.45. |
| Units | Defines the default units used by values assigned with the user scalar. Defaults to an empty string. A unit quantity may also be specified by using a colon ‘:’ character with the quantity before the colon and unit afterwards. See 9 The quantity should be the ‘script name’ for the quantity. Also, the script name for the unit can be used when a quantity is specified. e.g. afr:LA for Air Fuel Ratio : λ If the unit’s field is encapsulated in O[…], this refers to an option that has an enumeration defining the units. The enumeration must only contain the names of user scalars that will become a dynamic chained user scalar. Dynamic units will override the chained user scalar, if defined. |
| FP? | Defines whether the default scaled value uses floating-point. A ‘y’ or ‘Y’ indicates floating-point. An empty or other value indicates otherwise. Defaults to integer. |
| Format | Defines the default format used by the default user scalar. Defaults to an empty string. |
| Scalaroptname | Defines the name of the option used in the scalar. If the field is blank the scalar is not option scaled. |
| sm | Defines the scalar multiplier. If no scalar option is defined this value is used as the scalar multiplier. Defaults to 1. |
| sc | Defines the scalar offset. If no scalar option is defined this value is unused. Defaults to 0. |
| s*or/ | Defines whether the scalar option is multiplied or dividing into the value of sm. If no scalar option is defined this value is unused. A ‘/’ indicates the scalar option is a divisor. Defaults to multiply. |
| Offsetoptname | Defines the name of the option used in the offset. If the field is blank the offset is not option scaled. |
| om | Defines the offset multiplier. If no offset option is defined this value is used as the offset multiplier. Defaults to 1. |
| oc | Defines the offset. If no offset option is defined this value is unused. Defaults to 0. |
| o*or/ | Defines whether the offset option is multiplied or dividing into the value of sm. If no offset option is defined this value is unused. A ‘/’ indicates the offset option is a divisor. Defaults to multiply. |
| Chainusname | Defines the name of a chained user scalar name. If blank, no user scalar is chained to the option user scalar. If O[…] is used in the unit’s field for dynamic units, it will override the chained user scalar. It can be useful to leave this in if you might need to convert the gin file to an older version. |
If a value uses an option user scalar, the scaled value is calculated using the same function as user scalars, but the values of m and c are calculated using separate functions:
scaled =
If a scalar option is defined the value of m is calculated using one of the functions:
if <s*or/> is set as ‘*’, m =
if <s*or/> is set as ‘/’, m =
else m is set to
The value of c is similarly calculated for its respective fields of
If the offset/scalar option values are zero and division is used, the values are treated as if they were 1.
Some units require calibration through an option user scalar before a meaningful unit can be assigned to it. An example of this is Air Fuel Ratio (AFR).
From GWv4 2.03.45, it is possible to use dynamic chained units in user scalars so that the chosen calibrated units can be stored in the ECU. Prior to this, base unit overrides would need to be stored outside of the ECU, making the calibration less portable.
Multiple interacting elements are required to implement this feature in an ECU definition file:
AFR units that may be selected for this ECU. These user scalars associate a name with a unit ID and are looked up from the AFR_UNIT_LIST enumeration. So that these items do not show up in user unit selection in GW, their names are prefixed ‘!’ to hide them.
1[USERSCALAR,!AFR Not Calibrated,AFR Not Calibrated,y,,,]
2[USERSCALAR,!AFR Lambda,afr:LA,y,,,]
3[USERSCALAR,!AFR Ethanol,afr:AFR Ethanol,y,,,]
4[USERSCALAR,!AFR Methanol,afr:AFR Methanol,y,,,]
5[USERSCALAR,!AFR Gasoline,afr:AFR Gasoline,y,,,]
6[USERSCALAR,!AFR Diesel,afr:AFR Diesel,y,,,]
7[USERSCALAR,!AFR Propane,afr:AFR Propane,y,,,]
8[USERSCALAR,!AFR Hydrogen,afr:AFR H2,y,,,]
9[USERSCALAR,!AFR CNG,afr:AFR CNG,y,,,]Enumeration used for selection of chained user scalar from the AFR Base Units option. This lists the USERSCALAR items that specify the AFR units:
1[ENUM=AFR_UNIT_LIST, 0,AFR Not Calibrated, 1,AFR Lambda, 2,AFR Ethanol, 3,AFR Methanol, 4,AFR Gasoline, 5,AFR Diesel, 6,AFR Propane, 7,AFR Hydrogen, 8,AFR CNG ]Unit scalar, will offer unit conversions if a base unit has been set via AFR Base Units option – the AFR Base Units option is specified here via O[…]:
1[USERSCALAR,AFR Units,O[AFR Base Units],y,,,]Option User Scalar for calibration factors from raw values to an AFR unit. This is chained to the AFR Units user scalar. Option User Scalars do not offer unit overrides in GEMS GW software.
1[OPTUSERSCALAR,AFR,,y,,AFR Scalar,,,,AFR Offset,,,,AFR Units]Calibration Option allowing user to specify the units that AFR is calibrated to:
uint8_t afr_units; // [AFR Base Units,,ol(AFR_UNIT_LIST),,o,,,,]
Calibration Options for the AFR scaling factors:
1int16_t afr_scalar; // [AFR Scalar,,\*0.001,0,o,2,f,,]
2int16_t afr_offset; // [AFR Offset,,\*0.001,0,o,2,f,,]
Example Option using the AFR scaling chain:
Supported by Ginmake 1.25 and later, Gin file version 3.21
Objects may be supplied with default values. For many objects, it is acceptable that they are initialized to zero. For others it is not so good (can result in damaging behaviour from the ECU).
Default values can be specified in one of two ways:
1[VALUES={1, 2, 8, 16, 5}]1[VALUES=10]
2[VALUES=@8u:0xFFFFFFFFFFFFFFFF]
3[VALUES=_x \* _y]
4[VALUES=BILINEAR_INTERP(_x, _y, MAPSSTP, MAPLSTP, 10, 100, 80, 255)]The specified values correspond to the raw values that would be expected in the ECU memory.
The VALUES clause must be placed after the object definition that it should be attached to.
Type specifiers may be used. Useful if the value cannot be reasonably represented using a 32bit signed integer.
Initializer lists should have the same number of elements as the underlying object. You may specify a different number, but you will get a compiler warning. You should use column-major ordering:
| 0 | 1 | |
| 1 | 2 | 4 |
| 0 | 1 | 3 |
You would use: [VALUES={1, 2, 3, 4}]
Expressions can contain anything, providing they do not start with a curly brace (otherwise they will be interpreted as an initializer list).
In the above examples, the first and second expressions are simply numbers. This value is copied into all sites of the object.
The third expression uses the special _x and _y symbols. These correspond to the x and y position in the object being filled with data. So in this example, at position (0, 0) you would have a value of (0 * 0) = 0. at position (1, 1) you would have a value of (1 * 1) = 1.
The fourth example uses a function-like macro, which is defined as follows:
1#ifdef __GINMAKE__
2#define LINEAR_INTERP(x, width, x0, x1) (x0 + (x \* (x1 - x0)) / (width – 1))
3#define BILINEAR_INTERP(x, y, width, height, y0x0, y0x1, y1x0, y1x1) \
4 LINEAR_INTERP(y, height, \
5 LINEAR_INTERP(x, width, y0x0, y0x1), \
6 LINEAR_INTERP(x, width, y1x0, y1x1))
7#endifIt uses the _x and _y values to fill a map with the 4 specified corner values 10, 100, 80 and 255. These values are interpolated and is equivalent to the ‘calculate’ function in GW.
Ultimately a binary representation of the object is generated and stored in the Gin file.
Since Ginmake 1.38, it is possible to initialize a value with an address, with optional type discriminator:
Supported by Ginmake 1.24 and later, Gin file version 3.21.
This sets up its preceding object with a range of valid values. This will be used by GW in doing a sanity check on a given calibration and note possible problems.
e.g.
In this example, it suggests that Rad Fan should be in the range 1…255.
The minimum or maximum may be omitted if there’s no limit:
// [VALIDRANGE,1,]
Values are RAW unscaled values.
Type specifiers may be used. Useful if the value cannot be reasonably represented using a 32bit signed integer.
To specify VALIDRANGE in physical (scaled) values, use HARDLIMITS.
In GW 4.03.12+ this is more strongly enforced when setting values and is somewhat equivalent to EXTENDED_LIMITS in A2L files, though not a 1:1 mapping.
For A2L output, VALIDRANGE is exported as EXTENDED_LIMITS on calibration objects,
in the same way as HARDLIMITS, but with raw bounds converted
to physical values (except for enumerations). A2L does not support
EXTENDED_LIMITS on MEASUREMENT objects.
Supported by Ginmake 2.41 and later.
This sets a prefix for all following variable names. Can be useful for disambiguating identifers in A2L export when structures are used.
e.g.
Supported by Ginmake 1.24 and later, Gin file version 3.21
This is similar to VALIDRANGE but sets up a default range for views in the user interface. This can be useful if the range normally used is only a small subset of the total possible range. This is a soft limit – the user may specify values outside of this range. For ‘strong’ limits, use VALIDRANGE or HARDLIMITS.
e.g.
1// [Rad Fan 1,,OL3,,o,2,i,,][VIEWRANGE,1,100]
Values are RAW unscaled values.
Type specifiers may be used. Useful if the value cannot be reasonably represented using a 32bit signed integer.
To specify VIEWRANGE in physical (scaled) values, use LIMITS.
For A2L output, VIEWRANGE sets the object’s lower and upper limits. Raw values
are converted to physical values, except for enumerations, which use raw values.
For example, [VIEWRANGE,-1000,1000] with a *0.1 scalar exports limits of
-100 and 100.
DEPRECATED – use [PROTOCOL] in new code.
Version 1.07 generates v3.10 GIN files that include a word writes flag. The flag can be set by adding a comment in the source containing:
[WORDWRITES]
This allows data to be written two bytes at a time and increases comms performance. Note that word writes are always aligned to word boundaries.
Supported by Ginmake 1.44 and later, GIN file version 3.24.
Embeds an XML description file into the GIN file. See example_descriptions.xml.
[XMLDESCRIPTIONS,<filename.xml>]
The XML description file allows GWv4 to display descriptions about objects within the GIN file. This format file is extensible so that new features may be added to description files and GWv4 without requiring a new version of GIN file.
Example XML file:
Note some of the features here. This follows standard basic XML formatting – if you are unfamiliar, refer to http://www.w3schools.com/xml/default.asp .
The ‘descriptions’ root tag must always be present. Parameters, options, maps etc are referenced via specific tags and the mane attribute is given to identify the specific object. A short description that may show up as a tooltip in some situations in GWv4 can be defined using the ’tip’ attribute. The longer description is plain text within the tag.
Additional references may be present in the description – for example the parameter ‘Bar’ references the parameter ‘Foo’ from its description. GWv4 may show this as a hyperlink or draggable object.
Reference tags differ from the outer tags. And are prefixed with a ‘g’. This avoids overlap with existing HTML tags (param, option and map):
gparam, goption, gtable, gmap etc.
These references are equivalent to HTML anchors:
Which may also be used instead if the display text should be different to the actual name being referenced or if embedding HTML tags inside the link is required.