| 1 |
= YAML structure field type objects |
| 2 |
|
| 3 |
A _**structure field type object**_ is the type of structure data |
| 4 |
fields, found in xref:how-barectf-works:ctf-primer.adoc#ds[data |
| 5 |
streams]. |
| 6 |
|
| 7 |
A structure data field is a sequence of named data fields, or |
| 8 |
_members_. In CTF, the names of those members are found in the |
| 9 |
xref:how-barectf-works:ctf-primer.adoc#trace[metadata stream]. |
| 10 |
|
| 11 |
[[props]] |
| 12 |
== Properties |
| 13 |
|
| 14 |
[%autowidth.stretch, cols="d,a,a,d,a"] |
| 15 |
|=== |
| 16 |
|Name |Type |Description |{req-abbr} |Default |
| 17 |
|
| 18 |
|[[class-prop]]`class` |
| 19 |
|String |
| 20 |
|This property's value must be one of: |
| 21 |
|
| 22 |
* `structure` |
| 23 |
* `struct` |
| 24 |
|Yes if the <<inherit-prop,`$inherit`>> property is not set. |
| 25 |
| |
| 26 |
|
| 27 |
include::partial$ft-obj-inherit-prop.adoc[] |
| 28 |
| |
| 29 |
|
| 30 |
|[[min-align-prop]]`minimum-alignment` |
| 31 |
|Power-of-two integer |
| 32 |
|_Minimum_ alignment of the first bit of this field type's instances |
| 33 |
within a xref:how-barectf-works:ctf-primer.adoc#pkt[CTF{nbsp}packet] |
| 34 |
(bits). |
| 35 |
|No |
| 36 |
|1 |
| 37 |
|
| 38 |
|[[members-prop]]`members` |
| 39 |
|Sequence of mappings, where each mapping has a single entry: |
| 40 |
|
| 41 |
Key:: |
| 42 |
Member's name. |
| 43 |
|
| 44 |
Value:: |
| 45 |
<<struct-ft-member-obj,Structure field type member object>> |
| 46 |
or string. |
| 47 |
|
| 48 |
This sequence is considered to be an _ordered mapping_, similar to |
| 49 |
YAML's https://yaml.org/type/omap.html[`+!!omap+`] type. Therefore, |
| 50 |
each mapping key must be unique. |
| 51 |
|Members of this structure field type. |
| 52 |
|
| 53 |
If a mapping's value is a string, it must be the name of an existing |
| 54 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. This |
| 55 |
field type must _not_ be a structure field type. |
| 56 |
|No |
| 57 |
|No members |
| 58 |
|=== |
| 59 |
|
| 60 |
[[struct-ft-member-obj]] |
| 61 |
== Structure field type member object |
| 62 |
|
| 63 |
A member within a structure field type object. |
| 64 |
|
| 65 |
=== Properties |
| 66 |
|
| 67 |
[%autowidth.stretch, cols="d,d,a,d"] |
| 68 |
|=== |
| 69 |
|Name |Type |Description |{req-abbr} |
| 70 |
|
| 71 |
|[[member-ft-prop]]`field-type` |
| 72 |
|xref:ft-obj.adoc[Field type object] (except a structure field type |
| 73 |
object) or string |
| 74 |
|Member's field type. |
| 75 |
|
| 76 |
If this property's value is a string, it must be the name of an existing |
| 77 |
xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. This |
| 78 |
field type must _not_ be a structure field type. |
| 79 |
|Yes |
| 80 |
|=== |
| 81 |
|
| 82 |
== Examples |
| 83 |
|
| 84 |
.Basic structure field type object with no <<members-prop,members>>. |
| 85 |
==== |
| 86 |
[source,yaml] |
| 87 |
---- |
| 88 |
class: structure |
| 89 |
---- |
| 90 |
==== |
| 91 |
|
| 92 |
.Structure field type object with three <<members-prop,members>> using xref:trace-type-obj.adoc#ft-aliases-prop[field type aliases]. |
| 93 |
==== |
| 94 |
[source,yaml] |
| 95 |
---- |
| 96 |
class: structure |
| 97 |
members: |
| 98 |
- msg: string |
| 99 |
- msg_id: uint32 |
| 100 |
- src_ip_addr: ipv4 |
| 101 |
---- |
| 102 |
==== |
| 103 |
|
| 104 |
.Structure field type object with one <<struct-ft-member-obj,member object>>. |
| 105 |
==== |
| 106 |
[source,yaml] |
| 107 |
---- |
| 108 |
class: structure |
| 109 |
members: |
| 110 |
- msg: string |
| 111 |
- msg_id: |
| 112 |
field-type: |
| 113 |
class: unsigned-integer |
| 114 |
size: 32 |
| 115 |
- src_ip_addr: ipv4 |
| 116 |
---- |
| 117 |
==== |
| 118 |
|
| 119 |
.Structure field type object with an explicit <<min-align-prop,minimum alignment>>. |
| 120 |
==== |
| 121 |
[source,yaml] |
| 122 |
---- |
| 123 |
class: structure |
| 124 |
minimum-alignment: 64 |
| 125 |
members: |
| 126 |
- msg: string |
| 127 |
- msg_id: uint32 |
| 128 |
- src_ip_addr: ipv4 |
| 129 |
---- |
| 130 |
==== |