Debian Codegraph @

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

raw
1 = YAML field type object
2
3 A _**field type object**_ is the type of data field, found in
4 xref:how-barectf-works:ctf-primer.adoc#ds[data streams].
5
6 A field type object describes what a CTF consumer needs to decode a data
7 field.
8
9 You can use a xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]
10 name (a string) anywhere a field type object is expected.
11
12 == Expected usage locations
13
14 A field type object is expected at the following locations:
15
16 Within another field type object::
17 +
18 --
19 * The xref:struct-ft-obj.adoc#member-ft-prop[`field-type` property]
20 of a structure field type member object.
21
22 * The `element-field-type` property of a
23 xref:static-array-ft-obj.adoc#element-ft-prop[static] or
24 xref:dyn-array-ft-obj.adoc#element-ft-prop[dynamic field type object].
25 --
26
27 Within a xref:trace-type-obj.adoc[trace type object]::
28 +
29 --
30 * A value of a xref:trace-type-obj.adoc#ft-aliases-prop[field type
31 alias] mapping entry.
32
33 * Any property of a
34 xref:trace-type-obj.adoc#features-obj[features object].
35 --
36
37 Within a xref:dst-obj.adoc[data stream type object]::
38 +
39 --
40 * Any property of a
41 xref:dst-obj.adoc#pkt-features-obj[packet features object].
42
43 * Any property of an
44 xref:dst-obj.adoc#er-features-obj[event record features object].
45
46 * The
47 xref:dst-obj.adoc#er-common-ctx-ft-prop[`event-record-common-context-field-type`
48 property].
49 --
50
51 Within an xref:ert-obj.adoc[event record type object]::
52 +
53 --
54 * The xref:ert-obj.adoc#spec-ctx-ft-prop[`specific-context-field-type`
55 property].
56
57 * The xref:ert-obj.adoc#payload-ft-prop[`payload-field-type`
58 property].
59 --
60
61 == Available field type objects
62
63 As of barectf{nbsp}{page-component-version}, the available field type
64 objects are:
65
66 xref:int-ft-obj.adoc[Integer field type objects]::
67 Describes unsigned and signed integer data fields.
68
69 xref:enum-ft-obj.adoc[Enumeration field type objects]::
70 Describes unsigned and signed enumeration data fields.
71
72 xref:real-ft-obj.adoc[Real field type object]::
73 Describes single-precision and double-precision real data fields.
74
75 xref:str-ft-obj.adoc[String field type object]::
76 Describes null-terminated string data fields.
77
78 xref:struct-ft-obj.adoc[Structure field type object]::
79 Describes structure data fields.
80
81 xref:static-array-ft-obj.adoc[Static array field type object]::
82 Describes array data fields with a static length.
83
84 xref:dyn-array-ft-obj.adoc[Dynamic array field type object]::
85 Describes array data fields with a dynamic (variable) length.
86
87 [[gen-c-types]]
88 == Generated C{nbsp}types
89
90 barectf uses configured field types to generate user data parameters of
91 packet opening and tracing functions.
92
93 Each field type object page indicates the field type's corresponding
94 C{nbsp}type(s).
95
96 Here's a summary:
97
98 [%autowidth.stretch, cols="d,a"]
99 |===
100 |Field type |C type
101
102 |Unsigned
103 xref:int-ft-obj.adoc[integer]/xref:enum-ft-obj.adoc[enumeration field
104 type]
105 |Depending on the `size` property:
106
107 [1,{nbsp}8]::
108 `uint8_t`
109
110 [9,{nbsp}16]::
111 `uint16_t`
112
113 [17,{nbsp}32]::
114 `uint32_t`
115
116 [33,{nbsp}64]::
117 `uint64_t`
118
119 |Signed
120 xref:int-ft-obj.adoc[integer]/xref:enum-ft-obj.adoc[enumeration field
121 type]
122 |Depending on the `size` property:
123
124 [1,{nbsp}8]::
125 `int8_t`
126
127 [9,{nbsp}16]::
128 `int16_t`
129
130 [17,{nbsp}32]::
131 `int32_t`
132
133 [33,{nbsp}64]::
134 `int64_t`
135
136 |xref:real-ft-obj.adoc[Real field type]
137 |Depending on the xref:real-ft-obj.adoc#size-prop[`size` property]:
138
139 32::
140 `float`
141
142 64::
143 `double`
144
145 |xref:str-ft-obj.adoc[String field type]
146 |`const char *`
147
148 |xref:static-array-ft-obj.adoc[Static array field type]
149 |Pointer to `const __T__`, where `__T__` is the generated C{nbsp}type
150 for the field type object of the
151 xref:static-array-ft-obj.adoc#element-ft-prop[`element-field-type`
152 property].
153
154 |xref:dyn-array-ft-obj.adoc[Dynamic array field type]
155 |Two adjacent parameters:
156
157 Dynamic length::
158 `uint32_t`
159
160 Element::
161 Pointer to `const __T__`, where `__T__` is the generated C{nbsp}type
162 for the field type object of the
163 xref:dyn-array-ft-obj.adoc#element-ft-prop[`element-field-type`
164 property].
165 |===
166
167 [[inherit]]
168 == Inherit a field type object
169
170 A field type object can _inherit_ the properties of another field type
171 object with the common <<inherit-prop,`$inherit` property>>.
172
173 When a field type object __**A**__ inherits another field type object
174 __**B**__, the _effective_ field type object is __**A**__ "`patching`"
175 __**B**__.
176
177 include::partial$patching-rules-table.adoc[]
178
179 === Examples
180
181 In the examples below, the name of the base field type object's alias is
182 `base`.
183
184 .Override scalar property.
185 ====
186 .Base field type object
187 [source,yaml]
188 ----
189 class: unsigned-integer
190 size: 32
191 alignment: 8
192 ----
193
194 .Overlay field type object
195 [source,yaml]
196 ----
197 $inherit: base
198 size: 16
199 ----
200
201 .Effective field type object
202 [source,yaml]
203 ----
204 class: unsigned-integer
205 size: 16
206 alignment: 8
207 ----
208 ====
209
210 .Add and override scalar properties.
211 ====
212 .Base field type object
213 [source,yaml]
214 ----
215 class: unsigned-integer
216 size: 32
217 alignment: 8
218 ----
219
220 .Overlay field type object
221 [source,yaml]
222 ----
223 $inherit: base
224 size: 16
225 preferred-display-base: hexadecimal
226 ----
227
228 .Effective field type object
229 [source,yaml]
230 ----
231 class: unsigned-integer
232 size: 16
233 alignment: 8
234 preferred-display-base: hexadecimal
235 ----
236 ====
237
238 .Append to sequence property.
239 ====
240 .Base field type object
241 [source,yaml]
242 ----
243 class: signed-enumeration
244 mappings:
245 COMPOSE:
246 - 56
247 - [100, 299]
248 DIRTY: [0]
249 ----
250
251 .Overlay field type object
252 [source,yaml]
253 ----
254 $inherit: base
255 size: 16
256 mappings:
257 COMPOSE:
258 - -22
259 ----
260
261 .Effective field type object
262 [source,yaml]
263 ----
264 class: signed-enumeration
265 size: 16
266 mappings:
267 COMPOSE:
268 - 56
269 - [100, 299]
270 - -22
271 DIRTY: [0]
272 ----
273 ====
274
275 .Add to nested mapping property.
276 ====
277 .Base field type object
278 [source,yaml]
279 ----
280 class: structure
281 members:
282 - msg: string
283 - user_id: uint16
284 ----
285
286 .Overlay field type object
287 [source,yaml]
288 ----
289 $inherit: base
290 members:
291 - src_ip_addr:
292 field-type:
293 class: static-array
294 length: 4
295 element-field-type: uint8
296 - user_id: int8
297 ----
298
299 .Effective field type object
300 [source,yaml]
301 ----
302 class: structure
303 members:
304 - msg: string
305 - user_id: int8
306 - src_ip_addr:
307 field-type:
308 class: static-array
309 length: 4
310 element-field-type: uint8
311 ----
312 ====
313
314 [[props]]
315 == Common properties
316
317 All field type objects require that the <<class-prop,`class`>> _or_ the
318 <<inherit-prop,`$inherit` property>> be set, but not both.
319
320 [%autowidth.stretch, cols="d,d,a,d"]
321 |===
322 |Name |Type |Description |Required?
323
324 |[[class-prop]]`class`
325 |String
326 |Class of this field type amongst:
327
328 `unsigned-integer`::
329 `unsigned-int`::
330 `uint`::
331 Unsigned xref:int-ft-obj.adoc[integer field type]
332
333 `signed-integer`::
334 `signed-int`::
335 `sint`::
336 Signed xref:int-ft-obj.adoc[integer field type]
337
338 `unsigned-enumeration`::
339 `unsigned-enum`::
340 `uenum`::
341 Unsigned xref:enum-ft-obj.adoc[enumeration field type]
342
343 `signed-enumeration`::
344 `signed-enum`::
345 `senum`::
346 Signed xref:enum-ft-obj.adoc[enumeration field type]
347
348 `real`::
349 xref:real-ft-obj.adoc[Real field type]
350
351 `string`::
352 `str`::
353 xref:str-ft-obj.adoc[String field type]
354
355 `structure`::
356 `struct`::
357 xref:struct-ft-obj.adoc[Structure field type]
358
359 `static-array`::
360 xref:static-array-ft-obj.adoc[Static array field type]
361
362 `dynamic-array`::
363 xref:dyn-array-ft-obj.adoc[Dynamic array field type]
364 |Yes if the <<inherit-prop,`$inherit`>> property is not set.
365
366 |[[inherit-prop]]`$inherit`
367 |String
368 |Name of a xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]
369 from which to <<inherit,inherit>>.
370 |Yes if the <<class-prop,`class`>> property is not set.
371 |===