Update struct event_packet_context
[ctf.git] / common-trace-format-specification.txt
index 918b47218343c3bf5cae09b512a0dfa785efc119..e8c9e48f6d87145e20a4c4af7a7bf5cc6cedc729 100644 (file)
@@ -63,7 +63,7 @@ Table of Contents
    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
 
 
@@ -93,9 +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
-being recorded, each is associated with a separate file for output.  Therefore,
-a stored trace can be represented as a directory containing at least 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
@@ -415,8 +415,11 @@ struct example {
   uint64_t second_field_name;  /* Named type declared in the meta-data */
 };
 
-The fields are placed in a sequence next to each other. They each possess a
-field name, which is a unique identifier within the structure.
+The fields are placed in a sequence next to each other. They each
+possess a field name, which is a unique identifier within the structure.
+The identifier is not allowed to use any reserved keyword
+(see Section C.1.2). Replacing reserved keywords with
+underscore-prefixed field names is recommended.
 
 A nameless structure can be declared as a field type or as part of a typedef:
 
@@ -440,14 +443,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
-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
@@ -455,6 +457,11 @@ 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.
 
+Each variant type selector possess a field name, which is a unique
+identifier within the variant. The identifier is not allowed to use any
+reserved keyword (see Section C.1.2). Replacing reserved keywords with
+underscore-prefixed field names is recommended.
+
 A named variant declaration followed by its definition within a structure
 declaration:
 
@@ -529,16 +536,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
-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
-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
-                        * lexical scope of the type definition.
+                        * static scope of the type definition.
                         */
     uint32_t a;
     uint64_t b;
@@ -575,11 +582,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"
-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
-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:
 
@@ -745,7 +752,6 @@ struct event_packet_context {
   uint32_t cpu_id;
   uint32_t/uint16_t content_size;
   uint32_t/uint16_t packet_size;
-  uint8_t  stream_packet_count_bits;   /* Significant counter bits */
   uint8_t  compression_scheme;
   uint8_t  encryption_scheme;
   uint8_t  checksum_scheme;
@@ -934,7 +940,21 @@ 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 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
@@ -959,6 +979,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  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
@@ -994,10 +1016,10 @@ in Section 7.3.
 
 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
 
@@ -1010,25 +1032,41 @@ 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.
 
-7.3.2 Dynamic Scope
+7.3.2 Static and Dynamic Scopes
 
-A dynamic scope consists in the lexical scope augmented with the
+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 static scope augmented with the
 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 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. >,
@@ -1038,11 +1076,15 @@ The dynamic scope prefixes are thus:
  - 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). No
+conflict can occur between relative and dynamic paths, because the
+keywords "trace", "stream", and "event" are reserved, and thus
+not permitted as field names. It is recommended that field names
+clashing with CTF and C99 reserved keywords use an underscore prefix to
+eliminate the risk of generating a description containing an invalid
+field name.
 
 The information available in the dynamic scopes can be thought of as the
 current tracing context. At trace production, information about the
@@ -1086,9 +1128,11 @@ stream {
 };
 
 event {
-  name = event_name;
+  name = "event_name";
   id = value;                  /* Numeric identifier within the stream */
   stream_id = stream_id;
+  loglevel.identifier = "loglevel_identifier";
+  loglevel.value = value;
   context := struct {
     ...
   };
@@ -1533,7 +1577,7 @@ variant-specifier:
        variant identifier variant-tag
 
 variant-tag:
-       < identifier >
+       < unary-expression >
 
 enum-specifier:
        enum identifier-opt { enumerator-list }
This page took 0.035201 seconds and 4 git commands to generate.