Sequence: use field reference instead of type specifier

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index eb0342b721ef78ce5205d973bc4265acbc41a7d7..e10c3dcc271f3e88ecf92ba5dfea00b3aefbbbe7 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 sequence type definition:
+
+struct {
+  unsigned int length_field;
+  typedef elem_type typename[length_field];
+  typename seq_field_name;
+}
+
+A sequence can also be declared as a field type, e.g.:
+
+struct {
+  unsigned int length_field;
+  long seq_field_name[length_field];
+}

 
 

-TSDL meta-data representation for a named sequence:
+Multiple sequences can refer to the same length field, and these length
+fields can be in a different upper dynamic scope:

 
 

-typedef elem_type name[length_type];
+e.g., assuming the stream.event.header defines:

 
 

-A nameless sequence can be declared as a field type, e.g.:
+stream {
+  ...
+  id = 1;
+  event.header := struct {
+    uint16_t seq_len;
+  };
+};

 
 

-long field_name[int];
+event {
+  ...
+  stream_id = 1;
+  fields := struct {
+    long seq_a[stream.event.header.seq_len];
+    char seq_b[stream.event.header.seq_len];
+  };
+};

 
 

-The length type follows the integer types specifications, and the sequence
-elements follow the "array" specifications.
+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


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

+align-attribute:
+       align ( constant-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


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

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

        direct-declarator [ constant-expression ]
 
 abstract-declarator:
        direct-declarator [ constant-expression ]
 
 abstract-declarator:


@@ -1445,7 +1509,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 [ unary-expression ]

        direct-abstract-declarator [ constant-expression ]
        direct-abstract-declarator [ ]
 
        direct-abstract-declarator [ constant-expression ]
        direct-abstract-declarator [ ]