enum: Clarify behavior for omitted values after range

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index cb28d6afee7aecb7a730aed9a605bf6c75a54b68..e0944b5d84b6491e33c6e9c0b6b889b0751b845b 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.
 
@@ -358,7 +358,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 +422,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 +465,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
@@ -1027,14 +1030,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 +1076,7 @@ header as selector.
 
 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. >,
@@ -1089,7 +1093,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 +1114,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 +1125,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 +1151,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 +1420,7 @@ char
 clock
 double
 enum
+env
 event
 floating_point
 float
@@ -1719,8 +1733,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