| 1 |
= CTF primer |
| 2 |
|
| 3 |
The https://diamon.org/ctf/[_**Common Trace Format**_] (CTF) is a binary |
| 4 |
https://en.wikipedia.org/wiki/Tracing_(software)[trace] format which is |
| 5 |
designed to be very fast to write while offering many field types to |
| 6 |
represent data. |
| 7 |
|
| 8 |
A barectf configuration can use the following CTF field types: |
| 9 |
|
| 10 |
* Unsigned/signed xref:yaml:int-ft-obj.adoc[integer] (1 to 64 bits). |
| 11 |
* Unsigned/signed xref:yaml:enum-ft-obj.adoc[enumeration] (1 to |
| 12 |
64 bits). |
| 13 |
* xref:yaml:real-ft-obj.adoc[Real] (single or double precision). |
| 14 |
* Null-terminated xref:yaml:str-ft-obj.adoc[string]. |
| 15 |
* xref:yaml:struct-ft-obj.adoc[Structure] (zero or more named members). |
| 16 |
* xref:yaml:static-array-ft-obj.adoc[Static array] of any field type |
| 17 |
except structure and dynamic array. |
| 18 |
* xref:yaml:dyn-array-ft-obj.adoc[Dynamic array] of any field type |
| 19 |
except structure and dynamic array. |
| 20 |
|
| 21 |
CTF makes it possible to describe the alignment and byte order of |
| 22 |
integer, enumeration, and real fields. |
| 23 |
|
| 24 |
A system which produces CTF streams is known as a _CTF producer_. |
| 25 |
|
| 26 |
A system which consumes CTF streams is known as a _CTF consumer_. |
| 27 |
|
| 28 |
[[trace]] |
| 29 |
== CTF trace structure |
| 30 |
|
| 31 |
A _**CTF trace**_ is exactly one metadata stream and one or more |
| 32 |
<<ds,data streams>>: |
| 33 |
|
| 34 |
[.width-50] |
| 35 |
image::ctf-trace.svg[] |
| 36 |
|
| 37 |
The metadata stream describes the trace's data streams with TSDL |
| 38 |
(Trace Stream Description Language). On the file system, its file name |
| 39 |
must be `metadata`. |
| 40 |
|
| 41 |
The metadata stream describes things such as: |
| 42 |
|
| 43 |
* The xref:yaml:clk-type-obj.adoc[type] of the data stream default clocks. |
| 44 |
* The names of xref:yaml:ert-obj.adoc[event record types]. |
| 45 |
* The types of event record fields. |
| 46 |
* The xref:yaml:trace-obj.adoc[trace]'s environment variables. |
| 47 |
|
| 48 |
[[ds]] |
| 49 |
=== Data stream |
| 50 |
|
| 51 |
A _**CTF data stream**_ is a sequence of one or more data |
| 52 |
<<pkt,packets>>: |
| 53 |
|
| 54 |
[.width-100] |
| 55 |
image::ctf-trace-all.svg[] |
| 56 |
|
| 57 |
A xref:yaml:dst-obj.adoc[data stream type] describes data streams. |
| 58 |
|
| 59 |
A packet contains one or more bytes of data. |
| 60 |
|
| 61 |
Although a packet can contain padding itself, from the data stream's |
| 62 |
point of view, there's no padding between packets. |
| 63 |
|
| 64 |
A data stream can have, conceptually: |
| 65 |
|
| 66 |
[[def-clk]]A default clock:: |
| 67 |
Described by a xref:yaml:clk-type-obj.adoc[clock type] in the trace's |
| 68 |
metadata stream. |
| 69 |
+ |
| 70 |
<<pkt,Packets>> and event records can contain snapshots, named |
| 71 |
_timestamps_, of their data stream's clock. |
| 72 |
|
| 73 |
[[disc-er-counter]]A counter of discarded event records:: |
| 74 |
Indicates the number of event records which the generated tracer |
| 75 |
needed to discard for different reasons. |
| 76 |
+ |
| 77 |
For example, the tracer discards an event record when it doesn't fit the |
| 78 |
current packet and the back end is full (see |
| 79 |
xref:platform:index.adoc[]). |
| 80 |
+ |
| 81 |
A <<pkt,packet>> can contain a snapshot of this counter. |
| 82 |
|
| 83 |
On the file system, a data stream file: |
| 84 |
|
| 85 |
* Can have any name, except `metadata` and anything which begins with |
| 86 |
`.`. |
| 87 |
|
| 88 |
* Must be in the same directory as the `metadata` file. |
| 89 |
|
| 90 |
[[pkt]] |
| 91 |
=== Packet |
| 92 |
|
| 93 |
A _**CTF packet**_ is a part of a <<ds,data stream>>. |
| 94 |
|
| 95 |
A packet contains, in this order: |
| 96 |
|
| 97 |
. [.opt]##Optional##A header structure field, which contains: |
| 98 |
+ |
| 99 |
** [.opt]##Optional##The CTF magic number. |
| 100 |
+ |
| 101 |
See the trace type features object's |
| 102 |
xref:yaml:trace-type-obj.adoc#magic-ft-prop[`magic-field-type` |
| 103 |
property]. |
| 104 |
|
| 105 |
** [.opt]##Optional##A trace type |
| 106 |
https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID]. |
| 107 |
+ |
| 108 |
See the trace type object's |
| 109 |
xref:yaml:trace-type-obj.adoc#uuid-prop[`uuid` property] and the |
| 110 |
trace type features object's |
| 111 |
xref:yaml:trace-type-obj.adoc#uuid-ft-prop[`uuid-field-type` |
| 112 |
property]. |
| 113 |
|
| 114 |
** [.opt]##Optional##The numeric ID of the data stream type which, in the |
| 115 |
metadata stream, describes this packet's data stream. |
| 116 |
+ |
| 117 |
See the trace type features object's |
| 118 |
xref:yaml:trace-type-obj.adoc#dst-id-ft-prop[`data-stream-type-id-field-type` |
| 119 |
property]. |
| 120 |
|
| 121 |
** [.opt]##Optional##The numeric ID of this packet's data stream. |
| 122 |
|
| 123 |
. A context structure field, which contains: |
| 124 |
+ |
| 125 |
** The packet's total size, in bits (always a multiple of{nbsp}8). |
| 126 |
+ |
| 127 |
See the data stream type packet features object's |
| 128 |
xref:yaml:dst-obj.adoc#total-size-ft-prop[`total-size-field-type` |
| 129 |
property]. |
| 130 |
|
| 131 |
** The packet's content size, in bits. |
| 132 |
+ |
| 133 |
See the data stream type packet features object's |
| 134 |
xref:yaml:dst-obj.adoc#content-size-ft-prop[`content-size-field-type` |
| 135 |
property]. |
| 136 |
|
| 137 |
** [.opt]##Optional##The packet's beginning timestamp. |
| 138 |
+ |
| 139 |
See the data stream type packet features object's |
| 140 |
xref:yaml:dst-obj.adoc#beginning-ts-ft-prop[`beginning-timestamp-field-type` |
| 141 |
property]. |
| 142 |
|
| 143 |
** [.opt]##Optional##The packet's end timestamp. |
| 144 |
+ |
| 145 |
See the data stream type packet features object's |
| 146 |
xref:yaml:dst-obj.adoc#end-ts-ft-prop[`end-timestamp-field-type` |
| 147 |
property]. |
| 148 |
|
| 149 |
** [.opt]##Optional##A discarded event record counter snapshot. |
| 150 |
+ |
| 151 |
See the data stream type packet features object's |
| 152 |
xref:yaml:dst-obj.adoc#disc-er-counter-snapshot-ft-prop[`discarded-event-records-counter-snapshot-field-type` |
| 153 |
property]. |
| 154 |
|
| 155 |
** [.opt]##Optional##A packet sequence number (within its <<ds,data |
| 156 |
stream>>). |
| 157 |
+ |
| 158 |
See the data stream type packet features object's |
| 159 |
xref:yaml:dst-obj.adoc#seq-num-ft-prop[`sequence-number-field-type` |
| 160 |
property]. |
| 161 |
|
| 162 |
** [.opt]##Optional##User fields. |
| 163 |
+ |
| 164 |
See the data stream type object's |
| 165 |
xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[`packet-context-field-type-extra-members` |
| 166 |
property]. |
| 167 |
|
| 168 |
. Zero or more <<er,event records>>. |
| 169 |
|
| 170 |
A packet contains one or more bytes of data. |
| 171 |
|
| 172 |
A packet can have padding (garbage data) after its last event record if |
| 173 |
its total size is different from its content size. |
| 174 |
|
| 175 |
[[er]] |
| 176 |
=== Event record |
| 177 |
|
| 178 |
A _**CTF event record**_ is the result of a tracer writing a |
| 179 |
time-stamped record with user data when an event occurs during a user |
| 180 |
application's execution. |
| 181 |
|
| 182 |
An xref:yaml:ert-obj.adoc[event record type] describes event records. |
| 183 |
|
| 184 |
An event record contains, in this order: |
| 185 |
|
| 186 |
. [.opt]##Optional##A header structure field, which contains: |
| 187 |
+ |
| 188 |
** [.opt]##Optional##The numeric ID of the event record type which, in the |
| 189 |
metadata stream, describes this event record. |
| 190 |
+ |
| 191 |
See the data stream type event record features object's |
| 192 |
xref:yaml:dst-obj.adoc#type-id-ft-prop[`type-id-field-type` property]. |
| 193 |
|
| 194 |
** [.opt]##Optional##A timestamp. |
| 195 |
+ |
| 196 |
See the data stream type event record features object's |
| 197 |
xref:yaml:dst-obj.adoc#ts-prop[`timestamp-field-type` property]. |
| 198 |
|
| 199 |
. [.opt]##Optional##A common context structure field, which contains |
| 200 |
user fields. |
| 201 |
+ |
| 202 |
See the data stream type object's |
| 203 |
xref:yaml:dst-obj.adoc#er-common-ctx-ft-prop[`event-record-common-context-field-type` |
| 204 |
property]. |
| 205 |
|
| 206 |
. [.opt]##Optional##A specific context structure field, which contains user |
| 207 |
fields. |
| 208 |
+ |
| 209 |
See the event record type object's |
| 210 |
xref:yaml:ert-obj.adoc#spec-ctx-ft-prop[`specific-context-field-type` |
| 211 |
property]. |
| 212 |
|
| 213 |
. [.opt]##Optional##A payload structure field, which contains user |
| 214 |
fields. |
| 215 |
+ |
| 216 |
See the event record type object's |
| 217 |
xref:yaml:ert-obj.adoc#payload-ft-prop[`payload-field-type` property]. |