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

[Geneviève Bastien]

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