From: Philippe Proulx Date: Mon, 21 Mar 2016 20:43:44 +0000 (-0400) Subject: Update LTTng-modules API X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=349951ea269066d20366176cc9bca845b80d1aea;p=lttng-docs.git Update LTTng-modules API Signed-off-by: Philippe Proulx --- diff --git a/contents/reference/lttng-modules/lttng-modules-tp-fast-assign.md b/contents/reference/lttng-modules/lttng-modules-tp-fast-assign.md deleted file mode 100644 index 7c92978..0000000 --- a/contents/reference/lttng-modules/lttng-modules-tp-fast-assign.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -id: lttng-modules-tp-fast-assign ---- - -This table describes possible entries for the `TP_fast_assign()` part -of `LTTNG_TRACEPOINT_EVENT()`: - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MacroDescription/arguments
-
    -
  • tp_assign(d, s)
    • -
- 		-

- Assignment of C expression s - to tracepoint field d -

-
    -
  • - d name of destination - tracepoint field -
    • -
  • - s source C expression - (may refer to tracepoint arguments) -
    • -
-
-
    -
  • tp_memcpy(d, s, l)
    • -
- 		-

- Memory copy of l bytes from - s to tracepoint field - d (use with array fields) -

-
    -
  • - d name of destination - tracepoint field -
    • -
  • - s source C expression - (may refer to tracepoint arguments) -
    • -
  • - l number of bytes to - copy -
    • -
-
-
    -
  • tp_memcpy_from_user(d, s, l)
    • -
- 		-

- Memory copy of l bytes from - user space s to tracepoint field - d (use with array fields) -

-
    -
  • - d name of destination - tracepoint field -
    • -
  • - s source C expression - (may refer to tracepoint arguments) -
    • -
  • - l number of bytes to - copy -
    • -
-
-
    -
  • tp_memcpy_dyn(d, s)
    • -
- 		-

- Memory copy of dynamically-sized array - from s to tracepoint field - d; number of bytes is - known from the field's length expression (use with - dynamically-sized array fields) -

-
    -
  • - d name of destination - tracepoint field -
    • -
  • - s source C expression - (may refer to tracepoint arguments) -
    • -
  • - l number of bytes to - copy -
    • -
-
-
    -
  • tp_strcpy(d, s)
    • -
- 		-

- String copy of s - to tracepoint field d - (use with string fields) -

-
    -
  • - d name of destination - tracepoint field -
    • -
  • - s source C expression - (may refer to tracepoint arguments) -
    • -
-
-
diff --git a/contents/reference/lttng-modules/lttng-modules-tp-fields.md b/contents/reference/lttng-modules/lttng-modules-tp-fields.md new file mode 100644 index 0000000..8cad5e1 --- /dev/null +++ b/contents/reference/lttng-modules/lttng-modules-tp-fields.md @@ -0,0 +1,297 @@ +--- +id: lttng-modules-tp-fields +--- + + + +The available macros to define tracepoint fields, which should be listed +within `TP_FIELDS()` in `LTTNG_TRACEPOINT_EVENT()`, are: + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MacroDescription/arguments
+
    +
  • ctf_integer(t, n, e)
    • +
  • ctf_integer_nowrite(t, n, e)
    • +
  • ctf_user_integer(t, n, e)
    • +
  • ctf_user_integer_nowrite(t, n, e)
    • +
+ 		+

Standard integer, displayed in base 10

+
    +
  • + t integer C type + (int, long, + size_t, ...) +
    • +
  • n field name
    • +
  • e argument expression
    • +
+
+
    +
  • ctf_integer_hex(t, n, e)
    • +
  • ctf_user_integer_hex(t, n, e)
    • +
+ 		+

Standard integer, displayed in base 16

+
    +
  • t integer C type
    • +
  • n field name
    • +
  • e argument expression
    • +
+
ctf_integer_oct(t, n, e) +

Standard integer, displayed in base 8

+
    +
  • t integer C type
    • +
  • n field name
    • +
  • e argument expression
    • +
+
+
    +
  • ctf_integer_network(t, n, e)
    • +
  • ctf_user_integer_network(t, n, e)
    • +
+ 		+

+ Integer in network byte order (big-endian), + displayed in base 10 +

+
    +
  • t integer C type
    • +
  • n field name
    • +
  • e argument expression
    • +
+
+
    +
  • ctf_integer_network_hex(t, n, e)
    • +
  • ctf_user_integer_network_hex(t, n, e)
    • +
+ 		+

+ Integer in network byte order, displayed + in base 16

+
    +
  • t integer C type
    • +
  • n field name
    • +
  • e argument expression
    • +
+
+
    +
  • ctf_float(t, n, e)
    • +
  • ctf_user_float(t, n, e)
    • +
  • ctf_float_nowrite(t, n, e)
    • +
  • ctf_user_float_nowrite(t, n, e)
    • +
+ 		+

Floating point number

+
    +
  • + t floating point number + C type (float, double) +
    • +
  • n field name
    • +
  • e argument expression
    • +
+
+
    +
  • ctf_string(n, e)
    • +
  • ctf_user_string(n, e)
    • +
  • ctf_string_nowrite(n, e)
    • +
  • ctf_user_string_nowrite(n, e)
    • +
+ 		+

+ Null-terminated string; undefined behavior if + e is NULL +

+
    +
  • n field name
    • +
  • e argument expression
    • +
+
+
    +
  • ctf_array(t, n, e, s)
    • +
  • ctf_user_array(t, n, e, s)
    • +
  • ctf_array_nowrite(t, n, e, s)
    • +
  • ctf_user_array_nowrite(t, n, e, s)
    • +
+ 		+

+ Statically-sized array of integers, displayed in + base 10 +

+
    +
  • t array element C type
    • +
  • n field name
    • +
  • e argument expression
    • +
  • s number of elements
    • +
+
+
    +
  • ctf_array_text(t, n, e, s)
    • +
  • ctf_user_array_text(t, n, e, s)
    • +
  • ctf_array_text_nowrite(t, n, e, s)
    • +
  • ctf_user_array_text_nowrite(t, n, e, s)
    • +
+ 		+

+ Statically-sized array, printed as text; no need to + be null-terminated +

+
    +
  • t array element C type (always char)
    • +
  • n field name
    • +
  • e argument expression
    • +
  • s number of elements
    • +
+
+
    +
  • ctf_sequence(t, n, e, T, E)
    • +
  • ctf_user_sequence(t, n, e, T, E)
    • +
  • ctf_sequence_nowrite(t, n, e, T, E)
    • +
  • ctf_user_sequence_nowrite(t, n, e, T, E)
    • +
+ 		+

+ Dynamically-sized array of integers, displayed in + base 10; type of + E needs to be unsigned +

+
    +
  • t sequence element C type
    • +
  • n field name
    • +
  • e argument expression
    • +
  • T length expression C type
    • +
  • E length expression
    • +
+
+
    +
  • ctf_sequence_hex(t, n, e, T, E)
    • +
+ 		+

+ Dynamically-sized array of integers, displayed in + base 16; type of + E needs to be unsigned +

+
    +
  • t sequence element C type
    • +
  • n field name
    • +
  • e argument expression
    • +
  • T length expression C type
    • +
  • E length expression
    • +
+
+
    +
  • ctf_sequence_network(t, n, e, T, E)
    • +
+ 		+

+ Dynamically-sized array of integers in network byte + order (big endian), displayed in base 10; + type of + + + + E needs to be unsigned +

+
    +
  • t sequence element C type
    • +
  • n field name
    • +
  • e argument expression
    • +
  • T length expression C type
    • +
  • E length expression
    • +
+
+
    +
  • ctf_sequence_text(t, n, e, T, E)
    • +
  • ctf_user_sequence_text(t, n, e, T, E)
    • +
  • ctf_sequence_text_nowrite(t, n, e, T, E)
    • +
  • ctf_user_sequence_text_nowrite(t, n, e, T, E)
    • +
+ 		+

+ Dynamically-sized array, displayed as text; no need to + be null-terminated; undefined behavior if + e is NULL

+
    +
  • t sequence element C type (always char)
    • +
  • n field name
    • +
  • e argument expression
    • +
  • T length expression C type
    • +
  • E length expression
    • +
+
+
+ +The `_user` versions must be used when the argument expression, `e`, is +a user space address. In the cases of `ctf_user_integer*()` and +`ctf_user_float*()`, `&e` must be a user space address, thus `e` must +be addressable. + +The `_nowrite` versions omit themselves from the session trace, but are +otherwise identical. This means the `_nowrite` fields won't be written +in the recorded trace. Their primary purpose is to make some +of the event context available to the +[event filters](#doc-enabling-disabling-events) without having to +commit the data to sub-buffers. diff --git a/contents/reference/lttng-modules/lttng-modules-tp-struct-entry.md b/contents/reference/lttng-modules/lttng-modules-tp-struct-entry.md deleted file mode 100644 index 5f90f47..0000000 --- a/contents/reference/lttng-modules/lttng-modules-tp-struct-entry.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -id: lttng-modules-tp-struct-entry ---- - -This table describes possible entries for the `TP_STRUCT__entry()` part -of `LTTNG_TRACEPOINT_EVENT()`: - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MacroDescription/arguments
-
    -
  • __field(t, n)
    • -
- 		-

Standard integer, displayed in base 10

-
    -
  • - t integer C type - (int, unsigned char, - size_t, ...) -
    • -
  • n field name
    • -
-
-
    -
  • __field_hex(t, n)
    • -
- 		-

Standard integer, displayed in base 16

-
    -
  • t integer C type
    • -
  • n field name
    • -
-
-
    -
  • __field_oct(t, n)
    • -
- 		-

Standard integer, displayed in base 8

-
    -
  • - t integer C type -
    • -
  • n field name
    • -
-
-
    -
  • __field_network(t, n)
    • -
- 		-

- Integer in network byte order (big endian), - displayed in base 10 -

-
    -
  • - t integer C type -
    • -
  • n field name
    • -
-
-
    -
  • __field_network_hex(t, n)
    • -
- 		-

- Integer in network byte order (big endian), - displayed in base 16 -

-
    -
  • - t integer C type -
    • -
  • n field name
    • -
-
-
    -
  • __array(t, n, s)
    • -
- 		-

Statically-sized array, elements displayed in base 10

-
    -
  • - t array element C type -
    • -
  • n field name
    • -
  • s number of elements
    • -
-
-
    -
  • __array_hex(t, n, s)
    • -
- 		-

Statically-sized array, elements displayed in base 16

-
    -
  • - t array element C type -
    • -
  • n field name
    • -
  • s number of elements
    • -
-
-
    -
  • __array_text(t, n, s)
    • -
- 		-

Statically-sized array, displayed as text

-
    -
  • - t array element C type - (always char) -
    • -
  • n field name
    • -
  • s number of elements
    • -
-
-
    -
  • __dynamic_array(t, n, s)
    • -
- 		-

Dynamically-sized array, displayed in base 10

-
    -
  • - t array element C type -
    • -
  • n field name
    • -
  • s length C expression
    • -
-
-
    -
  • __dynamic_array_hex(t, n, s)
    • -
- 		-

Dynamically-sized array, displayed in base 16

-
    -
  • - t array element C type -
    • -
  • n field name
    • -
  • s length C expression
    • -
-
-
    -
  • __dynamic_array_text(t, n, s)
    • -
- 		-

Dynamically-sized array, displayed as text

-
    -
  • - t array element C type - (always char) -
    • -
  • n field name
    • -
  • s length C expression
    • -
-
-
    -
  • __string(n, s)
    • -
- 		-

- Null-terminated string; undefined behavior - if s is NULL -

-
    -
  • n field name
    • -
  • s string source (pointer)
    • -
-
-
- -The above macros should cover the majority of cases. For advanced items, -see `probes/lttng-events.h`. diff --git a/toc/docs.yml b/toc/docs.yml index d6f2492..6d817f0 100644 --- a/toc/docs.yml +++ b/toc/docs.yml @@ -221,7 +221,5 @@ cats: - id: lttng-modules-ref title: LTTng-modules cats: - - id: lttng-modules-tp-struct-entry - title: Tracepoint fields macros (for TP_STRUCT__entry()) - - id: lttng-modules-tp-fast-assign - title: Tracepoint assignment macros (for TP_fast_assign()) + - id: lttng-modules-tp-fields + title: Tracepoint fields macros (for TP_FIELDS())