Update proposal type class description
[ctf.git] / common-trace-format-proposal.txt
index 0daac2adccfa4115a91f0576f0402f5c31be3157..458b0977787edbad699d18590dacb10db95de165 100644 (file)
@@ -83,9 +83,13 @@ header" throughout the rest of this document.
 
 4. Types
 
+Types are organized as type classes. Each type class belong to either of two
+kind of types: basic types or compound types.
+
 4.1 Basic types
 
-A basic type is a scalar type, as described in this section.
+A basic type is a scalar type, as described in this section. It includes
+integers, GNU/C bitfields, enumerations, and floating point values.
 
 4.1.1 Type inheritance
 
@@ -181,19 +185,19 @@ Metadata representation:
 
 Example of type inheritance (creation of a uint32_t named type):
 
-typedef integer {
+typealias integer {
   size = 32;
   signed = false;
   align = 32;
-} uint32_t;
+} uint32_t;
 
 Definition of a named 5-bit signed bitfield:
 
-typedef integer {
+typealias integer {
   size = 5;
   signed = true;
   align = 1;
-} int5_t;
+} int5_t;
 
 4.1.6 GNU/C bitfields
 
@@ -248,11 +252,11 @@ floating_point {
 
 Example of type inheritance:
 
-typedef floating_point {
+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.
 
@@ -273,8 +277,8 @@ 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 <integer_type OR size> name {
-  string              = start_value1 ... end_value1,
+enum name <integer_type OR size> {
+  somestring          = start_value1 ... end_value1,
   "other string"      = start_value2 ... end_value2,
   yet_another_string,  /* will be assigned to end_value2 + 1 */
   "some other string" = value,
@@ -284,7 +288,7 @@ enum <integer_type OR size> name {
 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,
@@ -300,8 +304,12 @@ enum <integer_type> {
   ...
 }
 
+
 4.2 Compound types
 
+Compound are aggregation of type declarations. Compound types include
+structures, variant, arrays, sequences, and strings.
+
 4.2.1 Structures
 
 Structures are aligned on the largest alignment required by basic types
@@ -492,9 +500,9 @@ encoding attribute information, the default encoding is UTF-8.
 
 Metadata representation of a named string type:
 
-typedef string {
+typealias string {
   encoding = UTF8 OR ASCII;
-} name;
+} name;
 
 A nameless string type can be declared as a field type:
 
@@ -591,7 +599,7 @@ struct event_packet_context {
   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 +615,11 @@ The overall structure of an event is:
 
 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.
@@ -710,7 +719,7 @@ within the stream declaration within the metadata:
     ...
     event {
       ...
-      context = struct {
+      context := struct {
         uint pid;
         uint16_t payload_size;
       };
@@ -774,6 +783,13 @@ 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.
 
+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.
+Redefinition of a typedef or typealias, or hiding an uppermost definition, is
+not valid.
+
 The grammar representing the CTF metadata is presented in
 Appendix C. CTF Metadata Grammar.
 
@@ -787,11 +803,11 @@ trace {
 stream {
   id = stream_id;
   /* 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 {
+  event.header := event_header_1 OR event_header_2;
+  event.context := struct {
     ...
   };
-  packet.context = struct {
+  packet.context := struct {
     ...
   };
 };
@@ -800,10 +816,10 @@ event {
   name = event_name;
   id = value;                  /* Numeric identifier within the stream */
   stream = stream_id;
-  context = struct {
+  context := struct {
     ...
   };
-  fields = struct {
+  fields := struct {
     ...
   };
 };
@@ -813,26 +829,40 @@ event {
 /*
  * 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 type_class {
+/*
+ * 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.
+ */
+
+typealias type_class {
   ...
 } : new_type_prefix new_type new_type_postfix;
 
 /*
  * e.g.: 
- * typedef integer {
+ * typealias integer {
  *   size = 32;
  *   align = 32;
  *   signed = false;
  * } : struct page *;
+ *
+ * typealias integer {
+ *  size = 32;
+ *  align = 32;
+ *  signed = true;
+ * } : int;
  */
 
 struct name {
@@ -843,12 +873,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 {
   ...
@@ -932,4 +964,376 @@ header" throughout the rest of this document.
 
 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 < 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 >
+
+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
This page took 0.041668 seconds and 4 git commands to generate.