[v4,36/46] tools/lib/traceevent: Man pages for tep_set_function_resolver() and tep_reset_function_resolver()

Commit Message

Tzvetomir Stoyanov March 8, 2019, 1:36 p.m. UTC

Create man pages for tep_set_function_resolver() and tep_reset_function_resolver()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <[e-mail]>
---
 .../libtraceevent-func_resolve.txt            | 96 +++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt

Comments

Steven Rostedt March 13, 2019, 8:06 p.m. UTC | #1

On Fri,  8 Mar 2019 15:36:44 +0200
Tzvetomir Stoyanov <[e-mail]> wrote:

> Create man pages for tep_set_function_resolver() and tep_reset_function_resolver()
> as part of the libtraceevent APIs.
> 
>

These could probably be added to the tep_register_function() man pages
as well.

-- Steve

Matt Helsley March 19, 2019, 7:08 p.m. UTC | #2

> On Mar 13, 2019, at 1:06 PM, Steven Rostedt <[e-mail]> wrote:
> 
> On Fri,  8 Mar 2019 15:36:44 +0200
> Tzvetomir Stoyanov <[e-mail]> wrote:
> 
>> Create man pages for tep_set_function_resolver() and tep_reset_function_resolver()
>> as part of the libtraceevent APIs.
>> 
>> 
> 
> These could probably be added to the tep_register_function() man pages
> as well.
> 
> -- Steve

The content itself looks good and this makes sense to me.

Cheers,
     -Matt

Patch

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
new file mode 100644
index 000000000000..38b715bd926c
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
@@ -0,0 +1,96 @@ 
+libtraceevent(3)
+================
+
+NAME
+----
+tep_set_function_resolver,tep_reset_function_resolver - Set / reset an alternative function resolver
+
+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_);
+--
+
+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_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 _tep_reset_function_resolver()_ function resets the kernel functions
+resolver to the default function.  The _tep_ argument is trace event parser
+context.
+
+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_.
+
+RETURN VALUE
+------------
+The _tep_set_function_resolver()_ function returns 0 in case of success, or -1
+in case of an error.
+
+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)
+{
+	return NULL;
+}
+...
+	if (tep_set_function_resolver(tep, my_resolve_kernel_addr, NULL) != 0) {
+		/* failed to register my_resolve_kernel_addr */
+	}
+...
+	tep_reset_function_resolver(tep);
+...
+--
+
+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* <[e-mail]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[e-mail]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[e-mail]>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git