0001 libtraceevent(3)
0002 ================
0003
0004 NAME
0005 ----
0006 tep_find_function, tep_find_function_address, tep_set_function_resolver,
0007 tep_reset_function_resolver, tep_register_function, tep_register_print_string -
0008 function related tep APIs
0009
0010 SYNOPSIS
0011 --------
0012 [verse]
0013 --
0014 *#include <event-parse.h>*
0015
0016 typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_);
0017 int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_);
0018 void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_);
0019 const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
0020 unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
0021 int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
0022 int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
0023 --
0024
0025 DESCRIPTION
0026 -----------
0027 Some tools may have already a way to resolve the kernel functions. These APIs
0028 allow them to keep using it instead of duplicating all the entries inside.
0029
0030 The _tep_func_resolver_t_ type is the prototype of the alternative kernel
0031 functions resolver. This function receives a pointer to its custom context
0032 (set with the _tep_set_function_resolver()_ call ) and the address of a kernel
0033 function, which has to be resolved. In case of success, it should return
0034 the name of the function and its module (if any) in _modp_.
0035
0036 The _tep_set_function_resolver()_ function registers _func_ as an alternative
0037 kernel functions resolver. The _tep_ argument is trace event parser context.
0038 The _priv_ argument is a custom context of the _func_ function. The function
0039 resolver is used by the APIs _tep_find_function()_,
0040 _tep_find_function_address()_, and _tep_print_func_field()_ to resolve
0041 a function address to a function name.
0042
0043 The _tep_reset_function_resolver()_ function resets the kernel functions
0044 resolver to the default function. The _tep_ argument is trace event parser
0045 context.
0046
0047
0048 These APIs can be used to find function name and start address, by given
0049 address. The given address does not have to be exact, it will select
0050 the function that would contain it.
0051
0052 The _tep_find_function()_ function returns the function name, which contains the
0053 given address _addr_. The _tep_ argument is the trace event parser context.
0054
0055 The _tep_find_function_address()_ function returns the function start address,
0056 by given address _addr_. The _addr_ does not have to be exact, it will select
0057 the function that would contain it. The _tep_ argument is the trace event
0058 parser context.
0059
0060 The _tep_register_function()_ function registers a function name mapped to an
0061 address and (optional) module. This mapping is used in case the function tracer
0062 or events have "%pS" parameter in its format string. It is common to pass in
0063 the kallsyms function names with their corresponding addresses with this
0064 function. The _tep_ argument is the trace event parser context. The _name_ is
0065 the name of the function, the string is copied internally. The _addr_ is the
0066 start address of the function. The _mod_ is the kernel module the function may
0067 be in (NULL for none).
0068
0069 The _tep_register_print_string()_ function registers a string by the address
0070 it was stored in the kernel. Some strings internal to the kernel with static
0071 address are passed to certain events. The "%s" in the event's format field
0072 which has an address needs to know what string would be at that address. The
0073 tep_register_print_string() supplies the parsing with the mapping between kernel
0074 addresses and those strings. The _tep_ argument is the trace event parser
0075 context. The _fmt_ is the string to register, it is copied internally.
0076 The _addr_ is the address the string was located at.
0077
0078
0079 RETURN VALUE
0080 ------------
0081 The _tep_set_function_resolver()_ function returns 0 in case of success, or -1
0082 in case of an error.
0083
0084 The _tep_find_function()_ function returns the function name, or NULL in case
0085 it cannot be found.
0086
0087 The _tep_find_function_address()_ function returns the function start address,
0088 or 0 in case it cannot be found.
0089
0090 The _tep_register_function()_ function returns 0 in case of success. In case of
0091 an error -1 is returned, and errno is set to the appropriate error number.
0092
0093 The _tep_register_print_string()_ function returns 0 in case of success. In case
0094 of an error -1 is returned, and errno is set to the appropriate error number.
0095
0096 EXAMPLE
0097 -------
0098 [source,c]
0099 --
0100 #include <event-parse.h>
0101 ...
0102 struct tep_handle *tep = tep_alloc();
0103 ...
0104 char *my_resolve_kernel_addr(void *context,
0105 unsigned long long *addrp, char **modp)
0106 {
0107 struct db *function_database = context;
0108 struct symbol *sym = sql_lookup(function_database, *addrp);
0109
0110 if (!sym)
0111 return NULL;
0112
0113 *modp = sym->module_name;
0114 return sym->name;
0115 }
0116
0117 void show_function( unsigned long long addr)
0118 {
0119 unsigned long long fstart;
0120 const char *fname;
0121
0122 if (tep_set_function_resolver(tep, my_resolve_kernel_addr,
0123 function_database) != 0) {
0124 /* failed to register my_resolve_kernel_addr */
0125 }
0126
0127 /* These APIs use my_resolve_kernel_addr() to resolve the addr */
0128 fname = tep_find_function(tep, addr);
0129 fstart = tep_find_function_address(tep, addr);
0130
0131 /*
0132 addr is in function named fname, starting at fstart address,
0133 at offset (addr - fstart)
0134 */
0135
0136 tep_reset_function_resolver(tep);
0137
0138 }
0139 ...
0140 if (tep_register_function(tep, "kvm_exit",
0141 (unsigned long long) 0x12345678, "kvm") != 0) {
0142 /* Failed to register kvm_exit address mapping */
0143 }
0144 ...
0145 if (tep_register_print_string(tep, "print string",
0146 (unsigned long long) 0x87654321, NULL) != 0) {
0147 /* Failed to register "print string" address mapping */
0148 }
0149 ...
0150 --
0151
0152 FILES
0153 -----
0154 [verse]
0155 --
0156 *event-parse.h*
0157 Header file to include in order to have access to the library APIs.
0158 *-ltraceevent*
0159 Linker switch to add when building a program that uses the library.
0160 --
0161
0162 SEE ALSO
0163 --------
0164 _libtraceevent(3)_, _trace-cmd(1)_
0165
0166 AUTHOR
0167 ------
0168 [verse]
0169 --
0170 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
0171 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
0172 --
0173 REPORTING BUGS
0174 --------------
0175 Report bugs to <linux-trace-devel@vger.kernel.org>
0176
0177 LICENSE
0178 -------
0179 libtraceevent is Free Software licensed under the GNU LGPL 2.1
0180
0181 RESOURCES
0182 ---------
0183 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
