1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
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* <rostedt@goodmis.org>, author of *libtraceevent*.
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
--
REPORTING BUGS
--------------
Report bugs to <linux-trace-devel@vger.kernel.org>
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
|
