-It is made of "event packets", which each start with an event packet
-header. The event type within the metadata stream have no event header
-nor event context. Each event only contains a "string" payload without
-any null-character. The events are packed one next to another. Each
-event packet start with an event packet header, which contains, amongst
-other fields, the magic number, trace UUID and packet length. In the
-event packet header, the trace UUID is represented as an array of bytes.
-Within the string-based metadata description, the trace UUID is
-represented as a string of hexadecimal digits and dashes "-".
+The meta-data description can be expressed in two different formats:
+text-only and packet-based. The text-only description facilitates
+generation of meta-data and provides a convenient way to enter the
+meta-data information by hand. The packet-based meta-data provides the
+CTF stream packet facilities (checksumming, compression, encryption,
+network-readiness) for meta-data stream generated and transported by a
+tracer.
+
+The text-only meta-data file is a plain text TSDL description.
+
+The packet-based meta-data is made of "meta-data packets", which each
+start with a meta-data packet header. The packet-based meta-data
+description is detected by reading the magic number "0x75D11D57" at the
+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 "string" payload. 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 */
+ uint8_t trace_uuid[16]; /* Unique Universal Identifier */
+ uint32_t checksum; /* 0 if unused */
+ uint32_t content_size; /* in bits */
+ uint32_t packet_size; /* in bits */
+ uint8_t compression_scheme; /* 0 if unused */
+ uint8_t encryption_scheme; /* 0 if unused */
+ uint8_t checksum_scheme; /* 0 if unused */
+};