X-Git-Url: http://git.efficios.com/?p=ctf.git;a=blobdiff_plain;f=common-trace-format-proposal.txt;h=458b0977787edbad699d18590dacb10db95de165;hp=2a4dbfe25a40d8f206760054c80b196feaa4593b;hb=1fad7a855094f1dde6912a9d8f971cbbbc62f07b;hpb=550aca336f90ab7bca145122d5b138132fa58fa5 diff --git a/common-trace-format-proposal.txt b/common-trace-format-proposal.txt index 2a4dbfe..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. @@ -274,7 +278,7 @@ 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, + 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, @@ -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: @@ -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 { @@ -1177,6 +1202,10 @@ declarator-list: declarator declarator-list , declarator +abstract-declarator-list: + abstract-declarator + abstract-declarator-list , abstract-declarator + storage-class-specifier: typedef @@ -1209,7 +1238,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 declaration-specifiers declarator-list : 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,6 +1292,16 @@ 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 @@ -1279,7 +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 declaration-specifiers declarator-list : declaration-specifiers declarator-list ; + 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 } @@ -1294,4 +1335,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 declaration-specifiers declarator-list : declaration-specifiers declarator-list + typealias declaration-specifiers abstract-declarator-list : declaration-specifiers abstract-declarator-list + typealias declaration-specifiers abstract-declarator-list : declarator-list