TSDL grammar: Fold constant-expression into unary-expression

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index eb0342b721ef78ce5205d973bc4265acbc41a7d7..ff48de91266ad3029be23003f4f7216e91bf18d1 100644 (file)
--- a/common-trace-format-proposal.txt
+++ b/common-trace-format-proposal.txt
@@ -108,16 +108,18 @@ We define "bit-packed" types as following on the next bit, as defined by the
 "Integers" section.
 
 Each basic type must specify its alignment, in bits. Examples of
 "Integers" section.
 
 Each basic type must specify its alignment, in bits. Examples of

-possible alignments are: bit-packed, byte-packed, or word-aligned. The
-choice depends on the architecture preference and compactness vs
-performance trade-offs of the implementation.  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, 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. It is however recommended to always specify
-the alignment explicitly.
+possible alignments are: bit-packed (align = 1), byte-packed (align =
+8), or word-aligned (e.g. align = 32 or align = 64). The choice depends
+on the architecture preference and compactness vs performance trade-offs
+of the implementation.  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, it is assumed to be bit-packed for integers with size not multiple
+of 8 bits and for gcc bitfields. All other basic types are byte-packed
+by default. It is however recommended to always specify the alignment
+explicitly. Alignment values must be power of two. Compound types are
+aligned as specified in their individual specification.

 
 TSDL meta-data attribute representation of a specific alignment:
 
 
 TSDL meta-data attribute representation of a specific alignment:
 


@@ -188,6 +190,9 @@ TSDL meta-data representation:
     byte_order = native OR network OR be OR le; /* default native */
     size = value;                               /* value in bits, no default */
     align = value;                              /* value in bits */
     byte_order = native OR network OR be OR le; /* default native */
     size = value;                               /* value in bits, no default */
     align = value;                              /* value in bits */

+    /* based used for pretty-printing output, default: decimal. */
+    base = decimal OR dec OR OR d OR i OR u OR 10 OR hexadecimal OR hex OR x OR X OR p OR 16
+           OR octal OR oct OR o OR 8 OR binary OR b OR 2;

   }
 
 Example of type inheritance (creation of a uint32_t named type):
   }
 
 Example of type inheritance (creation of a uint32_t named type):


@@ -252,9 +257,10 @@ in bits. Some requirements are imposed on the floating point values:
 TSDL meta-data representation:
 
 floating_point {
 TSDL meta-data representation:
 
 floating_point {

-   exp_dig = value;
-   mant_dig = value;
-   byte_order = native OR network OR be OR le;
+  exp_dig = value;
+  mant_dig = value;
+  byte_order = native OR network OR be OR le;
+  align = value;

 }
 
 Example of type inheritance:
 }
 
 Example of type inheritance:


@@ -263,10 +269,14 @@ typealias floating_point {
   exp_dig = 8;         /* sizeof(float) * CHAR_BIT - FLT_MANT_DIG */
   mant_dig = 24;       /* FLT_MANT_DIG */
   byte_order = native;
   exp_dig = 8;         /* sizeof(float) * CHAR_BIT - FLT_MANT_DIG */
   mant_dig = 24;       /* FLT_MANT_DIG */
   byte_order = native;

+  align = 32;

 } := float;
 
 TODO: define NaN, +inf, -inf behavior.
 
 } := float;
 
 TODO: define NaN, +inf, -inf behavior.
 

+Bit-packed, byte-packed or larger alignments can be used for floating
+point values, similarly to integers.
+

 4.1.8 Enumerations
 
 Enumerations are a mapping between an integer type and a table of strings. The
 4.1.8 Enumerations
 
 Enumerations are a mapping between an integer type and a table of strings. The


@@ -357,17 +367,28 @@ struct {
   ...
 }
 
   ...
 }
 

+Alignment for a structure compound type can be forced to a minimum value
+by adding an "align" specifier after the declaration of a structure
+body. This attribute is read as: align(value). The value is specified in
+bits. The structure will be aligned on the maximum value between this
+attribute and the alignment required by the basic types contained within
+the structure. e.g.
+
+struct {
+  ...
+} align(32)
+

 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 structure (defined recursively). A "tag" enumeration
 field must appear in either the same lexical scope, prior to the variant
 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 structure (defined recursively). A "tag" enumeration
 field must appear in either the same lexical scope, prior to the variant

-field (in field declaration order), in an uppermost lexical scope (see
-Section 7.3.1), or in an uppermost dynamic scope (see Section 7.3.2).
-The type selection is indicated by the mapping from the enumeration
-value to the string used as variant type selector. The field to use as
-tag is specified by the "tag_field", specified between "< >" after the
+field (in field declaration order), in an upper lexical scope (see
+Section 7.3.1), or in an upper dynamic scope (see Section 7.3.2). The
+type selection is indicated by the mapping from the enumeration value to
+the string used as variant type selector. The field to use as tag is
+specified by the "tag_field", specified between "< >" after the

 "variant" keyword for unnamed variants, and after "variant name" for
 named variants.
 
 "variant" keyword for unnamed variants, and after "variant name" for
 named variants.
 


@@ -417,7 +438,8 @@ variant example {
 
 struct {
   enum : uint2_t { a, b, c } choice;
 
 struct {
   enum : uint2_t { a, b, c } choice;

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

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


@@ -491,23 +513,55 @@ A nameless array can be declared as a field type within a structure, e.g.:
 
   uint8_t field_name[10];
 
 
   uint8_t field_name[10];
 

+Arrays are always aligned on their element alignment requirement.

 
 4.2.4 Sequences
 
 
 4.2.4 Sequences
 

-Sequences are dynamically-sized arrays. They start with an integer that specify
-the length of the sequence, followed by an array of "inner type" elements.
-The length is the number of elements in the sequence.
+Sequences are dynamically-sized arrays. They refer to a a "length"
+unsigned integer field, which must appear in either the same lexical scope,
+prior to the sequence field (in field declaration order), in an upper
+lexical scope (see Section 7.3.1), or in an upper dynamic scope (see
+Section 7.3.2). This length field represents the number of elements in
+the sequence. The sequence per se is an array of "inner type" elements.

 
 

-TSDL meta-data representation for a named sequence:
+TSDL meta-data representation for a sequence type definition:

 
 

-typedef elem_type name[length_type];
+struct {
+  unsigned int length_field;
+  typedef elem_type typename[length_field];
+  typename seq_field_name;
+}

 
 

-A nameless sequence can be declared as a field type, e.g.:
+A sequence can also be declared as a field type, e.g.:

 
 

-long field_name[int];
+struct {
+  unsigned int length_field;
+  long seq_field_name[length_field];
+}

 
 

-The length type follows the integer types specifications, and the sequence
-elements follow the "array" specifications.
+Multiple sequences can refer to the same length field, and these length
+fields can be in a different upper dynamic scope:
+
+e.g., assuming the stream.event.header defines:
+
+stream {
+  ...
+  id = 1;
+  event.header := struct {
+    uint16_t seq_len;
+  };
+};
+
+event {
+  ...
+  stream_id = 1;
+  fields := struct {
+    long seq_a[stream.event.header.seq_len];
+    char seq_b[stream.event.header.seq_len];
+  };
+};
+
+The sequence elements follow the "array" specifications.

 
 4.2.5 Strings
 
 
 4.2.5 Strings
 


@@ -526,6 +580,8 @@ A nameless string type can be declared as a field type:
 
 string field_name;     /* Use default UTF8 encoding */
 
 
 string field_name;     /* Use default UTF8 encoding */
 

+Strings are always aligned on byte size.
+

 5. Event Packet Header
 
 The event packet header consists of two parts: the "event packet header"
 5. Event Packet Header
 
 The event packet header consists of two parts: the "event packet header"


@@ -1040,6 +1096,10 @@ struct {
   ...
 }
 
   ...
 }
 

+struct {
+  ...
+} align(value)
+

 variant {
   ...
 }
 variant {
   ...
 }


@@ -1145,6 +1205,7 @@ token:
 
 keyword: is one of
 
 
 keyword: is one of
 

+align

 const
 char
 double
 const
 char
 double


@@ -1331,11 +1392,8 @@ assignment-operator:
 type-assignment-operator:
        :=
 
 type-assignment-operator:
        :=
 

-constant-expression:
-       unary-expression
-

 constant-expression-range:
 constant-expression-range:

-       constant-expression ... constant-expression
+       unary-expression ... unary-expression

 
 2.2) Declarations:
 
 
 2.2) Declarations:
 


@@ -1378,9 +1436,12 @@ type-specifier:
        typedef-name
        ctf-type-specifier
 
        typedef-name
        ctf-type-specifier
 

+align-attribute:
+       align ( unary-expression )
+

 struct-specifier:
 struct-specifier:

-       struct identifier-opt { struct-or-variant-declaration-list-opt }
-       struct identifier
+       struct identifier-opt { struct-or-variant-declaration-list-opt } align-attribute-opt
+       struct identifier align-attribute-opt

 
 struct-or-variant-declaration-list:
        struct-or-variant-declaration
 
 struct-or-variant-declaration-list:
        struct-or-variant-declaration


@@ -1402,7 +1463,7 @@ struct-or-variant-declarator-list:
 
 struct-or-variant-declarator:
        declarator
 
 struct-or-variant-declarator:
        declarator

-       declarator-opt : constant-expression
+       declarator-opt : unary-expression

 
 variant-specifier:
        variant identifier-opt variant-tag-opt { struct-or-variant-declaration-list }
 
 variant-specifier:
        variant identifier-opt variant-tag-opt { struct-or-variant-declaration-list }


@@ -1424,7 +1485,7 @@ enumerator-list:
 
 enumerator:
        enumeration-constant
 
 enumerator:
        enumeration-constant

-       enumeration-constant = constant-expression
+       enumeration-constant = unary-expression

        enumeration-constant = constant-expression-range
 
 type-qualifier:
        enumeration-constant = constant-expression-range
 
 type-qualifier:


@@ -1436,8 +1497,7 @@ declarator:
 direct-declarator:
        identifier
        ( declarator )
 direct-declarator:
        identifier
        ( declarator )

-       direct-declarator [ type-specifier ]
-       direct-declarator [ constant-expression ]
+       direct-declarator [ unary-expression ]

 
 abstract-declarator:
        pointer-opt direct-abstract-declarator
 
 abstract-declarator:
        pointer-opt direct-abstract-declarator


@@ -1445,8 +1505,7 @@ abstract-declarator:
 direct-abstract-declarator:
        identifier-opt
        ( abstract-declarator )
 direct-abstract-declarator:
        identifier-opt
        ( abstract-declarator )

-       direct-abstract-declarator [ type-specifier ]
-       direct-abstract-declarator [ constant-expression ]
+       direct-abstract-declarator [ unary-expression ]

        direct-abstract-declarator [ ]
 
 pointer:
        direct-abstract-declarator [ ]
 
 pointer: