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.
 
 
 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
 };
 
 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,


@@ -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
 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:
 
 
 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
 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
 
 
 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
 
 
 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
 


@@ -1073,6 +1076,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. >,


@@ -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
 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
 
 
 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 {
 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 {


@@ -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. */
 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;
   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 {
     ...
   };


@@ -1407,6 +1420,7 @@ char
 clock
 double
 enum
 clock
 double
 enum

+env

 event
 floating_point
 float
 event
 floating_point
 float


@@ -1719,8 +1733,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