On Fri, 8 Mar 2019 15:36:24 +0200
Tzvetomir Stoyanov <tstoyanov@xxxxxxxxxx> wrote:
> Create man pages for tep_register_print_function() and tep_unregister_print_function()
> as part of the libtraceevent APIs.
>
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@xxxxxxxxxx>
> ---
> .../libtraceevent-reg_print_func.txt | 128 ++++++++++++++++++
> 1 file changed, 128 insertions(+)
> create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
>
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
> new file mode 100644
> index 000000000000..59cef18b71f1
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
> @@ -0,0 +1,128 @@
> +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 the address
> +of the helper function. The _ret_type_ argument is the return type of the
I would say "The _func_ argument is a pointer to the helper function".
> +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_.
We should elaborate more what this is for. Some events have internal
functions called that appear in the print format output. For example,
tracefs/events/i915/g4x_wm/format has:
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)
Where inside the kernel they define a function:
static const char *yesno(int x)
{
static const char *yes = "yes";
static const char *no = "no";
return x ? yes : no;
}
Now the event parser has no idea how to handle this "yesno()" function.
But if we have:
static const char *yesno(int x)
{
return x ? "yes" : "no";
}
tep_register_print_function(tep, yesno, TEP_FUNC_ARG_STRING, "yesno",
TEP_FUNC_ARG_INT, TEP_FUNC_ARG_VOID);
Then when the parser encounters this "yesno()" function, it will know
how to handle it.
This actually is a good example to use in the man page!
-- Steve
> +
> +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
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +#include <trace-seq.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +static long long
> +process_custom_helper(struct trace_seq *s, unsigned long long *args)
> +{
> + unsigned long long param = args[0];
> + trace_seq_printf(s, "the helper was called, with argument %lld", param);
> + return 0;
> +}
> +...
> + if ( tep_register_print_function(tep,
> + process_custom_helper,
> + TEP_FUNC_ARG_STRING,
> + "custom_helper",
> + TEP_FUNC_ARG_LONG,
> + TEP_FUNC_ARG_VOID) != 0) {
> + /* Failed to register my process_custom_helper function */
> + }
> +...
> + if (tep_unregister_print_function(tep, process_custom_helper,
> + "custom_helper") != 0) {
> + /* Failed to unregister my process_custom_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@xxxxxxxxxxx>, author of *libtraceevent*.
> +*Tzvetomir Stoyanov* <tz.stoyanov@xxxxxxxxx>, author of this man page.
> +--
> +REPORTING BUGS
> +--------------
> +Report bugs to <linux-trace-devel@xxxxxxxxxxxxxxx>
> +
> +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
|