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
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
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;
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:
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
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 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. >,
- 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
variant identifier variant-tag
variant-tag:
- < identifier >
+ < unary-expression >
enum-specifier:
enum identifier-opt { enumerator-list }
projects / ctf.git / commitdiff
