X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=e10c3dcc271f3e88ecf92ba5dfea00b3aefbbbe7;hp=eb0342b721ef78ce5205d973bc4265acbc41a7d7;hb=1ab22b2a8ccbc0766c46f4d5a5a15931644c3caa;hpb=67f02e24ac298e9517029ea4a53964852ea29ab4

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index eb0342b..e10c3dc 100644
--- 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
-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:
 
@@ -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 */
+    /* 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):
@@ -252,9 +257,10 @@ in bits. Some requirements are imposed on the floating point values:
 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:
@@ -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;
+  align = 32;
 } := 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
@@ -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
-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.
 
@@ -417,7 +438,8 @@ variant example {
 
 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:
@@ -491,23 +513,55 @@ A nameless array can be declared as a field type within a structure, e.g.:
 
   uint8_t field_name[10];
 
+Arrays are always aligned on their element alignment requirement.
 
 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
 
@@ -526,6 +580,8 @@ A nameless string type can be declared as a field type:
 
 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"
@@ -1040,6 +1096,10 @@ struct {
   ...
 }
 
+struct {
+  ...
+} align(value)
+
 variant {
   ...
 }
@@ -1145,6 +1205,7 @@ token:
 
 keyword: is one of
 
+align
 const
 char
 double
@@ -1378,9 +1439,12 @@ type-specifier:
 	typedef-name
 	ctf-type-specifier
 
+align-attribute:
+	align ( constant-expression )
+
 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
@@ -1436,7 +1500,7 @@ declarator:
 direct-declarator:
 	identifier
 	( declarator )
-	direct-declarator [ type-specifier ]
+	direct-declarator [ unary-expression ]
 	direct-declarator [ constant-expression ]
 
 abstract-declarator:
@@ -1445,7 +1509,7 @@ 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 [ ]