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 Examples:
  53 +
  54 [%autowidth.stretch]
  55 |===
  56 |Element field type |Generated C{nbsp}type
  57
  58 |8-bit unsigned xref:int-ft-obj.adoc[integer]
  59 |`const uint8_t *`
  60
  61 |32-bit signed integer
  62 |`const int32_t *`
  63
  64 |Single-precision xref:real-ft-obj.adoc[real]
  65 |`const float *`
  66
  67 |xref:str-ft-obj.adoc[String]
  68 |`const char * const *`
  69
  70 |Static array of 16-bit signed integers
  71 |`const int16_t * const *`
  72
  73 |Static array of double-precision reals
  74 |`const double * const *`
  75
  76 |Static array of strings
  77 |`const char * const * const *`
  78
  79 |Static array of static arrays of 32-bit unsigned integers
  80 |`const uint32_t * const * const *`
  81 |===
  82
  83 == Examples
  84
  85 .Dynamic array field type object: <<length-prop,four>> 8-bit unsigned xref:int-ft-obj.adoc[integers].
  86 ====
  87 [source,yaml]
  88 ----
  89 class: dynamic-array
  90 length: 4
  91 element-field-type: uint8
  92 ----
  93 ====
  94
  95 .Dynamic array field type object: <<length-prop,22>>{nbsp}xref:str-ft-obj.adoc[strings].
  96 ====
  97 [source,yaml]
  98 ----
  99 class: dynamic-array
 100 length: 22
 101 element-field-type:
 102   class: string
 103 ----
 104 ====
 105
 106 .Dynamic array field type object: <<length-prop,five>> xref:static-array-ft-obj.adoc[static arrays] of 32{nbsp}double-precision xref:real-ft-obj.adoc[reals].
 107 ====
 108 [source,yaml]
 109 ----
 110 class: dynamic-array
 111 length: 5
 112 element-field-type:
 113   class: static-array
 114   length: 32
 115   element-field-type:
 116     class: real
 117     size: 64
 118 ----
 119 ====