The CTF spec defines metadata types enumerations, structures and variants that are not yet available for use in tracepoints in LTTng-ust. This proposes the syntax for how those types could be defined and used.
For now, it won't be possible to define them inline in a tracepoint. They will have to be named and defined outside the TRACEPOINT_EVENT macro and used in the tracepoint definition. It will make it easier for a first implementation. Once that is done, it won't be too difficult to add inline support. Signed-off-by: Geneviève Bastien <[email protected]> --- doc/man/lttng-ust.3 | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 7624e88..c8229f2 100644 --- a/doc/man/lttng-ust.3 +++ b/doc/man/lttng-ust.3 @@ -158,6 +158,39 @@ TRACEPOINT_EVENT( */ ctf_float(float, floatfield, floatarg) ctf_float(double, doublefield, doublearg) + + /* + * ctf_enum: a field using a previously defined named enumeration + * args: (provider, enum name, field name, argument expression) + * The enumeration itself and its values must have been defined + * previously with the TRACEPOINT_ENUM macro, described below. + */ + ctf_enum(sample_component, enumeration_name, enumfield, enumarg) + + /* + * ctf_struct: a field using a previously defined struct + * args: (provider, struct name, field name, [argument expression]*) + * The structure must have been previously defined with the + * TRACEPOINT_STRUCT macro, described below. + * + * The [argument expression]* part must correspond to the arguments + * defined in the TP_ARGS of the struct. + */ + ctf_struct(sample_component, structure_name, structfield, args...) + + /* + * ctf_variant: a field using a previously defined variant + * args: (provider, variant name, field name, enum field name, + [argument expression]*) + * + * The [argument expression]* part must correspond to the arguments + * defined in the TP_ARGS of the variant. + * + * There must be a field in the same tracepoint named 'enumfield' + * defined with ctf_enum(...) + */ + ctf_variant(sample_component, variant_name, variantfield, + enumfield, args...) ) ) @@ -165,6 +198,166 @@ There can be an arbitrary number of tracepoint providers within an application, but they must each have their own provider name. Duplicate provider names are not allowed. +The CTF specification also supports some named basic and compound types that +can be defined inside a tracepoint provider and used as fields in the +tracepoint. This shows how to specify them and what they can be used for: + +The enumeration is a mapping between an integer and a string. It can be used +to have a more compact trace in cases where the possible values for a field are +limited: + +TRACEPOINT_ENUM( + /* + * The provider name, as described in the TRACEPOINT_EVENT macro + */ + sample_component, + + /* + * The name of this enumeration, that will be used when using this + * metadata type in tracepoint fields + */ + enumeration_name, + + /* + * Integer type by which this enumeration will be represented. + * It can be: char, int, long or any variant on those + */ + type, + + /* + * TP_ENUM_VALUES describe the values of this enumeration and what they + * map to. + */ + TP_ENUM_VALUES( + /* + * Maps an integer with this string value. By default, enumerations + * start at 0 and increment 1 for each entry. + */ + ctf_enum_value(string_value) + + /* + * Maps the string value to integers in the range 'start' to 'end' + * inclusively. If 'start' == 'end', then the string is mapped to + * a specific value. + */ + ctf_enum_range(start, end, string_value) + ) +) + +A structure allows to groupe fields together. They can be reused by different +tracepoints: + +TRACEPOINT_STRUCT( + /* + * The provider name, as described in the TRACEPOINT_EVENT macro + */ + sample_component, + + /* + * The name of this structure, that will be used when using this + * metadata type in tracepoint fields + */ + structure_name, + + /* + * TP_ARGS macro contains the arguments passed for the structure + * it is in the following format + * TP_ARGS(type1, name1, type2, name2, ... type10, + name10) + * where there can be from zero to ten elements. + * typeN is the datatype, such as int, struct or double **. + * name is the variable name (in "int myInt" the name would be + * myint) + * TP_ARGS() is valid to mean no arguments + * TP_ARGS(void) is valid too + */ + TP_ARGS(int, anint, int, netint, long *, values, + char *, text, size_t, textlen, + double, doublearg, float, floatarg), + + /* + * TP_FIELDS describes how to write the fields of the structure. + * You can put expressions in the "argument expression" area, + * typically using the input arguments from TP_ARGS. + * + * See TP_FIELDS macro in TRACEPOINT_EVENT for complete description + * of possible fields. A structure may not contain itself and there cannot + * be a cycle. + */ + TP_FIELDS(...) +) + +A variant is a selection between different types, given a +'tag'. It is linked with the value of an enumeration. + +TRACEPOINT_VARIANT( + /* + * The provider name, as described in the TRACEPOINT_EVENT macro + */ + sample_component, + + /* + * The name of this variant, that will be used when using this + * metadata type in tracepoint fields + */ + variant_name, + + /* + * The name of the provider where the linked enumeration is defined + */ + enumeration_component, + + /* + * The name of the enumeration, whose values will be linked to a field + * type + */ + enumeration_name, + + /* + * TP_ARGS macro contains the arguments passed for the structure + * it is in the following format + * TP_ARGS(type1, name1, type2, name2, ... type10, + name10) + * where there can be from zero to ten elements. + * typeN is the datatype, such as int, struct or double **. + * name is the variable name (in "int myInt" the name would be + * myint) + * TP_ARGS() is valid to mean no arguments + * TP_ARGS(void) is valid too + */ + TP_ARGS(int, anint, int, netint, long *, values, + char *, text, size_t, textlen, + double, doublearg, float, floatarg), + + /* + * TP_VARIANTS will describe what field will be linked to what value of + * the enumeration + */ + TP_VARIANTS( + /* + * TP_VARIANT describes one mapping from an enum value to a field + */ + TP_VARIANT( + /* + * The value of the enumeration field. This must correspond to one + * of the string_values defined in TP_ENUM_VALUES of the linked + * enumeration. + */ + enum_val, + + /* + * This is the field that will be added to the tracepoint if the + * value of the enum is enum_val. + * + * See TP_FIELDS macro in TRACEPOINT_EVENT for complete description + * of possible fields. A variant may not contain itself and there cannot + * be a cycle. + */ + <tp_field_expr> + ) + ) +) + .fi .SH "ASSIGNING LOGLEVEL TO EVENTS" -- 1.8.4.2 _______________________________________________ lttng-dev mailing list [email protected] http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
