Add CTF enum type support to tracepoint event

[lttng-ust.git] / doc / man / lttng-ust.3

diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3
index 398498913f104e6456bb87abedf38b7fc7f12e84..0455eea2810e2178dfe7c244eeeb6800d46e6106 100644 (file)
--- a/doc/man/lttng-ust.3
+++ b/doc/man/lttng-ust.3
@@ -224,6 +224,17 @@ TRACEPOINT_EVENT(
                 */
                ctf_float(float, floatfield, floatarg)
                ctf_float(double, doublefield, doublearg)
                 */
                ctf_float(float, floatfield, floatarg)
                ctf_float(double, doublefield, doublearg)

+
+               /*
+                * ctf_enum: a field using a previously declared
+                * enumeration args: (provider, enum name, container
+                * type, 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, int,
+                             enumfield, enumarg)

        )
 )
 
        )
 )
 


@@ -231,6 +242,49 @@ 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.
 
 application, but they must each have their own provider name. Duplicate
 provider names are not allowed.
 

+The CTF specification also supports enumerations that can be declared
+inside a tracepoint provider and used as fields in the tracepoint. This
+shows how to specify enumerations and what they can be used for:
+
+The enumeration is a mapping between an integer, or a range of integers, 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
+        * global type in tracepoint fields.
+        */
+       enumeration_name,
+
+       /*
+        * 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.
+                * Enumeration ranges may overlap, but the behavior is
+                * implementation-defined, each trace reader will handle overlapping
+                * as it wishes.
+                */
+               ctf_enum_range(start, end, string_value)
+       )
+)
+

 .fi
 
 .SH "ASSIGNING LOGLEVEL TO EVENTS"
 .fi
 
 .SH "ASSIGNING LOGLEVEL TO EVENTS"