Loading...
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 |