update proposal

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index 2a4dbfe25a40d8f206760054c80b196feaa4593b..fd7731f1bdd23ea435bb522bd04cd887a5fe35ce 100644 (file)
--- a/common-trace-format-proposal.txt
+++ b/common-trace-format-proposal.txt
@@ -181,19 +181,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 +248,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.
 
@@ -274,7 +274,7 @@ 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> {
-  string              = start_value1 ... end_value1,
+  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,
@@ -492,9 +492,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:
 
@@ -607,10 +607,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.
@@ -774,6 +775,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.
 
@@ -824,7 +832,10 @@ 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.
+ * 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 {
@@ -838,6 +849,12 @@ typealias type_class {
  *   align = 32;
  *   signed = false;
  * } : struct page *;
+ *
+ * typealias integer {
+ *  size = 32;
+ *  align = 32;
+ *  signed = true;
+ * } : int;
  */
 
 struct name {
@@ -1177,6 +1194,10 @@ declarator-list:
        declarator
        declarator-list , declarator
 
+abstract-declarator-list:
+       abstract-declarator
+       abstract-declarator-list , abstract-declarator
+
 storage-class-specifier:
        typedef
 
@@ -1209,7 +1230,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 declaration-specifiers declarator-list : 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
@@ -1234,9 +1256,9 @@ 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 < 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 >
@@ -1262,6 +1284,16 @@ direct-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
@@ -1279,7 +1311,8 @@ ctf-specifier:
        event { ctf-assignment-expression-list-opt }
        stream { ctf-assignment-expression-list-opt }
        trace { ctf-assignment-expression-list-opt }
-       typealias declaration-specifiers declaration-specifiers declarator-list : declaration-specifiers 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 }
@@ -1294,4 +1327,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 declaration-specifiers declarator-list : declaration-specifiers declarator-list
+       typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list
+       typealias declaration-specifiers abstract-declarator-list : declarator-list