cleanup: remove repetition

[ctf.git] / common-trace-format-specification.txt

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index d306ffc06a5cab5734e3e42622c71dc37e5147df..b220a771ee5d1eb7a509ab5b1e59288542806f69 100644 (file)
--- 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.
 
 
 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
 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.
 
 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
 
 
 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.
 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
 };
 
 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,
 
 enum name : unsigned int {
   ZERO,


@@ -1029,14 +1029,14 @@ path lookups) and for sequence references to length fields.
 
 7.3.1 Lexical Scope
 
 
 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
 
 
 7.3.2 Static and Dynamic Scopes
 


@@ -1075,6 +1075,7 @@ header as selector.
 
 The dynamic scope prefixes are thus:
 
 
 The dynamic scope prefixes are thus:
 

+ - Trace Environment: <env. >,

  - Trace Packet Header: <trace.packet.header. >,
  - Stream Packet Context: <stream.packet.context. >,
  - Event Header: <stream.event.header. >,
  - Trace Packet Header: <trace.packet.header. >,
  - Stream Packet Context: <stream.packet.context. >,
  - Event Header: <stream.event.header. >,


@@ -1112,8 +1113,8 @@ trace. The event "id" field can be left out if there is only one event
 in a stream.
 
 trace {
 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 {
   uuid = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa";       /* Trace UUID */
   byte_order = be OR le;                       /* Endianness (required) */
   packet.header := struct {


@@ -1123,6 +1124,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. */
 stream {
   id = stream_id;
   /* Type 1 - Few event IDs; Type 2 - Many event IDs. See section 6.1. */


@@ -1139,8 +1150,7 @@ event {
   name = "event_name";
   id = value;                  /* Numeric identifier within the stream */
   stream_id = stream_id;
   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 {
     ...
   };
   context := struct {
     ...
   };


@@ -1409,6 +1419,7 @@ char
 clock
 double
 enum
 clock
 double
 enum

+env

 event
 floating_point
 float
 event
 floating_point
 float


@@ -1721,8 +1732,10 @@ typedef-name:
 2.3) CTF-specific declarations
 
 ctf-specifier:
 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 }
        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
        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