X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=31037223237fbe0510831b9911da98d8ae731049;hp=238fbadfead6c69709bcffad007f8478d558dd67;hb=beabf088015cd7de7fc53cedf59c0551e692fc3b;hpb=2e7d7fcb288895571a682e1ae3344d15578b1f55;ds=sidebyside diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index 238fbad..3103722 100644 --- a/common-trace-format-proposal.txt +++ b/common-trace-format-proposal.txt @@ -24,6 +24,47 @@ formats. The development tree is available at: 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. @@ -193,6 +234,8 @@ TSDL meta-data representation: /* 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): @@ -211,6 +254,17 @@ typealias integer { 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 @@ -220,7 +274,7 @@ defined by the size of the type "unit_type". TSDL meta-data representation: - unit_type name:size: + unit_type name:size; As an example, the following structure declared in C compiled by GCC: @@ -649,7 +703,7 @@ the fields typically expected (although these fields are each optional): struct event_packet_header { uint32_t magic; - uint8_t trace_uuid[16]; + uint8_t uuid[16]; uint32_t stream_id; }; @@ -661,8 +715,8 @@ trace { 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 @@ -763,7 +817,7 @@ struct event_header_1 { uint64_t timestamp; /* 64-bit timestamps */ } extended; } v; -}; +} align(32); /* or align(8) */ 6.1.2 Type 2 - Many event IDs @@ -791,7 +845,7 @@ struct event_header_2 { uint64_t timestamp; /* 64-bit timestamps */ } extended; } v; -}; +} align(16); /* or align(8) */ 6.2 Event Context @@ -886,13 +940,16 @@ beginning of the file. This magic number is also used to detect the 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 "string" payload. Each meta-data packet start with a special -packet header, specific to the meta-data stream, which contains, -exactly: +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: 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 */ @@ -1007,7 +1064,7 @@ trace { 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; }; }; @@ -1451,9 +1508,9 @@ struct-or-variant-declaration-list: 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 @@ -1487,8 +1544,8 @@ enumerator-list: 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 @@ -1527,21 +1584,22 @@ ctf-specifier: 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