Add enum {} default mapping to integer type
[ctf.git] / common-trace-format-proposal.txt
index 4cb69429e9c0256ee8d46d261e34f924fe747ce4..d61b58c0fd73cc0856562db4b7c211e2ae338070 100644 (file)
@@ -68,14 +68,10 @@ A metadata event stream contains information on trace event types. It describes:
 3. Event stream
 
 An event stream is divided in 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 rationale for the event stream design choices is
-explained in Appendix B. Stream Header Rationale.
-
-An event stream is divided in 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.
+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.
 
 The event stream header will therefore be referred to as the "event packet
 header" throughout the rest of this document.
@@ -103,15 +99,16 @@ types, but must be derived into a type to be usable in an event field.
 
 We define "byte-packed" types as aligned on the byte size, namely 8-bit.
 We define "bit-packed" types as following on the next bit, as defined by the
-"bitfields" section.
+"Integers" section.
 
 All basic types, except bitfields, are either aligned on an architecture-defined
 specific alignment or byte-packed, depending on the architecture preference.
 Architectures providing fast unaligned write byte-packed basic types to save
 space, aligning each type on byte boundaries (8-bit). Architectures with slow
 unaligned writes align types on specific alignment values. If no specific
-alignment is declared for a type nor its parents, it is assumed to be bit-packed
-for bitfields and byte-packed for other types.
+alignment is declared for a type, it is assumed to be bit-packed for
+integers with size not multiple of 8 bits and for gcc bitfields. All
+other types are byte-packed.
 
 Metadata attribute representation of a specific alignment:
 
@@ -189,7 +186,7 @@ typealias integer {
   size = 32;
   signed = false;
   align = 32;
-} : uint32_t;
+} := uint32_t;
 
 Definition of a named 5-bit signed bitfield:
 
@@ -197,7 +194,7 @@ typealias integer {
   size = 5;
   signed = true;
   align = 1;
-} : int5_t;
+} := int5_t;
 
 4.1.6 GNU/C bitfields
 
@@ -256,7 +253,7 @@ typealias floating_point {
   exp_dig = 8;         /* sizeof(float) * CHAR_BIT - FLT_MANT_DIG */
   mant_dig = 24;       /* FLT_MANT_DIG */
   byte_order = native;
-} : float;
+} := float;
 
 TODO: define NaN, +inf, -inf behavior.
 
@@ -274,10 +271,7 @@ this format by having the same start_value and end_value for each element, which
 is in fact a range of size 1. This single-value range is supported without
 repeating the start and end values with the value = string declaration.
 
-If a numeric value is encountered between < >, it represents the integer type
-size used to hold the enumeration, in bits.
-
-enum name <integer_type OR size> {
+enum name : integer_type {
   somestring          = start_value1 ... end_value1,
   "other string"      = start_value2 ... end_value2,
   yet_another_string,  /* will be assigned to end_value2 + 1 */
@@ -288,7 +282,7 @@ enum name <integer_type OR size> {
 If the values are omitted, the enumeration starts at 0 and increment of 1 for
 each entry:
 
-enum name <32> {
+enum name : unsigned int {
   ZERO,
   ONE,
   TWO,
@@ -300,7 +294,17 @@ Overlapping ranges within a single enumeration are implementation defined.
 
 A nameless enumeration can be declared as a field type or as part of a typedef:
 
-enum <integer_type> {
+enum : integer_type {
+  ...
+}
+
+Enumerations omitting the container type ": integer_type" use the "int"
+type (for compatibility with C99). The "int" type must be previously
+declared. E.g.:
+
+typealias integer { size = 32; align = 32; signed = true } := int;
+
+enum {
   ...
 }
 
@@ -374,7 +378,7 @@ variant name {
 };
 
 struct {
-  enum <integer_type or size> { sel1, sel2, sel3, ... } tag_field;
+  enum : integer_type { sel1, sel2, sel3, ... } tag_field;
   ...
   variant name <tag_field> v;
 }
@@ -383,7 +387,7 @@ An unnamed variant definition within a structure is expressed by the following
 metadata:
 
 struct {
-  enum <integer_type or size> { sel1, sel2, sel3, ... } tag_field;
+  enum : integer_type { sel1, sel2, sel3, ... } tag_field;
   ...
   variant <tag_field> {
     field_type sel1;
@@ -402,14 +406,14 @@ variant example {
 };
 
 struct {
-  enum <uint2_t> { a, b, c } choice;
+  enum : uint2_t { a, b, c } choice;
   variant example <choice> v[unsigned int];
 }
 
 Example of an unnamed variant:
 
 struct {
-  enum <uint2_t> { a, b, c, d } choice;
+  enum : uint2_t { a, b, c, d } choice;
   /* Unrelated fields can be added between the variant and its tag */
   int32_t somevalue;
   variant <choice> {
@@ -426,7 +430,7 @@ struct {
 Example of an unnamed variant within an array:
 
 struct {
-  enum <uint2_t> { a, b, c } choice;
+  enum : uint2_t { a, b, c } choice;
   variant <choice> {
     uint32_t a;
     uint64_t b;
@@ -441,7 +445,7 @@ type definition referring to the tag "x" uses the closest preceding field from
 the lexical scope of the type definition.
 
 struct {
-  enum <uint2_t> { a, b, c, d } x;
+  enum : uint2_t { a, b, c, d } x;
 
   typedef variant <x> {        /*
                         * "x" refers to the preceding "x" enumeration in the
@@ -453,9 +457,9 @@ struct {
   } example_variant;
 
   struct {
-    enum <int> { x, y, z } x;  /* This enumeration is not used by "v". */
+    enum : int { x, y, z } x;  /* This enumeration is not used by "v". */
     example_variant v;                 /*
-                                * "v" uses the "enum <uint2_t> { a, b, c, d }"
+                                * "v" uses the "enum : uint2_t { a, b, c, d }"
                                 * tag.
                                 */
   } a[10];
@@ -504,7 +508,7 @@ Metadata representation of a named string type:
 
 typealias string {
   encoding = UTF8 OR ASCII;
-} : name;
+} := name;
 
 A nameless string type can be declared as a field type:
 
@@ -657,7 +661,7 @@ struct event_header_1 {
    * id: range: 0 - 30.
    * id 31 is reserved to indicate an extended header.
    */
-  enum <uint5_t> { compact = 0 ... 30, extended = 31 } id;
+  enum : uint5_t { compact = 0 ... 30, extended = 31 } id;
   variant <id> {
     struct {
       uint27_t timestamp;
@@ -685,7 +689,7 @@ struct event_header_2 {
    * id: range: 0 - 65534.
    * id 65535 is reserved to indicate an extended header.
    */
-  enum <uint16_t> { compact = 0 ... 65534, extended = 65535 } id;
+  enum : uint16_t { compact = 0 ... 65534, extended = 65535 } id;
   variant <id> {
     struct {
       uint32_t timestamp;
@@ -765,20 +769,23 @@ contained within the payload. (This follows the ISO/C standard for structures)
 
 7. Metadata
 
-The meta-data is located in a stream named "metadata". It is made of "event
-packets", which each start with an event packet header. The event type within
-the metadata stream have no event header nor event context. Each event only
-contains a null-terminated "string" payload, which is a metadata description
-entry. The events are packed one next to another. Each event packet start with
-an event packet header, which contains, amongst other fields, the magic number
-and trace UUID. The trace UUID is represented as a string of hexadecimal digits
-and dashes "-".
-
-The metadata can be parsed by reading through the metadata strings, skipping
-newlines and null-characters. Type names are made of a single identifier, and
-can be surrounded by prefix/postfix. Text contained within "/*" and "*/", as
-well as within "//" and end of line, are treated as comments. Boolean values can
-be represented as true, TRUE, or 1 for true, and false, FALSE, or 0 for false.
+The meta-data is located in a stream identified by its name: "metadata".
+It is made of "event packets", which each start with an event packet
+header. The event type within the metadata stream have no event header
+nor event context. Each event only contains a null-terminated "string"
+payload, which is a metadata description entry. The events are packed
+one next to another. Each event packet start with an event packet
+header, which contains, amongst other fields, the magic number and trace
+UUID. In the event packet header, the trace UUID is represented as an
+array of bytes. Within the string-based metadata description, the trace
+UUID is represented as a string of hexadecimal digits and dashes "-".
+
+The metadata can be parsed by reading through the metadata strings,
+skipping null-characters. Type names are made of a single identifier,
+and can be surrounded by prefix/postfix. Text contained within "/*" and
+"*/", as well as within "//" and end of line, are treated as comments.
+Boolean values can be represented as true, TRUE, or 1 for true, and
+false, FALSE, or 0 for false.
 
 
 7.1 Declaration vs Definition
@@ -791,11 +798,13 @@ variant field), a declaration is followed by a declarator, which specify
 the newly defined type name (for typedef), or the field name (for
 declarations located within structure and variants). Array and sequence,
 declared with square brackets ("[" "]"), are part of the declarator,
-similarly to C99. The enumeration type specifier and variant tag name
-(both specified with "<" ">") are part of the type specifier.
+similarly to C99. The enumeration base type is specified by
+": base_type", which is part of the type specifier. The variant tag
+name, specified between "<" ">", is also part of the type specifier.
 
 A definition associates a type to a location in the event structure
-hierarchy (see Section 6).
+hierarchy (see Section 6). This association is denoted by ":=", as shown
+in Section 7.3.
 
 
 7.2 Metadata Scopes
@@ -853,7 +862,7 @@ consumption, for each event, the current trace context is therefore
 readable by accessing the upper dynamic scopes.
 
 
-7.2 Metadata Examples
+7.3 Metadata Examples
 
 The grammar representing the CTF metadata is presented in
 Appendix C. CTF Metadata Grammar. This section presents a rather ligher
@@ -898,7 +907,7 @@ event {
  * Type declarations behave similarly to the C standard.
  */
 
-typedef aliased_type_prefix aliased_type new_type aliased_type_postfix;
+typedef aliased_type_specifiers new_type_declarators;
 
 /* e.g.: typedef struct example new_type_name[10]; */
 
@@ -906,15 +915,15 @@ typedef aliased_type_prefix aliased_type new_type aliased_type_postfix;
  * typealias
  *
  * The "typealias" declaration can be used to give a name (including
- * prefix/postfix) to a type. It should also be used to map basic C types
- * (float, int, unsigned long, ...) to a CTF type. Typealias is a superset of
- * "typedef": it also allows assignment of a simple variable identifier to a
- * type.
+ * pointer declarator specifier) to a type. It should also be used to
+ * map basic C types (float, int, unsigned long, ...) to a CTF type.
+ * Typealias is a superset of "typedef": it also allows assignment of a
+ * simple variable identifier to a type.
  */
 
 typealias type_class {
   ...
-} : new_type_prefix new_type new_type_postfix;
+} := type_specifiers type_declarator;
 
 /*
  * e.g.: 
@@ -922,13 +931,13 @@ typealias type_class {
  *   size = 32;
  *   align = 32;
  *   signed = false;
- * } : struct page *;
+ * } := struct page *;
  *
  * typealias integer {
  *  size = 32;
  *  align = 32;
  *  signed = true;
- * } : int;
+ * } := int;
  */
 
 struct name {
@@ -939,7 +948,7 @@ variant name {
   ...
 };
 
-enum name <integer_type or size> {
+enum name : integer_type {
   ...
 };
 
@@ -956,7 +965,7 @@ variant {
   ...
 }
 
-enum <integer_type or size> {
+enum : integer_type {
   ...
 }
 
@@ -1247,6 +1256,9 @@ unary-operator: one of
 assignment-operator:
        =
 
+type-assignment-operator:
+       :=
+
 constant-expression:
        unary-expression
 
@@ -1256,11 +1268,11 @@ constant-expression-range:
 2.2) Declarations:
 
 declaration:
-       declaration-specifiers ;
-       declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ;
+       declaration-specifiers declarator-list-opt ;
        ctf-specifier ;
 
 declaration-specifiers:
+       storage-class-specifier declaration-specifiers-opt
        type-specifier declaration-specifiers-opt
        type-qualifier declaration-specifiers-opt
 
@@ -1287,6 +1299,7 @@ type-specifier:
        unsigned
        _Bool
        _Complex
+       _Imaginary
        struct-specifier
        variant-specifier
        enum-specifier
@@ -1304,8 +1317,8 @@ struct-or-variant-declaration-list:
 struct-or-variant-declaration:
        specifier-qualifier-list struct-or-variant-declarator-list ;
        declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ;
-       typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list ;
-       typealias declaration-specifiers abstract-declarator-list : declarator-list ;
+       typealias declaration-specifiers abstract-declarator-list := declaration-specifiers abstract-declarator-list ;
+       typealias declaration-specifiers abstract-declarator-list := declarator-list ;
 
 specifier-qualifier-list:
        type-specifier specifier-qualifier-list-opt
@@ -1330,12 +1343,8 @@ enum-specifier:
        enum identifier-opt { enumerator-list }
        enum identifier-opt { enumerator-list , }
        enum identifier
-       enum identifier-opt < declaration-specifiers > { enumerator-list }
-       enum identifier-opt < declaration-specifiers > { enumerator-list , }
-       enum identifier < declaration-specifiers >
-       enum identifier-opt < integer-constant > { enumerator-list }
-       enum identifier-opt < integer-constant > { enumerator-list , }
-       enum identifier < integer-constant >
+       enum identifier-opt : declaration-specifiers { enumerator-list }
+       enum identifier-opt : declaration-specifiers { enumerator-list , }
 
 enumerator-list:
        enumerator
@@ -1385,8 +1394,8 @@ ctf-specifier:
        event { ctf-assignment-expression-list-opt }
        stream { ctf-assignment-expression-list-opt }
        trace { ctf-assignment-expression-list-opt }
-       typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list ;
-       typealias declaration-specifiers abstract-declarator-list : declarator-list ;
+       typealias declaration-specifiers abstract-declarator-list := declaration-specifiers abstract-declarator-list ;
+       typealias declaration-specifiers abstract-declarator-list := declarator-list ;
 
 ctf-type-specifier:
        floating_point { ctf-assignment-expression-list-opt }
@@ -1401,5 +1410,5 @@ ctf-assignment-expression:
        unary-expression assignment-operator unary-expression
        unary-expression type-assignment-operator type-specifier
        declaration-specifiers storage-class-specifier declaration-specifiers declarator-list
-       typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list
-       typealias declaration-specifiers abstract-declarator-list : declarator-list
+       typealias declaration-specifiers abstract-declarator-list := declaration-specifiers abstract-declarator-list
+       typealias declaration-specifiers abstract-declarator-list := declarator-list
This page took 0.041972 seconds and 4 git commands to generate.