Debian Codegraph @

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

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