Change metadata header to include version

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

diff --git a/common-trace-format-specification.txt b/common-trace-format-specification.txt
index 1400952f94d2cf2872e1ec83a529df35e3a4bdfd..704968d1054268990b4ed83d3095581d8f6156a1 100644 (file)
--- a/common-trace-format-specification.txt
+++ b/common-trace-format-specification.txt
@@ -63,7 +63,7 @@ Table of Contents
    7.2 Declaration vs Definition
    7.3 TSDL Scopes
        7.3.1 Lexical Scope
    7.2 Declaration vs Definition
    7.3 TSDL Scopes
        7.3.1 Lexical Scope

-       7.3.2 Dynamic Scope
+       7.3.2 Static and Dynamic Scopes

    7.4 TSDL Examples
 
 
    7.4 TSDL Examples
 
 


@@ -93,8 +93,9 @@ subset of the trace event types.
 The final output of the trace, after its generation and optional transport over
 the network, is expected to be either on permanent or temporary storage in a
 virtual file system. Because each event stream is appended to while a trace is
 The final output of the trace, after its generation and optional transport over
 the network, is expected to be either on permanent or temporary storage in a
 virtual file system. Because each event stream is appended to while a trace is

-being recorded, each is associated with a separate file for output.  Therefore,
-a stored trace can be represented as a directory containing one file per stream.
+being recorded, each is associated with a distinct set of files for
+output. Therefore, a stored trace can be represented as a directory
+containing zero, one or more files per stream.

 
 Meta-data description associated with the trace contains information on
 trace event types expressed in the Trace Stream Description Language
 
 Meta-data description associated with the trace contains information on
 trace event types expressed in the Trace Stream Description Language


@@ -439,14 +440,13 @@ struct {
 A CTF variant is a selection between different types. A CTF variant must
 always be defined within the scope of a structure or within fields
 contained within a structure (defined recursively). A "tag" enumeration
 A CTF variant is a selection between different types. A CTF variant must
 always be defined within the scope of a structure or within fields
 contained within a structure (defined recursively). A "tag" enumeration

-field must appear in either the same lexical scope, prior to the variant
-field (in field declaration order), in an upper lexical scope (see
-Section 7.3.1), or in an upper dynamic scope (see Section 7.3.2). The
-type selection is indicated by the mapping from the enumeration value to
-the string used as variant 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.
+field must appear in either the same static scope, prior to the variant
+field (in field declaration order), in an upper static scope , or in an
+upper dynamic scope (see Section 7.3.2). The type selection is indicated
+by the mapping from the enumeration value to the string used as variant
+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
 
 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


@@ -528,16 +528,16 @@ struct {
 
 Example of a variant type definition within a structure, where the defined type
 is then declared within an array of structures. This variant refers to a tag
 
 Example of a variant type definition within a structure, where the defined type
 is then declared within an array of structures. This variant refers to a tag

-located in an upper lexical scope. This example clearly shows that a variant
+located in an upper static scope. This example clearly shows that a variant

 type definition referring to the tag "x" uses the closest preceding field from
 type definition referring to the tag "x" uses the closest preceding field from

-the lexical scope of the type definition.
+the static scope of the type definition.

 
 struct {
   enum : uint2_t { a, b, c, d } x;
 
   typedef variant <x> {        /*
                         * "x" refers to the preceding "x" enumeration in the
 
 struct {
   enum : uint2_t { a, b, c, d } x;
 
   typedef variant <x> {        /*
                         * "x" refers to the preceding "x" enumeration in the

-                        * lexical scope of the type definition.
+                        * static scope of the type definition.

                         */
     uint32_t a;
     uint64_t b;
                         */
     uint32_t a;
     uint64_t b;


@@ -574,11 +574,11 @@ Arrays are always aligned on their element alignment requirement.
 4.2.4 Sequences
 
 Sequences are dynamically-sized arrays. They refer to a a "length"
 4.2.4 Sequences
 
 Sequences are dynamically-sized arrays. They refer to a a "length"

-unsigned integer field, which must appear in either the same lexical scope,
+unsigned integer field, which must appear in either the same static scope,

 prior to the sequence field (in field declaration order), in an upper
 prior to the sequence field (in field declaration order), in an upper

-lexical scope (see Section 7.3.1), or in an upper dynamic scope (see
-Section 7.3.2). This length field represents the number of elements in
-the sequence. The sequence per se is an array of "inner type" elements.
+static scope, or in an upper dynamic scope (see Section 7.3.2). This
+length field represents the number of elements in the sequence. The
+sequence per se is an array of "inner type" elements.

 
 TSDL meta-data representation for a sequence type definition:
 
 
 TSDL meta-data representation for a sequence type definition:
 


@@ -933,7 +933,21 @@ CTF stream packet facilities (checksumming, compression, encryption,
 network-readiness) for meta-data stream generated and transported by a
 tracer.
 
 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 text-only meta-data file is a plain-text TSDL description. This file
+must begin with the following characters to identify the file as a CTF
+TSDL text-based metadata file (without the double-quotes) :
+
+"/* CTF"
+
+It must be followed by a space, and the version of the specification
+followed by the CTF trace, e.g.:
+
+" 1.8"
+
+These characters allow automated discovery of file type and CTF
+specification version. They are interpreted as a the beginning of a
+comment by the TSDL metadata parser.  The comment can be continued to
+contain extra commented characters before it is closed.

 
 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
 
 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


@@ -958,6 +972,8 @@ struct metadata_packet_header {
   uint8_t  compression_scheme;         /* 0 if unused */
   uint8_t  encryption_scheme;          /* 0 if unused */
   uint8_t  checksum_scheme;            /* 0 if unused */
   uint8_t  compression_scheme;         /* 0 if unused */
   uint8_t  encryption_scheme;          /* 0 if unused */
   uint8_t  checksum_scheme;            /* 0 if unused */

+  uint8_t  major;                      /* CTF spec version major number */
+  uint8_t  minor;                      /* CTF spec version minor number */

 };
 
 The packet-based meta-data can be converted to a text-only meta-data by
 };
 
 The packet-based meta-data can be converted to a text-only meta-data by


@@ -993,10 +1009,10 @@ in Section 7.3.
 
 7.3 TSDL Scopes
 
 
 7.3 TSDL Scopes
 

-TSDL uses two different types of scoping: a lexical scope is used for
-declarations and type definitions, and a dynamic scope is used for
-variants references to tag fields and for sequence references to length
-fields.
+TSDL uses three different types of scoping: a lexical scope is used for
+declarations and type definitions, and static and dynamic scopes are
+used for variants references to tag fields (with relative and absolute
+path lookups) and for sequence references to length fields.

 
 7.3.1 Lexical Scope
 
 
 7.3.1 Lexical Scope
 


@@ -1009,25 +1025,42 @@ lexical scope prior to the inner declaration scope. Redefinition of a
 typedef or typealias is not valid, although hiding an upper scope
 typedef or typealias is allowed within a sub-scope.
 
 typedef or typealias is not valid, although hiding an upper scope
 typedef or typealias is allowed within a sub-scope.
 

-7.3.2 Dynamic Scope
+7.3.2 Static and Dynamic Scopes
+
+A local static scope consists in the scope generated by the declaration
+of fields within a compound type. A static scope is a local static scope
+augmented with the nested sub-static-scopes it contains.

 
 

-A dynamic scope consists in the lexical scope augmented with the
+A dynamic scope consists in the static scope augmented with the

 implicit event structure definition hierarchy presented at Section 6.
 implicit event structure definition hierarchy presented at Section 6.

-The dynamic scope is used for variant tag and sequence length
-definitions. It is used at definition time to look up the location of
-the tag field associated with a variant, and to lookup up the location
-of the length field associated with a sequence.
-
-Therefore, variants (or sequences) in lower levels in the dynamic scope
-(e.g. event context) can refer to a tag (or length) field located in
-upper levels (e.g. in the event header) by specifying, in this case, the
-associated tag with <header.field_name>. This allows, for instance, the
-event context to define a variant referring to the "id" field of the
-event header as selector.

 
 

-The target dynamic scope must be specified explicitly when referring to
-a field outside of the local static scope (a local static scope contains
-all fields present within the same scope, at the same nesting level).
+Multiple declarations of the same field name within a local static scope
+is not valid. It is however valid to re-use the same field name in
+different local scopes.
+
+Nested static and dynamic scopes form lookup paths. These are used for
+variant tag and sequence length references. They are used at the variant
+and sequence definition site to look up the location of the tag field
+associated with a variant, and to lookup up the location of the length
+field associated with a sequence.
+
+Variants and sequences can refer to a tag field either using a relative
+path or an absolute path. The relative path starts with "." to ensure
+there are no conflicts with dynamic scope names. It is relative to the
+scope in which the variant or sequence performing the lookup is located.
+Relative paths are only allowed to lookup within the same static scope,
+which includes its nested static scopes. Lookups targeting parent static
+scopes need to be performed with an absolute path.
+
+Absolute path lookups use the full path including the dynamic scope
+followed by a "." and then the static scope. Therefore, variants (or
+sequences) in lower levels in the dynamic scope (e.g. event context) can
+refer to a tag (or length) field located in upper levels (e.g. in the
+event header) by specifying, in this case, the associated tag with
+<stream.event.header.field_name>. This allows, for instance, the event
+context to define a variant referring to the "id" field of the event
+header as selector.
+

 The dynamic scope prefixes are thus:
 
  - Trace Packet Header: <trace.packet.header. >,
 The dynamic scope prefixes are thus:
 
  - Trace Packet Header: <trace.packet.header. >,


@@ -1037,11 +1070,17 @@ The dynamic scope prefixes are thus:
  - Event Context: <event.context. >,
  - Event Payload: <event.fields. >.
 
  - Event Context: <event.context. >,
  - Event Payload: <event.fields. >.
 

-Multiple declarations of the same field name within a single scope is
-not valid. It is however valid to re-use the same field name in
-different scopes. There is no possible conflict, because the dynamic
-scope must be specified when a variant refers to a tag field located in
-a different dynamic scope.
+
+The target dynamic scope must be specified explicitly when referring to
+a field outside of the static scope (absolute scope reference).
+References to fields within the static scope (including local static
+scopes and nested static scopes) can be referenced by using a relative
+reference (starting with ".").
+
+As a matter of convenience, the leading "." in relative paths can be
+omitted. In case of conflict between relative and dynamic paths, the
+relative path is preferred. It is recommended to use the "." prefix for
+relative paths to ensure no path name conflict can occur.

 
 The information available in the dynamic scopes can be thought of as the
 current tracing context. At trace production, information about the
 
 The information available in the dynamic scopes can be thought of as the
 current tracing context. At trace production, information about the


@@ -1532,7 +1571,7 @@ variant-specifier:
        variant identifier variant-tag
 
 variant-tag:
        variant identifier variant-tag
 
 variant-tag:

-       < identifier >
+       < unary-expression >

 
 enum-specifier:
        enum identifier-opt { enumerator-list }
 
 enum-specifier:
        enum identifier-opt { enumerator-list }