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

   1 = YAML dynamic array field type objects
   2
   3 A _**dynamic array field type object**_ is the type of dynamic
   4 (variable-length) array data fields, found in
   5 xref:how-barectf-works:ctf-primer.adoc#ds[data streams].
   6
   7 A dynamic array data field is a sequence of data fields, or _elements_.
   8 In CTF, the number of elements in a dynamic array data field (its
   9 length) is the value of a prior integer data field.
  10
  11 [[props]]
  12 == Properties
  13
  14 [%autowidth.stretch, cols="d,d,a,d"]
  15 |===
  16 |Name |Type |Description |{req-abbr}
  17
  18 |[[class-prop]]`class`
  19 |String
  20 |This property's value must be `dynamic-array`.
  21 |Yes if the <<inherit-prop,`$inherit`>> property is not set.
  22
  23 include::partial$ft-obj-inherit-prop.adoc[]
  24
  25 |[[element-ft-prop]]`element-field-type`
  26 |xref:ft-obj.adoc[Field type object] (except a
  27 xref:struct-ft-obj.adoc[structure field type object] and a
  28 dynamic array field type object) or string
  29 |Type of each element (data fields) in this field type's instances.
  30
  31 If this property's value is a string, it must be the name of an existing
  32 xref:trace-type-obj.adoc#ft-aliases-prop[field type alias]. This
  33 field type must _not_ be a structure field type or a dynamic array
  34 field type.
  35 |Yes
  36 |===
  37
  38 == Generated C{nbsp}types
  39
  40 barectf always generates two packet opening or tracing function
  41 parameters for a dynamic array field type object. Their C{nbsp}types
  42 are:
  43
  44 Dynamic array's length::
  45     `uint32_t`
  46
  47 Dynamic array's data::
  48     Pointer to `const __T__`, where `__T__` is the generated C{nbsp}type
  49     for the field type object of the
  50     <<element-ft-prop,`element-field-type` property>>.
  51 +
  52 include::partial$array-ft-obj-gen-c-types-example.adoc[]
  53
  54 == Examples
  55
  56 .Dynamic array field type object: 8-bit unsigned xref:int-ft-obj.adoc[integers].
  57 ====
  58 [source,yaml]
  59 ----
  60 class: dynamic-array
  61 element-field-type: uint8
  62 ----
  63 ====
  64
  65 .Dynamic array field type object: xref:str-ft-obj.adoc[strings].
  66 ====
  67 [source,yaml]
  68 ----
  69 class: dynamic-array
  70 element-field-type:
  71   class: string
  72 ----
  73 ====
  74
  75 .Dynamic array field type object: xref:static-array-ft-obj.adoc[static arrays] of 32{nbsp}double-precision xref:real-ft-obj.adoc[reals].
  76 ====
  77 [source,yaml]
  78 ----
  79 class: dynamic-array
  80 element-field-type:
  81   class: static-array
  82   length: 32
  83   element-field-type:
  84     class: real
  85     size: 64
  86 ----
  87 ====