hsk-libs-scripts
270
High Speed Karlsruhe XC878 build scripts
|
This script parses Vector CAN DBs (.dbc files), such as can be created using Vector CANdb++. More...
Functions | |
void | filter329 () |
Initialises globals. More... | |
void | filter439 () |
Strip DOS line endings and make sure there is a new line symbol at the end of the line, so multiline definitions can be parsed. More... | |
void | error (var no, var msg) |
Prints an error message on stderr and exits. More... | |
void | warn (var msg) |
Prints a warning message on stderr. More... | |
void | debug (var msg) |
Prints a debugging message on stderr. More... | |
void | buffer () |
Makes sure $0 is not empty. More... | |
var | fetchStr () |
Special function to fetch a string from the buffer. More... | |
var | fetch (var types) |
Fetch the next token from the input buffer, matching a given type. More... | |
var | whole (var re) |
Returns the expresion with ^ and $ at beginning and end to make ~ match entire strings only. More... | |
var | strip (var str) |
Remove quotes and escapes from strings. More... | |
var | getContext (var str) |
Returns the context type for a string. More... | |
void | getUniqueEnum (var ret, var enum, var val, var desc) |
Generates a unique name for a value table entry. More... | |
void | fsm_discard () |
Discards buffered symbols until an empty line is encountered. More... | |
void | fsm_ecu () |
Parse an ECU definition. More... | |
void | fsm_enum () |
Parse a value table. More... | |
void | fsm_sig_enum () |
Parse a value table bound to a signal. More... | |
void | fsm_env () |
Parse an environment variable. More... | |
void | fsm_env_data () |
Parse the data length count of DATA type environment variables. More... | |
void | fsm_msg () |
Parse a message definition. More... | |
void | fsm_sig () |
Parse a signal definition. More... | |
void | fsm_comment () |
Parse comments. More... | |
void | fsm_attrrange () |
Parse a custom attribute definition. More... | |
void | fsm_relattrrange () |
Parse a custom relation attribute definition. More... | |
void | fsm_attrdefault () |
Parse attribute default value. More... | |
var | fetch_attrval (var attribute) |
Fetches an attribute value of a given type from the read buffer. More... | |
void | fsm_attr () |
Parse an attribute value. More... | |
void | fsm_relattr () |
Parse a relation attribute value. More... | |
void | fsm_symbols () |
Parse the symbol table at the beginning of a .dbc file, bail if unsupported symbols are encountered. More... | |
void | fsm_tx () |
Gets a list of ECUs that transmit a certain message. More... | |
void | fsm_siggrp () |
Gets a signal group. More... | |
void | fsm_start () |
Pick tokens from the input buffer and call the respective parsing functions. More... | |
void | filter1434 () |
This starts the line wise parsing of the DBC file. More... | |
var | euclid (var a, var b) |
Returns the greatest common divider (GCD). More... | |
var | rationalFmt (var n, var d) |
Returns a compact string representation of a rational number. More... | |
var | rationalN (var val, var base, var precision) |
Returns a rational string representation of a real value. More... | |
var | rationalD (var val, var base, var precision) |
Returns a rational string representation of a real value. More... | |
var | rational (var val, var precision) |
Returns a rational string representation of a real value. More... | |
var | filter (var str, var filters, var template) |
Applies filter chains to a given string. More... | |
var | tpl_line (var data, var line, var template) |
Populates a template line with data. More... | |
var | template (var data, var name) |
Reads a template, substitutes place holders with data from a given array and returns it. More... | |
void | setTypes (var array, var bitpos) |
Set the necessary type to be able to shift something to the given bit. More... | |
var | sigident (var sig) |
Returns a unique signal identifier using the sigident.tpl file. More... | |
var | siggrpident (var sg) |
Returns a unique signal group identifier using the sigident.tpl file. More... | |
var | msgid (var id) |
Generates a printable message id be removing the extended bit. More... | |
var | msgidext (var id) |
Tests a message id for the extended bit. More... | |
void | filter1841 () |
Print the DBC files to stdout. More... | |
This script parses Vector CAN DBs (.dbc files), such as can be created using Vector CANdb++.
A subset of the parsed information is output using a set of templates.
The script uses certain environment variables.
Value | Effect |
---|---|
0, "" | Debugging output is deactivated |
1, any string != "" | Debugging output to stderr is activated |
> 1 | Additionally any string read is output |
This variable can be used to pass the template directory to the script.
If the LIBPROJDIR
environment variable is set it defaults to ${LIBPROJDIR}/scripts/templates.dbc2c
, otherwise it defaults to the relative path scripts/templates.dbc2c
.
This can be used to define the date string provided to header.tpl
.
It defaults to the output of the date
command.
Since values in value tables only consist of a number and description, the first word of this description is used as a symbolic name for a given value.
All non-alhpanumeric characters of this first word will be converted to underscores. Redundancies will be resolved by appending the value to the word that signifies the name.
This functionality is implemented in the function getUniqueEnum().
This section describes the templates that are used by the script and the arguments passed to them. Templates are listed in the chronological order of use.
Some of the arguments provided depend on custom attributes:
Template | Argument | Attribute | Object |
---|---|---|---|
sig.tpl | start | GenSigStartValue | Signal |
msg.tpl | fast | GenMsgCycleTimeFast | Message |
msg.tpl | cycle | GenMsgCycleTime | Message |
msg.tpl | delay | GenMsgDelayTime | Message |
msg.tpl | send | GenMsgSendType | Message |
timeout.tpl | timeout | GenSigTimeoutTime | Relation (ECU to Signal) |
These and more attributes are specified by the Vector Interaction Layer.
Templates are arbitrary text files that are provided with a set of arguments. Arguments have a symbolic name through which they can be used. In the following sections they are called fields, because they are provided to the template() function in an associative array.
Inserting data into a template is simple:
<:name:>
The previous example adds the data in the field name
into the file. It can be surrounded by additional context:
#define <:name:> <:value:>
If name
is "FOO_BAR" and value
is 1337, this line would be resolved to:
#define FOO_BAR 1337
It may be desired to reformat some of those values. A number of special filters (see filter()) as well es printf(3) style formatting is available. E.g. name
can be converted to camel case and value
to hex:
#define <:name:camel:%-16s:> <:value:%#x:>
The output would look like this:
#define fooBar 0x539
An important property of templates is that arguments may contain multiple lines. In that case the surrounding text is preserved for every line, which is useful to format multiline text or lists. This can be used to create lists or provide visual sugar around text:
+----[ <:title:%-50s:> ]----+ | <:text:%-60s:> | +--------------------------------------------------------------+
Output could look like this:
+----[ Racecar by Matt Brown ]----+ | 'Racecar - Searching for the Limit in Formula SAE' | | is available for download from: | | http://www.superfastmatt.com/2011/11/book.html | +--------------------------------------------------------------+
Multi line data is treated as an array of individual lines. Besides descriptions in DBC files multiline data can also originate from lists provided by this script in order to allow describing the relations between ECUs, messages, signals etc..
In some cases it is prudent to print lines conditionally. For that conditionals are provided:
<?name?>
If the reverenced field evaluates to true
, the conditional is removed from the line. If it evaluates to false
, the entire template line is omitted.
Used once with the following arguments:
Field | Type | Description |
---|---|---|
date | string | The current date |
db | string[] | A list of identifiers for the parsed DBCs |
Used for each input file with the following arguments:
Field | Type | Description |
---|---|---|
db | string | An identifier for this input file |
file | string | The file name |
comment | string[] | The comment text for this CANdb |
ecu | string[] | A list of ECUs provided with this file |
This template should only contain a single line that produces a unique identifier string for a signal, using the following arguments:
Field | Type | Description |
---|---|---|
msg | int | The message ID |
msgname | string | The message name |
sig | string | The signal name |
Signal names are not globally unique, thus an identifier must contain a message reference to avoid name collisions.
Used for each ECU with the following arguments:
Field | Type | Description |
---|---|---|
ecu | string | An identifier for the ECU |
comment | string[] | The comment text for this ECU |
db | string | The input file identifier |
txid | int[] | A list of message IDs belonging to messages sent by this ECU |
txname | string[] | A list of message names sent by this ECU |
rx | string[] | A list of signals received by this ECU |
rxid | string[] | A list of unique signal identifiers received by this ECU |
Used for each message with the following arguments:
Field | Type | Description |
---|---|---|
msg | int | The message ID |
name | string | The message name |
comment | string[] | The comment text for this message |
sig | string[] | A list of signal names contained in this message |
sigid | string[] | A list of signal identifiers contained in this message |
ecu | string | The ECU sending this message |
ext | bool | Message ID is extended |
dlc | int | The data length count |
cycle | int | The cycle time of this message |
fast | int | The fast cycle time of this message |
delay | int | The minimum delay time between two transmissions |
send | string | The send type (cyclic, spontaneous etc.) |
sgid | string[] | A list of signal group ids |
sgname | string[] | A list of signal group names |
Used for each signal group with the following arguments:
Field | Type | Description |
---|---|---|
id | string | The ID of the signal group (created using sigid.tpl) |
name | string | The name of the signal group |
msg | int | The ID of the message containing this signal group |
msgname | string | The name of the message containing this signal group |
sig | string[] | A list of signals belonging to this signal group |
sigid | string[] | A list of signal identifers belonging to this signal group |
Used for each signal with the following arguments:
Field | Type | Description |
---|---|---|
name | string | The signal name |
id | string | The unique signal identifier created with sigid.tpl |
comment | string[] | The comment text for this signal |
enum | bool | Indicates whether this signal has a value table |
msg | int | The ID of the message sending this signal |
sgid | string[] | The signal groups containing this signal |
sgname | string[] | The names of the signal groups containing this signal |
ecu | string[] | A list of the ECUs receiving this signal |
intel | bool | Intel (little endian) style signal |
motorola | bool | Motorola (big endian) style signal |
signed | bool | The signal is signed |
sbit | int | The start bit (meaning depends on endianess) |
len | int | The signal length |
start | int | The initial (default) signal value (raw) |
calc16 | string[] | A rational conversion function (see calc16) |
min | int | The raw minimum value |
max | int | The raw maximum value |
off | int | The raw offset value |
getbuf | string[] | The output of sig_getbuf.tpl |
setbuf | string[] | The output of sig_setbuf.tpl |
A rational conversion function for the raw signal value x
and formatting factor fmt
into a real value as defined by the linear factor and offset in the DBC, this function uses up to 16bit integers.
These templates can be used to construct static byte wise signal getters and setters.
For signed signals sig_getbuf.tpl
is first called with the following arguments:
Field | Type | Description |
---|---|---|
sign | string | "-" |
byte | int | The byte containing the most significant bit |
align | int | The position of the most significant bit in the byte |
msk | int | 1 |
pos | int | The position in front of the entire read signal |
int8 | bool | Indicates whether an 8 bit integer suffices to contain the signal |
int16 | bool | Indicates whether a 16 bit integer suffices to contain the signal |
int32 | bool | Indicates whether a 32 bit integer suffices to contain the signal |
These arguments can be used to duplicate the signed bit and shift it in front.
Both templates are used for each touched signal byte with the following arguments:
Field | Type | Description |
---|---|---|
sign | string | "+" |
byte | int | The signal byte |
align | int | The least significant bit within the byte belonging to the signal |
msk | int | A bit mask to mask the aligned signal bits |
pos | int | The position to shift the resulting bits to |
int8 | bool | Indicates whether an 8 bit integer suffices to address the desired bit |
int16 | bool | Indicates whether a 16 bit integer suffices to address the desired bit |
int32 | bool | Indicates whether a 32 bit integer suffices to address the desired bit |
In case a value table is assigned to the signal, sig_enum.tpl
is called with all the arguments provided to sig.tpl
.
For each entry in the value table sig_enumval.tpl
is called with these additional arguments:
Field | Type | Description |
---|---|---|
enumval | int | The value |
enumname | string | The name of the value |
comment | string[] | The comment part of the value description |
Used for each timeout with the following arguments:
Field | Type | Description |
---|---|---|
ecu | string | The ECU that times out |
sig | string | The signal that is expected by the ECU |
sigid | string | The unique identifier for the expected signal |
timeout | int | The timeout time |
msg | int | The ID of the CAN message containing the signal |
msgname | string | The name of the CAN message containing the signal |
Invoked for every value table with the following arguments:
Field | Type | Description |
---|---|---|
enum | string | The name of the value table |
db | string | The name of the CAN DB this enum was defined in |
Invoked for every value defined in a value table. All the template arguments for enum.tpl
are available in addition to the following arguments:
Field | Type | Description |
---|---|---|
val | int | The value |
name | string | The symbolic name for the value |
comment | string[] | The comment part of the value description |
void filter329 | ( | ) |
Initialises globals.
BEGIN
void filter439 | ( | ) |
Strip DOS line endings and make sure there is a new line symbol at the end of the line, so multiline definitions can be parsed.
void error | ( | var | no, |
var | msg | ||
) |
Prints an error message on stderr and exits.
no | The number to set errno to |
msg | The error message |
void warn | ( | var | msg | ) |
Prints a warning message on stderr.
msg | The message to print |
void debug | ( | var | msg | ) |
Prints a debugging message on stderr.
The debugging message is only printed if DEBUG is set.
msg | The message to print |
void buffer | ( | ) |
Makes sure $0 is not empty.
var fetchStr | ( | ) |
Special function to fetch a string from the buffer.
This is a special case, because strings may span multiple lines. This function supports strings with up to 256 lines.
var fetch | ( | var | types | ) |
Fetch the next token from the input buffer, matching a given type.
types | A regular expression describing the type of data to be fetched |
var whole | ( | var | re | ) |
Returns the expresion with ^ and $ at beginning and end to make ~ match entire strings only.
re | The expression to wrap |
var strip | ( | var | str | ) |
Remove quotes and escapes from strings.
This function is used by fetchStr().
str | The string to unescape |
var getContext | ( | var | str | ) |
Returns the context type for a string.
str | The string to interpret |
sig | The context is a signal |
msg | The context is a message |
ecu | The context is an ECU |
env | The context is an environment variable |
db | The context is the DB |
void getUniqueEnum | ( | var | ret, |
var | enum, | ||
var | val, | ||
var | desc | ||
) |
Generates a unique name for a value table entry.
Updates:
Sets the following fields in the given array:
ret | An array to return the data set in |
enum | The identifier of the value table |
val | The value |
desc | The description string to fetch a name from |
void fsm_discard | ( | ) |
Discards buffered symbols until an empty line is encountered.
This is used to skip the list of supported symbols at the beginning of a dbc file.
void fsm_ecu | ( | ) |
Parse an ECU definition.
Token: BU_
Creates:
void fsm_enum | ( | ) |
Parse a value table.
Token: VAL_TABLE_
Creates:
void fsm_sig_enum | ( | ) |
Parse a value table bound to a signal.
Token: VAL_
Creates:
void fsm_env | ( | ) |
Parse an environment variable.
Token: EV_
Creates:
void fsm_env_data | ( | ) |
Parse the data length count of DATA type environment variables.
Token: ENVVAR_DATA_
Creates:
void fsm_msg | ( | ) |
Parse a message definition.
Token: BO_
Creates:
void fsm_sig | ( | ) |
Parse a signal definition.
Token: SG_
Creates:
void fsm_comment | ( | ) |
Parse comments.
Token: CM_
Creates one of:
void fsm_attrrange | ( | ) |
Parse a custom attribute definition.
Token: BA_DEF_
Creates:
void fsm_relattrrange | ( | ) |
Parse a custom relation attribute definition.
Token: BA_DEF_REL_
Creates:
void fsm_attrdefault | ( | ) |
Parse attribute default value.
Token: BA_DEF_DEF_
Creates:
var fetch_attrval | ( | var | attribute | ) |
Fetches an attribute value of a given type from the read buffer.
attribute | The attribute type identifier |
void fsm_attr | ( | ) |
Parse an attribute value.
Token: BA_
Creates one of:
void fsm_relattr | ( | ) |
Parse a relation attribute value.
Token: BA_REL_
Creates:
The types of to and from are recorded in:
void fsm_symbols | ( | ) |
Parse the symbol table at the beginning of a .dbc file, bail if unsupported symbols are encountered.
Token: NS_
void fsm_tx | ( | ) |
Gets a list of ECUs that transmit a certain message.
This may appear when several device options are available.
Token: BO_TX_BU_
Creates:
void fsm_siggrp | ( | ) |
Gets a signal group.
Token: SIG_GROUP_
Creates:
void fsm_start | ( | ) |
Pick tokens from the input buffer and call the respective parsing functions.
Creates:
void filter1434 | ( | ) |
This starts the line wise parsing of the DBC file.
var euclid | ( | var | a, |
var | b | ||
) |
Returns the greatest common divider (GCD).
a | An integer |
b | An integer |
var rationalFmt | ( | var | n, |
var | d | ||
) |
Returns a compact string representation of a rational number.
n | The numerator |
d | The denominator |
var rationalN | ( | var | val, |
var | base, | ||
var | precision | ||
) |
Returns a rational string representation of a real value.
This function builds the value around the numerator.
val | The real value to return as a rational |
base | The logical number base to generate the rational from |
precision | The maximum number of bits for either rational component |
var rationalD | ( | var | val, |
var | base, | ||
var | precision | ||
) |
Returns a rational string representation of a real value.
This function builds the value around the denominator.
val | The real value to return as a rational |
base | The logical number base to generate the rational from |
precision | The maximum number of bits for either rational component |
var rational | ( | var | val, |
var | precision | ||
) |
Returns a rational string representation of a real value.
This uses the different rational*() functions to find a minimal representation of the value.
val | The real value to return as a rational |
precision | The maximum number of bits for either rational component |
var filter | ( | var | str, |
var | filters, | ||
var | template | ||
) |
Applies filter chains to a given string.
Filters are a colon separated lists of the following filter commands:
Command | Effect |
---|---|
low | Convert to lower case |
up | Convert to upper case |
camel | Convert to camel case |
uncamel | Convert camel case to _ separated |
%... | A printf(3) style format specification |
str | The string to apply the filters to |
filters | The list of filters |
template | The name of the current template |
var tpl_line | ( | var | data, |
var | line, | ||
var | template | ||
) |
Populates a template line with data.
Multiline data in a template needs to be in its own line.
Lines with empty data fields are removed.
Identifiers in templates have the following shape: "<:" name ":>"
Additionally boolean filters can be installed: "<?" name "?>"
If the variable addressed in the filter evaluetes to true, the filter is removed, otherwise the entire line is removed.
data | The array containing field data |
line | The line to perform substitutions in |
template | The name of the template this line comes from, this is used to warn about deprecated arguments |
var template | ( | var | data, |
var | name | ||
) |
Reads a template, substitutes place holders with data from a given array and returns it.
data | The array to take data from |
name | The name of the template file |
void setTypes | ( | var | array, |
var | bitpos | ||
) |
Set the necessary type to be able to shift something to the given bit.
Creates the entries int8, int16 and int32 in the given arrays, with the fitting type set to the value 1 and the others to 0.
array | The array put the entries into |
bitpos | The bit that needs to be addressable |
var sigident | ( | var | sig | ) |
Returns a unique signal identifier using the sigident.tpl file.
Returns an empty string if the template is missing.
sig | The signal reference consisting of message and signal name |
var siggrpident | ( | var | sg | ) |
Returns a unique signal group identifier using the sigident.tpl file.
Returns an empty string if the template is missing.
sg | The signal group reference consisting of message and signal name |
var msgid | ( | var | id | ) |
Generates a printable message id be removing the extended bit.
id | The message id to return |
var msgidext | ( | var | id | ) |
Tests a message id for the extended bit.
id | The message id to check |
1 | The message is extended |
0 | The message is not extended |
void filter1841 | ( | ) |
Print the DBC files to stdout.
END