Require trace byte_order field, remove use of magic number for autodetection

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index 8182ea991f7da92d49b2a35e193ec91213d62762..7f978306bd44eeb91ca40136a1c20c8a5f803324 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)
@@ -597,9 +593,6 @@ trace {
   packet.header := struct event_packet_header;
 };
 
-If a packet header lacks the "magic" number field, the trace endianness
-needs to be specified in the trace "endian" metadata attribute.
-
 If the trace_uuid is not present, no validation that the metadata
 actually corresponds to the stream is performed.
 
@@ -876,6 +869,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. >,
@@ -901,15 +895,15 @@ 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.
 
-Note that the trace endianness is usually extracted from the packet
-header magic number. The "endian" field is only needed when the magic
-number packet header field is not present.
+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 */
-  endian = big OR little;                      /* Endianness (optional) */
+  byte_order = be OR le;                       /* Endianness (required) */
   packet.header := struct {
     uint32_t magic;
     uint8_t  trace_uuid[16];