-Common Trace Format (CTF) Specification (pre-v1.8)
+Common Trace Format (CTF) Specification (v1.8.2)
Mathieu Desnoyers, EfficiOS Inc.
3. Event stream
An event stream can be divided into contiguous event packets of variable
-size. These subdivisions have a variable size. An event packet can
-contain a certain amount of padding at the end. The stream header is
-repeated at the beginning of each event packet. The rationale for the
-event stream design choices is explained in Appendix B. Stream Header
-Rationale.
+size. An event packet can contain a certain amount of padding at the
+end. The stream header is repeated at the beginning of each event
+packet. The rationale for the event stream design choices is explained
+in Appendix B. Stream Header Rationale.
The event stream header will therefore be referred to as the "event packet
header" throughout the rest of this document.
4.1.3 Byte order
-By default, the native endianness of the source architecture the trace is used.
+By default, the native endianness of the source architecture is used.
Byte order can be overridden for a basic type by specifying a "byte_order"
attribute. Typical use-case is to specify the network byte order (big endian:
"be") to save data captured from the network into the trace without conversion.
};
If the values are omitted, the enumeration starts at 0 and increment of 1 for
-each entry:
+each entry. An entry with omitted value that follows a range entry takes
+as value the end_value of the previous range + 1:
enum name : unsigned int {
ZERO,
specified between "< >" after the "variant" keyword for unnamed
variants, and after "variant name" for named variants.
-The alignment of the variant is the alignment of the type as selected by the tag
-value for the specific instance of the variant. The alignment of the type
-containing the variant is independent of the variant alignment. The size of the
-variant is the size as selected by the tag value for the specific instance of
-the variant.
+The alignment of the variant is the alignment of the type as selected by
+the tag value for the specific instance of the variant. The size of the
+variant is the size as selected by the tag value for the specific
+instance of the variant.
+
+The alignment of the type containing the variant is independent of the
+variant alignment. For instance, if a structure contains two fields, a
+32-bit integer, aligned on 32 bits, and a variant, which contains two
+choices: either a 32-bit field, aligned on 32 bits, or a 64-bit field,
+aligned on 64 bits, the alignment of the outmost structure will be
+32-bit (the alignment of its largest field, disregarding the alignment
+of the variant). The alignment of the variant will depend on the
+selector: if the variant's 32-bit field is selected, its alignment will
+be 32-bit, or 64-bit otherwise. It is important to note that variants
+are specifically tailored for compactness in a stream. Therefore, the
+relative offsets of compound type fields can vary depending on
+the offset at which the compound type starts if it contains a variant
+that itself contains a type with alignment larger than the largest field
+contained within the compound type. This is caused by the fact that the
+compound type may contain the enumeration that select the variant's
+choice, and therefore the alignment to be applied to the compound type
+cannot be determined before encountering the enumeration.
Each variant type selector possess a field name, which is a unique
identifier within the variant. The identifier is not allowed to use any
include all event timestamps assigned to events contained within the packet.
- Events discarded count
- Snapshot of a per-stream free-running counter, counting the number of
- events discarded that were supposed to be written in the stream prior to
- the first event in the event packet.
- * Note: producer-consumer buffer full condition should fill the current
+ events discarded that were supposed to be written in the stream after
+ the last event in the event packet.
+ * Note: producer-consumer buffer full condition can fill the current
event packet with padding so we know exactly where events have been
- discarded.
+ discarded. However, if the buffer full condition chooses not
+ to fill the current event packet with padding, all we know
+ about the timestamp range in which the events have been
+ discarded is that it is somewhere between the beginning and
+ the end of the packet.
- Lossless compression scheme used for the event packet content. Applied
directly to raw data. New types of compression can be added in following
versions of the format.
uint32_t stream_packet_count;
uint32_t events_discarded;
uint32_t cpu_id;
- uint32_t/uint16_t content_size;
- uint32_t/uint16_t packet_size;
+ uint64_t/uint32_t/uint16_t content_size;
+ uint64_t/uint32_t/uint16_t packet_size;
uint8_t compression_scheme;
uint8_t encryption_scheme;
uint8_t checksum_scheme;
endianness of the architecture by trying to read the CTF magic number
and its counterpart in reversed endianness. The events within the
meta-data stream have no event header nor event context. Each event only
-contains a "sequence" payload, which is a sequence of bits using the
-"trace.packet.header.content_size" field as a placeholder for its length
-(the packet header size should be substracted). The formatting of this
-sequence of bits is a plain-text representation of the TSDL description.
-Each meta-data packet start with a special packet header, specific to
-the meta-data stream, which contains, exactly:
+contains a special "sequence" payload, which is a sequence of bits which
+length is implicitly calculated by using the
+"trace.packet.header.content_size" field, minus the packet header size.
+The formatting of this sequence of bits is a plain-text representation
+of the TSDL description. Each meta-data packet start with a special
+packet header, specific to the meta-data stream, which contains,
+exactly:
struct metadata_packet_header {
uint32_t magic; /* 0x75D11D57 */
};
The packet-based meta-data can be converted to a text-only meta-data by
-concatenating all the strings in contains.
+concatenating all the strings it contains.
In the textual representation of the meta-data, the text contained
within "/*" and "*/", as well as within "//" and end of line, are
7.3.1 Lexical Scope
-Each of "trace", "stream", "event", "struct" and "variant" have their own
-nestable declaration scope, within which types can be declared using "typedef"
-and "typealias". A root declaration scope also contains all declarations
-located outside of any of the aforementioned declarations. An inner
-declaration scope can refer to type declared within its container
-lexical scope prior to the inner declaration scope. Redefinition of a
-typedef or typealias is not valid, although hiding an upper scope
-typedef or typealias is allowed within a sub-scope.
+Each of "trace", "env", "stream", "event", "struct" and "variant" have
+their own nestable declaration scope, within which types can be declared
+using "typedef" and "typealias". A root declaration scope also contains
+all declarations located outside of any of the aforementioned
+declarations. An inner declaration scope can refer to type declared
+within its container lexical scope prior to the inner declaration scope.
+Redefinition of a typedef or typealias is not valid, although hiding an
+upper scope typedef or typealias is allowed within a sub-scope.
7.3.2 Static and Dynamic Scopes
The dynamic scope prefixes are thus:
+ - Trace Environment: <env. >,
- Trace Packet Header: <trace.packet.header. >,
- Stream Packet Context: <stream.packet.context. >,
- Event Header: <stream.event.header. >,
in a stream.
trace {
- major = value; /* Trace format version */
- minor = value;
+ major = value; /* CTF spec version major number */
+ minor = value; /* CTF spec version minor number */
uuid = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"; /* Trace UUID */
byte_order = be OR le; /* Endianness (required) */
packet.header := struct {
};
};
+/*
+ * The "env" (environment) scope contains assignment expressions. The
+ * field names and content are implementation-defined.
+ */
+env {
+ pid = value; /* example */
+ proc_name = "name"; /* example */
+ ...
+};
+
stream {
id = stream_id;
/* Type 1 - Few event IDs; Type 2 - Many event IDs. See section 6.1. */
name = "event_name";
id = value; /* Numeric identifier within the stream */
stream_id = stream_id;
- loglevel.identifier = "loglevel_identifier";
- loglevel.value = value;
+ loglevel = value;
+ model.emf.uri = "string";
context := struct {
...
};
};
};
+callsite {
+ name = "event_name";
+ func = "func_name";
+ file = "myfile.c";
+ line = 39;
+ ip = 0x40096c;
+};
+
/* More detail on types in section 4. Types */
/*
keyword: is one of
align
+callsite
const
char
clock
double
enum
+env
event
floating_point
float
2.3) CTF-specific declarations
ctf-specifier:
+ clock { ctf-assignment-expression-list-opt }
event { ctf-assignment-expression-list-opt }
stream { ctf-assignment-expression-list-opt }
+ env { ctf-assignment-expression-list-opt }
trace { ctf-assignment-expression-list-opt }
+ callsite { ctf-assignment-expression-list-opt }
typealias declaration-specifiers abstract-declarator-list type-assignment-operator declaration-specifiers abstract-declarator-list
typealias declaration-specifiers abstract-declarator-list type-assignment-operator declarator-list