[lttng-dev] [Patch LTTng-ust] RFC: Syntax changes to add support of other CTF metadata
Amit Margalit
AMITM at il.ibm.com
Mon Dec 9 04:00:31 EST 2013
First, I'd like to say I am a proponent of this.
I'd also love to see some example code using this.
Thanks,
Amit Margalit
IBM XIV - Storage Reinvented
XIV-NAS Development Team
Tel. 03-689-7774
Fax. 03-689-7230
From: Geneviève Bastien <gbastien+lttng at versatic.net>
To: lttng-dev at lists.lttng.org
Date: 12/05/2013 10:23 PM
Subject: [lttng-dev] [Patch LTTng-ust] RFC: Syntax changes to add
support of other CTF metadata
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
_______________________________________________
lttng-dev mailing list
lttng-dev at lists.lttng.org
http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lttng.org/pipermail/lttng-dev/attachments/20131209/b8291b7a/attachment-0001.html>
More information about the lttng-dev
mailing list