Specify that size includes headers

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index 35c1e71b4c662abdfb509149c2a7ca73ade1ef27..655a00b4e19352bf044df522e3d213a3f9e7a00e 100644 (file)
--- a/common-trace-format-proposal.txt
+++ b/common-trace-format-proposal.txt
@@ -530,14 +530,10 @@ the metadata.
 
 Fixed layout (event packet header):
 
-- Magic number (CTF magic numbers: 0xC1FC1FC1 and its reverse endianness
-  representation: 0xC11FFCC1) It needs to have a non-symmetric bytewise
-  representation. Used to distinguish between big and little endian traces (this
-  information is determined by knowing the endianness of the architecture
-  reading the trace and comparing the magic number against its value and the
-  reverse, 0xC11FFCC1). This magic number specifies that we use the CTF metadata
-  description language described in this document. Different magic numbers
-  should be used for other metadata description languages.
+- Magic number (CTF magic number: 0xC1FC1FC1 This magic number specifies
+  that we use the CTF metadata description language described in this
+  document. Different magic numbers should be used for other metadata
+  description languages.
 - Trace UUID, used to ensure the event packet match the metadata used.
   (note: we cannot use a metadata checksum because metadata can be appended to
    while tracing is active)
@@ -551,7 +547,7 @@ Metadata-defined layout (event packet context):
   header.
 - Per-stream event packet sequence count (to deal with UDP packet loss). The
   number of significant sequence counter bits should also be present, so
-  wrap-arounds are deal with correctly.
+  wrap-arounds are dealt with correctly.
 - Timestamp at the beginning and timestamp at the end of the event packet.
   Both timestamps are written in the packet header, but sampled respectively
   while (or before) writing the first event and while (or after) writing the
@@ -597,11 +593,21 @@ trace {
   packet.header := struct event_packet_header;
 };
 
+If the trace_uuid is not present, no validation that the metadata
+actually corresponds to the stream is performed.
+
+If the stream_id packet header field is missing, the trace can only
+contain a single stream. Its "id" field can be left out, and its events
+don't need to declare a "stream_id" field.
+
+
 5.2 Event Packet Context Description
 
 Event packet context example. These are declared within the stream declaration
-in the metadata. All these fields are optional except for "content_size" and
-"packet_size", which must be present in the context.
+in the metadata. All these fields are optional. If the packet size field is
+missing, the whole stream only contains a single packet. If the content
+size field is missing, the packet is filled (no padding). The content
+and packet sizes include all headers.
 
 An example event packet context type:
 
@@ -865,6 +871,7 @@ The target dynamic scope must be specified explicitly when referring to
 a field outside of the local static scope. The dynamic scope prefixes
 are thus:
 
+ - Trace Packet Header: <trace.packet.header. >,
  - Stream Packet Context: <stream.packet.context. >,
  - Event Header: <stream.event.header. >,
  - Stream Event Context: <stream.event.context. >,
@@ -888,12 +895,17 @@ readable by accessing the upper dynamic scopes.
 
 The grammar representing the TSDL metadata is presented in Appendix C.
 TSDL Grammar. This section presents a rather ligher reading that
-consists in examples of TSDL metadata, with template values:
+consists in examples of TSDL metadata, with template values.
+
+The stream "id" can be left out if there is only one stream in the
+trace. The event "id" field can be left out if there is only one event
+in a stream.
 
 trace {
   major = value;                               /* Trace format version */
   minor = value;
   uuid = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa";       /* Trace UUID */
+  byte_order = be OR le;                       /* Endianness (required) */
   packet.header := struct {
     uint32_t magic;
     uint8_t  trace_uuid[16];