X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=7a3b61c7a6d6009704a84a703a6c8e8683e91905;hp=91a95048c5e51e192055020a652df9797d74cba7;hb=e0d9e2c75d3b40e1278a8a0ac05bb17997c4360e;hpb=6c7226e9d56e54d2387748a40d9198c333511442

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index 91a9504..7a3b61c 100644
--- a/common-trace-format-proposal.txt
+++ b/common-trace-format-proposal.txt
@@ -582,12 +582,32 @@ Metadata-defined layout (event packet context):
 
 5.1 Event Packet Header Fixed Layout Description
 
+The event packet header layout is indicated by the trace packet.header
+field. Here is an example structure type for the packet header with the
+fields typically expected:
+
 struct event_packet_header {
   uint32_t magic;
   uint8_t  trace_uuid[16];
   uint32_t stream_id;
 };
 
+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.
+
+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
@@ -856,6 +876,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. >,
@@ -879,13 +900,26 @@ 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.
+
+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 */
-  word_size = value;
+  endian = big OR little;			/* Endianness (optional) */
+  packet.header := struct {
+    uint32_t magic;
+    uint8_t  trace_uuid[16];
+    uint32_t stream_id;
+  };
 };
 
 stream {