X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-specification.txt;h=797dec14a53adc3009e11417257323e94635af6b;hp=3130d98014ea9639a8ebe302d968abc48ee20ebf;hb=fbf2fa4f7c15cfcde273e35cbc5ff2f9e7289043;hpb=3568031f04910c52dffce8a66c313fbc8744bfa3

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 3130d98..797dec1 100644
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -1,4 +1,4 @@
-Common Trace Format (CTF) Specification (v1.8.1)
+Common Trace Format (CTF) Specification (v1.8.2)
 
 Mathieu Desnoyers, EfficiOS Inc.
 
@@ -171,16 +171,24 @@ TSDL meta-data attribute representation of a specific alignment:
 
 4.1.3 Byte order
 
-By default, the native endianness of the source architecture is used.
-Byte order can be overridden for a basic type by specifying a "byte_order"
-attribute. Typical use-case is to specify the network byte order (big endian:
-"be") to save data captured from the network into the trace without conversion.
-If not specified, the byte order is native.
+By default, byte order of a basic type is the byte order described in
+the trace description.  It can be overridden by specifying a
+"byte_order" attribute for a basic type.  Typical use-case is to specify
+the network byte order (big endian: "be") to save data captured from the
+network into the trace without conversion.
 
 TSDL meta-data representation:
 
   byte_order = native OR network OR be OR le;	/* network and be are aliases */
 
+The "native" keyword selects the byte order described in the trace
+description. The "network" byte order is an alias for big endian.
+
+Even though the trace description section is not per se a type, for sake
+of clarity, it should be noted that "native" and "network" byte orders
+are only allowed within type declaration. The byte_order specified in
+the trace description section only accepts "be" or "le" values.
+
 4.1.4 Size
 
 Type size, in bits, for integers and floats is that returned by "sizeof()" in C
@@ -454,11 +462,28 @@ type selector. The field to use as tag is specified by the "tag_field",
 specified between "< >" after the "variant" keyword for unnamed
 variants, and after "variant name" for named variants.
 
-The alignment of the variant is the alignment of the type as selected by the tag
-value for the specific instance of the variant. The alignment of the type
-containing the variant is independent of the variant alignment.  The size of the
-variant is the size as selected by the tag value for the specific instance of
-the variant.
+The alignment of the variant is the alignment of the type as selected by
+the tag value for the specific instance of the variant.  The size of the
+variant is the size as selected by the tag value for the specific
+instance of the variant.
+
+The alignment of the type containing the variant is independent of the
+variant alignment.  For instance, if a structure contains two fields, a
+32-bit integer, aligned on 32 bits, and a variant, which contains two
+choices: either a 32-bit field, aligned on 32 bits, or a 64-bit field,
+aligned on 64 bits, the alignment of the outmost structure will be
+32-bit (the alignment of its largest field, disregarding the alignment
+of the variant). The alignment of the variant will depend on the
+selector: if the variant's 32-bit field is selected, its alignment will
+be 32-bit, or 64-bit otherwise. It is important to note that variants
+are specifically tailored for compactness in a stream. Therefore, the
+relative offsets of compound type fields can vary depending on
+the offset at which the compound type starts if it contains a variant
+that itself contains a type with alignment larger than the largest field
+contained within the compound type. This is caused by the fact that the
+compound type may contain the enumeration that select the variant's
+choice, and therefore the alignment to be applied to the compound type
+cannot be determined before encountering the enumeration.
 
 Each variant type selector possess a field name, which is a unique
 identifier within the variant. The identifier is not allowed to use any
@@ -587,7 +612,7 @@ Arrays are always aligned on their element alignment requirement.
 
 4.2.4 Sequences
 
-Sequences are dynamically-sized arrays. They refer to a a "length"
+Sequences are dynamically-sized arrays. They refer to a "length"
 unsigned integer field, which must appear in either the same static scope,
 prior to the sequence field (in field declaration order), in an upper
 static scope, or in an upper dynamic scope (see Section 7.3.2). This
@@ -760,8 +785,8 @@ struct event_packet_context {
   uint32_t stream_packet_count;
   uint32_t events_discarded;
   uint32_t cpu_id;
-  uint32_t/uint16_t content_size;
-  uint32_t/uint16_t packet_size;
+  uint64_t/uint32_t/uint16_t content_size;
+  uint64_t/uint32_t/uint16_t packet_size;
   uint8_t  compression_scheme;
   uint8_t  encryption_scheme;
   uint8_t  checksum_scheme;
@@ -973,12 +998,13 @@ 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 "sequence" payload, which is a sequence of bits using the
-"trace.packet.header.content_size" field as a placeholder for its length
-(the packet header size should be substracted). The formatting of this
-sequence of bits is a plain-text representation of the TSDL description.
-Each meta-data packet start with a special packet header, specific to
-the meta-data stream, which contains, exactly:
+contains a special "sequence" payload, which is a sequence of bits which
+length is implicitly calculated by using the
+"trace.packet.header.content_size" field, minus the packet header size.
+The formatting of this sequence of bits is a plain-text representation
+of the TSDL description.  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 */
@@ -1155,6 +1181,7 @@ event {
   id = value;			/* Numeric identifier within the stream */
   stream_id = stream_id;
   loglevel = value;
+  model.emf.uri = "string";
   context := struct {
     ...
   };
@@ -1163,6 +1190,14 @@ event {
   };
 };
 
+callsite {
+  name = "event_name";
+  func = "func_name";
+  file = "myfile.c";
+  line = 39;
+  ip = 0x40096c;
+};
+
 /* More detail on types in section 4. Types */
 
 /*
@@ -1418,6 +1453,7 @@ token:
 keyword: is one of
 
 align
+callsite
 const
 char
 clock
@@ -1741,6 +1777,7 @@ ctf-specifier:
 	stream { ctf-assignment-expression-list-opt }
 	env { ctf-assignment-expression-list-opt }
 	trace { ctf-assignment-expression-list-opt }
+	callsite { ctf-assignment-expression-list-opt }
 	typealias declaration-specifiers abstract-declarator-list type-assignment-operator declaration-specifiers abstract-declarator-list
 	typealias declaration-specifiers abstract-declarator-list type-assignment-operator declarator-list