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

   1 libtraceevent(3)
   2 ================
   3
   4 NAME
   5 ----
   6 tep_find_function, tep_find_function_address, tep_set_function_resolver,
   7 tep_reset_function_resolver, tep_register_function, tep_register_print_string -
   8 function related tep APIs
   9
  10 SYNOPSIS
  11 --------
  12 [verse]
  13 --
  14 *#include <event-parse.h>*
  15
  16 typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_);
  17 int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_);
  18 void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_);
  19 const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
  20 unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
  21 int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
  22 int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
  23 --
  24
  25 DESCRIPTION
  26 -----------
  27 Some tools may have already a way to resolve the kernel functions. These APIs
  28 allow them to keep using it instead of duplicating all the entries inside.
  29
  30 The _tep_func_resolver_t_ type is the prototype of the alternative kernel
  31 functions resolver. This function receives a pointer to its custom context
  32 (set with the _tep_set_function_resolver()_ call ) and the address of a kernel
  33 function, which has to be resolved. In case of success, it should return
  34 the name of the function and its module (if any) in _modp_.
  35
  36 The _tep_set_function_resolver()_ function registers _func_ as an alternative
  37 kernel functions resolver. The _tep_ argument is trace event parser context.
  38 The _priv_ argument is a custom context of the _func_ function. The function
  39 resolver is used by the APIs _tep_find_function()_,
  40 _tep_find_function_address()_, and _tep_print_func_field()_ to resolve
  41 a function address to a function name.
  42
  43 The _tep_reset_function_resolver()_ function resets the kernel functions
  44 resolver to the default function.  The _tep_ argument is trace event parser
  45 context.
  46
  47
  48 These APIs can be used to find function name and start address, by given
  49 address. The given address does not have to be exact, it will select
  50 the function that would contain it.
  51
  52 The _tep_find_function()_ function returns the function name, which contains the
  53 given address _addr_. The _tep_ argument is the trace event parser context.
  54
  55 The _tep_find_function_address()_ function returns the function start address,
  56 by given address _addr_. The _addr_ does not have to be exact, it will select
  57 the function that would contain it. The _tep_ argument is the trace event
  58 parser context.
  59
  60 The _tep_register_function()_ function registers a function name mapped to an
  61 address and (optional) module. This mapping is used in case the function tracer
  62 or events have "%pS" parameter in its format string. It is common to pass in
  63 the kallsyms function names with their corresponding addresses with this
  64 function. The _tep_ argument is the trace event parser context. The _name_ is
  65 the name of the function, the string is copied internally. The _addr_ is the
  66 start address of the function. The _mod_ is the kernel module the function may
  67 be in (NULL for none).
  68
  69 The _tep_register_print_string()_ function  registers a string by the address
  70 it was stored in the kernel. Some strings internal to the kernel with static
  71 address are passed to certain events. The "%s" in the event's format field
  72 which has an address needs to know what string would be at that address. The
  73 tep_register_print_string() supplies the parsing with the mapping between kernel
  74 addresses and those strings. The _tep_ argument is the trace event parser
  75 context. The _fmt_ is the string to register, it is copied internally.
  76 The _addr_ is the address the string was located at.
  77
  78
  79 RETURN VALUE
  80 ------------
  81 The _tep_set_function_resolver()_ function returns 0 in case of success, or -1
  82 in case of an error.
  83
  84 The _tep_find_function()_ function returns the function name, or NULL in case
  85 it cannot be found.
  86
  87 The _tep_find_function_address()_ function returns the function start address,
  88 or 0 in case it cannot be found.
  89
  90 The _tep_register_function()_ function returns 0 in case of success. In case of
  91 an error -1 is returned, and errno is set to the appropriate error number.
  92
  93 The _tep_register_print_string()_ function returns 0 in case of success. In case
  94 of an error -1 is returned, and errno is set to the appropriate error number.
  95
  96 EXAMPLE
  97 -------
  98 [source,c]
  99 --
 100 #include <event-parse.h>
 101 ...
 102 struct tep_handle *tep = tep_alloc();
 103 ...
 104 char *my_resolve_kernel_addr(void *context,
 105                              unsigned long long *addrp, char **modp)
 106 {
 107         struct db *function_database = context;
 108         struct symbol *sym = sql_lookup(function_database, *addrp);
 109
 110         if (!sym)
 111                 return NULL;
 112
 113         *modp = sym->module_name;
 114         return sym->name;
 115 }
 116
 117 void show_function( unsigned long long addr)
 118 {
 119         unsigned long long fstart;
 120         const char *fname;
 121
 122         if (tep_set_function_resolver(tep, my_resolve_kernel_addr,
 123                                       function_database) != 0) {
 124                 /* failed to register my_resolve_kernel_addr */
 125         }
 126
 127         /* These APIs use my_resolve_kernel_addr() to resolve the addr */
 128         fname = tep_find_function(tep, addr);
 129         fstart = tep_find_function_address(tep, addr);
 130
 131         /*
 132            addr is in function named fname, starting at fstart address,
 133            at offset (addr - fstart)
 134         */
 135
 136         tep_reset_function_resolver(tep);
 137
 138 }
 139 ...
 140         if (tep_register_function(tep, "kvm_exit",
 141                                 (unsigned long long) 0x12345678, "kvm") != 0) {
 142                 /* Failed to register kvm_exit address mapping */
 143         }
 144 ...
 145         if (tep_register_print_string(tep, "print string",
 146                                 (unsigned long long) 0x87654321, NULL) != 0) {
 147                 /* Failed to register "print string" address mapping */
 148         }
 149 ...
 150 --
 151
 152 FILES
 153 -----
 154 [verse]
 155 --
 156 *event-parse.h*
 157         Header file to include in order to have access to the library APIs.
 158 *-ltraceevent*
 159         Linker switch to add when building a program that uses the library.
 160 --
 161
 162 SEE ALSO
 163 --------
 164 _libtraceevent(3)_, _trace-cmd(1)_
 165
 166 AUTHOR
 167 ------
 168 [verse]
 169 --
 170 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
 171 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
 172 --
 173 REPORTING BUGS
 174 --------------
 175 Report bugs to  <linux-trace-devel@vger.kernel.org>
 176
 177 LICENSE
 178 -------
 179 libtraceevent is Free Software licensed under the GNU LGPL 2.1
 180
 181 RESOURCES
 182 ---------
 183 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git