X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-specification.txt;h=d3b354a5a63647b1f5794f9c35ffbe0cee683def;hp=d306ffc06a5cab5734e3e42622c71dc37e5147df;hb=8f34dd4fad5677f71397e56954881bcb0ab4e9ec;hpb=92250c710272a5993d31c345b08f0f6a143e9225 diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt index d306ffc..d3b354a 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, @@ -690,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. @@ -1029,14 +1033,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 @@ -1075,6 +1079,7 @@ header as selector. The dynamic scope prefixes are thus: + - Trace Environment: , - Trace Packet Header: , - Stream Packet Context: , - Event Header: , @@ -1112,8 +1117,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 { @@ -1123,6 +1128,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. */ @@ -1139,8 +1154,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 { ... }; @@ -1409,6 +1423,7 @@ char clock double enum +env event floating_point float @@ -1721,8 +1736,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