YAML field type object

A field type object is the type of data field, found in data streams.

A field type object describes what a CTF consumer needs to decode a data field.

You can use a field type alias name (a string) anywhere a field type object is expected.

Expected usage locations

A field type object is expected at the following locations:

Within another field type object
Within a trace type object
Within a data stream type object
Within an event record type object

Available field type objects

As of barectf 3.0, the available field type objects are:

Integer field type objects

Describes unsigned and signed integer data fields.

Enumeration field type objects

Describes unsigned and signed enumeration data fields.

Real field type object

Describes single-precision and double-precision real data fields.

String field type object

Describes null-terminated string data fields.

Structure field type object

Describes structure data fields.

Static array field type object

Describes array data fields with a static length.

Dynamic array field type object

Describes array data fields with a dynamic (variable) length.

Generated C types

barectf uses configured field types to generate user data parameters of packet opening and tracing functions.

Each field type object page indicates the field type’s corresponding C type(s).

Here’s a summary:

Field type C type

Unsigned integer/enumeration field type

Depending on the size property:

[1, 8]

uint8_t

[9, 16]

uint16_t

[17, 32]

uint32_t

[33, 64]

uint64_t

Signed integer/enumeration field type

Depending on the size property:

[1, 8]

int8_t

[9, 16]

int16_t

[17, 32]

int32_t

[33, 64]

int64_t

Real field type

Depending on the size property:

32

float

64

double

String field type

const char *

Static array field type

Pointer to const T, where T is the generated C type for the field type object of the element-field-type property.

Dynamic array field type

Two adjacent parameters:

Dynamic length

uint32_t

Element

Pointer to const T, where T is the generated C type for the field type object of the element-field-type property.

Inherit a field type object

A field type object can inherit the properties of another field type object with the common $inherit property.

When a field type object A inherits another field type object B, the effective field type object is A “patching” B.

For a given property of A, the patching rules are:

A's property type <em>A</em>'s property exists in <em>B</em> <em>A</em>'s property doesn’t exist in <em>B</em>

Null, boolean, integer, and string

Replace B's property with A's property.

Keep A's property.

Sequence
B's property is also a sequence

Append the items of A's property to B's property.

A structure field type object’s members property is an exception: A's property is considered to be an ordered mapping, therefore apply the mapping patching rules.

B's property is not a sequence

Replace B's property with A's property.

Keep A's property.

Mapping
B's property is also a mapping

Patch A's property over B's property according to those rules.

B's property is not a mapping

Replace B's property with A's property.

Keep A's property.
When A's property replaces B's property and the value of A's property is null, this effectively “resets” the property to its default value.

Examples

In the examples below, the name of the base field type object’s alias is base.

Example 1. Override scalar property.
Base field type object
class: unsigned-integer
size: 32
alignment: 8
Overlay field type object
$inherit: base
size: 16
Effective field type object
class: unsigned-integer
size: 16
alignment: 8
Example 2. Add and override scalar properties.
Base field type object
class: unsigned-integer
size: 32
alignment: 8
Overlay field type object
$inherit: base
size: 16
preferred-display-base: hexadecimal
Effective field type object
class: unsigned-integer
size: 16
alignment: 8
preferred-display-base: hexadecimal
Example 3. Append to sequence property.
Base field type object
class: signed-enumeration
mappings:
  COMPOSE:
    - 56
    - [100, 299]
  DIRTY: [0]
Overlay field type object
$inherit: base
size: 16
mappings:
  COMPOSE:
    - -22
Effective field type object
class: signed-enumeration
size: 16
mappings:
  COMPOSE:
    - 56
    - [100, 299]
    - -22
  DIRTY: [0]
Example 4. Add to nested mapping property.
Base field type object
class: structure
members:
  - msg: string
  - user_id: uint16
Overlay field type object
$inherit: base
members:
  - src_ip_addr:
      field-type:
        class: static-array
        length: 4
        element-field-type: uint8
  - user_id: int8
Effective field type object
class: structure
members:
  - msg: string
  - user_id: int8
  - src_ip_addr:
      field-type:
        class: static-array
        length: 4
        element-field-type: uint8

Common properties

All field type objects require that the class or the $inherit property be set, but not both.

Name Type Description Required?

class

String

Class of this field type amongst:

unsigned-integer
unsigned-int
uint

Unsigned integer field type

signed-integer
signed-int
sint

Signed integer field type

unsigned-enumeration
unsigned-enum
uenum

Unsigned enumeration field type

signed-enumeration
signed-enum
senum

Signed enumeration field type

real

Real field type

string
str

String field type

structure
struct

Structure field type

static-array

Static array field type

dynamic-array

Dynamic array field type

Yes if the $inherit property is not set.

$inherit

String

Name of a field type alias from which to inherit.

Yes if the class property is not set.