Clarify event layout

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 7a475e4f8af477ff2af4b1dea083649f97be1c93..b40193f4377661144b092bbc343b280d7588cfa7 100644 (file)
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -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.2 Event Context
+   6.2 Stream Event Context and Event Context
    6.3 Event Payload
        6.3.1 Padding
        6.3.2 Alignment
@@ -165,22 +165,35 @@ 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.
 
+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
 
-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 */
 
+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
+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
 
 Type size, in bits, for integers and floats is that returned by "sizeof()" in C
@@ -380,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.:
 
-typealias integer { size = 32; align = 32; signed = true } := int;
+typealias integer { size = 32; align = 32; signed = true; } := int;
 
 enum {
   ...
@@ -604,7 +617,7 @@ Arrays are always aligned on their element alignment requirement.
 
 4.2.4 Sequences
 
-Sequences are dynamically-sized arrays. They refer to a a "length"
+Sequences are dynamically-sized arrays. They refer to a "length"
 unsigned integer field, which must appear in either the same static scope,
 prior to the sequence field (in field declaration order), in an upper
 static scope, or in an upper dynamic scope (see Section 7.3.2). This
@@ -674,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
-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):
 
@@ -789,11 +801,10 @@ struct event_packet_context {
 
 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
@@ -822,11 +833,11 @@ array is then set to 1.
 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
 
-  typealias integer { size = X; align = 1; signed = false } := uintX_t;
+  typealias integer { size = X; align = 1; signed = false; } := uintX_t;
 
 6.1.1 Type 1 - Few event IDs
 
@@ -884,7 +895,7 @@ struct event_header_2 {
 } 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