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

   1 = YAML clock type object
   2
   3 A _**clock type object**_ is the type of data stream
   4 xref:how-barectf-works:ctf-primer.adoc#def-clk[clocks].
   5
   6 Clock type objects are only found under the
   7 xref:trace-type-obj.adoc#clk-types-prop[`clock-types` property] of a
   8 trace type object.
   9
  10 The only purpose of a clock type is to be a
  11 xref:dst-obj.adoc[data stream type object]'s default
  12 clock type.
  13
  14 [[props]]
  15 == Properties
  16
  17 All the properties are optional.
  18
  19 [%autowidth.stretch, cols="d,d,a,d", role="can-break"]
  20 |===
  21 |Name |Type |Description |Default
  22
  23 |[[freq-prop]]`frequency`
  24 |Integer, greater than{nbsp}0
  25 |Frequency of instances (Hz).
  26 |1,000,000,000 (1{nbsp}GHz)
  27
  28 |[[offset-prop]]`offset`
  29 |<<offset-obj>>
  30 |Offset of instances.
  31 |See <<offset-obj>> for default values.
  32
  33 |`origin-is-unix-epoch`
  34 |Boolean
  35 |True if the origin of instances is the Unix epoch.
  36 |True
  37
  38 |`precision`
  39 |Positive integer
  40 |Precision of instances (cycles).
  41 |0
  42
  43 |`uuid`
  44 |xref:common-values.adoc#uuid[UUID]
  45 |Clock type's UUID.
  46 |No UUID
  47
  48 |`description`
  49 |String
  50 |Clock type's description.
  51 |No description
  52
  53 |[[c-type-prop]]`$c-type`
  54 |String
  55 |Return C{nbsp}type of the clock source function for this clock type.
  56
  57 See xref:platform:index.adoc[] to learn more.
  58 |`uint32_t`
  59
  60 |[[include-prop]]`$include`
  61 |Sequence of strings.
  62 |See xref:include.adoc[].
  63 |No inclusions
  64 |===
  65
  66 [[offset-obj]]
  67 == Clock type offset object
  68
  69 Offset information of a clock type's instances.
  70
  71 === Properties
  72
  73 All the properties are optional.
  74
  75 [%autowidth.stretch, cols="d,d,a,d"]
  76 |===
  77 |Name |Type |Description |Default
  78
  79 |`seconds`
  80 |Integer
  81 |Offset in seconds.
  82 |0
  83
  84 |`cycles`
  85 |Positive integer
  86 |Offset in cycles.
  87 |0
  88 |===
  89
  90 The two properties form an effective offset (from the clock's origin) as
  91 such:
  92
  93 ----
  94 seconds + cycles / frequency
  95 ----
  96
  97 `frequency` is a <<freq-prop,clock type property>>.
  98
  99 == Examples
 100
 101 .Basic 1{nbsp}GHz clock type object.
 102 ====
 103 This empty mapping, when used where a clock type is expected, is a
 104 valid, default clock type.
 105
 106 [source,yaml]
 107 ----
 108 {}
 109 ----
 110 ====
 111
 112 .Basic <<freq-prop,100{nbsp}kHz>> clock type object.
 113 ====
 114 [source,yaml]
 115 ----
 116 frequency: 100000
 117 ----
 118 ====
 119
 120 .Basic <<freq-prop,1{nbsp}GHz>> clock type object with an `unsigned long long` <<c-type-prop,C{nbsp}type>>.
 121 ====
 122 [source,yaml]
 123 ----
 124 $c-type: unsigned long long
 125 ----
 126 ====
 127
 128 .Complete clock type object.
 129 ====
 130 [source,yaml]
 131 ----
 132 frequency: 8000000
 133 offset:
 134   seconds: 1600463226
 135   cycles: 200000
 136 origin-is-unix-epoch: false
 137 precision: 8
 138 uuid: 79e49040-21b5-42d4-a873-677261696e65
 139 description: System clock
 140 $c-type: uint64_t
 141 ----
 142 ====
 143
 144 .Clock type object with an <<include-prop,inclusion>>.
 145 ====
 146 [source,yaml]
 147 ----
 148 $include: [base-clock-type.yaml]
 149 frequency: 8000000
 150 ----
 151 ====