git.lttng.org Git - lttng-docs.git/blob

   1 ---
   2 id: lttng-tracepoint-event-code
   3 since: 2.7
   4 ---
   5
   6 Although it is recommended to always use the
   7 [`LTTNG_TRACEPOINT_EVENT()`](#doc-lttng-adaptation-layer)
   8 macro to describe the arguments and fields of an LTTng tracepoint when
   9 possible, sometimes a more complex process is needed to access the data
  10 to be recorded as tracepoint fields. In other words, local variables
  11 and multiple C statements are required instead of simple argument-based
  12 expressions passed to the
  13 [`ctf_*()` macros of `TP_FIELDS()`](#doc-lttng-modules-tp-fields).
  14
  15 The `LTTNG_TRACEPOINT_EVENT_CODE()` macro can be used instead of
  16 `LTTNG_TRACEPOINT_EVENT()` to declare custom local variables and
  17 define a block of C code to be executed before the fields are
  18 recorded. The structure of this macro is:
  19
  20 ~~~ c
  21 LTTNG_TRACEPOINT_EVENT_CODE(
  22     /* format identical to LTTNG_TRACEPOINT_EVENT() version for those */
  23     hello_world,
  24     TP_PROTO(int foo, const char *bar),
  25     TP_ARGS(foo, bar),
  26
  27     /* declarations of custom local variables */
  28     TP_locvar(
  29         int a = 0;
  30         unsigned long b = 0;
  31         const char *name = "(undefined)";
  32         struct my_struct *my_struct;
  33     ),
  34
  35     /*
  36      * Custom code using which use both tracepoint arguments
  37      * (in TP_ARGS()) and local variables (in TP_locvar()).
  38      *
  39      * Local variables are actually members of a structure pointed
  40      * to by the special variable tp_locvar.
  41      */
  42     TP_code(
  43         if (foo) {
  44             tp_locvar->a = foo + 17;
  45             tp_locvar->my_struct = get_my_struct_at(tp_locvar->a);
  46             tp_locvar->b = my_struct_compute_b(tp_locvar->my_struct);
  47             tp_locvar->name = my_struct_get_name(tp_locvar->my_struct);
  48             put_my_struct(tp_locvar->my_struct);
  49
  50             if (tp_locvar->b) {
  51                 tp_locvar->a = 1;
  52             }
  53         }
  54     ),
  55
  56     /*
  57      * Format identical to LTTNG_TRACEPOINT_EVENT() version for this,
  58      * except that tp_locvar members can be used in the argument
  59      * expression parameters of the ctf_*() macros.
  60      */
  61     TP_FIELDS(
  62         ctf_integer(unsigned long, my_struct_b, tp_locvar->b)
  63         ctf_integer(int, my_struct_a, tp_locvar->a)
  64         ctf_string(bar_field, bar)
  65         ctf_string(my_struct_name, tp_locvar->name)
  66     )
  67 )
  68 ~~~
  69
  70 Make sure that the C code defined in `TP_code()` has no side effects
  71 when executed. In particular, the code should not allocate memory or get
  72 resources without deallocating this memory or putting those resources
  73 afterwards.