X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=458b0977787edbad699d18590dacb10db95de165;hp=0daac2adccfa4115a91f0576f0402f5c31be3157;hb=1fad7a855094f1dde6912a9d8f971cbbbc62f07b;hpb=77a98c82d80ca2d562e29c32380feeffdcd6f4c2 diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index 0daac2a..458b097 100644 --- a/common-trace-format-proposal.txt +++ b/common-trace-format-proposal.txt @@ -83,9 +83,13 @@ header" throughout the rest of this document. 4. Types +Types are organized as type classes. Each type class belong to either of two +kind of types: basic types or compound types. + 4.1 Basic types -A basic type is a scalar type, as described in this section. +A basic type is a scalar type, as described in this section. It includes +integers, GNU/C bitfields, enumerations, and floating point values. 4.1.1 Type inheritance @@ -181,19 +185,19 @@ Metadata representation: Example of type inheritance (creation of a uint32_t named type): -typedef integer { +typealias integer { size = 32; signed = false; align = 32; -} uint32_t; +} : uint32_t; Definition of a named 5-bit signed bitfield: -typedef integer { +typealias integer { size = 5; signed = true; align = 1; -} int5_t; +} : int5_t; 4.1.6 GNU/C bitfields @@ -248,11 +252,11 @@ floating_point { Example of type inheritance: -typedef floating_point { +typealias floating_point { exp_dig = 8; /* sizeof(float) * CHAR_BIT - FLT_MANT_DIG */ mant_dig = 24; /* FLT_MANT_DIG */ byte_order = native; -} float; +} : float; TODO: define NaN, +inf, -inf behavior. @@ -273,8 +277,8 @@ 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 { - string = start_value1 ... end_value1, +enum name { + somestring = start_value1 ... end_value1, "other string" = start_value2 ... end_value2, yet_another_string, /* will be assigned to end_value2 + 1 */ "some other string" = value, @@ -284,7 +288,7 @@ enum name { If the values are omitted, the enumeration starts at 0 and increment of 1 for each entry: -enum <32> name { +enum name <32> { ZERO, ONE, TWO, @@ -300,8 +304,12 @@ enum { ... } + 4.2 Compound types +Compound are aggregation of type declarations. Compound types include +structures, variant, arrays, sequences, and strings. + 4.2.1 Structures Structures are aligned on the largest alignment required by basic types @@ -492,9 +500,9 @@ encoding attribute information, the default encoding is UTF-8. Metadata representation of a named string type: -typedef string { +typealias string { encoding = UTF8 OR ASCII; -} name; +} : name; A nameless string type can be declared as a field type: @@ -591,7 +599,7 @@ struct event_packet_context { uint8_t stream_packet_count_bits; /* Significant counter bits */ uint8_t compression_scheme; uint8_t encryption_scheme; - uint8_t checksum; + uint8_t checksum_scheme; }; @@ -607,10 +615,11 @@ The overall structure of an event is: 6.1 Lexical Scope -The lexical scope of each structure (stream packet context, header, stream event -context, event context and payload) is extended in the following way: lower -levels (e.g. 3) can refer to fields defined in prior levels (e.g. 2 and 1). The -field in the closest level has priority in case of field name conflict. +For variant tag definition only, the lexical scope of each structure (stream +packet context, header, stream event context, event context and payload) is +extended in the following way: lower levels (e.g. 3) can refer to fields defined +in prior levels (e.g. 2 and 1). The field in the closest level has priority in +case of field name conflict. This allows, for instance, the event context to define a variant refering to the "id" field of the event header as selector. @@ -710,7 +719,7 @@ within the stream declaration within the metadata: ... event { ... - context = struct { + context := struct { uint pid; uint16_t payload_size; }; @@ -774,6 +783,13 @@ 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. +Each of "trace", "stream", "event", "struct" and "variant" have their own +nestable declaration scope, within which types can be declared using "typedef" +and "typealias". An innermost declaration scope can refer to type declared +within its container lexical scope prior to the innermost declaration scope. +Redefinition of a typedef or typealias, or hiding an uppermost definition, is +not valid. + The grammar representing the CTF metadata is presented in Appendix C. CTF Metadata Grammar. @@ -787,11 +803,11 @@ trace { stream { id = stream_id; /* Type 1 - Few event IDs; Type 2 - Many event IDs. See section 6.2. */ - event.header = event_header_1 OR event_header_2; - event.context = struct { + event.header := event_header_1 OR event_header_2; + event.context := struct { ... }; - packet.context = struct { + packet.context := struct { ... }; }; @@ -800,10 +816,10 @@ event { name = event_name; id = value; /* Numeric identifier within the stream */ stream = stream_id; - context = struct { + context := struct { ... }; - fields = struct { + fields := struct { ... }; }; @@ -813,26 +829,40 @@ event { /* * Named types: * - * Type declarations behave similarly to the C standard, with the following - * added feature: new_type can be preceded by a colon to allow creation of a - * type name with prefix/postfix. + * Type declarations behave similarly to the C standard. */ typedef aliased_type_prefix aliased_type new_type aliased_type_postfix; /* e.g.: typedef struct example new_type_name[10]; */ -typedef type_class { +/* + * 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. + */ + +typealias type_class { ... } : new_type_prefix new_type new_type_postfix; /* * e.g.: - * typedef integer { + * typealias integer { * size = 32; * align = 32; * signed = false; * } : struct page *; + * + * typealias integer { + * size = 32; + * align = 32; + * signed = true; + * } : int; */ struct name { @@ -843,12 +873,14 @@ variant name { ... }; -enum name { +enum name { ... }; -/* Unnamed types, contained within compound type fields or typedef. */ +/* + * Unnamed types, contained within compound type fields, typedef or typealias. + */ struct { ... @@ -932,4 +964,376 @@ header" throughout the rest of this document. C. CTF Metadata Grammar -TODO +/* + * Common Trace Format (CTF) Metadata Grammar. + * + * Inspired from the C99 grammar: + * http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf (Annex A) + * + * Specialized for CTF needs by including only constant and declarations from + * C99 (excluding function declarations), and by adding support for variants, + * sequences and CTF-specific specifiers. + */ + +1) Lexical grammar + +1.1) Lexical elements + +token: + keyword + identifier + constant + string-literal + punctuator + +1.2) Keywords + +keyword: is one of + +const +char +double +enum +event +floating_point +float +integer +int +long +short +signed +stream +string +struct +trace +typealias +typedef +unsigned +variant +void +_Bool +_Complex +_Imaginary + + +1.3) Identifiers + +identifier: + identifier-nondigit + identifier identifier-nondigit + identifier digit + +identifier-nondigit: + nondigit + universal-character-name + any other implementation-defined characters + +nondigit: + _ + [a-zA-Z] /* regular expression */ + +digit: + [0-9] /* regular expression */ + +1.4) Universal character names + +universal-character-name: + \u hex-quad + \U hex-quad hex-quad + +hex-quad: + hexadecimal-digit hexadecimal-digit hexadecimal-digit hexadecimal-digit + +1.5) Constants + +constant: + integer-constant + enumeration-constant + character-constant + +integer-constant: + decimal-constant integer-suffix-opt + octal-constant integer-suffix-opt + hexadecimal-constant integer-suffix-opt + +decimal-constant: + nonzero-digit + decimal-constant digit + +octal-constant: + 0 + octal-constant octal-digit + +hexadecimal-constant: + hexadecimal-prefix hexadecimal-digit + hexadecimal-constant hexadecimal-digit + +hexadecimal-prefix: + 0x + 0X + +nonzero-digit: + [1-9] + +integer-suffix: + unsigned-suffix long-suffix-opt + unsigned-suffix long-long-suffix + long-suffix unsigned-suffix-opt + long-long-suffix unsigned-suffix-opt + +unsigned-suffix: + u + U + +long-suffix: + l + L + +long-long-suffix: + ll + LL + +digit-sequence: + digit + digit-sequence digit + +hexadecimal-digit-sequence: + hexadecimal-digit + hexadecimal-digit-sequence hexadecimal-digit + +enumeration-constant: + identifier + string-literal + +character-constant: + ' c-char-sequence ' + L' c-char-sequence ' + +c-char-sequence: + c-char + c-char-sequence c-char + +c-char: + any member of source charset except single-quote ('), backslash + (\), or new-line character. + escape-sequence + +escape-sequence: + simple-escape-sequence + octal-escape-sequence + hexadecimal-escape-sequence + universal-character-name + +simple-escape-sequence: one of + \' \" \? \\ \a \b \f \n \r \t \v + +octal-escape-sequence: + \ octal-digit + \ octal-digit octal-digit + \ octal-digit octal-digit octal-digit + +hexadecimal-escape-sequence: + \x hexadecimal-digit + hexadecimal-escape-sequence hexadecimal-digit + +1.6) String literals + +string-literal: + " s-char-sequence-opt " + L" s-char-sequence-opt " + +s-char-sequence: + s-char + s-char-sequence s-char + +s-char: + any member of source charset except double-quote ("), backslash + (\), or new-line character. + escape-sequence + +1.7) Punctuators + +punctuator: one of + [ ] ( ) { } . -> * + - < > : ; ... = , + + +2) Phrase structure grammar + +primary-expression: + identifier + constant + string-literal + ( unary-expression ) + +postfix-expression: + primary-expression + postfix-expression [ unary-expression ] + postfix-expression . identifier + postfix-expressoin -> identifier + +unary-expression: + postfix-expression + unary-operator postfix-expression + +unary-operator: one of + + - + +assignment-operator: + = + +constant-expression: + unary-expression + +constant-expression-range: + constant-expression ... constant-expression + +2.2) Declarations: + +declaration: + declaration-specifiers ; + declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ; + ctf-specifier ; + +declaration-specifiers: + type-specifier declaration-specifiers-opt + type-qualifier declaration-specifiers-opt + +declarator-list: + declarator + declarator-list , declarator + +abstract-declarator-list: + abstract-declarator + abstract-declarator-list , abstract-declarator + +storage-class-specifier: + typedef + +type-specifier: + void + char + short + int + long + float + double + signed + unsigned + _Bool + _Complex + struct-specifier + variant-specifier + enum-specifier + typedef-name + ctf-type-specifier + +struct-specifier: + struct identifier-opt { struct-or-variant-declaration-list-opt } + struct identifier + +struct-or-variant-declaration-list: + struct-or-variant-declaration + struct-or-variant-declaration-list struct-or-variant-declaration + +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 ; + +specifier-qualifier-list: + type-specifier specifier-qualifier-list-opt + type-qualifier specifier-qualifier-list-opt + +struct-or-variant-declarator-list: + struct-or-variant-declarator + struct-or-variant-declarator-list , struct-or-variant-declarator + +struct-or-variant-declarator: + declarator + declarator-opt : constant-expression + +variant-specifier: + variant identifier-opt variant-tag-opt { struct-or-variant-declaration-list } + variant identifier variant-tag + +variant-tag: + < identifier > + +enum-specifier: + enum identifier-opt { enumerator-list } + enum identifier-opt { enumerator-list , } + enum identifier + 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 + enumerator-list , enumerator + +enumerator: + enumeration-constant + enumeration-constant = constant-expression + enumeration-constant = constant-expression-range + +type-qualifier: + const + +declarator: + pointer-opt direct-declarator + +direct-declarator: + identifier + ( declarator ) + direct-declarator [ type-specifier ] + direct-declarator [ constant-expression ] + +abstract-declarator: + pointer-opt direct-abstract-declarator + +direct-abstract-declarator: + identifier-opt + ( abstract-declarator ) + direct-abstract-declarator [ type-specifier ] + direct-abstract-declarator [ constant-expression ] + direct-abstract-declarator [ ] + +pointer: + * type-qualifier-list-opt + * type-qualifier-list-opt pointer + +type-qualifier-list: + type-qualifier + type-qualifier-list type-qualifier + +typedef-name: + identifier + +2.3) CTF-specific declarations + +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 ; + +ctf-type-specifier: + floating_point { ctf-assignment-expression-list-opt } + integer { ctf-assignment-expression-list-opt } + string { ctf-assignment-expression-list-opt } + +ctf-assignment-expression-list: + ctf-assignment-expression + ctf-assignment-expression-list ; ctf-assignment-expression + +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