X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=4cd7e7c751fcdbb851ac1f0c500471826827a269;hp=a036b30625c7c3db484e879254146ae424ff2af9;hb=b9606a77153ca805c474ad34693085fdebcbc36d;hpb=fdf2bb051263f91bbd55b8e3acfacee3c5a1efa5 diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index a036b30..4cd7e7c 100644 --- a/common-trace-format-proposal.txt +++ b/common-trace-format-proposal.txt @@ -68,14 +68,10 @@ A metadata event stream contains information on trace event types. It describes: 3. Event stream An event stream is divided in contiguous event packets of variable size. These -subdivisions have a variable size. An event packet can contain a certain amount -of padding at the end. The rationale for the event stream design choices is -explained in Appendix B. Stream Header Rationale. - -An event stream is divided in contiguous event packets of variable size. These -subdivisions have a variable size. An event packet can contain a certain amount -of padding at the end. The stream header is repeated at the beginning of each -event packet. +subdivisions have a variable size. An event packet can contain a certain +amount of padding at the end. The stream header is repeated at the +beginning of each event packet. The rationale for the event stream +design choices is explained in Appendix B. Stream Header Rationale. The event stream header will therefore be referred to as the "event packet header" throughout the rest of this document. @@ -616,9 +612,9 @@ The overall structure of an event is: 5 - Event Payload (as specified by the event metadata) This structure defines an implicit dynamic scoping, where variants -located in structures with higher number can refer to the fields of -structures with lower number. See Section 7.2 Metadata Scopes for more -detail. +located in inner structures (those with a higher number in the listing +above) can refer to the fields of outer structures (with lower number in +the listing above). See Section 7.2 Metadata Scopes for more detail. 6.1 Event Header @@ -791,10 +787,12 @@ variant field), a declaration is followed by a declarator, which specify the newly defined type name (for typedef), or the field name (for declarations located within structure and variants). Array and sequence, declared with square brackets ("[" "]"), are part of the declarator, -similarly to C99. +similarly to C99. The enumeration type specifier and variant tag name +(both specified with "<" ">") are part of the type specifier. A definition associates a type to a location in the event structure -hierarchy (see Section 6). +hierarchy (see Section 6). This association is denoted by ":=", as shown +in Section 7.3. 7.2 Metadata Scopes @@ -808,34 +806,36 @@ for variants references to tag fields. Each of "trace", "stream", "event", "struct" and "variant" have their own nestable declaration scope, within which types can be declared using "typedef" and "typealias". A root declaration scope also contains all declarations -located outside of any of the aforementioned declarations. An innermost +located outside of any of the aforementioned declarations. An inner declaration scope can refer to type declared within its container -lexical scope prior to the innermost declaration scope. Redefinition of -a typedef or typealias is not valid, although hiding an uppermost scope +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.2.2 Dynamic Scope -For variant tag definition only, the dynamic scope used to look up the -location of the associated tag field consists in the lexical scope of -the structures where the variant is declared, extended with the implicit -dynamic scope specified by the event structure hierarchy presented at -the beginning of Section 6. Therefore, lower levels in the dynamic scope -(e.g. event context) can refer to a tag field located in upper levels -(e.g. in the event header) by specifying, in this case, -"header.field_name" as tag identifier. This allows, for instance, the -event context to define a variant referring to the "id" field of the -event header as selector. +A dynamic scope consists in the lexical scope augmented with the +implicit event structure definition hierarchy presented at Section 6. +The dynamic scope is only used for variant tag definitions. It is used +at definition time to look up the location of the tag field associated +with a variant. + +Therefore, variants in lower levels in the dynamic scope (e.g. event +context) can refer to a tag field located in upper levels (e.g. in the +event header) by specifying, in this case, the associated tag with +. 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. The dynamic scope prefixes are thus: - - Stream Packet Context: "stream.packet.context.", - - Event Header: "stream.event.header.", - - Stream Event Context: "stream.event.context.", - - Event Context: "event.context.", - - Event Payload: "event.fields.". + - Stream Packet Context: , + - Event Header: , + - Stream Event Context: , + - Event Context: , + - Event Payload: . 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 @@ -843,8 +843,14 @@ 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 information available in the dynamic scopes can be thought of as the +current tracing context. At trace production, information about the +current context is saved into the specified scope field levels. At trace +consumption, for each event, the current trace context is therefore +readable by accessing the upper dynamic scopes. -7.2 Metadata Examples + +7.3 Metadata Examples The grammar representing the CTF metadata is presented in Appendix C. CTF Metadata Grammar. This section presents a rather ligher @@ -1238,6 +1244,9 @@ unary-operator: one of assignment-operator: = +type-assignment-operator: + := + constant-expression: unary-expression @@ -1278,6 +1287,7 @@ type-specifier: unsigned _Bool _Complex + _Imaginary struct-specifier variant-specifier enum-specifier