xref: /aosp_15_r20/external/libtraceevent/Documentation/libtraceevent-func_apis.txt (revision 436bf2bcd5202612ffffe471bbcc1f277cc8d28e)

libtraceevent(3)
================

NAME
----
tep_set_function_resolver, tep_reset_function_resolver, tep_register_function, tep_register_print_string,
tep_get_function_count - function related tep APIs

SYNOPSIS
--------
[verse]
--
*#include <event-parse.h>*

typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_);
int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_);
void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_);
int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
int *tep_get_function_count*(struct tep_handle *_tep_)
--

DESCRIPTION
-----------
Some tools may have already a way to resolve the kernel functions. These APIs
allow them to keep using it instead of duplicating all the entries inside.

The _tep_func_resolver_t_ type is the prototype of the alternative kernel
functions resolver. This function receives a pointer to its custom context
(set with the *tep_set_function_resolver()* call ) and the address of a kernel
function, which has to be resolved. In case of success, it should return
the name of the function and its module (if any) in _modp_.

The *tep_set_function_resolver()* function registers _func_ as an alternative
kernel functions resolver. The _tep_ argument is trace event parser context.
The _priv_ argument is a custom context of the _func_ function. The function
resolver is used by the APIs *tep_find_function*(3),
*tep_find_function_address*(3), and *tep_print_func_field()* to resolve
a function address to a function name.

The *tep_reset_function_resolver()* function resets the kernel functions
resolver to the default function.  The _tep_ argument is trace event parser
context.


These APIs can be used to find function name and start address, by given
address. The given address does not have to be exact, it will select
the function that would contain it.

The *tep_register_function()* function registers a function name mapped to an
address and (optional) module. This mapping is used in case the function tracer
or events have "%pS" parameter in its format string. It is common to pass in
the kallsyms function names with their corresponding addresses with this
function. The _tep_ argument is the trace event parser context. The _name_ is
the name of the function, the string is copied internally. The _addr_ is the
start address of the function. The _mod_ is the kernel module the function may
be in (NULL for none).

The *tep_register_print_string()* function  registers a string by the address
it was stored in the kernel. Some strings internal to the kernel with static
address are passed to certain events. The "%s" in the event's format field
which has an address needs to know what string would be at that address. The
tep_register_print_string() supplies the parsing with the mapping between kernel
addresses and those strings. The _tep_ argument is the trace event parser
context. The _fmt_ is the string to register, it is copied internally.
The _addr_ is the address the string was located at.

*tep_get_function_count*() returns the number of registered functions in a tep handler.

RETURN VALUE
------------
The *tep_set_function_resolver()* function returns 0 in case of success, or -1
in case of an error.

The *tep_register_function()* function returns 0 in case of success. In case of
an error -1 is returned, and errno is set to the appropriate error number.

The *tep_register_print_string()* function returns 0 in case of success. In case
of an error -1 is returned, and errno is set to the appropriate error number.

EXAMPLE
-------
[source,c]
--
#include <event-parse.h>
...
struct tep_handle *tep = tep_alloc();
...
char *my_resolve_kernel_addr(void *context,
			     unsigned long long *addrp, char **modp)
{
	struct db *function_database = context;
	struct symbol *sym = sql_lookup(function_database, *addrp);

	if (!sym)
		return NULL;

	*modp = sym->module_name;
	return sym->name;
}

void show_function( unsigned long long addr)
{
	unsigned long long fstart;
	const char *fname;

	if (tep_set_function_resolver(tep, my_resolve_kernel_addr,
				      function_database) != 0) {
		/* failed to register my_resolve_kernel_addr */
	}

	/* These APIs use my_resolve_kernel_addr() to resolve the addr */
	fname = tep_find_function(tep, addr);
	fstart = tep_find_function_address(tep, addr);

	/*
	   addr is in function named fname, starting at fstart address,
	   at offset (addr - fstart)
	*/

	tep_reset_function_resolver(tep);

}
...
	if (tep_register_function(tep, "kvm_exit",
				(unsigned long long) 0x12345678, "kvm") != 0) {
		/* Failed to register kvm_exit address mapping */
	}
...
	if (tep_register_print_string(tep, "print string",
				(unsigned long long) 0x87654321, NULL) != 0) {
		/* Failed to register "print string" address mapping */
	}
...
--

FILES
-----
[verse]
--
*event-parse.h*
	Header file to include in order to have access to the library APIs.
*-ltraceevent*
	Linker switch to add when building a program that uses the library.
--

SEE ALSO
--------
*libtraceevent*(3), *trace-cmd*(1)

AUTHOR
------
[verse]
--
*Steven Rostedt* <[email protected]>, author of *libtraceevent*.
*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
--
REPORTING BUGS
--------------
Report bugs to  <[email protected]>

LICENSE
-------
libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES
---------
https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/