<font size=2 face="sans-serif">Thanks, Genevieve, I appreciate that. I
feel the examples it make easier to give feedback on the use cases, rather
than the ideas.</font>
<br>
<br><font size=2 color=#000080 face="sans-serif">Amit Margalit</font>
<br><font size=2 color=#808000 face="sans-serif">IBM XIV </font><font size=2 face="sans-serif">-
<i>Storage Reinvented</i></font>
<br><font size=2 face="sans-serif">XIV-NAS Development Team</font>
<br><font size=2 face="sans-serif">Tel. 03</font><font size=2 face="Arial">-689-7774</font>
<br><font size=2 face="Arial">Fax. 03-689-7230</font>
<br>
<br>
<br>
<br><font size=1 color=#5f5f5f face="sans-serif">From:
</font><font size=1 face="sans-serif">Geneviève Bastien <gbastien+lttng@versatic.net></font>
<br><font size=1 color=#5f5f5f face="sans-serif">To:
</font><font size=1 face="sans-serif">lttng-dev@lists.lttng.org</font>
<br><font size=1 color=#5f5f5f face="sans-serif">Date:
</font><font size=1 face="sans-serif">12/10/2013 05:19 PM</font>
<br><font size=1 color=#5f5f5f face="sans-serif">Subject:
</font><font size=1 face="sans-serif">Re: [lttng-dev]
[Patch LTTng-ust] RFC: Syntax changes to add support of other CTF metadata</font>
<br>
<hr noshade>
<br>
<br>
<br><font size=3>Thanks Amit,<br>
<br>
I'll add support of those metadata one at a time, starting with the enum
and then going for the struct and the variant. As support is added, I'll
add to the documentation/examples and there will be a test application
in the code to showcase those fields. But for myself, I'll probably work
on the examples before implementing their support so I can share it on
this list for discussion beforehand.<br>
<br>
Geneviève<br>
<br>
<br>
On 12/09/2013 04:00 AM, Amit Margalit wrote:</font>
<br><font size=2 face="sans-serif">First, I'd like to say I am a proponent
of this.</font><font size=3> <br>
</font><font size=2 face="sans-serif"><br>
I'd also love to see some example code using this.</font><font size=3>
<br>
</font><font size=2 face="sans-serif"><br>
Thanks,</font><font size=3> <br>
</font><font size=2 color=#000080 face="sans-serif"><br>
Amit Margalit</font><font size=3> </font><font size=2 color=#808000 face="sans-serif"><br>
IBM XIV </font><font size=2 face="sans-serif">- <i>Storage Reinvented</i></font><font size=3>
</font><font size=2 face="sans-serif"><br>
XIV-NAS Development Team</font><font size=3> </font><font size=2 face="sans-serif"><br>
Tel. 03</font><font size=2 face="Arial">-689-7774</font><font size=3> </font><font size=2 face="Arial"><br>
Fax. 03-689-7230</font><font size=3> <br>
<br>
<br>
</font><font size=1 color=#5f5f5f face="sans-serif"><br>
From: </font><font size=1 face="sans-serif">Geneviève
Bastien </font><a href="mailto:gbastien+lttng@versatic.net"><font size=1 color=blue face="sans-serif"><u><gbastien+lttng@versatic.net></u></font></a><font size=3>
</font><font size=1 color=#5f5f5f face="sans-serif"><br>
To: </font><a href="mailto:lttng-dev@lists.lttng.org"><font size=1 color=blue face="sans-serif"><u>lttng-dev@lists.lttng.org</u></font></a><font size=3>
</font><font size=1 color=#5f5f5f face="sans-serif"><br>
Date: </font><font size=1 face="sans-serif">12/05/2013
10:23 PM</font><font size=3> </font><font size=1 color=#5f5f5f face="sans-serif"><br>
Subject: </font><font size=1 face="sans-serif">[lttng-dev]
[Patch LTTng-ust] RFC: Syntax changes to add support of
other CTF metadata</font><font size=3> <br>
</font>
<hr noshade><font size=3><br>
<br>
</font><tt><font size=2><br>
The CTF spec defines metadata types enumerations, structures and variants<br>
that are not yet available for use in tracepoints in LTTng-ust. This<br>
proposes the syntax for how those types could be defined and used.<br>
<br>
For now, it won't be possible to define them inline in a tracepoint. They<br>
will have to be named and defined outside the TRACEPOINT_EVENT macro and<br>
used in the tracepoint definition. It will make it easier for a first<br>
implementation. Once that is done, it won't be too difficult to add inline<br>
support.<br>
<br>
Signed-off-by: Geneviève Bastien </font></tt><a href="mailto:gbastien+lttng@versatic.net"><tt><font size=2 color=blue><u><gbastien+lttng@versatic.net></u></font></tt></a><tt><font size=2><br>
---<br>
doc/man/lttng-ust.3 | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++<br>
1 file changed, 193 insertions(+)<br>
<br>
diff --git a/doc/man/lttng-ust.3 b/doc/man/lttng-ust.3<br>
index 7624e88..c8229f2 100644<br>
--- a/doc/man/lttng-ust.3<br>
+++ b/doc/man/lttng-ust.3<br>
@@ -158,6 +158,39 @@ TRACEPOINT_EVENT(<br>
*/<br>
ctf_float(float, floatfield,
floatarg)<br>
ctf_float(double, doublefield,
doublearg)<br>
+<br>
+
/*<br>
+
* ctf_enum: a field using
a previously defined named enumeration<br>
+
* args: (provider, enum
name, field name, argument expression)<br>
+
* The enumeration itself
and its values must have been defined<br>
+
* previously with the
TRACEPOINT_ENUM macro, described below.<br>
+
*/<br>
+
ctf_enum(sample_component,
enumeration_name, enumfield, enumarg)<br>
+<br>
+
/*<br>
+
* ctf_struct: a field
using a previously defined struct<br>
+
* args: (provider, struct
name, field name, [argument expression]*)<br>
+
* The structure must have
been previously defined with the<br>
+
* TRACEPOINT_STRUCT macro,
described below.<br>
+
*<br>
+
* The [argument expression]*
part must correspond to the arguments<br>
+
* defined in the TP_ARGS
of the struct.<br>
+
*/<br>
+
ctf_struct(sample_component,
structure_name, structfield, args...)<br>
+<br>
+
/*<br>
+
* ctf_variant: a field
using a previously defined variant<br>
+
* args: (provider, variant
name, field name, enum field name,<br>
+
[argument expression]*)<br>
+
*<br>
+
* The [argument expression]*
part must correspond to the arguments<br>
+
* defined in the TP_ARGS
of the variant.<br>
+
*<br>
+
* There must be a field
in the same tracepoint named 'enumfield'<br>
+
* defined with ctf_enum(...)<br>
+
*/<br>
+
ctf_variant(sample_component,
variant_name, variantfield,<br>
+
enumfield, args...)<br>
)<br>
)<br>
<br>
@@ -165,6 +198,166 @@ There can be an arbitrary number of tracepoint providers
within an<br>
application, but they must each have their own provider name. Duplicate<br>
provider names are not allowed.<br>
<br>
+The CTF specification also supports some named basic and compound types
that<br>
+can be defined inside a tracepoint provider and used as fields in the<br>
+tracepoint. This shows how to specify them and what they can be used for:<br>
+<br>
+The enumeration is a mapping between an integer and a string. It can be
used<br>
+to have a more compact trace in cases where the possible values for a
field are<br>
+limited:<br>
+<br>
+TRACEPOINT_ENUM(<br>
+ /*<br>
+ * The provider
name, as described in the TRACEPOINT_EVENT macro<br>
+ */<br>
+ sample_component,<br>
+<br>
+ /*<br>
+ * The name
of this enumeration, that will be used when using this<br>
+ * metadata
type in tracepoint fields<br>
+ */<br>
+ enumeration_name,<br>
+<br>
+ /*<br>
+ * Integer
type by which this enumeration will be represented.<br>
+ * It can
be: char, int, long or any variant on those<br>
+ */<br>
+ type,<br>
+<br>
+ /*<br>
+ * TP_ENUM_VALUES
describe the values of this enumeration and what they<br>
+ * map to.<br>
+ */<br>
+ TP_ENUM_VALUES(<br>
+
/*<br>
+
* Maps an integer with
this string value. By default, enumerations<br>
+
* start at 0 and increment
1 for each entry.<br>
+
*/<br>
+
ctf_enum_value(string_value)<br>
+<br>
+
/*<br>
+
* Maps the string value
to integers in the range 'start' to 'end'<br>
+
* inclusively. If 'start'
== 'end', then the string is mapped to<br>
+
* a specific value.<br>
+
*/<br>
+
ctf_enum_range(start, end,
string_value)<br>
+ )<br>
+)<br>
+<br>
+A structure allows to groupe fields together. They can be reused by different<br>
+tracepoints:<br>
+<br>
+TRACEPOINT_STRUCT(<br>
+ /*<br>
+ * The provider
name, as described in the TRACEPOINT_EVENT macro<br>
+ */<br>
+ sample_component,<br>
+<br>
+ /*<br>
+ * The name
of this structure, that will be used when using this<br>
+ * metadata
type in tracepoint fields<br>
+ */<br>
+ structure_name,<br>
+<br>
+ /*<br>
+ * TP_ARGS
macro contains the arguments passed for the structure<br>
+ * it is
in the following format<br>
+ *
TP_ARGS(type1,
name1, type2, name2, ... type10,<br>
+
name10)<br>
+ * where
there can be from zero to ten elements.<br>
+ * typeN
is the datatype, such as int, struct or double **.<br>
+ * name
is the variable name (in "int myInt" the name would be<br>
+ * myint)<br>
+ *
TP_ARGS()
is valid to mean no arguments<br>
+ *
TP_ARGS(void)
is valid too<br>
+ */<br>
+ TP_ARGS(int,
anint, int, netint, long *, values,<br>
+
char *, text, size_t,
textlen,<br>
+
double, doublearg, float,
floatarg),<br>
+<br>
+ /*<br>
+ * TP_FIELDS
describes how to write the fields of the structure.<br>
+ * You can
put expressions in the "argument expression" area,<br>
+ * typically
using the input arguments from TP_ARGS.<br>
+ *<br>
+ * See TP_FIELDS
macro in TRACEPOINT_EVENT for complete description<br>
+ * of possible
fields. A structure may not contain itself and there cannot<br>
+ * be a
cycle.<br>
+ */<br>
+ TP_FIELDS(...)<br>
+)<br>
+<br>
+A variant is a selection between different types, given a<br>
+'tag'. It is linked with the value of an enumeration.<br>
+<br>
+TRACEPOINT_VARIANT(<br>
+ /*<br>
+ * The provider
name, as described in the TRACEPOINT_EVENT macro<br>
+ */<br>
+ sample_component,<br>
+<br>
+ /*<br>
+ * The name
of this variant, that will be used when using this<br>
+ * metadata
type in tracepoint fields<br>
+ */<br>
+ variant_name,<br>
+<br>
+ /*<br>
+ * The name
of the provider where the linked enumeration is defined<br>
+ */<br>
+ enumeration_component,<br>
+<br>
+ /*<br>
+ * The name
of the enumeration, whose values will be linked to a field<br>
+ * type<br>
+ */<br>
+ enumeration_name,<br>
+<br>
+ /*<br>
+ * TP_ARGS
macro contains the arguments passed for the structure<br>
+ * it is
in the following format<br>
+ *
TP_ARGS(type1,
name1, type2, name2, ... type10,<br>
+
name10)<br>
+ * where
there can be from zero to ten elements.<br>
+ * typeN
is the datatype, such as int, struct or double **.<br>
+ * name
is the variable name (in "int myInt" the name would be<br>
+ * myint)<br>
+ *
TP_ARGS()
is valid to mean no arguments<br>
+ *
TP_ARGS(void)
is valid too<br>
+ */<br>
+ TP_ARGS(int,
anint, int, netint, long *, values,<br>
+
char *, text, size_t,
textlen,<br>
+
double, doublearg, float,
floatarg),<br>
+<br>
+ /*<br>
+ * TP_VARIANTS
will describe what field will be linked to what value of<br>
+ * the enumeration<br>
+ */<br>
+ TP_VARIANTS(<br>
+
/*<br>
+
* TP_VARIANT describes
one mapping from an enum value to a field<br>
+
*/<br>
+
TP_VARIANT(<br>
+
/*<br>
+
* The value of the enumeration field.
This must correspond to one<br>
+
* of the string_values defined in TP_ENUM_VALUES
of the linked<br>
+
* enumeration.<br>
+
*/<br>
+
enum_val,<br>
+<br>
+
/*<br>
+
* This is the field that will be added
to the tracepoint if the<br>
+
* value of the enum is enum_val.<br>
+
*<br>
+
* See TP_FIELDS macro in TRACEPOINT_EVENT
for complete description<br>
+
* of possible fields. A variant may not
contain itself and there cannot<br>
+
* be a cycle.<br>
+
*/<br>
+
<tp_field_expr><br>
+
)<br>
+ )<br>
+)<br>
+<br>
.fi<br>
<br>
.SH "ASSIGNING LOGLEVEL TO EVENTS"<br>
-- <br>
1.8.4.2<br>
<br>
<br>
_______________________________________________<br>
lttng-dev mailing list</font></tt><tt><font size=2 color=blue><u><br>
</u></font></tt><a href="mailto:lttng-dev@lists.lttng.org"><tt><font size=2 color=blue><u>lttng-dev@lists.lttng.org</u></font></tt></a><font size=3 color=blue><u><br>
</u></font><a href="http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev"><tt><font size=2 color=blue><u>http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev</u></font></tt></a><font size=3><br>
</font>
<br><tt><font size=2>_______________________________________________<br>
lttng-dev mailing list<br>
lttng-dev@lists.lttng.org<br>
</font></tt><a href="http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev"><tt><font size=2>http://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev</font></tt></a><tt><font size=2><br>
</font></tt>
<br>