Option, Channel, Table and Map Definitions

Definitions for these kinds of objects are based upon the number of fields in the definition & do not have a directive name.

Note

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 (), then the item will not be used in conversions. This is useful to prevent problems where aliased items overwrite one another. If the field is preceded with an exclamation mark (!), then the item is hidden in GWv4 (Gin version 3.27+) Any combination of ‘’ and ‘!’ may be used. The field may also include ‘old names’ for the item by appending additional names, separated by semicolons (;). This can reduce the need for aliasing items and additionally hides the old name from the user in GW. For Gin versions 3.28+: A dynamic name option may be specified by adding the name of an option in square brackets. You should also specify a static name for the object. If one is not specified, then the variable name will be used. e.g. [Fuel A[Fuel A Name],…] or [[Fuel A Name]Fuel A,…] This specifies that the ‘Fuel A Name’ option should be used to pick up the dynamic name. The static name is ‘Fuel A’ and this is used in calibration conversions and comparisons. Options used for the selector MUST have an enumeration associated with it, otherwise an error will be issued. The enumeration may have empty items in it that will cause the object to default to its static name.
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.

Channel Comm Codes

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.

Value Formatting

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.