From patchwork Fri Nov 2 14:57:29 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759649 Return-Path: Received: from mail-eopbgr730040.outbound.protection.outlook.com ([40.107.73.40]:32992 "EHLO NAM05-DM3-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1726265AbeKCAE4 (ORCPT ); Fri, 2 Nov 2018 20:04:56 -0400 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 3/3] tools/lib/traceevent: Implement libtraceevent man pages Date: Fri, 2 Nov 2018 14:57:29 +0000 Message-ID: <20181102145714.25885-4-tstoyanov@vmware.com> References: <20181102145714.25885-1-tstoyanov@vmware.com> In-Reply-To: <20181102145714.25885-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 15672 This patch implements 5 new man pages, which describe following libtraceevent APIs: tep_register_comm,tep_pid_is_registered,tep_data_comm_from_pid, tep_data_pid_from_comm,tep_cmdline_pid,tep_alloc,tep_free,tep_get_long_size, tep_set_long_size,tep_set_flag. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-commands.txt | 125 ++++++++++++++++++ .../Documentation/libtraceevent-handle.txt | 77 +++++++++++ .../Documentation/libtraceevent-long_size.txt | 75 +++++++++++ .../Documentation/libtraceevent-ref.txt | 84 ++++++++++++ .../Documentation/libtraceevent-set_flag.txt | 94 +++++++++++++ 5 files changed, 455 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-commands.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-handle.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-long_size.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-ref.txt create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-commands.txt b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt new file mode 100644 index 000000000000..9ca6c19cf9cb --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-commands.txt @@ -0,0 +1,125 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_comm,tep_pid_is_registered,tep_data_comm_from_pid,tep_data_pid_from_comm,tep_cmdline_pid - handle pid to process name mappings + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_); +int *tep_pid_is_registered*(struct tep_handle pass:[*]_tep_, int _pid_); +const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_pevent_, int _pid_); +struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_pevent_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_); +int *tep_cmdline_pid*(struct tep_handle pass:[*]_pevent_, struct cmdline pass:[*]_cmdline_); +-- + +DESCRIPTION +----------- +These functions can be used to handle the mapping between pid and process name. +The library builds a cache of these mappings, which is used to display the name of +the process, instead of its pid. This information can be retrieved from +debugfs/tracing/saved_cmdlines file. It is also saved in trace.dat file. + +The _tep_register_comm()_ function registers a pid / process name mapping. +The _pid_ argument is the process ID, the _comm_ argument is the process name, +_tep_ is the event context. The process name string is duplicated. + +The _tep_pid_is_registered()_ function checks if a pid has a process name mapping registered. +The _pid_ argumnet is the process ID, _tep_ is the event context. + +The _tep_data_comm_from_pid()_ function returns the process name for given pid. +The _pid_ argument is the process ID, _tep_ is the event context. + +The _tep_data_pid_from_comm()_ function returns pid for given process name. +The _comm_ argument is the process name, _tep_ is the event context. +The argument _next_ is the cmdline structure to search for the next pid, can be NULL. +As there may be more than one pid for a given process, the result of this call +can be passed back into a recurring call in the _next_ parameter, to search for the next pid. +The function performs a linear seach, so it may be slow. + +The _tep_cmdline_pid()_ function returns the pid associated with a given _cmdline_. +The _tep_ argument is the event context. + +RETURN VALUE +------------ +_tep_register_comm()_ function returns 0 on success completion, or -1 in case of a error. + +_tep_pid_is_registered()_ function returns 1 if the _pid_ has a process name mapped to it, 0 otherwise. + +_tep_data_comm_from_pid()_ function returns the process name as string, or the string "<...>" if thers is no mapping for the given pid. + +_tep_data_pid_from_comm()_ function returns pointer to struct cmdline, that holds a pid for a given +process, or NULL if none is found. This result can be passed back into a recurring call as the _next_ parameter of the function. + +_tep_cmdline_pid()_ functions returns the pid for the give cmdline. If _cmdline_ is NULL, then + -1 is returned. + +EXAMPLE +------- +The following example registers pid for command "ls", in context of event _tep_ +and performs various searches for pid / process name mappings: +[source,c] +-- +#include +... +int ls_pid = 1021; +struct tep_handle *tep = tep_alloc(); +... + if (0 != tep_register_comm(tep, "ls", ls_pid)) { + /* Failed to register pid / command mapping */ + } +.... + if (0 == tep_pid_is_registered(tep, ls_pid)) { + /* Command mapping for ls_pid is not registered */ + } +... + const char *comm = tep_data_comm_from_pid(tep, ls_pid); + if (comm) { + /* Found process name for ls_pid */ + } +... + int pid; + struct cmdline *cmd = tep_data_pid_from_comm(tep, "ls", NULL); + while (cmd) { + pid = tep_cmdline_pid(tep, cmd); + /* Found pid for process "ls" */ + cmd = tep_data_pid_from_comm(tep, "ls", cmd); + } +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +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 diff --git a/tools/lib/traceevent/Documentation/libtraceevent-handle.txt b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt new file mode 100644 index 000000000000..f6dcfad7b264 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt @@ -0,0 +1,77 @@ +libtraceevent(3) +================ + +NAME +---- +tep_alloc,tep_free - Create / destroy trace event parser context. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_handle pass:[*]*tep_alloc*(void); +void *tep_free*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +These are main functions to create and destroy tep_handle - the main structure, representing the trace event parser context. +This context is used as input parameter of all library APIs. + +The _tep_alloc()_ functions allocates and initializes the tep context. It sets its reference counter to 1. + +The _tep_free()_ functions decrements the tep context reference counter by 1. When this counter reaches 0, the context is destroyed. +Before destroying, a full clean up is performed of all internal structures. +The argument _tep_ is pointer to the trace event parser context. + +RETURN VALUE +------------ +_tep_alloc()_ returns pointer to newly created tep_handle structure. A NULL is returned in case there is not enough free memory to allocate it. + +EXAMPLE +------- +[source,c] +-- +#include + +... +struct tep_handle *tep = tep_alloc(); + +... +tep_free(tep); +... +-- +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +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 diff --git a/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt new file mode 100644 index 000000000000..327922e52af4 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-long_size.txt @@ -0,0 +1,75 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_long_size,tep_set_long_size - Get / set the size of of a long integer on the current machine, in bytes + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_); +void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_); +-- + +DESCRIPTION +----------- +The _tep_get_long_size()_ function returns the size of a long integer on the current machine. +The _tep_ argument is trace event parser context. + +The _tep_set_long_size()_ function sets the size of a long integer on the current machine. +The _tep_ argument is trace event parser context. The _long_size_ is the size of a long integer, in bytes. + +RETURN VALUE +------------ +The _tep_get_long_size()_ function returns the size of of a long integer on the current machine, in bytes. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +tep_set_long_size(tep, 4); +... +int long_size = tep_get_long_size(tep); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +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 diff --git a/tools/lib/traceevent/Documentation/libtraceevent-ref.txt b/tools/lib/traceevent/Documentation/libtraceevent-ref.txt new file mode 100644 index 000000000000..ef0b6f0935d0 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-ref.txt @@ -0,0 +1,84 @@ +libtraceevent(3) +================ + +NAME +---- +tep_ref,tep_unref,tep_ref_get - Manage reference counter of trace event parser context. + +SYNOPSIS +-------- +[verse] +-- +*#include * +void *tep_ref*(struct tep_handle pass:[*]_tep_); +void *tep_unref*(struct tep_handle pass:[*]_tep_); +int *tep_ref_get*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +These functions manage the reference counter of trace event parser context. When this counter reaches 0, the context is destroyed. + +The _tep_ref()_ function increments the reference counter of _tep_ by 1. + +The _tep_unref()_ function decrements the reference counter of _tep_ by 1. If this counter reaches 0, the context is destroyed. + +The _tep_ref_get()_ functions gets the current value of _tep_ reference counter. + +RETURN VALUE +------------ +_tep_ref_get()_ returns the value of _tep_ reference counter. If _tep_ is NULL, 0 is returned. + +EXAMPLE +------- +[source,c] +-- +#include + ... +struct tep_handle *tep = tep_alloc(); +if ( 1 != _tep_ref_get(tep)) { + /* Something wrong happened, the counter must be 1 right after its creation */ +} + +... +int ref = tep_ref_get(tep); +tep_ref(tep); +if ( (ref+1) != tep_ref_get(tep)) { + /* Something wrong happened, the counter is not incremented by 1 */ +} +tep_unref(tep); +... +-- + +FILES +----- +[verse] +-- +*event-parse.h* + Header file to include in order to have access to the library APIs. +*-ltraceevent* + Linker switch to add when building a program that uses the library. +-- + +SEE ALSO +-------- +_libtraceevent(3)_, _trace-cmd(1)_ + +AUTHOR +------ +[verse] +-- +*Steven Rostedt* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +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 diff --git a/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt new file mode 100644 index 000000000000..751814985b16 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-set_flag.txt @@ -0,0 +1,94 @@ +libtraceevent(3) +================ + +NAME +---- +tep_set_flag - Set a flag or combination of flags of trace event parser context + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_flag* { + _TEP_NSEC_OUTPUT_, + _TEP_DISABLE_SYS_PLUGINS_, + _TEP_DISABLE_PLUGINS_ +}; +void *tep_set_flag*(struct tep_handle pass:[*]_tep_, int _flag_); +-- + +DESCRIPTION +----------- +[verse] +-- +The _tep_set_flag()_ function sets _flag_ or any combination of flags to _tep_ context. +Flags are defined in *enum tep_flag*: + _TEP_NSEC_OUTPUT_ - print event's timestamp in nano seconds, instead of micro seconds. + _TEP_DISABLE_SYS_PLUGINS_ - disable plugins, located in system's plugin directory. + This directory is defined at library compile time, and usually is + depends on library installation prefix: (install_preffix)/lib/traceevent/plugins + _TEP_DISABLE_PLUGINS_ - disable all library plugins: + - in system's plugin directory + - in directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_ + - in user's home directory, _~/.traceevent/plugins_ + +Note: plugin related flags must me set before calling _tep_load_plugins()_ API. +-- + +RETURN VALUE +------------ +_tep_set_flag()_ functions has no return value. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +/* Set printing of timestamps in nano seconds and disable system plugins */ +tep_set_flag(tep, TEP_NSEC_OUTPUT | TEP_DISABLE_SYS_PLUGINS); +... +/* Disable all library plugins */ +tep_set_flag(tep, TEP_DISABLE_PLUGINS); +... +-- +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* , author of *libtraceevent*. +*Tzvetomir Stoyanov* , author of this man page. +-- +REPORTING BUGS +-------------- +Report bugs to + +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