YAML data stream type object

A data stream type object is the type of a data stream.

A data stream type describes everything a CTF consumer needs to decode its instances (data streams).

Data stream type objects are only found under the data-stream-types property of a trace type object.

Properties

Name Type Description Req? Default

Name	Type	Description	Req?	Default
`$is-default`	Boolean	If this property is true, then this data stream type is its trace type's default data stream type. For a generated tracing function `F` named `barectf_trace_my_stream_my_event()`, where `my_stream` is the name of the default data stream type, barectf also generates a public C preprocessor definition named `barectf_trace_my_event` and set to `F`. For a given trace type object, a single data stream type object can have this property set to true. See also the code generation header option object’s `def-dst-name-def-prop` property.	No	False
`$default-clock-type-name`	String	Name of the clock type which describes the default clock of this data stream type’s instances. This property’s value must be an existing key within this trace type’s `clock-types` mapping. When a data stream type has a default clock type, all its instances (data streams) have their own default clock. A data stream clock is an integral counter of cycles. With the clock’s type’s frequency and type’s offset properties, you can convert a clock value to seconds from its origin. The header fields of CTF packets and event records can contain snapshots, named timestamps, of the value of their data stream’s default clock.	No	No default clock type
`$features`	Features object	Features of this data stream type’s instances.	No	See Features object for default values.
`packet-context-field-type-extra-members`	Type of the structure field type object’s `members` property	Extra, user-defined members to be appended to this data stream type’s packet context structure field type. For each member name `NAME` of this property, the packet opening function which barectf generates for this data stream type has an additional parameter named `pc_NAME`. Member names must be valid TSDL identifiers.	No	No packet context field type extra members
`event-record-common-context-field-type`	Structure field type object or string	Event record common context field type of this data stream type. If this property’s value is a string, it must be the name of an existing field type alias. For each member `NAME` of this property, all the tracing functions which barectf generates for this data stream type have an additional parameter named `cc_NAME`. Member names must be valid TSDL identifiers.	No	No event record common context field type
`event-record-types`	Mapping of string keys to event record type objects	Event record types of this data stream type. Keys of this mapping are event record 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

$is-default

Boolean

If this property is true, then this data stream type is its trace type's default data stream type.

For a generated tracing function F named barectf_trace_my_stream_my_event(), where my_stream is the name of the default data stream type, barectf also generates a public C preprocessor definition named barectf_trace_my_event and set to F.

For a given trace type object, a single data stream type object can have this property set to true.

See also the code generation header option object’s def-dst-name-def-prop property.

False

$default-clock-type-name

String

Name of the clock type which describes the default clock of this data stream type’s instances.

This property’s value must be an existing key within this trace type’s clock-types mapping.

When a data stream type has a default clock type, all its instances (data streams) have their own default clock.

A data stream clock is an integral counter of cycles. With the clock’s type’s frequency and type’s offset properties, you can convert a clock value to seconds from its origin.

The header fields of CTF packets and event records can contain snapshots, named timestamps, of the value of their data stream’s default clock.

No default clock type

$features

Features object

Features of this data stream type’s instances.

See Features object for default values.

packet-context-field-type-extra-members

Type of the structure field type object’s members property

Extra, user-defined members to be appended to this data stream type’s packet context structure field type.

For each member name NAME of this property, the packet opening function which barectf generates for this data stream type has an additional parameter named pc_NAME.

Member names must be valid TSDL identifiers.

No packet context field type extra members

event-record-common-context-field-type

Structure field type object or string

Event record common context field type of this data stream type.

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

For each member NAME of this property, all the tracing functions which barectf generates for this data stream type have an additional parameter named cc_NAME.

Member names must be valid TSDL identifiers.

No event record common context field type

event-record-types

Mapping of string keys to event record type objects

Event record types of this data stream type.

Keys of this mapping are event record 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 inclusions

Features object

The features of a data stream type object.

Properties

All the properties are optional.

Name Type Description Default

Name	Type	Description	Default
`packet`	Packet features object	Features related to CTF packets.	See Packet features object for default values.
`event-record`	Event record features object	Features related to CTF event records.	See Event record features object for default values.

packet

Packet features object

Features related to CTF packets.

See Packet features object for default values.

event-record

Event record features object

Features related to CTF event records.

See Event record features object for default values.

Packet features object

The packet features of a data stream type object.

As of barectf 3.1, each feature controls whether or not some information will be part of the context 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 (if possible).

All the properties are optional.

Name Type Description Default

Name	Type	Description	Default
`total-size-field-type`	Unsigned integer field type object, string, or boolean	Type of packet context’s total size field. If this property’s value is a string, it must be the name of an existing field type alias. The size of this feature’s integer field type must be greater than or equal to the size of the `content-size-field-type` property’s field type. You can’t disable this feature.	Use a default field type (true)
`content-size-field-type`	Unsigned integer field type object, string, or boolean	Type of packet context’s content size field. If this property’s value is a string, it must be the name of an existing field type alias. The size of this feature’s integer field type must be less than or equal to the size of the `total-size-field-type` property’s field type. You can’t disable this feature.	Use a default field type (true)
`beginning-timestamp-field-type`	Unsigned integer field type object, string, or boolean	Type of packet context’s beginning timestamp 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 data stream type has a default clock type, or false otherwise
`end-timestamp-field-type`	Unsigned integer field type object, string, or boolean	Type of packet context’s end timestamp 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 data stream type has a default clock type, or false otherwise
`discarded-event-records-counter-snapshot-field-type`	Unsigned integer field type object, string, or boolean	Type of packet context’s discarded event record counter snapshot 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)
`sequence-number-field-type`	Unsigned integer field type object, string, or boolean	Type of packet context’s sequence number field. If this property’s value is a string, it must be the name of an existing field type alias.	Disabled (false)

total-size-field-type

Unsigned integer field type object, string, or boolean

Type of packet context’s total size field.

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

The size of this feature’s integer field type must be greater than or equal to the size of the content-size-field-type property’s field type.

You can’t disable this feature.

Use a default field type (true)

content-size-field-type

Unsigned integer field type object, string, or boolean

Type of packet context’s content size field.

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

The size of this feature’s integer field type must be less than or equal to the size of the total-size-field-type property’s field type.

You can’t disable this feature.

Use a default field type (true)

beginning-timestamp-field-type

Unsigned integer field type object, string, or boolean

Type of packet context’s beginning timestamp 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 data stream type has a default clock type, or false otherwise

end-timestamp-field-type

Unsigned integer field type object, string, or boolean

Type of packet context’s end timestamp 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 data stream type has a default clock type, or false otherwise

discarded-event-records-counter-snapshot-field-type

Unsigned integer field type object, string, or boolean

Type of packet context’s discarded event record counter snapshot 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)

sequence-number-field-type

Unsigned integer field type object, string, or boolean

Type of packet context’s sequence number field.

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

Disabled (false)

Event record features object

The event records features of a data stream type object.

As of barectf 3.1, each feature controls whether or not some information will be part of the header of each CTF event record 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

Name	Type	Description	Default
`type-id-field-type`	Unsigned integer field type object, string, or boolean	Type of event header’s event record 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 data stream type has more than one event record type (`event-record-types` property).	Use a default field type (true)
`timestamp-field-type`	Unsigned integer field type object, string, or boolean	Type of event header’s timestamp 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 data stream type has a default clock type, or false otherwise

type-id-field-type

Unsigned integer field type object, string, or boolean

Type of event header’s event record 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 data stream type has more than one event record type (event-record-types property).

Use a default field type (true)

timestamp-field-type

Unsigned integer field type object, string, or boolean

Type of event header’s timestamp 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 data stream type has a default clock type, or false otherwise

Examples

The following examples can omit event record type objects for clarity.

Example 1. Basic data stream type object.

event-record-types:
  # ...

Example 2. Basic default data stream type object.

$is-default: true
event-record-types:
  # ...

Example 3. Data stream type object with a default clock type.

$default-clock-type-name: sys_clock2
event-record-types:
  # ...

Example 4. Data stream type object with a disabled packet discarded event records counter snapshot field type feature.

$features:
  packet:
    discarded-event-records-counter-snapshot-field-type: false
event-record-types:
  # ...

Example 5. Data stream type object with an enabled packet sequence number field type feature.

$features:
  packet:
    sequence-number-field-type: true
event-record-types:
  # ...

Example 6. Data stream type object with 16-bit packet total and content size field type features.

$features:
  packet:
    total-size-field-type: uint16
    content-size-field-type: uint16
event-record-types:
  # ...

Example 7. Data stream type object with a disabled event record timestamp field type feature.

$features:
  event-record:
    timestamp-field-type: false
event-record-types:
  # ...

Example 8. Data stream type object with packet context field type extra members.

packet-context-field-type-extra-members:
  - cur_load: int8
  - node_id: uint16
  - node_addr: string
event-record-types:
  # ...

Example 9. Data stream type object with an event record common context field type.

event-record-common-context-field-type:
  class: structure
  members:
    - pid: uint32
    - level: double
event-record-types:
  # ...

Example 10. Data stream type object with inclusions.

event-record-types:
  # ...
$include:
  - project-b-event-record-types.yaml
  - common-data-stream-type-features.yaml