Debian Codegraph @

docs/modules/yaml/pages/dst-obj.adoc

raw
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 ====