libtraceevent-func_apis.txt (6464B)
1libtraceevent(3) 2================ 3 4NAME 5---- 6tep_find_function, tep_find_function_address, tep_set_function_resolver, 7tep_reset_function_resolver, tep_register_function, tep_register_print_string - 8function related tep APIs 9 10SYNOPSIS 11-------- 12[verse] 13-- 14*#include <event-parse.h>* 15 16typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_); 17int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_); 18void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_); 19const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); 20unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); 21int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_); 22int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_); 23-- 24 25DESCRIPTION 26----------- 27Some tools may have already a way to resolve the kernel functions. These APIs 28allow them to keep using it instead of duplicating all the entries inside. 29 30The _tep_func_resolver_t_ type is the prototype of the alternative kernel 31functions 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 33function, which has to be resolved. In case of success, it should return 34the name of the function and its module (if any) in _modp_. 35 36The _tep_set_function_resolver()_ function registers _func_ as an alternative 37kernel functions resolver. The _tep_ argument is trace event parser context. 38The _priv_ argument is a custom context of the _func_ function. The function 39resolver is used by the APIs _tep_find_function()_, 40_tep_find_function_address()_, and _tep_print_func_field()_ to resolve 41a function address to a function name. 42 43The _tep_reset_function_resolver()_ function resets the kernel functions 44resolver to the default function. The _tep_ argument is trace event parser 45context. 46 47 48These APIs can be used to find function name and start address, by given 49address. The given address does not have to be exact, it will select 50the function that would contain it. 51 52The _tep_find_function()_ function returns the function name, which contains the 53given address _addr_. The _tep_ argument is the trace event parser context. 54 55The _tep_find_function_address()_ function returns the function start address, 56by given address _addr_. The _addr_ does not have to be exact, it will select 57the function that would contain it. The _tep_ argument is the trace event 58parser context. 59 60The _tep_register_function()_ function registers a function name mapped to an 61address and (optional) module. This mapping is used in case the function tracer 62or events have "%pS" parameter in its format string. It is common to pass in 63the kallsyms function names with their corresponding addresses with this 64function. The _tep_ argument is the trace event parser context. The _name_ is 65the name of the function, the string is copied internally. The _addr_ is the 66start address of the function. The _mod_ is the kernel module the function may 67be in (NULL for none). 68 69The _tep_register_print_string()_ function registers a string by the address 70it was stored in the kernel. Some strings internal to the kernel with static 71address are passed to certain events. The "%s" in the event's format field 72which has an address needs to know what string would be at that address. The 73tep_register_print_string() supplies the parsing with the mapping between kernel 74addresses and those strings. The _tep_ argument is the trace event parser 75context. The _fmt_ is the string to register, it is copied internally. 76The _addr_ is the address the string was located at. 77 78 79RETURN VALUE 80------------ 81The _tep_set_function_resolver()_ function returns 0 in case of success, or -1 82in case of an error. 83 84The _tep_find_function()_ function returns the function name, or NULL in case 85it cannot be found. 86 87The _tep_find_function_address()_ function returns the function start address, 88or 0 in case it cannot be found. 89 90The _tep_register_function()_ function returns 0 in case of success. In case of 91an error -1 is returned, and errno is set to the appropriate error number. 92 93The _tep_register_print_string()_ function returns 0 in case of success. In case 94of an error -1 is returned, and errno is set to the appropriate error number. 95 96EXAMPLE 97------- 98[source,c] 99-- 100#include <event-parse.h> 101... 102struct tep_handle *tep = tep_alloc(); 103... 104char *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 117void 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 152FILES 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 162SEE ALSO 163-------- 164_libtraceevent(3)_, _trace-cmd(1)_ 165 166AUTHOR 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-- 173REPORTING BUGS 174-------------- 175Report bugs to <linux-trace-devel@vger.kernel.org> 176 177LICENSE 178------- 179libtraceevent is Free Software licensed under the GNU LGPL 2.1 180 181RESOURCES 182--------- 183https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git