YAML trace type object

A trace type object is the type of a trace object.

A trace type describes everything a CTF consumer needs to decode all the trace’s data streams.

A trace type object is only found as the type property of a trace object.

Properties

Name Type Description Req? Default

native-byte-order

Byte order

Native byte order of the system which produces this trace type’s instance’s data streams.

Yes

uuid

UUID or string

UUID of this trace type.

If this property’s value is the string auto, barectf generates a UUID.

No

No UUID

$field-type-aliases

Mapping of string keys to field type objects or strings

Field type aliases.

Keys of this mapping are field type alias names.

If an entry’s value is a string, it must be the name of an existing field type alias.

You can use a field type alias name anywhere you can use a field type object.

No

Empty mapping

$log-level-aliases

Mapping of string keys to integers

Log level aliases.

Keys of this mapping are log level alias names.

Values of this mapping are positive integral log levels.

You can use a log level alias name as the value of an event record type object’s log-level property.

No

Empty mapping

$features

Features object

Features of this trace type’s instance (trace).

No

See Features object for default values.

clock-types

Mapping of string keys to clock type objects

Clock type store for this trace type.

Keys of this mapping are clock type names. They must be valid TSDL identifiers.

The $default-clock-type-name property of a data stream type object refers to a key of this mapping.

No

No clock type store

data-stream-types

Mapping of string keys to data stream type objects

Data stream types of this trace type.

Keys of this mapping are data stream type names. They must be valid C identifiers.

This mapping must contain at least one entry.

Yes

$include

Sequence of strings.

See Include partial YAML files.

No

No inclusions

Features object

The features of a trace type object.

As of barectf 3.0, each feature controls whether or not some information will be part of the header of each CTF packet which the generated tracer produces.

You can enable or disable a feature. When you enable one, you can set its field type explicitly or make barectf choose a sane default.

Properties

For all the feature properties below, if the value is a boolean:

True

Make barectf use a default field type.

False

Disable the feature.

All the properties are optional.

Name Type Description Default

magic-field-type

32-bit unsigned integer field type object, string, or boolean

Type of packet header’s magic number field.

If this property’s value is a string, it must be the name of an existing field type alias.

Use a default field type (true)

uuid-field-type

Static array field type object of 16 8-bit unsigned integer field type objects (8-bit alignment), string, or boolean

Type of packet header’s trace type UUID field.

If this property’s value is a string, it must be the name of an existing field type alias.

Use a default field type (true) if this trace type has a uuid property, or false otherwise

data-stream-type-id-field-type

Unsigned integer field type object, string, or boolean

Type of packet header’s data stream type ID field.

If this property’s value is a string, it must be the name of an existing field type alias.

This feature is required when this trace type has more than one data stream type (data-stream-types property).

Use a default field type (true)

Examples

The following examples can omit data stream type objects for clarity.
Example 1. Basic trace type object.
native-byte-order: little-endian
data-stream-types:
  # ...
Example 2. Trace type object with a specific UUID.
native-byte-order: little-endian
uuid: 1b706833-b56c-4960-b5f7-e43651ff01fb
data-stream-types:
  # ...
Example 3. Trace type object with an automatic UUID.
native-byte-order: little-endian
uuid: auto
data-stream-types:
  # ...
Example 4. Trace type object with a disabled magic field type feature.
native-byte-order: little-endian
$features:
  magic-field-type: false
data-stream-types:
  # ...
Example 5. Trace type object with a specific data stream type ID field type feature.
native-byte-order: little-endian
$features:
  data-stream-type-id-field-type:
    class: unsigned-integer
    size: 8
data-stream-types:
  # ...
Example 6. Trace type object with a clock type object.
native-byte-order: little-endian
clock-types:
  sys_clock:
    frequency: 8000000
    description: Clock A13 (8 MHz)
    origin-is-unix-epoch: false
data-stream-types:
  my_stream:
    $default-clock-type-name: sys_clock
    # ...
  # ...
Example 7. Trace type object with field type aliases.
native-byte-order: little-endian
$field-type-aliases:
  hex-uint8:
    $inherit: uint8
    preferred-display-base: hexadecimal
  string-array:
    class: dynamic-array
    element-field-type:
      class: string
$features:
  magic-field-type: hex-uint8
data-stream-types:
  my_stream:
    event-record-types:
      my_event:
        payload-field-type:
          client_id: hex-uint8
          messages: string-array
      # ...
    # ...
  # ...
Example 8. Trace type object with a log level alias.
native-byte-order: little-endian
$log-level-aliases:
  WARN: 17
data-stream-types:
  my_stream:
    event-record-types:
      my_event:
        log-level: WARN
        # ...
      # ...
    # ...
  # ...
Example 9. Trace type object with inclusions.
native-byte-order: little-endian
data-stream-types:
  # ...
$include:
  - stdint.yaml
  - stdmisc.yaml
  - network-field-type-aliases.yaml
  - sched-field-type-aliases.yaml
  - default-log-levels.yaml
  - project-b-data-stream-types.yaml