Add base integer attribute for pretty-print

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index f9d9b5fd0cce3e40eeaedfe56052c2655323f8ea..c305c9e37d593d603b443d9847a10da74be357a1 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,6 +367,17 @@ 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
 4.2.2 Variants (Discriminated/Tagged Unions)
 
 A CTF variant is a selection between different types. A CTF variant must


@@ -491,6 +512,7 @@ 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
 


@@ -526,6 +548,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"


@@ -835,7 +859,7 @@ packet header, specific to the meta-data stream, which contains,
 exactly:
 
 struct metadata_packet_header {
 exactly:
 
 struct metadata_packet_header {

-  uint32_t magic;                      /* 0x3FF1C105 */
+  uint32_t magic;                      /* 0x75D11D57 */

   uint8_t  trace_uuid[16];             /* Unique Universal Identifier */
   uint32_t checksum;                   /* 0 if unused */
   uint32_t content_size;               /* in bits */
   uint8_t  trace_uuid[16];             /* Unique Universal Identifier */
   uint32_t checksum;                   /* 0 if unused */
   uint32_t content_size;               /* in bits */


@@ -935,7 +959,7 @@ readable by accessing the upper dynamic scopes.
 7.4 TSDL Examples
 
 The grammar representing the TSDL meta-data is presented in Appendix C.
 7.4 TSDL Examples
 
 The grammar representing the TSDL meta-data is presented in Appendix C.

-TSDL Grammar. This section presents a rather ligher reading that
+TSDL Grammar. This section presents a rather lighter reading that

 consists in examples of TSDL meta-data, with template values.
 
 The stream "id" can be left out if there is only one stream in the
 consists in examples of TSDL meta-data, with template values.
 
 The stream "id" can be left out if there is only one stream in the


@@ -969,7 +993,7 @@ stream {
 event {
   name = event_name;
   id = value;                  /* Numeric identifier within the stream */
 event {
   name = event_name;
   id = value;                  /* Numeric identifier within the stream */

-  stream = stream_id;
+  stream_id = stream_id;

   context := struct {
     ...
   };
   context := struct {
     ...
   };


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

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

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


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

+align

 const
 char
 double
 const
 char
 double


@@ -1248,14 +1277,6 @@ long-long-suffix:
        ll
        LL
 
        ll
        LL
 

-digit-sequence:
-       digit
-       digit-sequence digit
-
-hexadecimal-digit-sequence:
-       hexadecimal-digit
-       hexadecimal-digit-sequence hexadecimal-digit
-

 enumeration-constant:
        identifier
        string-literal
 enumeration-constant:
        identifier
        string-literal


@@ -1386,9 +1407,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