From mboxrd@z Thu Jan 1 00:00:00 1970 From: gbastien+lttng@versatic.net (=?UTF-8?q?Genevi=C3=A8ve=20Bastien?=) Date: Tue, 11 Feb 2014 16:35:36 -0500 Subject: [lttng-dev] [Patch LTTng-ust v2 7/7] Update the LTTng documentation with CTF global enumerations In-Reply-To: <1392154536-31191-1-git-send-email-gbastien+lttng@versatic.net> References: <1390593885-7463-1-git-send-email-gbastien+lttng@versatic.net> <1392154536-31191-1-git-send-email-gbastien+lttng@versatic.net> Message-ID: <1392154536-31191-8-git-send-email-gbastien+lttng@versatic.net> Signed-off-by: Genevi?ve Bastien --- doc/man/lttng-ust.3 | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3 index 7624e88..9958e59 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 declared global 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,55 @@ 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 global named basic and compound types +that can be declared 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, 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, + + /* + * 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. + * 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" -- 1.8.5.4