Cleanup: update alignment of TOC

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 4ab3ed99861b15af950a26d75722dcec382a2c12..4af2244ab37adfa5a513cff029811cbdcc48bcea 100644 (file)
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -41,12 +41,12 @@ Table of Contents
        4.1.6 GNU/C bitfields
        4.1.7 Floating point
        4.1.8 Enumerations
        4.1.6 GNU/C bitfields
        4.1.7 Floating point
        4.1.8 Enumerations

-4.2 Compound types
-    4.2.1 Structures
-    4.2.2 Variants (Discriminated/Tagged Unions)
-    4.2.3 Arrays
-    4.2.4 Sequences
-    4.2.5 Strings
+   4.2 Compound types
+       4.2.1 Structures
+       4.2.2 Variants (Discriminated/Tagged Unions)
+       4.2.3 Arrays
+       4.2.4 Sequences
+       4.2.5 Strings

 5. Event Packet Header
    5.1 Event Packet Header Description
    5.2 Event Packet Context Description
 5. Event Packet Header
    5.1 Event Packet Header Description
    5.2 Event Packet Context Description


@@ -54,7 +54,7 @@ Table of Contents
    6.1 Event Header
        6.1.1 Type 1 - Few event IDs
        6.1.2 Type 2 - Many event IDs
    6.1 Event Header
        6.1.1 Type 1 - Few event IDs
        6.1.2 Type 2 - Many event IDs

-   6.2 Event Context
+   6.2 Stream Event Context and Event Context

    6.3 Event Payload
        6.3.1 Padding
        6.3.2 Alignment
    6.3 Event Payload
        6.3.1 Padding
        6.3.2 Alignment


@@ -165,26 +165,34 @@ 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.
 
 explicitly. Alignment values must be power of two. Compound types are
 aligned as specified in their individual specification.
 

+The base offset used for field alignment is the start of the packet
+containing the field. For instance, a field aligned on 32-bit needs to
+be at an offset multiple of 32-bit from the start of the packet that
+contains it.
+

 TSDL meta-data attribute representation of a specific alignment:
 
   align = value;                                /* value in bits */
 
 4.1.3 Byte order
 
 TSDL meta-data attribute representation of a specific alignment:
 
   align = value;                                /* value in bits */
 
 4.1.3 Byte order
 

-By default, the native endianness of the source architecture is used.
-Byte order can be overridden for a basic type by specifying a "byte_order"
-attribute. Typical use-case is to specify the network byte order (big endian:
-"be") to save data captured from the network into the trace without conversion.
-If not specified, the byte order is native.
+By default, byte order of a basic type is the byte order described in
+the trace description.  It can be overridden by specifying a
+"byte_order" attribute for a basic type.  Typical use-case is to specify
+the network byte order (big endian: "be") to save data captured from the
+network into the trace without conversion.

 
 TSDL meta-data representation:
 
   byte_order = native OR network OR be OR le;  /* network and be are aliases */
 
 
 TSDL meta-data representation:
 
   byte_order = native OR network OR be OR le;  /* network and be are aliases */
 

+The "native" keyword selects the byte order described in the trace
+description. The "network" byte order is an alias for big endian.
+

 Even though the trace description section is not per se a type, for sake
 Even though the trace description section is not per se a type, for sake

-of clarity, it should be noted that native and network byte orders are
-only allowed within type declaration. The byte_order specified in the
-trace description section only accepts be OR le values.
+of clarity, it should be noted that "native" and "network" byte orders
+are only allowed within type declaration. The byte_order specified in
+the trace description section only accepts "be" or "le" values.

 
 4.1.4 Size
 
 
 4.1.4 Size
 


@@ -240,7 +248,7 @@ TSDL meta-data representation:
     size = value;                               /* value in bits, no default */
     align = value;                              /* value in bits */
     /* based used for pretty-printing output, default: decimal. */
     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
+    base = decimal OR dec 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;
     /* character encoding, default: none */
     encoding = none or UTF8 or ASCII;
            OR octal OR oct OR o OR 8 OR binary OR b OR 2;
     /* character encoding, default: none */
     encoding = none or UTF8 or ASCII;


@@ -385,7 +393,7 @@ Enumerations omitting the container type ": integer_type" use the "int"
 type (for compatibility with C99). The "int" type must be previously
 declared. E.g.:
 
 type (for compatibility with C99). The "int" type must be previously
 declared. E.g.:
 

-typealias integer { size = 32; align = 32; signed = true } := int;
+typealias integer { size = 32; align = 32; signed = true; } := int;

 
 enum {
   ...
 
 enum {
   ...


@@ -679,8 +687,7 @@ Strings are always aligned on byte size.
 The event packet header consists of two parts: the "event packet header"
 is the same for all streams of a trace. The second part, the "event
 packet context", is described on a per-stream basis. Both are described
 The event packet header consists of two parts: the "event packet header"
 is the same for all streams of a trace. The second part, the "event
 packet context", is described on a per-stream basis. Both are described

-in the TSDL meta-data. The packets are aligned on architecture-page-sized
-addresses.
+in the TSDL meta-data.

 
 Event packet header (all fields are optional, specified by TSDL meta-data):
 
 
 Event packet header (all fields are optional, specified by TSDL meta-data):
 


@@ -710,6 +717,11 @@ Event packet context (all fields are optional, specified by TSDL meta-data):
   while (or before) writing the first event and while (or after) writing the
   last event in the packet. The inclusive range between these timestamps should
   include all event timestamps assigned to events contained within the packet.
   while (or before) writing the first event and while (or after) writing the
   last event in the packet. The inclusive range between these timestamps should
   include all event timestamps assigned to events contained within the packet.

+  The timestamp at the beginning of an event packet is guaranteed to be
+  below or equal the timestamp at the end of that event packet.
+  The timestamp at the end of an event packet is guaranteed to be below
+  or equal the timestamps at the end of any following packet within the
+  same stream. See Section 8. Clocks for more detail.

 - Events discarded count
   - Snapshot of a per-stream free-running counter, counting the number of
     events discarded that were supposed to be written in the stream after
 - Events discarded count
   - Snapshot of a per-stream free-running counter, counting the number of
     events discarded that were supposed to be written in the stream after


@@ -794,17 +806,22 @@ struct event_packet_context {
 
 The overall structure of an event is:
 
 
 The overall structure of an event is:
 

-1 - Stream Packet Context (as specified by the stream meta-data)
- 2 - Event Header (as specified by the stream meta-data)
-  3 - Stream Event Context (as specified by the stream meta-data)
-   4 - Event Context (as specified by the event meta-data)
-    5 - Event Payload (as specified by the event meta-data)
+1 - Event Header (as specified by the stream meta-data)
+ 2 - Stream Event Context (as specified by the stream meta-data)
+  3 - Event Context (as specified by the event meta-data)
+   4 - Event Payload (as specified by the event meta-data)

 
 This structure defines an implicit dynamic scoping, where variants
 located in inner structures (those with a higher number in the listing
 above) can refer to the fields of outer structures (with lower number in
 the listing above). See Section 7.3 TSDL Scopes for more detail.
 
 
 This structure defines an implicit dynamic scoping, where variants
 located in inner structures (those with a higher number in the listing
 above) can refer to the fields of outer structures (with lower number in
 the listing above). See Section 7.3 TSDL Scopes for more detail.
 

+The total length of an event is defined as the difference between the
+end of its Event Payload and the end of the previous event's Event
+Payload. Therefore, it includes the event header alignment padding, and
+all its fields and their respective alignment padding. Events of length
+0 are forbidden.
+

 6.1 Event Header
 
 Event headers can be described within the meta-data. We hereby propose, as an
 6.1 Event Header
 
 Event headers can be described within the meta-data. We hereby propose, as an


@@ -827,11 +844,13 @@ array is then set to 1.
 Types uintX_t represent an X-bit unsigned integer, as declared with
 either:
 
 Types uintX_t represent an X-bit unsigned integer, as declared with
 either:
 

-  typealias integer { size = X; align = X; signed = false } := uintX_t;
+  typealias integer { size = X; align = X; signed = false; } := uintX_t;

 
     or
 
 
     or
 

-  typealias integer { size = X; align = 1; signed = false } := uintX_t;
+  typealias integer { size = X; align = 1; signed = false; } := uintX_t;
+
+For more information about timestamp fields, see Section 8. Clocks.

 
 6.1.1 Type 1 - Few event IDs
 
 
 6.1.1 Type 1 - Few event IDs
 


@@ -889,7 +908,7 @@ struct event_header_2 {
 } align(16);   /* or align(8) */
 
 
 } align(16);   /* or align(8) */
 
 

-6.2 Event Context
+6.2 Stream Event Context and Event Context

 
 The event context contains information relative to the current event.
 The choice and meaning of this information is specified by the TSDL
 
 The event context contains information relative to the current event.
 The choice and meaning of this information is specified by the TSDL


@@ -1371,10 +1390,11 @@ stream {
 };
 
 For a N-bit integer type referring to a clock, if the integer overflows
 };
 
 For a N-bit integer type referring to a clock, if the integer overflows

-compared to the N low order bits of the clock prior value, then it is
-assumed that one, and only one, overflow occurred. It is therefore
-important that events encoding time on a small number of bits happen
-frequently enough to detect when more than one N-bit overflow occurs.
+compared to the N low order bits of the clock prior value found in the
+same stream, then it is assumed that one, and only one, overflow
+occurred. It is therefore important that events encoding time on a small
+number of bits happen frequently enough to detect when more than one
+N-bit overflow occurs.

 
 In a packet context, clock field names ending with "_begin" and "_end"
 have a special meaning: this refers to the time-stamps at, respectively,
 
 In a packet context, clock field names ending with "_begin" and "_end"
 have a special meaning: this refers to the time-stamps at, respectively,