[lttng-dev] [Patch LTTng-ust] RFC: Syntax changes to add support of other CTF metadata

Tue Dec 10 10:17:50 EST 2013

Thanks Amit,

I'll add support of those metadata one at a time, starting with the enum 
and then going for the struct and the variant. As support is added, I'll 
add to the documentation/examples and there will be a test application 
in the code to showcase those fields. But for myself, I'll probably work 
on the examples before implementing their support so I can share it on 
this list for discussion beforehand.

Geneviève

On 12/09/2013 04:00 AM, Amit Margalit wrote:
> First, I'd like to say I am a proponent of this.
>
> I'd also love to see some example code using this.
>
> Thanks,
>
> Amit Margalit
> IBM XIV - /Storage Reinvented/
> XIV-NAS Development Team
> Tel. 03-689-7774
> Fax. 03-689-7230
>
>
>
> From: Geneviève Bastien <gbastien+lttng at versatic.net>
> To: lttng-dev at lists.lttng.org
> Date: 12/05/2013 10:23 PM
> Subject: [lttng-dev] [Patch LTTng-ust] RFC: Syntax changes to add 
> support of  other CTF metadata
> ------------------------------------------------------------------------
>
>
>
> 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 <gbastien+lttng at versatic.net>
> ---
> 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
> lttng-dev at lists.lttng.org
> http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lttng.org/pipermail/lttng-dev/attachments/20131210/5b028d81/attachment-0001.html>