-Common Trace Format (CTF) Specification (v1.8.1)
+Common Trace Format (CTF) Specification (v1.8.2)
Mathieu Desnoyers, EfficiOS Inc.
4.1.6 GNU/C bitfields
4.1.7 Floating point
4.1.8 Enumerations
-4.2 Compound types
- 4.2.1 Structures
- 4.2.2 Variants (Discriminated/Tagged Unions)
- 4.2.3 Arrays
- 4.2.4 Sequences
- 4.2.5 Strings
+ 4.2 Compound types
+ 4.2.1 Structures
+ 4.2.2 Variants (Discriminated/Tagged Unions)
+ 4.2.3 Arrays
+ 4.2.4 Sequences
+ 4.2.5 Strings
5. Event Packet Header
5.1 Event Packet Header Description
5.2 Event Packet Context Description
6.1 Event Header
6.1.1 Type 1 - Few event IDs
6.1.2 Type 2 - Many event IDs
- 6.2 Event Context
+ 6.2 Stream Event Context and Event Context
6.3 Event Payload
6.3.1 Padding
6.3.2 Alignment
explicitly. Alignment values must be power of two. Compound types are
aligned as specified in their individual specification.
+The base offset used for field alignment is the start of the packet
+containing the field. For instance, a field aligned on 32-bit needs to
+be at an offset multiple of 32-bit from the start of the packet that
+contains it.
+
TSDL meta-data attribute representation of a specific alignment:
align = value; /* value in bits */
4.1.3 Byte order
-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 not specified, the byte order is native.
+By default, byte order of a basic type is the byte order described in
+the trace description. It can be overridden by specifying a
+"byte_order" attribute for a basic type. 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.
TSDL meta-data representation:
byte_order = native OR network OR be OR le; /* network and be are aliases */
+The "native" keyword selects the byte order described in the trace
+description. The "network" byte order is an alias for big endian.
+
+Even though the trace description section is not per se a type, for sake
+of clarity, it should be noted that "native" and "network" byte orders
+are only allowed within type declaration. The byte_order specified in
+the trace description section only accepts "be" or "le" values.
+
4.1.4 Size
Type size, in bits, for integers and floats is that returned by "sizeof()" in C
integers with alignment and/or size that are _not_ a multiple of the
byte size are permitted; these correspond to the C99 standard bitfields,
with the added specification that the CTF integer bitfields have a fixed
-binary representation. A MIT-licensed reference implementation of the
-CTF portable bitfields is available at:
+binary representation. Integer size needs to be a positive integer.
+Integers of size 0 are forbidden. A MIT-licensed reference
+implementation of the CTF portable bitfields is available at:
http://git.efficios.com/?p=babeltrace.git;a=blob;f=include/babeltrace/bitfield.h
size = value; /* value in bits, no default */
align = value; /* value in bits */
/* based used for pretty-printing output, default: decimal. */
- base = decimal OR dec OR OR d OR i OR u OR 10 OR hexadecimal OR hex OR x OR X OR p OR 16
+ base = decimal OR dec OR d OR i OR u OR 10 OR hexadecimal OR hex OR x OR X OR p OR 16
OR octal OR oct OR o OR 8 OR binary OR b OR 2;
/* character encoding, default: none */
encoding = none or UTF8 or ASCII;
"value -> string" mappings, these enumerations map
"[ start_value ... end_value ] -> string", which map inclusive ranges of
values to strings. An enumeration from the C language can be represented in
-this format by having the same start_value and end_value for each element, which
-is in fact a range of size 1. This single-value range is supported without
-repeating the start and end values with the value = string declaration.
+this format by having the same start_value and end_value for each
+mapping, which is in fact a range of size 1. This single-value range is
+supported without repeating the start and end values with the value =
+string declaration. Enumerations need to contain at least one entry.
enum name : integer_type {
somestring = start_value1 ... end_value1,
type (for compatibility with C99). The "int" type must be previously
declared. E.g.:
-typealias integer { size = 32; align = 32; signed = true } := int;
+typealias integer { size = 32; align = 32; signed = true; } := int;
enum {
...
always be defined within the scope of a structure or within fields
contained within a structure (defined recursively). A "tag" enumeration
field must appear in either the same static scope, prior to the variant
-field (in field declaration order), in an upper static scope , or in an
+field (in field declaration order), in an upper static scope, or in an
upper dynamic scope (see Section 7.3.2). The type selection is indicated
by the mapping from the enumeration value to the string used as variant
type selector. The field to use as tag is specified by the "tag_field",
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.
+variants, and after "variant name" for named variants. It is not
+required that each enumeration mapping appears as variant type tag
+field. It is also not required that each variant type tag appears as
+enumeration mapping. However, it is required that any enumeration
+mapping encountered within a stream has a matching variant type tag
+field.
+
+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
4.2.4 Sequences
-Sequences are dynamically-sized arrays. They refer to a a "length"
+Sequences are dynamically-sized arrays. They refer to a "length"
unsigned integer field, which must appear in either the same static scope,
prior to the sequence field (in field declaration order), in an upper
static scope, or in an upper dynamic scope (see Section 7.3.2). This
The event packet header consists of two parts: the "event packet header"
is the same for all streams of a trace. The second part, the "event
packet context", is described on a per-stream basis. Both are described
-in the TSDL meta-data. The packets are aligned on architecture-page-sized
-addresses.
+in the TSDL meta-data.
Event packet header (all fields are optional, specified by TSDL meta-data):
while (or before) writing the first event and while (or after) writing the
last event in the packet. The inclusive range between these timestamps should
include all event timestamps assigned to events contained within the packet.
+ The timestamp at the beginning of an event packet is guaranteed to be
+ below or equal the timestamp at the end of that event packet.
+ The timestamp at the end of an event packet is guaranteed to be below
+ or equal the timestamps at the end of any following packet within the
+ same stream. See Section 8. Clocks for more detail.
- 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 after
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;
The overall structure of an event is:
-1 - Stream Packet Context (as specified by the stream meta-data)
- 2 - Event Header (as specified by the stream meta-data)
- 3 - Stream Event Context (as specified by the stream meta-data)
- 4 - Event Context (as specified by the event meta-data)
- 5 - Event Payload (as specified by the event meta-data)
+1 - Event Header (as specified by the stream meta-data)
+ 2 - Stream Event Context (as specified by the stream meta-data)
+ 3 - Event Context (as specified by the event meta-data)
+ 4 - Event Payload (as specified by the event meta-data)
This structure defines an implicit dynamic scoping, where variants
located in inner structures (those with a higher number in the listing
above) can refer to the fields of outer structures (with lower number in
the listing above). See Section 7.3 TSDL Scopes for more detail.
+The total length of an event is defined as the difference between the
+end of its Event Payload and the end of the previous event's Event
+Payload. Therefore, it includes the event header alignment padding, and
+all its fields and their respective alignment padding. Events of length
+0 are forbidden.
+
6.1 Event Header
Event headers can be described within the meta-data. We hereby propose, as an
Types uintX_t represent an X-bit unsigned integer, as declared with
either:
- typealias integer { size = X; align = X; signed = false } := uintX_t;
+ typealias integer { size = X; align = X; signed = false; } := uintX_t;
or
- typealias integer { size = X; align = 1; signed = false } := uintX_t;
+ typealias integer { size = X; align = 1; signed = false; } := uintX_t;
+
+For more information about timestamp fields, see Section 8. Clocks.
6.1.1 Type 1 - Few event IDs
} align(16); /* or align(8) */
-6.2 Event Context
+6.2 Stream Event Context and Event Context
The event context contains information relative to the current event.
The choice and meaning of this information is specified by the TSDL
numeric value).
event {
- context = struct {
+ context := struct {
variant <id> {
struct { } compact;
struct {
id = value; /* Numeric identifier within the stream */
stream_id = stream_id;
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 */
/*
event.header := struct {
uint64_ccnt_t timestamp;
/* ... */
- }
+ };
packet.context := struct packet_context;
};
For a N-bit integer type referring to a clock, if the integer overflows
-compared to the N low order bits of the clock prior value, then it is
-assumed that one, and only one, overflow occurred. It is therefore
-important that events encoding time on a small number of bits happen
-frequently enough to detect when more than one N-bit overflow occurs.
+compared to the N low order bits of the clock prior value found in the
+same stream, then it is assumed that one, and only one, overflow
+occurred. It is therefore important that events encoding time on a small
+number of bits happen frequently enough to detect when more than one
+N-bit overflow occurs.
In a packet context, clock field names ending with "_begin" and "_end"
have a special meaning: this refers to the time-stamps at, respectively,
keyword: is one of
align
+callsite
const
char
clock
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
projects / ctf.git / blobdiff