mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
155 lines
4.6 KiB
155 lines
4.6 KiB
libtraceevent(3) |
|
================ |
|
|
|
NAME |
|
---- |
|
tep_register_print_function,tep_unregister_print_function - |
|
Registers / Unregisters a helper function. |
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
-- |
|
*#include <event-parse.h>* |
|
|
|
enum *tep_func_arg_type* { |
|
TEP_FUNC_ARG_VOID, |
|
TEP_FUNC_ARG_INT, |
|
TEP_FUNC_ARG_LONG, |
|
TEP_FUNC_ARG_STRING, |
|
TEP_FUNC_ARG_PTR, |
|
TEP_FUNC_ARG_MAX_TYPES |
|
}; |
|
|
|
typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args); |
|
|
|
int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._); |
|
int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_); |
|
-- |
|
|
|
DESCRIPTION |
|
----------- |
|
Some events may have helper functions in the print format arguments. |
|
This allows a plugin to dynamically create a way to process one of |
|
these functions. |
|
|
|
The _tep_register_print_function()_ registers such helper function. The _tep_ |
|
argument is the trace event parser context. The _func_ argument is a pointer |
|
to the helper function. The _ret_type_ argument is the return type of the |
|
helper function, value from the _tep_func_arg_type_ enum. The _name_ is the name |
|
of the helper function, as seen in the print format arguments. The _..._ is a |
|
variable list of _tep_func_arg_type_ enums, the _func_ function arguments. |
|
This list must end with _TEP_FUNC_ARG_VOID_. See 'EXAMPLE' section. |
|
|
|
The _tep_unregister_print_function()_ unregisters a helper function, previously |
|
registered with _tep_register_print_function()_. The _tep_ argument is the |
|
trace event parser context. The _func_ and _name_ arguments are the same, used |
|
when the helper function was registered. |
|
|
|
The _tep_func_handler_ is the type of the helper function. The _s_ argument is |
|
the trace sequence, it can be used to create a custom string. |
|
The _args_ is a list of arguments, defined when the helper function was |
|
registered. |
|
|
|
RETURN VALUE |
|
------------ |
|
The _tep_register_print_function()_ function returns 0 in case of success. |
|
In case of an error, TEP_ERRNO_... code is returned. |
|
|
|
The _tep_unregister_print_function()_ returns 0 in case of success, or -1 in |
|
case of an error. |
|
|
|
EXAMPLE |
|
------- |
|
Some events have internal functions calls, that appear in the print format |
|
output. For example "tracefs/events/i915/g4x_wm/format" has: |
|
[source,c] |
|
-- |
|
print fmt: "pipe %c, frame=%u, scanline=%u, wm %d/%d/%d, sr %s/%d/%d/%d, hpll %s/%d/%d/%d, fbc %s", |
|
((REC->pipe) + 'A'), REC->frame, REC->scanline, REC->primary, |
|
REC->sprite, REC->cursor, yesno(REC->cxsr), REC->sr_plane, |
|
REC->sr_cursor, REC->sr_fbc, yesno(REC->hpll), REC->hpll_plane, |
|
REC->hpll_cursor, REC->hpll_fbc, yesno(REC->fbc) |
|
-- |
|
Notice the call to function _yesno()_ in the print arguments. In the kernel |
|
context, this function has the following implementation: |
|
[source,c] |
|
-- |
|
static const char *yesno(int x) |
|
{ |
|
static const char *yes = "yes"; |
|
static const char *no = "no"; |
|
|
|
return x ? yes : no; |
|
} |
|
-- |
|
The user space event parser has no idea how to handle this _yesno()_ function. |
|
The _tep_register_print_function()_ API can be used to register a user space |
|
helper function, mapped to the kernel's _yesno()_: |
|
[source,c] |
|
-- |
|
#include <event-parse.h> |
|
#include <trace-seq.h> |
|
... |
|
struct tep_handle *tep = tep_alloc(); |
|
... |
|
static const char *yes_no_helper(int x) |
|
{ |
|
return x ? "yes" : "no"; |
|
} |
|
... |
|
if ( tep_register_print_function(tep, |
|
yes_no_helper, |
|
TEP_FUNC_ARG_STRING, |
|
"yesno", |
|
TEP_FUNC_ARG_INT, |
|
TEP_FUNC_ARG_VOID) != 0) { |
|
/* Failed to register yes_no_helper function */ |
|
} |
|
|
|
/* |
|
Now, when the event parser encounters this yesno() function, it will know |
|
how to handle it. |
|
*/ |
|
... |
|
if (tep_unregister_print_function(tep, yes_no_helper, "yesno") != 0) { |
|
/* Failed to unregister yes_no_helper function */ |
|
} |
|
-- |
|
|
|
FILES |
|
----- |
|
[verse] |
|
-- |
|
*event-parse.h* |
|
Header file to include in order to have access to the library APIs. |
|
*trace-seq.h* |
|
Header file to include in order to have access to trace sequences |
|
related APIs. Trace sequences are used to allow a function to call |
|
several other functions to create a string of data to use. |
|
*-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/linux/kernel/git/torvalds/linux.git
|
|
|