tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_register_print_function,tep_unregister_print_function -
   7 Registers / Unregisters a helper function.
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 --
  13 *#include <event-parse.h>*
  14
  15 enum *tep_func_arg_type* {
  16         TEP_FUNC_ARG_VOID,
  17         TEP_FUNC_ARG_INT,
  18         TEP_FUNC_ARG_LONG,
  19         TEP_FUNC_ARG_STRING,
  20         TEP_FUNC_ARG_PTR,
  21         TEP_FUNC_ARG_MAX_TYPES
  22 };
  23
  24 typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args);
  25
  26 int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
  27 int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
  28 --
  29
  30 DESCRIPTION
  31 -----------
  32 Some events may have helper functions in the print format arguments.
  33 This allows a plugin to dynamically create a way to process one of
  34 these functions.
  35
  36 The _tep_register_print_function()_ registers such helper function. The _tep_
  37 argument is the trace event parser context. The _func_ argument  is a pointer
  38 to the helper function. The _ret_type_ argument is  the return type of the
  39 helper function, value from the _tep_func_arg_type_ enum. The _name_ is the name
  40 of the helper function, as seen in the print format arguments. The _..._ is a
  41 variable list of _tep_func_arg_type_ enums, the _func_ function arguments.
  42 This list must end with _TEP_FUNC_ARG_VOID_. See 'EXAMPLE' section.
  43
  44 The _tep_unregister_print_function()_ unregisters a helper function, previously
  45 registered with _tep_register_print_function()_. The _tep_ argument is the
  46 trace event parser context. The _func_ and _name_ arguments are the same, used
  47 when the helper function was registered.
  48
  49 The _tep_func_handler_ is the type of the helper function. The _s_ argument is
  50 the trace sequence, it can be used to create a custom string.
  51 The _args_  is a list of arguments, defined when the helper function was
  52 registered.
  53
  54 RETURN VALUE
  55 ------------
  56 The _tep_register_print_function()_ function returns 0 in case of success.
  57 In case of an error, TEP_ERRNO_... code is returned.
  58
  59 The _tep_unregister_print_function()_ returns 0 in case of success, or -1 in
  60 case of an error.
  61
  62 EXAMPLE
  63 -------
  64 Some events have internal functions calls, that appear in the print format
  65 output. For example "tracefs/events/i915/g4x_wm/format" has:
  66 [source,c]
  67 --
  68 print fmt: "pipe %c, frame=%u, scanline=%u, wm %d/%d/%d, sr %s/%d/%d/%d, hpll %s/%d/%d/%d, fbc %s",
  69             ((REC->pipe) + 'A'), REC->frame, REC->scanline, REC->primary,
  70             REC->sprite, REC->cursor, yesno(REC->cxsr), REC->sr_plane,
  71             REC->sr_cursor, REC->sr_fbc, yesno(REC->hpll), REC->hpll_plane,
  72             REC->hpll_cursor, REC->hpll_fbc, yesno(REC->fbc)
  73 --
  74 Notice the call to function _yesno()_ in the print arguments. In the kernel
  75 context, this function has the following implementation:
  76 [source,c]
  77 --
  78 static const char *yesno(int x)
  79 {
  80         static const char *yes = "yes";
  81         static const char *no = "no";
  82
  83         return x ? yes : no;
  84 }
  85 --
  86 The user space event parser has no idea how to handle this _yesno()_ function.
  87 The _tep_register_print_function()_ API can be used to register a user space
  88 helper function, mapped to the kernel's _yesno()_:
  89 [source,c]
  90 --
  91 #include <event-parse.h>
  92 #include <trace-seq.h>
  93 ...
  94 struct tep_handle *tep = tep_alloc();
  95 ...
  96 static const char *yes_no_helper(int x)
  97 {
  98         return x ? "yes" : "no";
  99 }
 100 ...
 101         if ( tep_register_print_function(tep,
 102                                     yes_no_helper,
 103                                     TEP_FUNC_ARG_STRING,
 104                                     "yesno",
 105                                     TEP_FUNC_ARG_INT,
 106                                     TEP_FUNC_ARG_VOID) != 0) {
 107                 /* Failed to register yes_no_helper function */
 108         }
 109
 110 /*
 111    Now, when the event parser encounters this yesno() function, it will know
 112    how to handle it.
 113 */
 114 ...
 115         if (tep_unregister_print_function(tep, yes_no_helper, "yesno") != 0) {
 116                 /* Failed to unregister yes_no_helper function */
 117         }
 118 --
 119
 120 FILES
 121 -----
 122 [verse]
 123 --
 124 *event-parse.h*
 125         Header file to include in order to have access to the library APIs.
 126 *trace-seq.h*
 127         Header file to include in order to have access to trace sequences
 128         related APIs. Trace sequences are used to allow a function to call
 129         several other functions to create a string of data to use.
 130 *-ltraceevent*
 131         Linker switch to add when building a program that uses the library.
 132 --
 133
 134 SEE ALSO
 135 --------
 136 _libtraceevent(3)_, _trace-cmd(1)_
 137
 138 AUTHOR
 139 ------
 140 [verse]
 141 --
 142 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 143 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 144 --
 145 REPORTING BUGS
 146 --------------
 147 Report bugs to  <linux-trace-devel@vger.kernel.org>
 148
 149 LICENSE
 150 -------
 151 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 152
 153 RESOURCES
 154 ---------
 155 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git