0001 libtraceevent(3)
0002 ================
0003
0004 NAME
0005 ----
0006 tep_register_print_function,tep_unregister_print_function -
0007 Registers / Unregisters a helper function.
0008
0009 SYNOPSIS
0010 --------
0011 [verse]
0012 --
0013 *#include <event-parse.h>*
0014
0015 enum *tep_func_arg_type* {
0016 TEP_FUNC_ARG_VOID,
0017 TEP_FUNC_ARG_INT,
0018 TEP_FUNC_ARG_LONG,
0019 TEP_FUNC_ARG_STRING,
0020 TEP_FUNC_ARG_PTR,
0021 TEP_FUNC_ARG_MAX_TYPES
0022 };
0023
0024 typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args);
0025
0026 int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
0027 int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
0028 --
0029
0030 DESCRIPTION
0031 -----------
0032 Some events may have helper functions in the print format arguments.
0033 This allows a plugin to dynamically create a way to process one of
0034 these functions.
0035
0036 The _tep_register_print_function()_ registers such helper function. The _tep_
0037 argument is the trace event parser context. The _func_ argument is a pointer
0038 to the helper function. The _ret_type_ argument is the return type of the
0039 helper function, value from the _tep_func_arg_type_ enum. The _name_ is the name
0040 of the helper function, as seen in the print format arguments. The _..._ is a
0041 variable list of _tep_func_arg_type_ enums, the _func_ function arguments.
0042 This list must end with _TEP_FUNC_ARG_VOID_. See 'EXAMPLE' section.
0043
0044 The _tep_unregister_print_function()_ unregisters a helper function, previously
0045 registered with _tep_register_print_function()_. The _tep_ argument is the
0046 trace event parser context. The _func_ and _name_ arguments are the same, used
0047 when the helper function was registered.
0048
0049 The _tep_func_handler_ is the type of the helper function. The _s_ argument is
0050 the trace sequence, it can be used to create a custom string.
0051 The _args_ is a list of arguments, defined when the helper function was
0052 registered.
0053
0054 RETURN VALUE
0055 ------------
0056 The _tep_register_print_function()_ function returns 0 in case of success.
0057 In case of an error, TEP_ERRNO_... code is returned.
0058
0059 The _tep_unregister_print_function()_ returns 0 in case of success, or -1 in
0060 case of an error.
0061
0062 EXAMPLE
0063 -------
0064 Some events have internal functions calls, that appear in the print format
0065 output. For example "tracefs/events/i915/g4x_wm/format" has:
0066 [source,c]
0067 --
0068 print fmt: "pipe %c, frame=%u, scanline=%u, wm %d/%d/%d, sr %s/%d/%d/%d, hpll %s/%d/%d/%d, fbc %s",
0069 ((REC->pipe) + 'A'), REC->frame, REC->scanline, REC->primary,
0070 REC->sprite, REC->cursor, yesno(REC->cxsr), REC->sr_plane,
0071 REC->sr_cursor, REC->sr_fbc, yesno(REC->hpll), REC->hpll_plane,
0072 REC->hpll_cursor, REC->hpll_fbc, yesno(REC->fbc)
0073 --
0074 Notice the call to function _yesno()_ in the print arguments. In the kernel
0075 context, this function has the following implementation:
0076 [source,c]
0077 --
0078 static const char *yesno(int x)
0079 {
0080 static const char *yes = "yes";
0081 static const char *no = "no";
0082
0083 return x ? yes : no;
0084 }
0085 --
0086 The user space event parser has no idea how to handle this _yesno()_ function.
0087 The _tep_register_print_function()_ API can be used to register a user space
0088 helper function, mapped to the kernel's _yesno()_:
0089 [source,c]
0090 --
0091 #include <event-parse.h>
0092 #include <trace-seq.h>
0093 ...
0094 struct tep_handle *tep = tep_alloc();
0095 ...
0096 static const char *yes_no_helper(int x)
0097 {
0098 return x ? "yes" : "no";
0099 }
0100 ...
0101 if ( tep_register_print_function(tep,
0102 yes_no_helper,
0103 TEP_FUNC_ARG_STRING,
0104 "yesno",
0105 TEP_FUNC_ARG_INT,
0106 TEP_FUNC_ARG_VOID) != 0) {
0107 /* Failed to register yes_no_helper function */
0108 }
0109
0110 /*
0111 Now, when the event parser encounters this yesno() function, it will know
0112 how to handle it.
0113 */
0114 ...
0115 if (tep_unregister_print_function(tep, yes_no_helper, "yesno") != 0) {
0116 /* Failed to unregister yes_no_helper function */
0117 }
0118 --
0119
0120 FILES
0121 -----
0122 [verse]
0123 --
0124 *event-parse.h*
0125 Header file to include in order to have access to the library APIs.
0126 *trace-seq.h*
0127 Header file to include in order to have access to trace sequences
0128 related APIs. Trace sequences are used to allow a function to call
0129 several other functions to create a string of data to use.
0130 *-ltraceevent*
0131 Linker switch to add when building a program that uses the library.
0132 --
0133
0134 SEE ALSO
0135 --------
0136 _libtraceevent(3)_, _trace-cmd(1)_
0137
0138 AUTHOR
0139 ------
0140 [verse]
0141 --
0142 *Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
0143 *Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
0144 --
0145 REPORTING BUGS
0146 --------------
0147 Report bugs to <linux-trace-devel@vger.kernel.org>
0148
0149 LICENSE
0150 -------
0151 libtraceevent is Free Software licensed under the GNU LGPL 2.1
0152
0153 RESOURCES
0154 ---------
0155 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
