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