X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-specification.txt;h=331b9dade401bf5f115024434efc4b90103fb6a9;hp=cb28d6afee7aecb7a730aed9a605bf6c75a54b68;hb=46400bde253c50d554b28b4635eea853c05dea45;hpb=70375f9227df920c09b2255ded94cb378172d7ba diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt index cb28d6a..331b9da 100644 --- a/common-trace-format-specification.txt +++ b/common-trace-format-specification.txt @@ -1,4 +1,4 @@ -Common Trace Format (CTF) Specification (pre-v1.8) +Common Trace Format (CTF) Specification (v1.8.1) Mathieu Desnoyers, EfficiOS Inc. @@ -118,11 +118,10 @@ trace event types expressed in the Trace Stream Description Language 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. @@ -172,7 +171,7 @@ TSDL meta-data attribute representation of a specific alignment: 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. @@ -358,7 +357,8 @@ enum name : integer_type { }; 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, @@ -421,7 +421,8 @@ possess a field name, which is a unique identifier within the structure. The identifier is not allowed to use any reserved keyword (see Section C.1.2). Replacing reserved keywords with underscore-prefixed field names is recommended. Fields starting with an -underscore should have their leading underscore removed by the CTF parser. +underscore should have their leading underscore removed by the CTF trace +readers. A nameless structure can be declared as a field type or as part of a typedef: @@ -463,7 +464,8 @@ Each variant type selector possess a field name, which is a unique identifier within the variant. The identifier is not allowed to use any reserved keyword (see Section C.1.2). Replacing reserved keywords with underscore-prefixed field names is recommended. Fields starting with an -underscore should have their leading underscore removed by the CTF parser. +underscore should have their leading underscore removed by the CTF trace +readers. A named variant declaration followed by its definition within a structure @@ -688,11 +690,15 @@ Event packet context (all fields are optional, specified by TSDL meta-data): 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. @@ -967,12 +973,13 @@ 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 "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 */ @@ -988,7 +995,7 @@ struct metadata_packet_header { }; 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 @@ -1027,14 +1034,14 @@ path lookups) and for sequence references to length fields. 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 @@ -1073,6 +1080,7 @@ header as selector. The dynamic scope prefixes are thus: + - Trace Environment: , - Trace Packet Header: , - Stream Packet Context: , - Event Header: , @@ -1089,7 +1097,7 @@ not permitted as field names. It is recommended that field names clashing with CTF and C99 reserved keywords use an underscore prefix to eliminate the risk of generating a description containing an invalid field name. Consequently, fields starting with an underscore should have -their leading underscore removed by the CTF parser. +their leading underscore removed by the CTF trace readers. The information available in the dynamic scopes can be thought of as the @@ -1110,8 +1118,8 @@ trace. The event "id" field can be left out if there is only one event 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 { @@ -1121,6 +1129,16 @@ trace { }; }; +/* + * 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. */ @@ -1137,8 +1155,7 @@ event { name = "event_name"; id = value; /* Numeric identifier within the stream */ stream_id = stream_id; - loglevel.identifier = "loglevel_identifier"; - loglevel.value = value; + loglevel = value; context := struct { ... }; @@ -1407,6 +1424,7 @@ char clock double enum +env event floating_point float @@ -1719,8 +1737,10 @@ typedef-name: 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 } 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