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