X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=458b0977787edbad699d18590dacb10db95de165;hp=aeb8b780d7c16e9ed2063791ebf7891f7dd4c49e;hb=1fad7a855094f1dde6912a9d8f971cbbbc62f07b;hpb=3e1e1a78fbe28433adf45e1b7b62a29c4eaaa7b1 diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index aeb8b78..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. @@ -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. @@ -824,7 +840,10 @@ 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. + * 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 { @@ -838,6 +857,12 @@ typealias type_class { * align = 32; * signed = false; * } : struct page *; + * + * typealias integer { + * size = 32; + * align = 32; + * signed = true; + * } : int; */ struct name { @@ -848,7 +873,7 @@ variant name { ... }; -enum name { +enum name { ... }; @@ -1153,9 +1178,6 @@ unary-expression: unary-operator: one of + - -assignment-expression: - unary-expression assignment-operator unary-expression - assignment-operator: = @@ -1168,11 +1190,11 @@ constant-expression-range: 2.2) Declarations: declaration: - declaration-specifiers declarator-list-opt ; + declaration-specifiers ; + declaration-specifiers storage-class-specifier declaration-specifiers declarator-list ; ctf-specifier ; declaration-specifiers: - storage-class-specifier declaration-specifiers-opt type-specifier declaration-specifiers-opt type-qualifier declaration-specifiers-opt @@ -1180,6 +1202,10 @@ declarator-list: declarator declarator-list , declarator +abstract-declarator-list: + abstract-declarator + abstract-declarator-list , abstract-declarator + storage-class-specifier: typedef @@ -1195,13 +1221,14 @@ type-specifier: unsigned _Bool _Complex - struct-or-variant-specifier + struct-specifier + variant-specifier enum-specifier typedef-name ctf-type-specifier struct-specifier: - struct identifier-opt { struct-or-variant-declaration-list } + struct identifier-opt { struct-or-variant-declaration-list-opt } struct identifier struct-or-variant-declaration-list: @@ -1210,6 +1237,9 @@ 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 ; specifier-qualifier-list: type-specifier specifier-qualifier-list-opt @@ -1234,9 +1264,9 @@ enum-specifier: enum identifier-opt { enumerator-list } enum identifier-opt { enumerator-list , } enum identifier - enum identifier-opt < type-specifier > { enumerator-list } - enum identifier-opt < type-specifier > { enumerator-list , } - enum identifier < type-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 > @@ -1262,18 +1292,24 @@ direct-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-opt + * type-qualifier-list-opt pointer type-qualifier-list: type-qualifier type-qualifier-list type-qualifier -identifier-list: - identifier - identifier-list , identifier - typedef-name: identifier @@ -1283,6 +1319,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 ; ctf-type-specifier: floating_point { ctf-assignment-expression-list-opt } @@ -1296,3 +1334,6 @@ ctf-assignment-expression-list: 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