gitweb: http://git.efficios.com/?p=babeltrace.git
+Table of Contents
+
+1. Preliminary definitions
+2. High-level representation of a trace
+3. Event stream
+4. Types
+ 4.1 Basic types
+ 4.1.1 Type inheritance
+ 4.1.2 Alignment
+ 4.1.3 Byte order
+ 4.1.4 Size
+ 4.1.5 Integers
+ 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
+5. Event Packet Header
+ 5.1 Event Packet Header Description
+ 5.2 Event Packet Context Description
+6. Event Structure
+ 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.3 Event Payload
+ 6.3.1 Padding
+ 6.3.2 Alignment
+7. Trace Stream Description Language (TSDL)
+ 7.1 Meta-data
+ 7.2 Declaration vs Definition
+ 7.3 TSDL Scopes
+ 7.3.1 Lexical Scope
+ 7.3.2 Dynamic Scope
+ 7.4 TSDL Examples
+
+
1. Preliminary definitions
- Event Trace: An ordered sequence of events.
/* 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
OR octal OR oct OR o OR 8 OR binary OR b OR 2;
+ /* character encoding, default: none */
+ encoding = none or UTF8 or ASCII;
}
Example of type inheritance (creation of a uint32_t named type):
align = 1;
} := int5_t;
+The character encoding field can be used to specify that the integer
+must be printed as a text character when read. e.g.:
+
+typealias integer {
+ size = 8;
+ align = 8;
+ signed = false;
+ encoding = UTF8;
+} := utf_char;
+
+
4.1.6 GNU/C bitfields
The GNU/C bitfields follow closely the integer representation, with a
TSDL meta-data representation:
- unit_type name:size:
+ unit_type name:size;
As an example, the following structure declared in C compiled by GCC:
struct event_packet_header {
uint32_t magic;
- uint8_t trace_uuid[16];
+ uint8_t uuid[16];
uint32_t stream_id;
};
If the magic number is not present, tools such as "file" will have no
mean to discover the file type.
-If the trace_uuid is not present, no validation that the meta-data
-actually corresponds to the stream is performed.
+If the uuid is not present, no validation that the meta-data actually
+corresponds to the stream is performed.
If the stream_id packet header field is missing, the trace can only
contain a single stream. Its "id" field can be left out, and its events
uint64_t timestamp; /* 64-bit timestamps */
} extended;
} v;
-};
+} align(32); /* or align(8) */
6.1.2 Type 2 - Many event IDs
uint64_t timestamp; /* 64-bit timestamps */
} extended;
} v;
-};
+} align(16); /* or align(8) */
6.2 Event Context
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 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:
+"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:
struct metadata_packet_header {
uint32_t magic; /* 0x75D11D57 */
- uint8_t trace_uuid[16]; /* Unique Universal Identifier */
+ uint8_t uuid[16]; /* Unique Universal Identifier */
uint32_t checksum; /* 0 if unused */
uint32_t content_size; /* in bits */
uint32_t packet_size; /* in bits */
byte_order = be OR le; /* Endianness (required) */
packet.header := struct {
uint32_t magic;
- uint8_t trace_uuid[16];
+ uint8_t uuid[16];
uint32_t stream_id;
};
};
struct-or-variant-declaration:
specifier-qualifier-list struct-or-variant-declarator-list ;
- declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ;
- typealias declaration-specifiers abstract-declarator-list := declaration-specifiers abstract-declarator-list ;
- typealias declaration-specifiers abstract-declarator-list := declarator-list ;
+ declaration-specifiers-opt storage-class-specifier declaration-specifiers-opt declarator-list ;
+ 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 ;
specifier-qualifier-list:
type-specifier specifier-qualifier-list-opt
enumerator:
enumeration-constant
- enumeration-constant = unary-expression
- enumeration-constant = constant-expression-range
+ enumeration-constant assignment-operator unary-expression
+ enumeration-constant assignment-operator constant-expression-range
type-qualifier:
const
event { ctf-assignment-expression-list-opt }
stream { ctf-assignment-expression-list-opt }
trace { ctf-assignment-expression-list-opt }
- typealias declaration-specifiers abstract-declarator-list := declaration-specifiers abstract-declarator-list ;
- typealias declaration-specifiers abstract-declarator-list := declarator-list ;
+ 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
ctf-type-specifier:
floating_point { ctf-assignment-expression-list-opt }
integer { ctf-assignment-expression-list-opt }
string { ctf-assignment-expression-list-opt }
+ string
ctf-assignment-expression-list:
- ctf-assignment-expression
- ctf-assignment-expression-list ; ctf-assignment-expression
+ ctf-assignment-expression ;
+ ctf-assignment-expression-list ctf-assignment-expression ;
ctf-assignment-expression:
unary-expression assignment-operator unary-expression
unary-expression type-assignment-operator type-specifier
- declaration-specifiers storage-class-specifier declaration-specifiers declarator-list
- typealias declaration-specifiers abstract-declarator-list := declaration-specifiers abstract-declarator-list
- typealias declaration-specifiers abstract-declarator-list := declarator-list
+ declaration-specifiers-opt storage-class-specifier declaration-specifiers-opt declarator-list
+ 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