X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=ef6739ff114375135fb65eb57bd2eccbd36b97b1;hp=a036b30625c7c3db484e879254146ae424ff2af9;hb=80af8ac60b88e28f699d15c28ce44723efdb82ad;hpb=fdf2bb051263f91bbd55b8e3acfacee3c5a1efa5 diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index a036b30..ef6739f 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. @@ -103,15 +99,16 @@ types, but must be derived into a type to be usable in an event field. We define "byte-packed" types as aligned on the byte size, namely 8-bit. We define "bit-packed" types as following on the next bit, as defined by the -"bitfields" section. +"Integers" section. All basic types, except bitfields, are either aligned on an architecture-defined specific alignment or byte-packed, depending on the architecture preference. Architectures providing fast unaligned write byte-packed basic types to save space, aligning each type on byte boundaries (8-bit). Architectures with slow unaligned writes align types on specific alignment values. If no specific -alignment is declared for a type nor its parents, it is assumed to be bit-packed -for bitfields and byte-packed for other types. +alignment is declared for a type, it is assumed to be bit-packed for +integers with size not multiple of 8 bits and for gcc bitfields. All +other types are byte-packed. Metadata attribute representation of a specific alignment: @@ -189,7 +186,7 @@ typealias integer { size = 32; signed = false; align = 32; -} : uint32_t; +} typename uint32_t; Definition of a named 5-bit signed bitfield: @@ -197,7 +194,7 @@ typealias integer { size = 5; signed = true; align = 1; -} : int5_t; +} typename int5_t; 4.1.6 GNU/C bitfields @@ -256,7 +253,7 @@ typealias floating_point { exp_dig = 8; /* sizeof(float) * CHAR_BIT - FLT_MANT_DIG */ mant_dig = 24; /* FLT_MANT_DIG */ byte_order = native; -} : float; +} typename float; TODO: define NaN, +inf, -inf behavior. @@ -274,10 +271,7 @@ this format by having the same start_value and end_value for each element, which is in fact a range of size 1. This single-value range is supported without repeating the start and end values with the value = string declaration. -If a numeric value is encountered between < >, it represents the integer type -size used to hold the enumeration, in bits. - -enum name { +enum name { somestring = start_value1 ... end_value1, "other string" = start_value2 ... end_value2, yet_another_string, /* will be assigned to end_value2 + 1 */ @@ -288,7 +282,7 @@ enum name { If the values are omitted, the enumeration starts at 0 and increment of 1 for each entry: -enum name <32> { +enum name { ZERO, ONE, TWO, @@ -374,7 +368,7 @@ variant name { }; struct { - enum { sel1, sel2, sel3, ... } tag_field; + enum { sel1, sel2, sel3, ... } tag_field; ... variant name v; } @@ -383,7 +377,7 @@ An unnamed variant definition within a structure is expressed by the following metadata: struct { - enum { sel1, sel2, sel3, ... } tag_field; + enum { sel1, sel2, sel3, ... } tag_field; ... variant { field_type sel1; @@ -504,7 +498,7 @@ Metadata representation of a named string type: typealias string { encoding = UTF8 OR ASCII; -} : name; +} typename name; A nameless string type can be declared as a field type: @@ -616,9 +610,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 @@ -765,20 +759,23 @@ contained within the payload. (This follows the ISO/C standard for structures) 7. Metadata -The meta-data is located in a stream named "metadata". It is made of "event -packets", which each start with an event packet header. The event type within -the metadata stream have no event header nor event context. Each event only -contains a null-terminated "string" payload, which is a metadata description -entry. The events are packed one next to another. Each event packet start with -an event packet header, which contains, amongst other fields, the magic number -and trace UUID. The trace UUID is represented as a string of hexadecimal digits -and dashes "-". - -The metadata can be parsed by reading through the metadata strings, skipping -newlines and null-characters. Type names are made of a single identifier, and -can be surrounded by prefix/postfix. Text contained within "/*" and "*/", as -well as within "//" and end of line, are treated as comments. Boolean values can -be represented as true, TRUE, or 1 for true, and false, FALSE, or 0 for false. +The meta-data is located in a stream identified by its name: "metadata". +It is made of "event packets", which each start with an event packet +header. The event type within the metadata stream have no event header +nor event context. Each event only contains a null-terminated "string" +payload, which is a metadata description entry. The events are packed +one next to another. Each event packet start with an event packet +header, which contains, amongst other fields, the magic number and trace +UUID. In the event packet header, the trace UUID is represented as an +array of bytes. Within the string-based metadata description, the trace +UUID is represented as a string of hexadecimal digits and dashes "-". + +The metadata can be parsed by reading through the metadata strings, +skipping null-characters. Type names are made of a single identifier, +and can be surrounded by prefix/postfix. Text contained within "/*" and +"*/", as well as within "//" and end of line, are treated as comments. +Boolean values can be represented as true, TRUE, or 1 for true, and +false, FALSE, or 0 for false. 7.1 Declaration vs Definition @@ -791,10 +788,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 +807,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 +844,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 @@ -889,7 +896,7 @@ event { * Type declarations behave similarly to the C standard. */ -typedef aliased_type_prefix aliased_type new_type aliased_type_postfix; +typedef aliased_type_specifiers new_type_declarators; /* e.g.: typedef struct example new_type_name[10]; */ @@ -897,15 +904,17 @@ typedef aliased_type_prefix aliased_type new_type aliased_type_postfix; * typealias * * The "typealias" declaration can be used to give a name (including - * prefix/postfix) to a type. It should also be used to map basic C types - * (float, int, unsigned long, ...) to a CTF type. Typealias is a superset of - * "typedef": it also allows assignment of a simple variable identifier to a - * type. + * pointer declarator specifier) to a type. It should also be used to + * map basic C types (float, int, unsigned long, ...) to a CTF type. + * Typealias is a superset of "typedef": it also allows assignment of a + * simple variable identifier to a type. The keyword "typename" is + * reserved to separate the aliased type from the newly declared alias + * name. */ typealias type_class { ... -} : new_type_prefix new_type new_type_postfix; +} typename type_specifiers type_declarator; /* * e.g.: @@ -913,13 +922,13 @@ typealias type_class { * size = 32; * align = 32; * signed = false; - * } : struct page *; + * } typename struct page *; * * typealias integer { * size = 32; * align = 32; * signed = true; - * } : int; + * } typename int; */ struct name { @@ -930,7 +939,7 @@ variant name { ... }; -enum name { +enum name { ... }; @@ -947,7 +956,7 @@ variant { ... } -enum { +enum { ... } @@ -1065,6 +1074,7 @@ struct trace typealias typedef +typename unsigned variant void @@ -1238,6 +1248,9 @@ unary-operator: one of assignment-operator: = +type-assignment-operator: + := + constant-expression: unary-expression @@ -1247,11 +1260,11 @@ constant-expression-range: 2.2) Declarations: declaration: - declaration-specifiers ; - declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ; + declaration-specifiers declarator-list-opt ; ctf-specifier ; declaration-specifiers: + storage-class-specifier declaration-specifiers-opt type-specifier declaration-specifiers-opt type-qualifier declaration-specifiers-opt @@ -1278,6 +1291,7 @@ type-specifier: unsigned _Bool _Complex + _Imaginary struct-specifier variant-specifier enum-specifier @@ -1295,8 +1309,8 @@ struct-or-variant-declaration-list: struct-or-variant-declaration: specifier-qualifier-list struct-or-variant-declarator-list ; declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ; - typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list ; - typealias declaration-specifiers abstract-declarator-list : declarator-list ; + typealias declaration-specifiers abstract-declarator-list typename declaration-specifiers abstract-declarator-list ; + typealias declaration-specifiers abstract-declarator-list typename declarator-list ; specifier-qualifier-list: type-specifier specifier-qualifier-list-opt @@ -1324,9 +1338,6 @@ enum-specifier: enum identifier-opt < declaration-specifiers > { enumerator-list } enum identifier-opt < declaration-specifiers > { enumerator-list , } enum identifier < declaration-specifiers > - enum identifier-opt < integer-constant > { enumerator-list } - enum identifier-opt < integer-constant > { enumerator-list , } - enum identifier < integer-constant > enumerator-list: enumerator @@ -1376,8 +1387,8 @@ ctf-specifier: event { ctf-assignment-expression-list-opt } stream { ctf-assignment-expression-list-opt } trace { ctf-assignment-expression-list-opt } - typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list ; - typealias declaration-specifiers abstract-declarator-list : declarator-list ; + typealias declaration-specifiers abstract-declarator-list typename declaration-specifiers abstract-declarator-list ; + typealias declaration-specifiers abstract-declarator-list typename declarator-list ; ctf-type-specifier: floating_point { ctf-assignment-expression-list-opt } @@ -1392,5 +1403,5 @@ ctf-assignment-expression: unary-expression assignment-operator unary-expression unary-expression type-assignment-operator type-specifier declaration-specifiers storage-class-specifier declaration-specifiers declarator-list - typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list - typealias declaration-specifiers abstract-declarator-list : declarator-list + typealias declaration-specifiers abstract-declarator-list typename declaration-specifiers abstract-declarator-list + typealias declaration-specifiers abstract-declarator-list typename declarator-list