1LIBTRACEEVENT(3)             libtraceevent Manual             LIBTRACEEVENT(3)
2
3
4

NAME

6       tep_set_function_resolver, tep_reset_function_resolver,
7       tep_register_function, tep_register_print_string,
8       tep_get_function_count - function related tep APIs
9

SYNOPSIS

11       #include <event-parse.h>
12
13       typedef char *(tep_func_resolver_t)(void *priv, unsigned long long *addrp, char **modp);
14       int tep_set_function_resolver(struct tep_handle *tep, tep_func_resolver_t *func, void *priv);
15       void tep_reset_function_resolver(struct tep_handle *tep);
16       int tep_register_function(struct tep_handle *tep, char *name, unsigned long long addr, char *mod);
17       int tep_register_print_string(struct tep_handle *tep, const char *fmt, unsigned long long addr);
18       int tep_get_function_count(struct tep_handle *tep)
19

DESCRIPTION

21       Some tools may have already a way to resolve the kernel functions.
22       These APIs allow them to keep using it instead of duplicating all the
23       entries inside.
24
25       The tep_func_resolver_t type is the prototype of the alternative kernel
26       functions resolver. This function receives a pointer to its custom
27       context (set with the tep_set_function_resolver() call ) and the
28       address of a kernel function, which has to be resolved. In case of
29       success, it should return the name of the function and its module (if
30       any) in modp.
31
32       The tep_set_function_resolver() function registers func as an
33       alternative kernel functions resolver. The tep argument is trace event
34       parser context. The priv argument is a custom context of the func
35       function. The function resolver is used by the APIs
36       tep_find_function(3), tep_find_function_address(3), and
37       tep_print_func_field() to resolve a function address to a function
38       name.
39
40       The tep_reset_function_resolver() function resets the kernel functions
41       resolver to the default function. The tep argument is trace event
42       parser context.
43
44       These APIs can be used to find function name and start address, by
45       given address. The given address does not have to be exact, it will
46       select the function that would contain it.
47
48       The tep_register_function() function registers a function name mapped
49       to an address and (optional) module. This mapping is used in case the
50       function tracer or events have "%pS" parameter in its format string. It
51       is common to pass in the kallsyms function names with their
52       corresponding addresses with this function. The tep argument is the
53       trace event parser context. The name is the name of the function, the
54       string is copied internally. The addr is the start address of the
55       function. The mod is the kernel module the function may be in (NULL for
56       none).
57
58       The tep_register_print_string() function registers a string by the
59       address it was stored in the kernel. Some strings internal to the
60       kernel with static address are passed to certain events. The "%s" in
61       the event’s format field which has an address needs to know what string
62       would be at that address. The tep_register_print_string() supplies the
63       parsing with the mapping between kernel addresses and those strings.
64       The tep argument is the trace event parser context. The fmt is the
65       string to register, it is copied internally. The addr is the address
66       the string was located at.
67
68       tep_get_function_count() returns the number of registered functions in
69       a tep handler.
70

RETURN VALUE

72       The tep_set_function_resolver() function returns 0 in case of success,
73       or -1 in case of an error.
74
75       The tep_register_function() function returns 0 in case of success. In
76       case of an error -1 is returned, and errno is set to the appropriate
77       error number.
78
79       The tep_register_print_string() function returns 0 in case of success.
80       In case of an error -1 is returned, and errno is set to the appropriate
81       error number.
82

EXAMPLE

84           #include <event-parse.h>
85           ...
86           struct tep_handle *tep = tep_alloc();
87           ...
88           char *my_resolve_kernel_addr(void *context,
89                                        unsigned long long *addrp, char **modp)
90           {
91                   struct db *function_database = context;
92                   struct symbol *sym = sql_lookup(function_database, *addrp);
93
94                   if (!sym)
95                           return NULL;
96
97                   *modp = sym->module_name;
98                   return sym->name;
99           }
100
101           void show_function( unsigned long long addr)
102           {
103                   unsigned long long fstart;
104                   const char *fname;
105
106                   if (tep_set_function_resolver(tep, my_resolve_kernel_addr,
107                                                 function_database) != 0) {
108                           /* failed to register my_resolve_kernel_addr */
109                   }
110
111                   /* These APIs use my_resolve_kernel_addr() to resolve the addr */
112                   fname = tep_find_function(tep, addr);
113                   fstart = tep_find_function_address(tep, addr);
114
115                   /*
116                      addr is in function named fname, starting at fstart address,
117                      at offset (addr - fstart)
118                   */
119
120                   tep_reset_function_resolver(tep);
121
122           }
123           ...
124                   if (tep_register_function(tep, "kvm_exit",
125                                           (unsigned long long) 0x12345678, "kvm") != 0) {
126                           /* Failed to register kvm_exit address mapping */
127                   }
128           ...
129                   if (tep_register_print_string(tep, "print string",
130                                           (unsigned long long) 0x87654321, NULL) != 0) {
131                           /* Failed to register "print string" address mapping */
132                   }
133           ...
134

FILES

136           event-parse.h
137                   Header file to include in order to have access to the library APIs.
138           -ltraceevent
139                   Linker switch to add when building a program that uses the library.
140

SEE ALSO

142       libtraceevent(3), trace-cmd(1)
143

AUTHOR

145           Steven Rostedt <rostedt@goodmis.org[1]>, author of libtraceevent.
146           Tzvetomir Stoyanov <tz.stoyanov@gmail.com[2]>, author of this man page.
147

REPORTING BUGS

149       Report bugs to <linux-trace-devel@vger.kernel.org[3]>
150

LICENSE

152       libtraceevent is Free Software licensed under the GNU LGPL 2.1
153

RESOURCES

155       https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
156

NOTES

158        1. rostedt@goodmis.org
159           mailto:rostedt@goodmis.org
160
161        2. tz.stoyanov@gmail.com
162           mailto:tz.stoyanov@gmail.com
163
164        3. linux-trace-devel@vger.kernel.org
165           mailto:linux-trace-devel@vger.kernel.org
166
167
168
169libtraceevent 1.7.2               07/20/2023                  LIBTRACEEVENT(3)
Impressum