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 797dec14a53adc3009e11417257323e94635af6b..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,6 +165,11 @@ 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 */
@@ -388,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 {
   ...
@@ -682,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):
 
@@ -797,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
@@ -830,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
 
@@ -892,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