X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=31037223237fbe0510831b9911da98d8ae731049;hp=6974f7ce6497afd7f65c754fc77d0284568d86d1;hb=beabf088015cd7de7fc53cedf59c0551e692fc3b;hpb=5ae2352de690f0a4d9b8ee4ae3d313af568b966c;ds=sidebyside diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index 6974f7c..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 @@ -887,15 +941,15 @@ 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 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 */ @@ -1010,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; }; }; @@ -1454,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 @@ -1490,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 @@ -1530,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