| 1 |
= YAML data stream type object |
| 2 |
|
| 3 |
A _**data stream type object**_ is the type of a |
| 4 |
xref:how-barectf-works:ctf-primer.adoc#ds[data stream]. |
| 5 |
|
| 6 |
A data stream type describes everything a CTF consumer needs to decode |
| 7 |
its instances (data streams). |
| 8 |
|
| 9 |
Data stream type objects are only found under the |
| 10 |
xref:trace-type-obj.adoc#dsts-prop[`data-stream-types` property] of a |
| 11 |
trace type 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 |
|[[is-def-prop]]`$is-default` |
| 21 |
|Boolean |
| 22 |
|If this property is true, then this data stream type is its |
| 23 |
xref:trace-type-obj.adoc[trace type]'s default data stream type. |
| 24 |
|
| 25 |
For a generated tracing function `__F__` named |
| 26 |
`+barectf_trace_my_stream_my_event()+`, where `my_stream` is the name of |
| 27 |
the default data stream type, barectf also generates a public |
| 28 |
C{nbsp}preprocessor definition named `barectf_trace_my_event` and set to |
| 29 |
`__F__`. |
| 30 |
|
| 31 |
For a given trace type object, a single data stream type object can |
| 32 |
have this property set to true. |
| 33 |
|
| 34 |
See also the code generation header option object's |
| 35 |
xref:cfg-obj.adoc#def-dst-name-def-prop[`def-dst-name-def-prop` |
| 36 |
property]. |
| 37 |
|No |
| 38 |
|False |
| 39 |
|
| 40 |
|[[def-clk-type-name-prop]]`$default-clock-type-name` |
| 41 |
|String |
| 42 |
|Name of the xref:clk-type-obj.adoc[clock type] which describes the |
| 43 |
default clock of this data stream type's instances. |
| 44 |
|
| 45 |
This property's value must be an existing key within this trace type's |
| 46 |
xref:trace-type-obj.adoc#clk-types-prop[`clock-types`] mapping. |
| 47 |
|
| 48 |
When a data stream type has a default clock type, all its instances |
| 49 |
(xref:how-barectf-works:ctf-primer.adoc#ds[data streams]) |
| 50 |
have their own default clock. |
| 51 |
|
| 52 |
A data stream clock is an integral counter of _cycles_. With the clock's |
| 53 |
type's xref:clk-type-obj.adoc#freq-prop[frequency] and |
| 54 |
type's xref:clk-type-obj.adoc#offset-prop[offset] properties, you can |
| 55 |
convert a clock value to seconds from its origin. |
| 56 |
|
| 57 |
The header fields of CTF |
| 58 |
xref:how-barectf-works:ctf-primer.adoc#pkt[packets] and |
| 59 |
xref:how-barectf-works:ctf-primer.adoc#er[event records] can contain |
| 60 |
snapshots, named _timestamps_, of the value of their data stream's |
| 61 |
default clock. |
| 62 |
|No |
| 63 |
|No default clock type |
| 64 |
|
| 65 |
|`$features` |
| 66 |
|<<features-obj>> |
| 67 |
|Features of this data stream type's instances. |
| 68 |
|No |
| 69 |
|See <<features-obj>> for default values. |
| 70 |
|
| 71 |
|[[pkt-ctx-ft-extra-members-prop]]`packet-context-field-type-extra-members` |
| 72 |
|Type of the structure field type object's |
| 73 |
xref:struct-ft-obj.adoc#members-prop[`members` property] |
| 74 |
|Extra, user-defined members to be appended to this data stream type's |
| 75 |
packet context structure field type. |
| 76 |
|
| 77 |
For each member name `__NAME__` of this property, the packet opening |
| 78 |
function which barectf generates for this data stream type has an |
| 79 |
additional parameter named `pc___NAME__`. |
| 80 |
|
| 81 |
Member names must be valid xref:index.adoc#tsdl-ident[TSDL identifiers]. |
| 82 |
|No |
| 83 |
|No packet context field type extra members |
| 84 |
|
| 85 |
|[[er-common-ctx-ft-prop]]`event-record-common-context-field-type` |
| 86 |
|xref:struct-ft-obj.adoc[Structure field type object] or string |
| 87 |
| |
| 88 |
xref:how-barectf-works:ctf-primer.adoc#er[Event record common context |
| 89 |
field] type of this data stream type. |
| 90 |
|
| 91 |
If this property's value is a string, it must be the name of an existing |
| 92 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 93 |
|
| 94 |
For each member `__NAME__` of this property, all the |
| 95 |
xref:tracing-funcs:index.adoc[tracing functions] which barectf generates |
| 96 |
for this data stream type have an additional parameter named |
| 97 |
`cc___NAME__`. |
| 98 |
|
| 99 |
Member names must be valid xref:index.adoc#tsdl-ident[TSDL identifiers]. |
| 100 |
|No |
| 101 |
|No event record common context field type |
| 102 |
|
| 103 |
|[[erts-prop]]`event-record-types` |
| 104 |
|Mapping of string keys to xref:ert-obj.adoc[event record type objects] |
| 105 |
|Event record types of this data stream type. |
| 106 |
|
| 107 |
Keys of this mapping are event record type names. They must be valid |
| 108 |
C{nbsp}identifiers. |
| 109 |
|
| 110 |
This mapping must contain at least one entry. |
| 111 |
|Yes |
| 112 |
| |
| 113 |
|
| 114 |
|[[include-prop]]`$include` |
| 115 |
|Sequence of strings. |
| 116 |
|See xref:include.adoc[]. |
| 117 |
|No |
| 118 |
|No inclusions |
| 119 |
|=== |
| 120 |
|
| 121 |
[[features-obj]] |
| 122 |
== Features object |
| 123 |
|
| 124 |
The features of a data stream type object. |
| 125 |
|
| 126 |
=== Properties |
| 127 |
|
| 128 |
All the properties are optional. |
| 129 |
|
| 130 |
[%autowidth.stretch] |
| 131 |
|=== |
| 132 |
|Name |Type |Description |Default |
| 133 |
|
| 134 |
|`packet` |
| 135 |
|<<pkt-features-obj>> |
| 136 |
|Features related to xref:how-barectf-works:ctf-primer.adoc#pkt[CTF packets]. |
| 137 |
|See <<pkt-features-obj>> for default values. |
| 138 |
|
| 139 |
|`event-record` |
| 140 |
|<<er-features-obj>> |
| 141 |
|Features related to xref:how-barectf-works:ctf-primer.adoc#er[CTF |
| 142 |
event records]. |
| 143 |
|See <<er-features-obj>> for default values. |
| 144 |
|=== |
| 145 |
|
| 146 |
[[pkt-features-obj]] |
| 147 |
== Packet features object |
| 148 |
|
| 149 |
The packet features of a data stream type object. |
| 150 |
|
| 151 |
As of barectf{nbsp}{page-component-version}, each feature controls |
| 152 |
whether or not some information will be part of the context of each |
| 153 |
xref:how-barectf-works:ctf-primer.adoc#pkt[CTF packet] which the generated |
| 154 |
tracer produces. |
| 155 |
|
| 156 |
You can enable or disable a feature. When you enable one, you can set |
| 157 |
its xref:ft-obj.adoc[field type] explicitly or make barectf choose a |
| 158 |
sane default. |
| 159 |
|
| 160 |
=== Properties |
| 161 |
|
| 162 |
For all the feature properties below, if the value is a boolean: |
| 163 |
|
| 164 |
True:: |
| 165 |
Make barectf use a default field type. |
| 166 |
|
| 167 |
False:: |
| 168 |
Disable the feature (if possible). |
| 169 |
|
| 170 |
All the properties are optional. |
| 171 |
|
| 172 |
[%autowidth.stretch, cols="d,d,a,d", role="can-break"] |
| 173 |
|=== |
| 174 |
|Name |Type |Description |Default |
| 175 |
|
| 176 |
|[[total-size-ft-prop]]`total-size-field-type` |
| 177 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 178 |
or boolean |
| 179 |
|Type of packet context's total size field. |
| 180 |
|
| 181 |
If this property's value is a string, it must be the name of an existing |
| 182 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 183 |
|
| 184 |
The size of this feature's integer field type must be greater than or |
| 185 |
equal to the size of the `content-size-field-type` property's field |
| 186 |
type. |
| 187 |
|
| 188 |
You **can't** disable this feature. |
| 189 |
|Use a default field type (true) |
| 190 |
|
| 191 |
|[[content-size-ft-prop]]`content-size-field-type` |
| 192 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 193 |
or boolean |
| 194 |
|Type of packet context's content size field. |
| 195 |
|
| 196 |
If this property's value is a string, it must be the name of an existing |
| 197 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 198 |
|
| 199 |
The size of this feature's integer field type must be less than or equal |
| 200 |
to the size of the `total-size-field-type` property's field type. |
| 201 |
|
| 202 |
You **can't** disable this feature. |
| 203 |
|Use a default field type (true) |
| 204 |
|
| 205 |
|[[beginning-ts-ft-prop]]`beginning-timestamp-field-type` |
| 206 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 207 |
or boolean |
| 208 |
|Type of packet context's beginning timestamp field. |
| 209 |
|
| 210 |
If this property's value is a string, it must be the name of an existing |
| 211 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 212 |
|Use a default field type (true) if this data stream type has a |
| 213 |
<<def-clk-type-name-prop,default clock type>>, or false otherwise |
| 214 |
|
| 215 |
|[[end-ts-ft-prop]]`end-timestamp-field-type` |
| 216 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 217 |
or boolean |
| 218 |
|Type of packet context's end timestamp field. |
| 219 |
|
| 220 |
If this property's value is a string, it must be the name of an existing |
| 221 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 222 |
|Use a default field type (true) if this data stream type has a |
| 223 |
<<def-clk-type-name-prop,default clock type>>, or false otherwise |
| 224 |
|
| 225 |
|[[disc-er-counter-snapshot-ft-prop]]`discarded-event-records-counter-snapshot-field-type` |
| 226 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 227 |
or boolean |
| 228 |
|Type of packet context's |
| 229 |
xref:how-barectf-works:ctf-primer.adoc#disc-er-counter[discarded event |
| 230 |
record counter] snapshot field. |
| 231 |
|
| 232 |
If this property's value is a string, it must be the name of an existing |
| 233 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 234 |
|Use a default field type (true) |
| 235 |
|
| 236 |
|[[seq-num-ft-prop]]`sequence-number-field-type` |
| 237 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 238 |
or boolean |
| 239 |
|Type of packet context's sequence number field. |
| 240 |
|
| 241 |
If this property's value is a string, it must be the name of an existing |
| 242 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 243 |
|Disabled (false) |
| 244 |
|=== |
| 245 |
|
| 246 |
[[er-features-obj]] |
| 247 |
== Event record features object |
| 248 |
|
| 249 |
The event records features of a data stream type object. |
| 250 |
|
| 251 |
As of barectf{nbsp}{page-component-version}, each feature controls |
| 252 |
whether or not some information will be part of the header of each |
| 253 |
xref:how-barectf-works:ctf-primer.adoc#er[CTF event record] which the |
| 254 |
generated tracer produces. |
| 255 |
|
| 256 |
You can enable or disable a feature. When you enable one, you can set |
| 257 |
its xref:ft-obj.adoc[field type] explicitly or make barectf choose a |
| 258 |
sane default. |
| 259 |
|
| 260 |
=== Properties |
| 261 |
|
| 262 |
For all the feature properties below, if the value is a boolean: |
| 263 |
|
| 264 |
True:: |
| 265 |
Make barectf use a default field type. |
| 266 |
|
| 267 |
False:: |
| 268 |
Disable the feature. |
| 269 |
|
| 270 |
All the properties are optional. |
| 271 |
|
| 272 |
[%autowidth.stretch, cols="d,d,a,d", role="can-break"] |
| 273 |
|=== |
| 274 |
|Name |Type |Description |Default |
| 275 |
|
| 276 |
|[[type-id-ft-prop]]`type-id-field-type` |
| 277 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 278 |
or boolean |
| 279 |
|Type of event header's xref:ert-obj.adoc[event record type] ID field. |
| 280 |
|
| 281 |
If this property's value is a string, it must be the name of an existing |
| 282 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 283 |
|
| 284 |
This feature is required when this data stream type has more than one |
| 285 |
event record type (<<erts-prop,`event-record-types` property>>). |
| 286 |
|Use a default field type (true) |
| 287 |
|
| 288 |
|[[ts-prop]]`timestamp-field-type` |
| 289 |
|Unsigned xref:int-ft-obj.adoc[integer field type object], string, |
| 290 |
or boolean |
| 291 |
|Type of event header's timestamp field. |
| 292 |
|
| 293 |
If this property's value is a string, it must be the name of an existing |
| 294 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. |
| 295 |
|Use a default field type (true) if this data stream type has a |
| 296 |
<<def-clk-type-name-prop,default clock type>>, or false otherwise |
| 297 |
|=== |
| 298 |
|
| 299 |
== Examples |
| 300 |
|
| 301 |
NOTE: The following examples can omit <<erts-prop,event record type |
| 302 |
objects>> for clarity. |
| 303 |
|
| 304 |
.Basic data stream type object. |
| 305 |
==== |
| 306 |
[source,yaml] |
| 307 |
---- |
| 308 |
event-record-types: |
| 309 |
# ... |
| 310 |
---- |
| 311 |
==== |
| 312 |
|
| 313 |
.Basic <<is-def-prop,default>> data stream type object. |
| 314 |
==== |
| 315 |
[source,yaml] |
| 316 |
---- |
| 317 |
$is-default: true |
| 318 |
event-record-types: |
| 319 |
# ... |
| 320 |
---- |
| 321 |
==== |
| 322 |
|
| 323 |
.Data stream type object with a <<def-clk-type-name-prop,default clock type>>. |
| 324 |
==== |
| 325 |
[source,yaml] |
| 326 |
---- |
| 327 |
$default-clock-type-name: sys_clock2 |
| 328 |
event-record-types: |
| 329 |
# ... |
| 330 |
---- |
| 331 |
==== |
| 332 |
|
| 333 |
.Data stream type object with a disabled packet <<disc-er-counter-snapshot-ft-prop,discarded event records counter snapshot field type feature>>. |
| 334 |
==== |
| 335 |
[source,yaml] |
| 336 |
---- |
| 337 |
$features: |
| 338 |
packet: |
| 339 |
discarded-event-records-counter-snapshot-field-type: false |
| 340 |
event-record-types: |
| 341 |
# ... |
| 342 |
---- |
| 343 |
==== |
| 344 |
|
| 345 |
.Data stream type object with an enabled packet <<seq-num-ft-prop,sequence number field type feature>>. |
| 346 |
==== |
| 347 |
[source,yaml] |
| 348 |
---- |
| 349 |
$features: |
| 350 |
packet: |
| 351 |
sequence-number-field-type: true |
| 352 |
event-record-types: |
| 353 |
# ... |
| 354 |
---- |
| 355 |
==== |
| 356 |
|
| 357 |
.Data stream type object with 16-bit packet <<total-size-ft-prop,total>> and <<content-size-ft-prop,content size field type features>>. |
| 358 |
==== |
| 359 |
[source,yaml] |
| 360 |
---- |
| 361 |
$features: |
| 362 |
packet: |
| 363 |
total-size-field-type: uint16 |
| 364 |
content-size-field-type: uint16 |
| 365 |
event-record-types: |
| 366 |
# ... |
| 367 |
---- |
| 368 |
==== |
| 369 |
|
| 370 |
.Data stream type object with a disabled event record <<ts-prop,timestamp field type feature>>. |
| 371 |
==== |
| 372 |
[source,yaml] |
| 373 |
---- |
| 374 |
$features: |
| 375 |
event-record: |
| 376 |
timestamp-field-type: false |
| 377 |
event-record-types: |
| 378 |
# ... |
| 379 |
---- |
| 380 |
==== |
| 381 |
|
| 382 |
.Data stream type object with <<pkt-ctx-ft-extra-members-prop,packet context field type extra members>>. |
| 383 |
==== |
| 384 |
[source,yaml] |
| 385 |
---- |
| 386 |
packet-context-field-type-extra-members: |
| 387 |
- cur_load: int8 |
| 388 |
- node_id: uint16 |
| 389 |
- node_addr: string |
| 390 |
event-record-types: |
| 391 |
# ... |
| 392 |
---- |
| 393 |
==== |
| 394 |
|
| 395 |
.Data stream type object with an <<er-common-ctx-ft-prop,event record common context field type>>. |
| 396 |
==== |
| 397 |
[source,yaml] |
| 398 |
---- |
| 399 |
event-record-common-context-field-type: |
| 400 |
class: structure |
| 401 |
members: |
| 402 |
- pid: uint32 |
| 403 |
- level: double |
| 404 |
event-record-types: |
| 405 |
# ... |
| 406 |
---- |
| 407 |
==== |
| 408 |
|
| 409 |
.Data stream type object with <<include-prop,inclusions>>. |
| 410 |
==== |
| 411 |
[source,yaml] |
| 412 |
---- |
| 413 |
event-record-types: |
| 414 |
# ... |
| 415 |
$include: |
| 416 |
- project-b-event-record-types.yaml |
| 417 |
- common-data-stream-type-features.yaml |
| 418 |
---- |
| 419 |
==== |