[lttng-dev] [RFC Patch Ust 5/5] Update the LTTng documentation with CTF global structures

[gbastien+lttng@versatic.net (Geneviève Bastien)]

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 40452df..45f8549 100644
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -194,6 +194,17 @@ TRACEPOINT_EVENT(
 		 * 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...)
 	)
 )
 
@@ -250,6 +261,49 @@ TRACEPOINT_ENUM(
 	)
 )
 
+A structure allows to group 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(...)
+)
+
 .fi
 
 .SH "ASSIGNING LOGLEVEL TO EVENTS"
-- 
1.9.1