gse_parsers_conf(5)

NAME
Binary Blob Parser Configuration Files.

SYNOPSIS
Basic File Structure:
/* C-style comments supported */
parameters {
  prop_name1=value  prop_name2=value ...
}
parser parser_name1 {
  field_name1 { prop_name1=value  prop_name2=value ... }
  field_name2 { prop_name1=value  prop_name2=value ... }
  ...
}
parser parser_name2 {
  field_name1 { prop_name1=value  prop_name2=value ... }
  field_name2 { prop_name1=value  prop_name2=value ... }
  ...
}
...

DESCRIPTION
The rpwgse library contains a facility for parsing binary blobs of data into ASCII strings. Though blob parsers may be defined directly in C source code, this is tedious and inflexible. Instead one can feed the ASCII text configuration data to the gse_build_parsers library function which will instantiate the parser objects at runtime.

The configuration file (i.e. the configuration text string) consists of an optional parameters section followed by one or more parser definitions. Parsers are a collection of fields, which are themselves a collection of properties. Field names must be unique within a parser and property names must be unique within a field.

Fields form the basic unit of configuration data. A field defines how a single chunk of bits are to be converted into a meaningful value and how that value is to be rendered as text. The default text conversion is:

    LABEL:PFUNC_OUTPUT[UNITS]

Where:
    LABEL is the field's name or the label property value.
    PFUNC_OUTPUT is the output of the selected printing function.
    UNITS is the value of the field's unit property.

Properties are (string = value) pairs where value may be a:

string
    Any set of characters starting with a letter, an underscore , or a double quote. Strings that start with a double quote must end with a double quote.

integer
    Standard integer syntax applies including the '0x' prefix for base 16 values.

float
    Standard floating point value syntax applies including exponential notation.

enum
    An integer to string map. Ex: [ 1:One 4:Four 0xF:Fifteen ]

list
    A comma seperated group of values in parenthesis, including other lists. Ex: (1, two, (sub,list), 3.1416)

REQUIRED FIELD PROPERTIES
The following properties are required for all field definitions. If one or more of these are not defined, default values are assumed.

ty=string
    This property defines the byte interperatiation during the initital read. Here string may be one of the following:
    B Just raw bytes
    U Unsigned Integer
    S Signed Integer
    F An IEEE floating point value
    C Character Data

    Defaults to Unsigned integer.

off=integer
    integer is the offset to the 0-th order byte of the field. For little endian fields (bo=LE) this is the starting byte index of the field. For big endian fields (bo=BE) this is the final byte index of the field. The offset is measured in bytes. Reading bit fields is accomplished by defining the bytes to read along with a shift and/or mask. See the sft and msk properties below for more information of shifting and masking. Defaults to 0 bytes.

sz=integer
    The number bytes to read out of the blob. integer may be any value > 0 for fields of type B (bytes), or C (ASCII Characters). For any other type the maximum size is 8 bytes. Defaults to 1 byte.

bo=string
    The library always reads multibyte regions from the least significant byte to the most significant byte. This means the read direction may be to the left, or to the right, of the starting offset! Where string may be:

    BE  The field is defined to have big end first byte order. Reading proceeds from high offset to low offset (i.e. to the left.) This means the most significant byte is at the lowest offset.

    LE  The field is defined to have little end first byte order. Reading proceeds from low offset to high offset (i.e. to the right.) This means the most significant byte is at the highest offset.

    To avoid confusion, one should always use bo=LE for Binary and Character fields, or else the text and bytes will printed backwards.

    Defauts to BE, a historical accident.

pfunc=string
    string defines which printing function to use when rendering the converted values to ASCII text.

    This list is NOT comprehensive, further printing functions may be defined by applications at runtime via the library call gse_add_field_printer. The builtin printing functions are:

    printf
    Print using a format string in the style of sprintf(3). This will make use of, but does not require, a pfmt=string property to define the format string. Internally GseField objects store integers as 8-byte types. Thus even if input data is a single byte the ll length modifier must be used for all integer format strings. The printf printer does not work for Binary or Character fields as these are not necessarily null terminated. For these types use the direct or hex printers instead.

    direct
    Print field bytes directly as ASCII Text. Any non-printable characters are replaced by *'s.

    hex
    Convert the byte values to uppercase hexidecimal strings. This hex printer always works, however, it only display's the original bytes. Operations such as shifting, masking or calibrating do not affect the output.

    enum
    Converts integers to strings using an enumeration. This printing function requires an enumeration as the value of the pfmt property, thus the format would have the form:

    pfmt=[integer:string integer:status ...]

    If the value matches one of the integers then the corresponding string will be printed.

    Instead of an integer the literal DEF may be used for integer to specify a default string to print for any values not specifically mentioned in the enumeration. If DEF is missing and the converted value is not one of the specific entries in the enumeration, then the integer itself printed with the "%d" printf format.

    gmtime
    This printer assumes the converted value is an integer representing a UNIX epoch time in the UTC time zone. The integer is then converted to a broken down time and printed. This function requires a pfmt=string property to define a format string in the style of strftime(3).

    The default print function is printf.

OPTIONAL FIELD PROPERTIES
The following properties are optional in field definitions.

sft=integer
    The sft (short for shift) propety is useful for extrating bit fields. integer is the number of bits to down shift. If integer is negative, then it's absolute value is the number of bits to up shift.

msk=integer
    If the msk (short for mask) property is defined, then integer will be AND'ed with converted value after any shifts are applied. Note that any integers in the configuration file that start with the prefix 0x are read in base 16.

or=integer
    If the or property is defined, then integer will be OR'ed with the read in value after any masks are applied. Note that any integers in the configuration file that start with the prefix 0x are read in base 16.

cal=(coeff_0, coeff_1, coeff_2, ... )
    The cal property is used specify a calibration polynomial for the value. Calibrations are applied after any or operations. Each entry in the calibration list is a coefficient for the value rasied to the power i, where i is the 0-based index of the coefficient. See the EXAMPLES section for more information on using cal properties.

alarm=(error_lo, warn_lo, warn_hi, error_hi)
    In librpwgse, an alarm state is maintained for each field. Programs using the library can retrieve the alarm state using supplied API functions. This version of the alarm property defines an alarm range for a converted value. The converted value is compared to the values error_lo, warn_lo, warn_hi, and error_hi. which are used to set the internal alarm state as follows:

    *   If the value is <= error_lo the field's alarm status will be set to "Error Lo".

    *   If the value > error_lo but <= warn_lo the field's alarm status will be set to "Warning Lo".

    *   If the value is > warn_lo and < warn_hi the field's alarm status will be set to "Normal".

    *   If the value is >= warn_hi but < error_hi the field's alarm status will be set to "Warning High".

    *   If the value is >= to error_hi the field's alarm status will be set to "Error High".

    Alarm comparisons are preformed after any calibrations. If the alarm property is missing, all values are considered normal.

alarm=[integer:status integer:status ...]
    In librpwgse, an alarm state is maintained for each field. Programs using the library can retrieve the alarm state using supplied API functions. This version of the alarm property defines alarm settings for specific converted values. It is intended for use with fields that take on only a limited range of values. For a particular integer the status may be one of the following strings which should be self explainitory: err_lo
    warn_lo
    normal
    warn_hi
    err_hi As with the pfmt property for the enum print function, the string DEF may be used for integer to specify a default alarm state to assign to any values not specifically mentioned in the enumeration. If a default is not defined and the converted value doesn't correspond to on of the specific entries in the enumeration, then the alarm status will be set to "Error Low". If the alarm property is missing, all values are considered normal.

label=string
    string will be prepended verbatium to the print function output text. As a special setting the property value pair:

    "label=0"

    may be used to indicate that NO label should be output, not even the implied label:

    "field_name:"

desc=string
    string is a human readable description of the field or parser.

units=string
    If this property is present, then string will be affixed to the end of the print function output without an intervening space.

EXTENDED PROPERTIES
The parser builder will accept any additional properties not defined here. Additional properties may be defined in three locations:

1.  Globally in a parameters block before any parsers are defined.

2.  Inside a parser definition, before any fields are defined.

3.  Inside a field definition at any location.

Extended properties have no special meaning to librpwgse but as long as they follow the general property syntax rules they will be parsed and stored by gse_build_parsers.

One common extended property is the area property used to define a screen region for displaying fields.

CHANGING DEFAULTS
The builtin default property values are mutable. At any point in a config file, outside a field definition one may add to, remove, or change the current property default values. Any property value pair may be set as a default, not just those understood by GseField objects. Only fields make use of default properties. The default property list is not consulted by gse_build_parsers when generating GseParser objects in memory.

default{property=value property=value... }
    Use this construct to add or change one or more of the default field properties.

rmdefault{property property ... }
    Use this construct to remove one or more of the default field properties.

EXAMPLES

1.  Applying a calibration and an alarm to a signed byte field: CHIP_PS{
       off=18 ty=S pfmt="%6.3f" cal=(0, 0.01968, 0.000045) unit="V"
       alarm=(1.40, 1.45, 1.55, 1.60) desc="+1.5Volts to chip Foo"
    } In this instance if the value read in is V, then fully converted value, C, will be: C = 0.0 + 0.01968*V + 0.000045*V*V

2.  Retrieve a 1-bit status flag located the high bit of byte 47: IEB_memory{
       off=47 sft=7 msk=0x3 pfunc=enum pfmt=[0:"Empty" 1:"Loaded"]
       alarm=[0:err_lo 1:normal] desc="Memory load status"
    }

3.  Read a 31-bit big-endian integer that represents UNIX time -30 years from the 1st 4 bytes of a blob.
    TIME{
       bo=BE off=3 sz=4 msk=0x7FFFFFFF cal=(946728000, 1) ty=U
       pfunc=gmtime pfmt="UTC %Y-%m-%dT%H:%M:%S (day %j)"
       desc="Data packet Spacecraft Event Time" label=0
    }
    Note that for big endian fields the 0th order byte is NOT at offset zero!

4.  Changing default values for a set of fields. /* The following voltage fields have similar settings */
    default{ty=S sz=2 bo=LE alarm=(1.40,1.45,1.55,1.60) pfmt="%6.3f"}
      LINE1{ off=20 cal=(0,.05413) desc="Power line 1 Voltage"}
      LINE2{ off=21 cal=(0,.05520) desc="Power line 1 Voltage"}
      LINE3{ off=22 cal=(0,.05411) desc="Power line 1 Voltage"}
      LINE4{ off=23 cal=(0,.05486) desc="Power line 1 Voltage"} rmdefault{alarm unit pfmt} /* Remove unneeded defaults */
    default{ty=U sz=1 bo=BE} /* Reset to standard defaults */

5.  Using extended properties. parser my_parser{
      use_if=(0, 0xF1) /* If byte 0 is 0xF1 use this parser */
      TYPE{off=0 sz=1 pfmt="0x%02llX" row=1 col=2
           span_beg="<b><i>" span_end="<\b><\i>"
          }
    } In this example the parser level property use_if as well as the field level properties row, col, span_beg, and span_end are assumed to have meaning to some application built using librpwgse.

SEE ALSO
sprintf(3) strftime(3) and the librpwgse API documentation.

KNOWN BUGS

The default field byte order is big endian, which makes no sense for Binary and Character fields, nor is it compatabile with the natural byte order of the vast majority of modern processors. This should be changed.

To avoid confusion, the off property should always specify the starting byte of set for a region to extract instead of the offset to the 0th order byte.

AUTHOR
librpwgse was written by Chris Piker <chris-piker@uiowa.edu> to support the Juno and RBSP NASA missions. Please bring any errors or ommissions in this manual page to his attention.