Add scope semantic, add abstract declarations

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index 2311fb0e9ea0e0724912b2c6405daad334876e9a..d1136a2cd3a08d2de52819c3efced30b9778f252 100644 (file)
--- a/common-trace-format-proposal.txt
+++ b/common-trace-format-proposal.txt
@@ -273,7 +273,7 @@ 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.
 
 If a numeric value is encountered between < >, it represents the integer type
 size used to hold the enumeration, in bits.
 

-enum <integer_type OR size> name {
+enum name <integer_type OR size> {

   string              = start_value1 ... end_value1,
   "other string"      = start_value2 ... end_value2,
   yet_another_string,  /* will be assigned to end_value2 + 1 */
   string              = start_value1 ... end_value1,
   "other string"      = start_value2 ... end_value2,
   yet_another_string,  /* will be assigned to end_value2 + 1 */


@@ -284,7 +284,7 @@ enum <integer_type OR size> name {
 If the values are omitted, the enumeration starts at 0 and increment of 1 for
 each entry:
 
 If the values are omitted, the enumeration starts at 0 and increment of 1 for
 each entry:
 

-enum <32> name {
+enum name <32> {

   ZERO,
   ONE,
   TWO,
   ZERO,
   ONE,
   TWO,


@@ -335,7 +335,7 @@ struct {
   ...
 }
 
   ...
 }
 

-4.2.2 Variants (Discriminated Unions)
+4.2.2 Variants (Discriminated/Tagged Unions)

 
 A CTF variant is a selection between different types. A CTF variant must always
 be defined within the scope of a structure or within fields contained within a
 
 A CTF variant is a selection between different types. A CTF variant must always
 be defined within the scope of a structure or within fields contained within a


@@ -393,7 +393,7 @@ variant example {
 
 struct {
   enum <uint2_t> { a, b, c } choice;
 
 struct {
   enum <uint2_t> { a, b, c } choice;

-  variant example <choice> u[unsigned int];
+  variant example <choice> v[unsigned int];

 }
 
 Example of an unnamed variant:
 }
 
 Example of an unnamed variant:


@@ -421,7 +421,7 @@ struct {
     uint32_t a;
     uint64_t b;
     short c;
     uint32_t a;
     uint64_t b;
     short c;

-  } u[10];
+  } v[10];

 }
 
 Example of a variant type definition within a structure, where the defined type
 }
 
 Example of a variant type definition within a structure, where the defined type


@@ -591,7 +591,7 @@ struct event_packet_context {
   uint8_t  stream_packet_count_bits;   /* Significant counter bits */
   uint8_t  compression_scheme;
   uint8_t  encryption_scheme;
   uint8_t  stream_packet_count_bits;   /* Significant counter bits */
   uint8_t  compression_scheme;
   uint8_t  encryption_scheme;

-  uint8_t  checksum;
+  uint8_t  checksum_scheme;

 };
 
 
 };
 
 


@@ -607,10 +607,11 @@ The overall structure of an event is:
 
 6.1 Lexical Scope
 
 
 6.1 Lexical Scope
 

-The lexical scope of each structure (stream packet context, header, stream event
-context, event context and payload) is extended in the following way: lower
-levels (e.g. 3) can refer to fields defined in prior levels (e.g. 2 and 1). The
-field in the closest level has priority in case of field name conflict.
+For variant tag definition only, the lexical scope of each structure (stream
+packet context, header, stream event context, event context and payload) is
+extended in the following way: lower levels (e.g. 3) can refer to fields defined
+in prior levels (e.g. 2 and 1). The field in the closest level has priority in
+case of field name conflict.

 
 This allows, for instance, the event context to define a variant refering to the
 "id" field of the event header as selector.
 
 This allows, for instance, the event context to define a variant refering to the
 "id" field of the event header as selector.


@@ -710,7 +711,7 @@ within the stream declaration within the metadata:
     ...
     event {
       ...
     ...
     event {
       ...

-      context = struct {
+      context := struct {

         uint pid;
         uint16_t payload_size;
       };
         uint pid;
         uint16_t payload_size;
       };


@@ -771,7 +772,13 @@ and trace UUID.
 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
 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.
+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.
+
+Each of "trace", "stream", "event", "struct" and "variant" have their own
+nestable declaration scope, within which types can be declared using "typedef"
+and "typealias". An innermost declaration scope can refer to type declared
+within its container lexical scope prior to the innermost declaration scope.

 
 The grammar representing the CTF metadata is presented in
 Appendix C. CTF Metadata Grammar.
 
 The grammar representing the CTF metadata is presented in
 Appendix C. CTF Metadata Grammar.


@@ -785,18 +792,13 @@ trace {
 
 stream {
   id = stream_id;
 
 stream {
   id = stream_id;

-  event {
-    header_alignment = value;
-    /* Type 1 - Few event IDs; Type 2 - Many event IDs. See section 6.2. */
-    header = event_header_1 OR event_header_2;
-    context = struct {
-      ...
-    };
+  /* Type 1 - Few event IDs; Type 2 - Many event IDs. See section 6.2. */
+  event.header := event_header_1 OR event_header_2;
+  event.context := struct {
+    ...

   };
   };

-  packet {
-    context = struct {
-      ...
-    };
+  packet.context := struct {
+    ...

   };
 };
 
   };
 };
 


@@ -804,10 +806,10 @@ event {
   name = event_name;
   id = value;                  /* Numeric identifier within the stream */
   stream = stream_id;
   name = event_name;
   id = value;                  /* Numeric identifier within the stream */
   stream = stream_id;

-  context = struct {
+  context := struct {

     ...
   };
     ...
   };

-  fields = struct {
+  fields := struct {

     ...
   };
 };
     ...
   };
 };


@@ -817,22 +819,27 @@ event {
 /*
  * Named types:
  *
 /*
  * Named types:
  *

- * Type declarations behave similarly to the C standard, with the following
- * added feature: new_type can be preceded by a colon to allow creation of a
- * type name with prefix/postfix.
+ * Type declarations behave similarly to the C standard.

  */
 
 typedef aliased_type_prefix aliased_type new_type aliased_type_postfix;
 
 /* e.g.: typedef struct example new_type_name[10]; */
 
  */
 
 typedef aliased_type_prefix aliased_type new_type aliased_type_postfix;
 
 /* e.g.: typedef struct example new_type_name[10]; */
 

-typedef type_class {
+/*
+ * typealias
+ *
+ * The "typealias" declaration can be used to give a name (including
+ * prefix/postfix) to a type.
+ */
+
+typealias type_class {

   ...
 } : new_type_prefix new_type new_type_postfix;
 
 /*
  * e.g.: 
   ...
 } : new_type_prefix new_type new_type_postfix;
 
 /*
  * e.g.: 

- * typedef integer {
+ * typealias integer {

  *   size = 32;
  *   align = 32;
  *   signed = false;
  *   size = 32;
  *   align = 32;
  *   signed = false;


@@ -847,12 +854,14 @@ variant name {
   ...
 };
 
   ...
 };
 

-enum <integer_type or size> name {
+enum name <integer_type or size> {

   ...
 };
 
 
   ...
 };
 
 

-/* Unnamed types, contained within compound type fields or typedef. */
+/*
+ * Unnamed types, contained within compound type fields, typedef or typealias.
+ */

 
 struct {
   ...
 
 struct {
   ...


@@ -936,4 +945,376 @@ header" throughout the rest of this document.
 
 C. CTF Metadata Grammar
 
 
 C. CTF Metadata Grammar
 

-TODO
+/*
+ * Common Trace Format (CTF) Metadata Grammar.
+ *
+ * Inspired from the C99 grammar:
+ * http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf (Annex A)
+ *
+ * Specialized for CTF needs by including only constant and declarations from
+ * C99 (excluding function declarations), and by adding support for variants,
+ * sequences and CTF-specific specifiers.
+ */
+
+1) Lexical grammar
+
+1.1) Lexical elements
+
+token:
+       keyword
+       identifier
+       constant
+       string-literal
+       punctuator
+
+1.2) Keywords
+
+keyword: is one of
+
+const
+char
+double
+enum
+event
+floating_point
+float
+integer
+int
+long
+short
+signed
+stream
+string
+struct
+trace
+typealias
+typedef
+unsigned
+variant
+void
+_Bool
+_Complex
+_Imaginary
+
+
+1.3) Identifiers
+
+identifier:
+       identifier-nondigit
+       identifier identifier-nondigit
+       identifier digit
+
+identifier-nondigit:
+       nondigit
+       universal-character-name
+       any other implementation-defined characters
+
+nondigit:
+       _
+       [a-zA-Z]        /* regular expression */
+
+digit:
+       [0-9]           /* regular expression */
+
+1.4) Universal character names
+
+universal-character-name:
+       \u hex-quad
+       \U hex-quad hex-quad
+
+hex-quad:
+       hexadecimal-digit hexadecimal-digit hexadecimal-digit hexadecimal-digit
+
+1.5) Constants
+
+constant:
+       integer-constant
+       enumeration-constant
+       character-constant
+
+integer-constant:
+       decimal-constant integer-suffix-opt
+       octal-constant integer-suffix-opt
+       hexadecimal-constant integer-suffix-opt
+
+decimal-constant:
+       nonzero-digit
+       decimal-constant digit
+
+octal-constant:
+       0
+       octal-constant octal-digit
+
+hexadecimal-constant:
+       hexadecimal-prefix hexadecimal-digit
+       hexadecimal-constant hexadecimal-digit
+
+hexadecimal-prefix:
+       0x
+       0X
+
+nonzero-digit:
+       [1-9]
+
+integer-suffix:
+       unsigned-suffix long-suffix-opt
+       unsigned-suffix long-long-suffix
+       long-suffix unsigned-suffix-opt
+       long-long-suffix unsigned-suffix-opt
+
+unsigned-suffix:
+       u
+       U
+
+long-suffix:
+       l
+       L
+
+long-long-suffix:
+       ll
+       LL
+
+digit-sequence:
+       digit
+       digit-sequence digit
+
+hexadecimal-digit-sequence:
+       hexadecimal-digit
+       hexadecimal-digit-sequence hexadecimal-digit
+
+enumeration-constant:
+       identifier
+       string-literal
+
+character-constant:
+       ' c-char-sequence '
+       L' c-char-sequence '
+
+c-char-sequence:
+       c-char
+       c-char-sequence c-char
+
+c-char:
+       any member of source charset except single-quote ('), backslash
+       (\), or new-line character.
+       escape-sequence
+
+escape-sequence:
+       simple-escape-sequence
+       octal-escape-sequence
+       hexadecimal-escape-sequence
+       universal-character-name
+
+simple-escape-sequence: one of
+       \' \" \? \\ \a \b \f \n \r \t \v
+
+octal-escape-sequence:
+       \ octal-digit
+       \ octal-digit octal-digit
+       \ octal-digit octal-digit octal-digit
+
+hexadecimal-escape-sequence:
+       \x hexadecimal-digit
+       hexadecimal-escape-sequence hexadecimal-digit
+
+1.6) String literals
+
+string-literal:
+       " s-char-sequence-opt "
+       L" s-char-sequence-opt "
+
+s-char-sequence:
+       s-char
+       s-char-sequence s-char
+
+s-char:
+       any member of source charset except double-quote ("), backslash
+       (\), or new-line character.
+       escape-sequence
+
+1.7) Punctuators
+
+punctuator: one of
+       [ ] ( ) { } . -> * + - < > : ; ... = ,
+
+
+2) Phrase structure grammar
+
+primary-expression:
+       identifier
+       constant
+       string-literal
+       ( unary-expression )
+
+postfix-expression:
+       primary-expression
+       postfix-expression [ unary-expression ]
+       postfix-expression . identifier
+       postfix-expressoin -> identifier
+
+unary-expression:
+       postfix-expression
+       unary-operator postfix-expression
+
+unary-operator: one of
+       + -
+
+assignment-operator:
+       =
+
+constant-expression:
+       unary-expression
+
+constant-expression-range:
+       constant-expression ... constant-expression
+
+2.2) Declarations:
+
+declaration:
+       declaration-specifiers ;
+       declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ;
+       ctf-specifier ;
+
+declaration-specifiers:
+       type-specifier declaration-specifiers-opt
+       type-qualifier declaration-specifiers-opt
+
+declarator-list:
+       declarator
+       declarator-list , declarator
+
+abstract-declarator-list:
+       abstract-declarator
+       abstract-declarator-list , abstract-declarator
+
+storage-class-specifier:
+       typedef
+
+type-specifier:
+       void
+       char
+       short
+       int
+       long
+       float
+       double
+       signed
+       unsigned
+       _Bool
+       _Complex
+       struct-specifier
+       variant-specifier
+       enum-specifier
+       typedef-name
+       ctf-type-specifier
+
+struct-specifier:
+       struct identifier-opt { struct-or-variant-declaration-list-opt }
+       struct identifier
+
+struct-or-variant-declaration-list:
+       struct-or-variant-declaration
+       struct-or-variant-declaration-list struct-or-variant-declaration
+
+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 ;
+
+specifier-qualifier-list:
+       type-specifier specifier-qualifier-list-opt
+       type-qualifier specifier-qualifier-list-opt
+
+struct-or-variant-declarator-list:
+       struct-or-variant-declarator
+       struct-or-variant-declarator-list , struct-or-variant-declarator
+
+struct-or-variant-declarator:
+       declarator
+       declarator-opt : constant-expression
+
+variant-specifier:
+       variant identifier-opt variant-tag-opt { struct-or-variant-declaration-list }
+       variant identifier variant-tag
+
+variant-tag:
+       < identifier >
+
+enum-specifier:
+       enum identifier-opt { enumerator-list }
+       enum identifier-opt { enumerator-list , }
+       enum identifier
+       enum identifier-opt < type-specifier > { enumerator-list }
+       enum identifier-opt < type-specifier > { enumerator-list , }
+       enum identifier < type-specifier >
+       enum identifier-opt < integer-constant > { enumerator-list }
+       enum identifier-opt < integer-constant > { enumerator-list , }
+       enum identifier < integer-constant >
+
+enumerator-list:
+       enumerator
+       enumerator-list , enumerator
+
+enumerator:
+       enumeration-constant
+       enumeration-constant = constant-expression
+       enumeration-constant = constant-expression-range
+
+type-qualifier:
+       const
+
+declarator:
+       pointer-opt direct-declarator
+
+direct-declarator:
+       identifier
+       ( declarator )
+       direct-declarator [ type-specifier ]
+       direct-declarator [ constant-expression ]
+
+abstract-declarator:
+       pointer-opt direct-abstract-declarator
+
+direct-abstract-declarator:
+       identifier-opt
+       ( abstract-declarator )
+       direct-abstract-declarator [ type-specifier ]
+       direct-abstract-declarator [ constant-expression ]
+       direct-abstract-declarator [ ]
+
+pointer:
+       * type-qualifier-list-opt
+       * type-qualifier-list-opt pointer
+
+type-qualifier-list:
+       type-qualifier
+       type-qualifier-list type-qualifier
+
+typedef-name:
+       identifier
+
+2.3) CTF-specific declarations
+
+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 ;
+
+ctf-type-specifier:
+       floating_point { ctf-assignment-expression-list-opt }
+       integer { ctf-assignment-expression-list-opt }
+       string { ctf-assignment-expression-list-opt }
+
+ctf-assignment-expression-list:
+       ctf-assignment-expression
+       ctf-assignment-expression-list ; ctf-assignment-expression
+
+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