Update proposal type class description

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index d1136a2cd3a08d2de52819c3efced30b9778f252..458b0977787edbad699d18590dacb10db95de165 100644 (file)
--- a/common-trace-format-proposal.txt
+++ b/common-trace-format-proposal.txt
@@ -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.
 
@@ -274,7 +278,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,
@@ -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:
 
@@ -779,6 +787,8 @@ 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.
@@ -830,7 +840,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 {
@@ -844,6 +857,12 @@ typealias type_class {
  *   align = 32;
  *   signed = false;
  * } : struct page *;
+ *
+ * typealias integer {
+ *  size = 32;
+ *  align = 32;
+ *  signed = true;
+ * } : int;
  */
 
 struct name {
@@ -1245,9 +1264,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 >