Explain that ids can be left out if single stream/event

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

diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt
index 91a95048c5e51e192055020a652df9797d74cba7..71d9140704eb049dba1032c11c392f209f802b21 100644 (file)
--- 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
 
 
 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;
 };
 
 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
 5.2 Event Packet Context Description
 
 Event packet context example. These are declared within the stream declaration


@@ -879,13 +899,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
 
 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 */
 
 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 {
 };
 
 stream {