[lttng-dev] [Patch LTTng-ust 7/7] Update the LTTng documentation with CTF named enumerations

[Mathieu Desnoyers]

----- Original Message -----
> From: "Geneviève Bastien" <gbastien+lttng at versatic.net>
> To: lttng-dev at lists.lttng.org
> Sent: Friday, January 24, 2014 3:04:45 PM
> Subject: [lttng-dev] [Patch LTTng-ust 7/7] Update the LTTng documentation	with CTF named enumerations
> 
> Signed-off-by: Geneviève Bastien <gbastien+lttng at versatic.net>
> ---
>  doc/man/lttng-ust.3 | 54
>  +++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 54 insertions(+)
> 
> diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
> index 7624e88..d474225 100644
> --- a/doc/man/lttng-ust.3
> +++ b/doc/man/lttng-ust.3
> @@ -158,6 +158,14 @@ 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)
>  	)
>  )
>  
> @@ -165,6 +173,52 @@ 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:
> +

For each of the comments below, please add a final "." at the end to
complete each sentence.

> +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.

We should document whether overlaps are permitted.

Thanks,

Mathieu

> +		 */
> +		ctf_enum_range(start, end, string_value)
> +	)
> +)
> +
>  .fi
>  
>  .SH "ASSIGNING LOGLEVEL TO EVENTS"
> --
> 1.8.5.3
> 
> 
> _______________________________________________
> lttng-dev mailing list
> lttng-dev at lists.lttng.org
> http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
> 

-- 
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com