Added annotations

These annotations are needed for understanding on how to extract the correct values for a characteristic from the hex file. More annotations will follow.

Author: asap2Go

a2l/characteristic.go

@@ -8,27 +8,29 @@ import (
 )
 
 type Characteristic struct {
-	Name                    string
-	nameSet                 bool
-	LongIdentifier          string
-	longIdentifierSet       bool
-	Type                    typeEnum
-	TypeSet                 bool
-	Address                 string
-	addressSet              bool
-	deposit                 string
-	depositSet              bool
-	maxDiff                 float64
-	maxDiffSet              bool
-	conversion              string
-	conversionSet           bool
-	lowerLimit              float64
-	lowerLimitSet           bool
-	upperLimit              float64
-	upperLimitSet           bool
-	annotation              []annotation
-	axisDescr               []axisDescr
-	bitMask                 bitMask
+	Name              string
+	nameSet           bool
+	LongIdentifier    string
+	longIdentifierSet bool
+	Type              typeEnum
+	TypeSet           bool
+	Address           string
+	addressSet        bool
+	//Deposit is the identifier of the corresponding record layout
+	Deposit       string
+	DepositSet    bool
+	maxDiff       float64
+	maxDiffSet    bool
+	conversion    string
+	conversionSet bool
+	lowerLimit    float64
+	lowerLimitSet bool
+	upperLimit    float64
+	upperLimitSet bool
+	annotation    []annotation
+	axisDescr     []axisDescr
+	bitMask       bitMask
+	//byteOrder can be used to overwrite the standard byte order defined in mod par
 	byteOrder               byteOrder
 	calibrationAccess       calibrationAccessEnum
 	comparisonQuantity      comparisonQuantity
@@ -287,9 +289,9 @@ forLoop:
 				c.Address = tok.current()
 				c.addressSet = true
 				log.Info().Msg("characteristic Address successfully parsed")
-			} else if !c.depositSet {
-				c.deposit = tok.current()
-				c.depositSet = true
+			} else if !c.DepositSet {
+				c.Deposit = tok.current()
+				c.DepositSet = true
 				log.Info().Msg("characteristic deposit successfully parsed")
 			} else if !c.maxDiffSet {
 				var buf float64

a2l/enums.go

@@ -275,24 +275,32 @@ type typeEnum string
 
 const (
 	undefinedType typeEnum = emptyToken
-	Ascii         typeEnum = asciiToken
-	Curve         typeEnum = curveToken
-	Map           typeEnum = mapToken
-	Cuboid        typeEnum = cuboidToken
-	cube4         typeEnum = cube4Token
-	cube5         typeEnum = cube5Token
-	ValBlk        typeEnum = valBlkToken
-	Value         typeEnum = valueToken
-	derived       typeEnum = derivedToken
-	extendedSi    typeEnum = extendedSiToken
+	//String value in ASCII format.
+	ASCII typeEnum = asciiToken
+	//Curve Datatype of a characteristic is like an array for the y axis plus an axis description on the x axis
+	Curve typeEnum = curveToken
+	//Map defines a two dimensional array
+	Map typeEnum = mapToken
+	//Cuboid defines a three dimensional array mostly represented as an array of Maps
+	Cuboid typeEnum = cuboidToken
+	//The cuboid is stored as an array of maps with incremented or decremented Z coordinates. Rarely used
+	cube4 typeEnum = cube4Token
+	//The CUBE_5 is stored as an array of CUBE_4 with incremented or decremented Z5 coordinates. Rarely used
+	cube5 typeEnum = cube5Token
+	//Value Block is a a array with one, two or up to three dimensions.
+	ValBlk typeEnum = valBlkToken
+	//Value is used in characteristics that only have one value like e.g. "1.0"
+	Value      typeEnum = valueToken
+	derived    typeEnum = derivedToken
+	extendedSi typeEnum = extendedSiToken
 )
 
 func parseTypeEnum(tok *tokenGenerator) (typeEnum, error) {
 	t := undefinedType
 	var err error
 	switch tok.current() {
 	case asciiToken:
-		t = Ascii
+		t = ASCII
 	case curveToken:
 		t = Curve
 	case mapToken:
@@ -321,13 +329,15 @@ type conversionTypeEnum string
 
 const (
 	undefinedConversionType conversionTypeEnum = emptyToken
-	Identical               conversionTypeEnum = identicalToken
-	Form                    conversionTypeEnum = formToken
-	Linear                  conversionTypeEnum = linearToken
-	RatFunc                 conversionTypeEnum = ratFuncToken
-	TabIntp                 conversionTypeEnum = tabIntpToken
-	TabNointp               conversionTypeEnum = tabNointpToken
-	TabVerb                 conversionTypeEnum = tabVerbToken
+	//Identical defines a OneToOne conversion from hex to decimal
+	Identical conversionTypeEnum = identicalToken
+	Form      conversionTypeEnum = formToken
+	Linear    conversionTypeEnum = linearToken
+	RatFunc   conversionTypeEnum = ratFuncToken
+	TabIntp   conversionTypeEnum = tabIntpToken
+	TabNointp conversionTypeEnum = tabNointpToken
+	//Tab Verb is a table to convert numeric values into strings. e.g.: 1 -> "True"
+	TabVerb conversionTypeEnum = tabVerbToken
 )
 
 func parseConversionTypeEnum(tok *tokenGenerator) (conversionTypeEnum, error) {
@@ -358,23 +368,63 @@ type indexModeEnum string
 
 const (
 	undefinedIndexMode indexModeEnum = emptyToken
-	alternateCurves    indexModeEnum = alternateCurvesToken
-	alternateWithX     indexModeEnum = alternateWithXToken
-	alternateWithY     indexModeEnum = alternateWithYToken
-	ColumnDir          indexModeEnum = columnDirToken
-	RowDir             indexModeEnum = rowDirToken
+	/* curves which share a common axis are deposited in columns;
+	each row of memory contains values for all the shared axis curves
+	at a given axis breakpoint.
+	Required in order to represent characteristics which correspond to
+	arrays of structures in ECU program code.*/
+	AlternateCurves indexModeEnum = alternateCurvesToken
+	/*AlternateWithX defines that values of a map are
+	stored in columns and the columns of table values alternate with the
+	respective X-coordinates. A map of format
+	 9 8 7
+	[0 1 2
+	 3 4 5
+	 6 7 8]
+	could be stored within the hex file as an array of format
+	[9,0,3,6,8,1,4,7,7,2,5,8]
+	The order of axis points and table values can be defined differently
+	by the position statement in the FNC_VALUE
+	In case of a curve the values of x-Axis and values alternate.*/
+	AlternateWithX indexModeEnum = alternateWithXToken
+	/*AlternateWithY defines that values of a map are
+	deposited in rows, the rows of table values alternate with the
+	respective Y-coordinates. A map of format
+	9 [0 1 2
+	8  3 4 5
+	7  6 7 8]
+	could be within the hex file as an array of format
+	[9,0,1,2,8,3,4,5,7,6,7,8]
+	The order of axis points and table values can be defined differently
+	by the position statement in the FNC_VALUE
+	Only applicable to maps*/
+	AlternateWithY indexModeEnum = alternateWithYToken
+	/*Column Direction defines that values of a map
+	[0 1 2
+	 3 4 5
+	 6 7 8]
+	are stored within the hex file as an array of format
+	[0,3,6,1,4,7,2,5,8]	*/
+	ColumnDir indexModeEnum = columnDirToken
+	/*Row Direction defines that values of a map
+	[0 1 2
+	 3 4 5
+	 6 7 8]
+	are stored within the hex file as an array of format
+	[0,1,2,3,4,5,6,7,8]	*/
+	RowDir indexModeEnum = rowDirToken
 )
 
 func parseIndexModeEnum(tok *tokenGenerator) (indexModeEnum, error) {
 	im := undefinedIndexMode
 	var err error
 	switch tok.current() {
 	case alternateCurvesToken:
-		im = alternateCurves
+		im = AlternateCurves
 	case alternateWithXToken:
-		im = alternateWithX
+		im = AlternateWithX
 	case alternateWithYToken:
-		im = alternateWithY
+		im = AlternateWithY
 	case columnDirToken:
 		im = ColumnDir
 	case rowDirToken:

a2l/fnc_values.go

@@ -8,17 +8,28 @@ import (
 )
 
 type fncValues struct {
-	//position of table values (function values) in the deposit structure (description of sequence of elements in the data record).
-	position    uint16
-	positionSet bool
+	//Position of table values (function values) in the deposit structure (description of sequence of elements in the data record).
+	Position    uint16
+	PositionSet bool
 	//data type of the table values
-	datatype    dataTypeEnum
-	datatypeSet bool
-	//for characteristic maps, this attribute is used to describe how the 2-dimensional table values are mapped onto the 1-dimensional address space
-	indexMode      indexModeEnum
-	indexModeSet   bool
-	addresstype    addrTypeEnum
-	addresstypeSet bool
+	Datatype    dataTypeEnum
+	DatatypeSet bool
+	//for characteristic maps, curves and value blocks, this field is used to describe how the 2-dimensional table values are mapped onto the 1-dimensional address space
+	IndexMode    indexModeEnum
+	IndexModeSet bool
+	/*addressing of the table values:
+	Enumeration for description of the addressing of table
+	values or axis point values:
+	PBYTE:	The relevant memory location has a 1 byte pointer
+			to this table value or axis point value.
+	PWORD:	The relevant memory location has a 2 byte pointer
+			to this table value or axis point value.
+	PLONG:	The relevant memory location has a 4 byte pointer
+			to this table value or axis point value.
+	DIRECT:	The relevant memory location has the first table value
+			or axis point value, all others follow with incrementing address. */
+	Addresstype    addrTypeEnum
+	AddresstypeSet bool
 }
 
 func parseFncValues(tok *tokenGenerator) (fncValues, error) {
@@ -35,39 +46,39 @@ forLoop:
 			err = errors.New("unexpected token " + tok.current())
 			log.Err(err).Msg("fncValues could not be parsed")
 			break forLoop
-		} else if !fv.positionSet {
+		} else if !fv.PositionSet {
 			var buf uint64
 			buf, err = strconv.ParseUint(tok.current(), 10, 16)
 			if err != nil {
 				log.Err(err).Msg("fncValues position could not be parsed")
 				break forLoop
 			}
-			fv.position = uint16(buf)
-			fv.positionSet = true
+			fv.Position = uint16(buf)
+			fv.PositionSet = true
 			log.Info().Msg("fncValues position successfully parsed")
-		} else if !fv.datatypeSet {
-			fv.datatype, err = parseDataTypeEnum(tok)
+		} else if !fv.DatatypeSet {
+			fv.Datatype, err = parseDataTypeEnum(tok)
 			if err != nil {
 				log.Err(err).Msg("fncValues datatype could not be parsed")
 				break forLoop
 			}
-			fv.datatypeSet = true
+			fv.DatatypeSet = true
 			log.Info().Msg("fncValues datatype successfully parsed")
-		} else if !fv.indexModeSet {
-			fv.indexMode, err = parseIndexModeEnum(tok)
+		} else if !fv.IndexModeSet {
+			fv.IndexMode, err = parseIndexModeEnum(tok)
 			if err != nil {
 				log.Err(err).Msg("fncValues indexMode could not be parsed")
 				break forLoop
 			}
-			fv.indexModeSet = true
+			fv.IndexModeSet = true
 			log.Info().Msg("fncValues indexMode successfully parsed")
-		} else if !fv.addresstypeSet {
-			fv.addresstype, err = parseAddrTypeEnum(tok)
+		} else if !fv.AddresstypeSet {
+			fv.Addresstype, err = parseAddrTypeEnum(tok)
 			if err != nil {
 				log.Err(err).Msg("fncValues addresstype could not be parsed")
 				break forLoop
 			}
-			fv.addresstypeSet = true
+			fv.AddresstypeSet = true
 			log.Info().Msg("fncValues addresstype successfully parsed")
 			break forLoop
 		}

a2l/record_layout.go

@@ -32,7 +32,7 @@ type recordLayout struct {
 	fixNoAxisPtsZ        fixNoAxisPtsZ
 	fixNoAxisPts4        fixNoAxisPts4
 	fixNoAxisPts5        fixNoAxisPts5
-	fncValues            fncValues
+	FncValues            fncValues
 	identification       identification
 	noAxisPtsX           noAxisPtsX
 	noAxisPtsY           noAxisPtsY
@@ -234,7 +234,7 @@ forLoop:
 			}
 			log.Info().Msg("recordLayout fixNoAxisPts5 successfully parsed")
 		case fncValuesToken:
-			rl.fncValues, err = parseFncValues(tok)
+			rl.FncValues, err = parseFncValues(tok)
 			if err != nil {
 				log.Err(err).Msg("recordLayout fncValues could not be parsed")
 				break forLoop