docs/modules/yaml/pages/trace-type-obj.adoc

   1 = YAML trace type object
   2
   3 A _**trace type object**_ is the type of a xref:trace-obj.adoc[trace
   4 object].
   5
   6 A trace type describes everything a CTF consumer needs to decode all the
   7 trace's xref:how-barectf-works:ctf-primer.adoc#ds[data
   8 streams].
   9
  10 A trace type object is only found as the
  11 xref:trace-obj.adoc#type-prop[`type` property] of a trace object.
  12
  13 [[props]]
  14 == Properties
  15
  16 [%autowidth.stretch, cols="d,d,a,d,d", role="can-break"]
  17 |===
  18 |Name |Type |Description |{req-abbr} |Default
  19
  20 |[[native-bo]]`native-byte-order`
  21 |xref:common-values.adoc#byte-order[Byte order]
  22 |Native byte order of the system which produces this trace type's
  23 instance's xref:how-barectf-works:ctf-primer.adoc#ds[data streams].
  24 |Yes
  25 |
  26
  27 |[[uuid-prop]]`uuid`
  28 |xref:common-values.adoc#uuid[UUID] or string
  29 |UUID of this trace type.
  30
  31 If this property's value is the string `auto`, barectf generates a UUID.
  32
  33 |No
  34 |No UUID
  35
  36 |[[ft-aliases-prop]]`$field-type-aliases`
  37 |Mapping of string keys to xref:ft-obj.adoc[field type objects]
  38 or strings
  39 |Field type aliases.
  40
  41 Keys of this mapping are field type alias names.
  42
  43 If an entry's value is a string, it must be the name of an existing
  44 field type alias.
  45
  46 You can use a field type alias name anywhere you can use a
  47 xref:ft-obj.adoc[field type object].
  48 |No
  49 |Empty mapping
  50
  51 |[[ll-aliases-prop]]`$log-level-aliases`
  52 |Mapping of string keys to integers
  53 |Log level aliases.
  54
  55 Keys of this mapping are log level alias names.
  56
  57 Values of this mapping are positive integral log levels.
  58
  59 You can use a log level alias name as the value of an event record type
  60 object's xref:ert-obj.adoc#ll-prop[`log-level` property].
  61 |No
  62 |Empty mapping
  63
  64 |`$features`
  65 |<<features-obj>>
  66 |Features of this trace type's instance (trace).
  67 |No
  68 |See <<features-obj>> for default values.
  69
  70 |[[clk-types-prop]]`clock-types`
  71 |Mapping of string keys to xref:clk-type-obj.adoc[clock type objects]
  72 |Clock type store for this trace type.
  73
  74 Keys of this mapping are clock type names. They must be valid
  75 xref:index.adoc#tsdl-ident[TSDL identifiers].
  76
  77 The
  78 xref:dst-obj.adoc#def-clk-type-name-prop[`$default-clock-type-name`
  79 property] of a data stream type object refers to a key of this mapping.
  80 |No
  81 |No clock type store
  82
  83 |[[dsts-prop]]`data-stream-types`
  84 |Mapping of string keys to xref:dst-obj.adoc[data stream
  85 type objects]
  86 |Data stream types of this trace type.
  87
  88 Keys of this mapping are data stream type names. They must be valid
  89 C{nbsp}identifiers.
  90
  91 This mapping must contain at least one entry.
  92 |Yes
  93 |
  94
  95 |[[include-prop]]`$include`
  96 |Sequence of strings.
  97 |See xref:include.adoc[].
  98 |No
  99 |No inclusions
 100 |===
 101
 102 [[features-obj]]
 103 == Features object
 104
 105 The features of a trace type object.
 106
 107 As of barectf{nbsp}{page-component-version}, each feature controls
 108 whether or not some information will be part of the header of each
 109 xref:how-barectf-works:ctf-primer.adoc#pkt[CTF packet] which the
 110 generated tracer produces.
 111
 112 You can enable or disable a feature. When you enable one, you can set
 113 its xref:ft-obj.adoc[field type] explicitly or make barectf choose a
 114 sane default.
 115
 116 === Properties
 117
 118 For all the feature properties below, if the value is a boolean:
 119
 120 True::
 121     Make barectf use a default field type.
 122
 123 False::
 124     Disable the feature.
 125
 126 All the properties are optional.
 127
 128 [%autowidth.stretch, cols="d,d,a,d", role="can-break"]
 129 |===
 130 |Name |Type |Description |Default
 131
 132 |[[magic-ft-prop]]`magic-field-type`
 133 |32-bit{nbsp}unsigned xref:int-ft-obj.adoc[integer field type object],
 134 string, or boolean
 135 |Type of packet header's magic number field.
 136
 137 If this property's value is a string, it must be the name of an existing
 138 <<ft-aliases-prop,field type alias>>.
 139 |True
 140
 141 |[[uuid-ft-prop]]`uuid-field-type`
 142 |xref:static-array-ft-obj.adoc[Static array field type object] of
 143 16{nbsp}8-bit{nbsp}unsigned xref:int-ft-obj.adoc[integer field
 144 type objects] (8-bit{nbsp}alignment), string, or boolean
 145 |Type of packet header's trace type UUID field.
 146
 147 If this property's value is a string, it must be the name of an existing
 148 <<ft-aliases-prop,field type alias>>.
 149 |True if this trace type has a <<uuid-prop,`uuid` property>>, or false
 150 otherwise.
 151
 152 |[[dst-id-ft-prop]]`data-stream-type-id-field-type`
 153 |Unsigned xref:int-ft-obj.adoc[integer field type object], string,
 154 or boolean
 155 |Type of packet header's xref:dst-obj.adoc[data stream type] ID field.
 156
 157 If this property's value is a string, it must be the name of an existing
 158 <<ft-aliases-prop,field type alias>>.
 159
 160 This feature is required when this trace type has more than one
 161 data stream type (<<dsts-prop,`data-stream-types` property>>).
 162 |True
 163 |===
 164
 165 == Examples
 166
 167 NOTE: The following examples can omit <<dsts-prop,data stream type
 168 objects>> for clarity.
 169
 170 .Basic trace type object.
 171 ====
 172 [source,yaml]
 173 ----
 174 native-byte-order: little-endian
 175 data-stream-types:
 176   # ...
 177 ----
 178 ====
 179
 180 .Trace type object with a specific <<uuid-prop,UUID>>.
 181 ====
 182 [source,yaml]
 183 ----
 184 native-byte-order: little-endian
 185 uuid: 1b706833-b56c-4960-b5f7-e43651ff01fb
 186 data-stream-types:
 187   # ...
 188 ----
 189 ====
 190
 191 .Trace type object with an automatic <<uuid-prop,UUID>>.
 192 ====
 193 [source,yaml]
 194 ----
 195 native-byte-order: little-endian
 196 uuid: auto
 197 data-stream-types:
 198   # ...
 199 ----
 200 ====
 201
 202 .Trace type object with a disabled <<magic-ft-prop,magic field type feature>>.
 203 ====
 204 [source,yaml]
 205 ----
 206 native-byte-order: little-endian
 207 $features:
 208   magic-field-type: false
 209 data-stream-types:
 210   # ...
 211 ----
 212 ====
 213
 214 .Trace type object with a specific <<dst-id-ft-prop,data stream type ID field type feature>>.
 215 ====
 216 [source,yaml]
 217 ----
 218 native-byte-order: little-endian
 219 $features:
 220   data-stream-type-id-field-type:
 221     class: unsigned-integer
 222     size: 8
 223 data-stream-types:
 224   # ...
 225 ----
 226 ====
 227
 228 .Trace type object with a <<clk-types-prop,clock type object>>.
 229 ====
 230 [source,yaml]
 231 ----
 232 native-byte-order: little-endian
 233 clock-types:
 234   sys_clock:
 235     frequency: 8000000
 236     description: Clock A13 (8 MHz)
 237     origin-is-unix-epoch: false
 238 data-stream-types:
 239   my_stream:
 240     $default-clock-type-name: sys_clock
 241     # ...
 242   # ...
 243 ----
 244 ====
 245
 246 .Trace type object with <<ft-aliases-prop,field type aliases>>.
 247 ====
 248 [source,yaml]
 249 ----
 250 native-byte-order: little-endian
 251 $field-type-aliases:
 252   hex-uint8:
 253     $inherit: uint8
 254     preferred-display-base: hexadecimal
 255   string-array:
 256     class: dynamic-array
 257     element-field-type:
 258       class: string
 259 $features:
 260   magic-field-type: hex-uint8
 261 data-stream-types:
 262   my_stream:
 263     event-record-types:
 264       my_event:
 265         payload-field-type:
 266           client_id: hex-uint8
 267           messages: string-array
 268       # ...
 269     # ...
 270   # ...
 271 ----
 272 ====
 273
 274 .Trace type object with a <<ll-aliases-prop,log level alias>>.
 275 ====
 276 [source,yaml]
 277 ----
 278 native-byte-order: little-endian
 279 $log-level-aliases:
 280   WARN: 17
 281 data-stream-types:
 282   my_stream:
 283     event-record-types:
 284       my_event:
 285         log-level: WARN
 286         # ...
 287       # ...
 288     # ...
 289   # ...
 290 ----
 291 ====
 292
 293 .Trace type object with <<include-prop,inclusions>>.
 294 ====
 295 [source,yaml]
 296 ----
 297 native-byte-order: little-endian
 298 data-stream-types:
 299   # ...
 300 $include:
 301   - stdint.yaml
 302   - stdmisc.yaml
 303   - network-field-type-aliases.yaml
 304   - sched-field-type-aliases.yaml
 305   - default-log-levels.yaml
 306   - project-b-data-stream-types.yaml
 307 ----
 308 ====