Clarify metadata sequence

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 86e95b2e521a34ed360e61636f5d4df97820cf58..331b9dade401bf5f115024434efc4b90103fb6a9 100644 (file)
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -118,11 +118,10 @@ trace event types expressed in the Trace Stream Description Language
 3. Event stream
 
 An event stream can be divided into contiguous event packets of variable
-size. These subdivisions have a variable size. An event packet can
-contain a certain amount of padding at the end. The stream header is
-repeated at the beginning of each event packet. The rationale for the
-event stream design choices is explained in Appendix B. Stream Header
-Rationale.
+size. An event packet can contain a certain amount of padding at the
+end. The stream header is repeated at the beginning of each event
+packet. The rationale for the event stream design choices is explained
+in Appendix B. Stream Header Rationale.
 
 The event stream header will therefore be referred to as the "event packet
 header" throughout the rest of this document.
@@ -691,11 +690,15 @@ Event packet context (all fields are optional, specified by TSDL meta-data):
   include all event timestamps assigned to events contained within the packet.
 - 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 prior to
-    the first event in the event packet.
-    * Note: producer-consumer buffer full condition should fill the current
+    events discarded that were supposed to be written in the stream after
+    the last event in the event packet.
+    * Note: producer-consumer buffer full condition can fill the current
             event packet with padding so we know exactly where events have been
-            discarded.
+           discarded. However, if the buffer full condition chooses not
+           to fill the current event packet with padding, all we know
+           about the timestamp range in which the events have been
+           discarded is that it is somewhere between the beginning and
+            the end of the packet.
 - Lossless compression scheme used for the event packet content. Applied
   directly to raw data. New types of compression can be added in following
   versions of the format.
@@ -970,12 +973,13 @@ beginning of the file. This magic number is also used to detect the
 endianness of the architecture by trying to read the CTF magic number
 and its counterpart in reversed endianness. The events within the
 meta-data stream have no event header nor event context. Each event only
-contains a "sequence" payload, which is a sequence of bits using the
-"trace.packet.header.content_size" field as a placeholder for its length
-(the packet header size should be substracted). The formatting of this
-sequence of bits is a plain-text representation of the TSDL description.
-Each meta-data packet start with a special packet header, specific to
-the meta-data stream, which contains, exactly:
+contains a special "sequence" payload, which is a sequence of bits which
+length is implicitly calculated by using the
+"trace.packet.header.content_size" field, minus the packet header size.
+The formatting of this sequence of bits is a plain-text representation
+of the TSDL description.  Each meta-data packet start with a special
+packet header, specific to the meta-data stream, which contains,
+exactly:
 
 struct metadata_packet_header {
   uint32_t magic;                      /* 0x75D11D57 */
@@ -991,7 +995,7 @@ struct metadata_packet_header {
 };
 
 The packet-based meta-data can be converted to a text-only meta-data by
-concatenating all the strings in contains.
+concatenating all the strings it contains.
 
 In the textual representation of the meta-data, the text contained
 within "/*" and "*/", as well as within "//" and end of line, are