From patchwork Mon Nov 19 12:54:10 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759751 Return-Path: Received: from mail-eopbgr710056.outbound.protection.outlook.com ([40.107.71.56]:22208 "EHLO NAM05-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXRt (ORCPT ); Mon, 19 Nov 2018 18:17:49 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 01/34] tools/lib/traceevent: Man page for tep_register_trace_clock() Date: Mon, 19 Nov 2018 12:54:10 +0000 Message-ID: <20181119125357.19449-2-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2618 Create man page for tep_register_trace_clock() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-reg_clock.txt | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt new file mode 100644 index 000000000000..60dd81df6b37 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt @@ -0,0 +1,77 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_trace_clock - Registers the clock, used for the timestamp of +the events. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_trace_clock*(struct tep_handle pass:[*]_tep_, const char pass:[*]_trace_clock_); +-- + +DESCRIPTION +----------- +The _tep_register_trace_clock()_ function registers the clock, used for +the timestamps of the events. When an event is recorded, a timestamp is attached +to it. This timestamp comes from a specified clock. Supported clocks can be seen +in tracefs/trace_clock, the selected one is in square brackets. +The _tep_ argument is the trace event parser context. The _trace_clock_ argument +is the name of the clock, the string is copied internally. + +RETURN VALUE +------------ +The _tep_register_trace_clock()_ function returns 0 in case of success. +If there is not enough memory to copy the _trace_clock_ string -1 is returned +and errno is set to ENOMEM. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + if(tep_register_trace_clock(tep, "local") != 0) { + /* Failed to register the clock */ + } +-- + +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 From patchwork Mon Nov 19 12:54:11 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759753 Return-Path: Received: from mail-eopbgr710056.outbound.protection.outlook.com ([40.107.71.56]:22208 "EHLO NAM05-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728877AbeKSXRv (ORCPT ); Mon, 19 Nov 2018 18:17:51 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 02/34] tools/lib/traceevent: Man pages for tep_register_event_handler() and tep_unregister_event_handler() Date: Mon, 19 Nov 2018 12:54:11 +0000 Message-ID: <20181119125357.19449-3-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 5495 Create man pages for tep_register_event_handler() and tep_unregister_event_handler() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-reg_event_handler.txt | 123 ++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt new file mode 100644 index 000000000000..1a9269039f6c --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt @@ -0,0 +1,123 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_event_handler,tep_unregister_event_handler - Register / unregisters +a callback function to parse an event information. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_); +int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_); + +typedef int (*pass:[*]tep_event_handler_func*)(struct trace_seq pass:[*]s, struct tep_record pass:[*]record, struct tep_event pass:[*]event, void pass:[*]context); +-- + +DESCRIPTION +----------- +The _tep_register_event_handler()_ function registers a handler function, +which is going to be called to parse the information for a given event. +The _tep_ argument is the trace event parser context. The _id_ argument is +the id of the event. The _sys_name_ argument is the name of the system, +the event belongs to. The _event_name_ argument is the name of the event. +If _id_ is >= 0, it is used to find the event, otherwise _sys_name_ and +_event_name_ are used. The _func_ is a pointer to the function, which is going +to be called to parse the event information. The _context_ argument is a pointer +to the context data, which will be passed to the _func_. If a handler function +for the same event is already registered, it will be overridden with the new +one. This mechanism allows a developer to override the parsing of a given event. +If for some reason the default print format is not sufficient, the developer +can register a function for an event to be used to parse the data instead. + +The _tep_unregister_event_handler()_ function unregisters the handler function, +previously registered with _tep_register_event_handler()_. The _tep_ argument +is the trace event parser context. The _id_, _sys_name_, _event_name_, _func_, +and _context_ are the same arguments, as when the callback function _func_ was +registered. + +The _tep_event_handler_func_ is the type of the custom event handler +function. The _s_ argument is the trace sequence, it can be used to create a +custom string, describing the event. A _record_ to get the event from is passed +as input parameter and also the _event_ - the handle to the record's event. The +_context_ is custom context, set when the custom event handler is registered. + +RETURN VALUE +------------ +The _tep_register_event_handler()_ function returns 0 in case of success. +If there is not enough memory to complete the registration, +TEP_ERRNO__MEM_ALLOC_FAILED is returned. + +The _tep_unregister_event_handler()_ function returns 0 if _func_ was removed +successful or, -1 if the event was not found. + +The _tep_event_handler_func_ should return -1 in case of an error, or 0 otherwise. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +int custom_event_handler(struct trace_seq *s, struct tep_record *record, + struct tep_event *event, void *context) +{ + trace_seq_printf(s, "kvm_exit event"); + return 0; +} +... + if (tep_register_event_handler(tep, -1, "kvm", "kvm_exit", + custom_event_handler, NULL)) { + /* Failed to register the handler for event "kvm_exit" from "kvm" system */ + } +... + if (tep_unregister_event_handler(pevent, -1, "kvm", "kvm_exit", + custom_event_handler, NULL) != ) { + /* Failed to unregister the handler for event "kvm_exit" from "kvm" system */ + } + +-- + +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 From patchwork Mon Nov 19 12:54:12 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759755 Return-Path: Received: from mail-eopbgr710056.outbound.protection.outlook.com ([40.107.71.56]:22208 "EHLO NAM05-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728890AbeKSXRw (ORCPT ); Mon, 19 Nov 2018 18:17:52 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 03/34] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string() Date: Mon, 19 Nov 2018 12:54:12 +0000 Message-ID: <20181119125357.19449-4-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3417 Create man pages for tep_register_function() and tep_register_print_string() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-reg_funcstr.txt | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt new file mode 100644 index 000000000000..b0e196a1e47b --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt @@ -0,0 +1,89 @@ +libtraceevent(3) +================ + +NAME +---- +tep_register_function, tep_register_print_string - Registers a function / string +with a given address. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_); +int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_); +-- + +DESCRIPTION +----------- +The _tep_register_function()_ function registers a function name with an +address and module. The _tep_ argument is the trace event parser context. The +_name_ is the name of the function, the string is copied internally. The _addr_ +is the start address of the function. The _mod_ is the kernel module +the function may be in (NULL for none). + +The _tep_register_print_string()_ function registers a string by the address +it was stored in the kernel. The _tep_ argument is the trace event parser +context. The _fmt_ is the string to register, it is copied internally. The _addr_ +is the address the string was located at. + +RETURN VALUE +------------ +The _tep_register_function()_ function returns 0 in case of success. In case of +an error -1 is returned, and errno is set to the appropriate error number. + +The _tep_register_print_string()_ function returns 0 in case of success. In case +of an error -1 is returned, and errno is set to the appropriate error number. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... + if (tep_register_function(tep, "my_custom_func", + (unsigned long long) 0x12345678, NULL) != 0) { + /* Failed to register my_custom_func address mapping */ + } +... + if (tep_register_print_string(tep, "print string", + (unsigned long long) 0x87654321, NULL) != 0) { + /* Failed to register "print string" address mapping */ + } +-- +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 From patchwork Mon Nov 19 12:54:13 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759757 Return-Path: Received: from mail-eopbgr710056.outbound.protection.outlook.com ([40.107.71.56]:22208 "EHLO NAM05-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728877AbeKSXRy (ORCPT ); Mon, 19 Nov 2018 18:17:54 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 04/34] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function() Date: Mon, 19 Nov 2018 12:54:13 +0000 Message-ID: <20181119125357.19449-5-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 4804 Create man pages for tep_register_print_function() and tep_unregister_print_function() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../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..fbb2f973f3b0 --- /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 * + +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 +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_. + +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 +#include +... +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* , 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 From patchwork Mon Nov 19 12:54:14 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759759 Return-Path: Received: from mail-eopbgr710056.outbound.protection.outlook.com ([40.107.71.56]:22208 "EHLO NAM05-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728890AbeKSXRz (ORCPT ); Mon, 19 Nov 2018 18:17:55 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 05/34] tools/lib/traceevent: Man page for tep_read_number() Date: Mon, 19 Nov 2018 12:54:14 +0000 Message-ID: <20181119125357.19449-6-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2455 Create man page for tep_read_number() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-endian_read.txt | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt b/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt new file mode 100644 index 000000000000..7f355e439a6e --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt @@ -0,0 +1,76 @@ +libtraceevent(3) +================ + +NAME +---- +tep_read_number - Reads a number from raw data. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +unsigned long long *tep_read_number*(struct tep_handle pass:[*]_tep_, const void pass:[*]_ptr_, int _size_); +-- + +DESCRIPTION +----------- +The _tep_read_number()_ function reads an integer from raw data, taking into +account the endianness of the raw data and the current host. The _tep_ argument +is the trace event parser context. The _ptr_ is a pointer to the raw data, where +the integer is, and the _size_ is the size of the integer. + +RETURN VALUE +------------ +The _tep_read_number()_ function returns the integer in the byte order of +the current host. In case of an error, 0 is returned. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +void process_record(struct tep_record *record) +{ + int data = tep_read_number(tep, record->data, 4); + /* Read the first 4 bytes of the record as integer */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:16 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759795 Return-Path: Received: from mail-eopbgr700074.outbound.protection.outlook.com ([40.107.70.74]:19586 "EHLO NAM04-SN1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXSa (ORCPT ); Mon, 19 Nov 2018 18:18:30 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 06/34] tools/lib/traceevent: Man pages for tep_find_event(), tep_find_event_by_name() and tep_find_event_by_record() Date: Mon, 19 Nov 2018 12:54:16 +0000 Message-ID: <20181119125357.19449-7-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3295 Create man pages for tep_find_event(), tep_find_event_by_name() and tep_find_event_by_record() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-event_find.txt | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt new file mode 100644 index 000000000000..69a91bd21639 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_find.txt @@ -0,0 +1,99 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_event,tep_find_event_by_name,tep_find_event_by_record - Find events by given key. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_); +struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_); +struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_); +-- + +DESCRIPTION +----------- +This set of functions can be used to search for an event, based on a given +criteria. All functions require a pointer to a _tep_, trace event parser context. + +The _tep_find_event()_ function searches for an event by given event _id_. + +The tep_find_event_by_name()_ function searches for an event by given +event _name_, under the system _sys_. If the _sys_ is NULL (not specified), +the first event with _name_ is returned. + +The tep_find_event_by_record()_ function searches for an event from a given +_record_. + +RETURN VALUE +------------ +All these functions return a pointer to the found event, or NULL if there is no +such event. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event; + +event = tep_find_event(tep, 1857); +if (event == NULL) { + /* There is no event with ID 1857 */ +} + +event = tep_find_event_by_name(tep, "kvm", "kvm_exit"); +if (event == NULL) { + /* There is no kvm_exit event, from kvm system */ +} + +void event_from_record(struct tep_record *record) +{ + struct tep_event *event = tep_find_event_by_record(tep, record); + if (event == NULL) { + /* There is no event from given record */ + } +} +... +-- + +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 From patchwork Mon Nov 19 12:54:17 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759767 Return-Path: Received: from mail-eopbgr800073.outbound.protection.outlook.com ([40.107.80.73]:62612 "EHLO NAM03-DM3-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728957AbeKSXSF (ORCPT ); Mon, 19 Nov 2018 18:18:05 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 07/34] tools/lib/traceevent: Man page for tep_list_events() Date: Mon, 19 Nov 2018 12:54:17 +0000 Message-ID: <20181119125357.19449-8-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2924 Create man page for tep_list_events() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-event_list.txt | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt new file mode 100644 index 000000000000..f443d8648a34 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_list.txt @@ -0,0 +1,94 @@ +libtraceevent(3) +================ + +NAME +---- +tep_list_events - Get list of events, sorted by given criteria. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_event_sort_type* { + _TEP_EVENT_SORT_ID_, + _TEP_EVENT_SORT_NAME_, + _TEP_EVENT_SORT_SYSTEM_, +}; + +struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_); +-- + +DESCRIPTION +----------- +The _tep_list_events()_ function returns an array of pointers to the events, +sorted by the _sort_type_ criteria. The last element of the array is NULL. +The returned memory must not be freed, it is managed by the library. +The _tep_ argument is trace event parser context. The _sort_type_ argument is +the required sort criteria: +[verse] +-- + _TEP_EVENT_SORT_ID_ - sort by the event ID. + _TEP_EVENT_SORT_NAME_ - sort by the event (name, system, id) triplet. + _TEP_EVENT_SORT_SYSTEM_ - sort by the event (system, name, id) triplet. +-- + +RETURN VALUE +------------ +The _tep_list_events()_ function returns an array of pointers to events. +In case of an error, NULL is returned. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +int i=0; +struct tep_event_format **events = tep_list_events(tep, TEP_EVENT_SORT_ID); +if (events == NULL) { + /* Failed to get the events, sorted by ID */ +} else { + while(events[i]) { + /* walk through the list of the events, sorted by the ID */ + i++; + } +} +... +-- + +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 From patchwork Mon Nov 19 12:54:18 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759815 Return-Path: Received: from mail-eopbgr800073.outbound.protection.outlook.com ([40.107.80.73]:62612 "EHLO NAM03-DM3-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728933AbeKSXS6 (ORCPT ); Mon, 19 Nov 2018 18:18:58 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 08/34] tools/lib/traceevent: Man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time() Date: Mon, 19 Nov 2018 12:54:18 +0000 Message-ID: <20181119125357.19449-9-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 5106 Create man pages for tep_print_event(), tep_print_event_data(), tep_event_info(), tep_print_event_task() and tep_print_event_time() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-event_print.txt | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt new file mode 100644 index 000000000000..f5af35d0d409 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-event_print.txt @@ -0,0 +1,126 @@ +libtraceevent(3) +================ + +NAME +---- +tep_print_event,tep_print_event_data,tep_event_info,tep_print_event_task,tep_print_event_time - Parses the data into the print format. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *tep_print_event_time*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]record, bool _use_trace_clock_); +void *tep_print_event_task*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); +void *tep_event_info*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); +void *tep_print_event_data*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_); +void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, bool _use_trace_clock_); +-- + +DESCRIPTION +----------- +The _tep_print_event_time()_ function prints the timestamp of the _record_ using +the given _event_ information as trace sequence in _s_. The _tep_ argument is +trace event parser context. The _use_trace_clock_ argument indicates if +the tep->trace_clock should be used for parsing the timestamp. + +The _tep_print_event_task()_ function prints the task command, pid and CPU of +the _record_ using the given _event_ information as trace sequence in _s_. +The _tep_ argument is trace event parser context. + +The _tep_event_info()_ function parses the raw data from the _record_ using +the given _event_ information and writes the print format as trace sequence in +_s_. + +The _tep_print_event_data()_ function writes the _event_ name as trace +sequence in _s_ and calls _tep_event_info()_ to parse and write the raw data +from the _record_. The _tep_ argument is trace event parser context. + +The _tep_print_event()_ function prints the _record_ information as trace +sequence in _s_. It finds the corresponding event and calls +_tep_print_event_task()_,_tep_print_event_time()_ and _tep_print_event_data()_ +to parse and print the information. +The _tep_ argument is trace event parser context. The _use_trace_clock_ +argument indicates if the tep->trace_clock should be used for parsing +the timestamp. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +struct tep_handle *tep = tep_alloc(); +... +void print_my_event(struct tep_record *record) +{ + struct tep_event *event; + + /* print all event information */ + trace_seq_reset(&seq); + tep_print_event(tep, &seq, record, TRUE); + + event = tep_find_event_by_record(tep, record); + + if (event != NULL) { + /* print event timestamp */ + trace_seq_reset(&seq); + tep_print_event_time(tep, &seq, event, record, TRUE); + + /* print event task information */ + trace_seq_reset(&seq); + tep_print_event_task(tep, &seq, event, record); + + /* print event name and raw data */ + trace_seq_reset(&seq); + tep_print_event_data(tep, &seq, event, record); + + /* print event raw data */ + trace_seq_reset(&seq); + tep_event_info(&seq, event, record); + } +} +... +-- + +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 From patchwork Mon Nov 19 12:54:19 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759797 Return-Path: Received: from mail-eopbgr700074.outbound.protection.outlook.com ([40.107.70.74]:19586 "EHLO NAM04-SN1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728828AbeKSXSc (ORCPT ); Mon, 19 Nov 2018 18:18:32 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 09/34] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count() Date: Mon, 19 Nov 2018 12:54:19 +0000 Message-ID: <20181119125357.19449-10-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2809 Create man pages for tep_get_first_event() and tep_get_events_count() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-events.txt | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-events.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-events.txt b/tools/lib/traceevent/Documentation/libtraceevent-events.txt new file mode 100644 index 000000000000..169bb3240633 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-events.txt @@ -0,0 +1,87 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_first_event,tep_get_events_count - Access events. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_event pass:[*]*tep_get_first_event*(struct tep_handle pass:[*]_tep_); +int *tep_get_events_count*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +The _tep_get_first_event()_ function returns a pointer to the first event. As events are +stored in an array, this function returns the pointer to the beginning +of the array. The _tep_ argument is trace event parser context. + +The _tep_get_events_count()_ function returns the number of the events +in the array. The _tep_ argument is trace event parser context. + +RETURN VALUE +------------ +The _tep_get_first_event()_ returns a pointer to the first event. NULL is +returned in case of error, or in case there are no events. + +The _tep_get_events_count()_ returns the number of the events. 0 is +returned in case of error, or in case there are no events. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +int i,count = tep_get_events_count(tep); +struct tep_event *event, *events = tep_get_first_event(tep); + +if (events == NULL) { + /* There are no events */ +} else { + for (i=0; i, 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 From patchwork Mon Nov 19 12:54:20 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759799 Return-Path: Received: from mail-eopbgr700074.outbound.protection.outlook.com ([40.107.70.74]:19586 "EHLO NAM04-SN1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXSg (ORCPT ); Mon, 19 Nov 2018 18:18:36 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 10/34] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field() Date: Mon, 19 Nov 2018 12:54:20 +0000 Message-ID: <20181119125357.19449-11-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3288 Create man pages for tep_find_common_field(), tep_find_field() and tep_find_any_field() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_find.txt | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt new file mode 100644 index 000000000000..a5afe260285a --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_find.txt @@ -0,0 +1,98 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_common_field,tep_find_field,tep_find_any_field - Search for a field in an event. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_); +struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_); +struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_); +-- + +DESCRIPTION +----------- +These functions search for a field with given name in an event. + +The _tep_find_common_field()_ function searches for a common field with _name_ +in the _event_. + +The _tep_find_field()_ function searches for an event specific field with +_name_ in the _event_. + +The _tep_find_any_field()_ function searches for any field with _name_ in the +_event_. + +RETURN VALUE +------------ +The _tep_find_common_field(), _tep_find_field()_ and _tep_find_any_field()_ +functions return a pointer to the found field, or NULL in case there is no field +with the requested name. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start"); +... + struct tep_format_field *field; + + field = tep_find_common_field(event, "common_pid"); + if (field == NULL) { + /* Cannot find "common_pid" common field in the event */ + } + + field = tep_find_field(event, "softexpires"); + if (field == NULL) { + /* Cannot find "softexpires" event specific field in the event */ + } + + field = tep_find_any_field(event, "mode"); + if (field == NULL) { + /* Cannot find "mode" field in the event */ + } +... +-- + +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 From patchwork Mon Nov 19 12:54:21 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759761 Return-Path: Received: from mail-eopbgr810089.outbound.protection.outlook.com ([40.107.81.89]:53856 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728890AbeKSXR4 (ORCPT ); Mon, 19 Nov 2018 18:17:56 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 11/34] tools/lib/traceevent: Man pages tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw() Date: Mon, 19 Nov 2018 12:54:21 +0000 Message-ID: <20181119125357.19449-12-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 4916 Create man pages for tep_get_any_field_val(), tep_get_common_field_val(), tep_get_field_val() and tep_get_field_raw() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_get_val.txt | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt new file mode 100644 index 000000000000..4d2b99bf342f --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt @@ -0,0 +1,117 @@ +libtraceevent(3) +================ + +NAME +---- +tep_get_any_field_val,tep_get_common_field_val,tep_get_field_val,tep_get_field_raw - Get value of a field. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); +int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); +int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_); +void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_); +-- + +DESCRIPTION +----------- +These functions can be used to find a field and retrieve its value. + +The _tep_get_any_field_val()_ function searches in the _record_ for a filed with +_name_, part of the _event_. If the field is found, its value is stored in _val_. +In case of an error, an error string is printed into _s_, if _err_ is not 0. + +The _tep_get_common_field_val()_ function does the same as +_tep_get_any_field_val()_, but searches only in the common fields. + +The _tep_get_field_val()_ function does the same as +_tep_get_any_field_val()_, but searches only in the event specific fields. + +The _tep_get_field_raw()_ function searches in the _record_ for a filed with _name_, +part of the _event_. If the field is found, a pointer to its raw data is returned. +The size of the data is stored in _len_. In case of an error, an error string +is printed into _s_, if _err_ is not 0. + +RETURN VALUE +------------ +The _tep_get_any_field_val()_, _tep_get_common_field_val()_ and +_tep_get_field_val()_ functions return 0 on success, or -1 in case of an error. + +The _tep_get_field_raw()_ function returns a pointer to field's raw data, and +places the length of this data in _len_. In case of an error NULL is returned. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit"); +... +void process_record(struct tep_record *record) +{ + int len; + char *comm; + struct tep_event_format *event; + unsigned long long val; + + event = tep_find_event_by_record(pevent, record); + if (event != NULL) { + if (tep_get_common_field_val(NULL, event, "common_type", record, &val, 0) == 0) { + /* Got the value of common type field */ + } + if (tep_get_field_val(NULL, event, "pid", record, &val, 0) == 0) { + /* Got the value of pid specific field */ + } + comm = tep_get_field_raw(NULL, event, "comm", record, &len, 0); + if (comm != NULL) { + /* Got a pointer to the comm event specific field */ + } + } +} +-- + +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 From patchwork Mon Nov 19 12:54:22 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759773 Return-Path: Received: from mail-eopbgr810089.outbound.protection.outlook.com ([40.107.81.89]:53856 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728933AbeKSXR5 (ORCPT ); Mon, 19 Nov 2018 18:17:57 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 12/34] tools/lib/traceevent: Man pages for tep_print_field(), tep_print_fields(), tep_print_num_field() and tep_print_func_field() Date: Mon, 19 Nov 2018 12:54:22 +0000 Message-ID: <20181119125357.19449-13-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 6354 Create man pages for tep_print_field(), tep_print_fields(), tep_print_num_field() and tep_print_func_field() as part of the libtraceevent APIs. Updated description of functions in event-parse.c Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_print.txt | 120 ++++++++++++++++++ tools/lib/traceevent/event-parse.c | 4 +- 2 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt new file mode 100644 index 000000000000..3a9372ba1102 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_print.txt @@ -0,0 +1,120 @@ +libtraceevent(3) +================ + +NAME +---- +tep_print_field,tep_print_fields,tep_print_num_field,tep_print_func_field - Print the field content. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *tep_print_field*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, struct tep_format_field pass:[*]_field_); +void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_); +int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_); +int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_); +-- + +DESCRIPTION +----------- +These functions print recorded field's data, according to the field's type. + +The _tep_print_field()_ function extracts from the recorded raw _data_ value of +the _field_ and prints it into _s_, according to the field type. + +The _tep_print_fields()_ prints recorded values of all _event_'s fields. It +iterates all fileds of the _event_, and calls _tep_print_field()_ for each of +them. + +The _tep_print_num_field()_ function prints a numeric field with given format +string. A search is performed in the _event_ for a field with _name_. If such +field is found, its value is extracted from the _record_ and is printed in the +_s_, according to the given format string _fmt_. If the argument _err_ is non-zero, +and an error occures - it is printed in the _s_. + +The _tep_print_func_field()_ function prints a function field with given format +string. A search is performed in the _event_ for a field with _name_. If such +field is found, its value is extracted from the _record_. The value is assumed +to be a function address, and a search is perform to find the name of this +function. The function name (if found) and its address are printed in the _s_, +according to the given format string _fmt_. If the argument _err_ is non-zero, +and an error occures - it is printed in _s_. + +RETURN VALUE +------------ +The _tep_print_num_field()_ and _tep_print_func_field()_ functions return 1 +on success, -1 in case of an error or 0 if the print buffer _s_ is full. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct trace_seq seq; +trace_seq_init(&seq); +struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start"); +... +void process_record(struct tep_record *record) +{ + struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid"); + + trace_seq_reset(&seq); + + /* Print the value of "common_pid" */ + tep_print_field(&seq, record->data, field_pid); + + /* Print all fields of the "hrtimer_start" event */ + tep_print_fields(&seq, record->data, record->size, event); + + /* Print the value of "expires" field with custom format string */ + tep_print_num_field(&seq, " timer expires in %llu ", event, "expires", record, 0); + + /* Print the address and the name of "function" field with custom format string */ + tep_print_func_field(&seq, " timer function is %s ", event, "function", record, 0); + } + ... +-- + +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 diff --git a/tools/lib/traceevent/event-parse.c b/tools/lib/traceevent/event-parse.c index 4e768357a30d..966c4b7fd163 100644 --- a/tools/lib/traceevent/event-parse.c +++ b/tools/lib/traceevent/event-parse.c @@ -6402,7 +6402,7 @@ int tep_get_any_field_val(struct trace_seq *s, struct tep_event *event, * @record: The record with the field name. * @err: print default error if failed. * - * Returns: 0 on success, -1 field not found, or 1 if buffer is full. + * Returns: 1 on success, -1 field not found, or 0 if buffer is full. */ int tep_print_num_field(struct trace_seq *s, const char *fmt, struct tep_event *event, const char *name, @@ -6434,7 +6434,7 @@ int tep_print_num_field(struct trace_seq *s, const char *fmt, * @record: The record with the field name. * @err: print default error if failed. * - * Returns: 0 on success, -1 field not found, or 1 if buffer is full. + * Returns: 1 on success, -1 field not found, or 0 if buffer is full. */ int tep_print_func_field(struct trace_seq *s, const char *fmt, struct tep_event *event, const char *name, From patchwork Mon Nov 19 12:54:23 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759777 Return-Path: Received: from mail-eopbgr810089.outbound.protection.outlook.com ([40.107.81.89]:53856 "EHLO NAM01-BY2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728818AbeKSXR7 (ORCPT ); Mon, 19 Nov 2018 18:17:59 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 13/34] tools/lib/traceevent: Man page for tep_read_number_field() Date: Mon, 19 Nov 2018 12:54:23 +0000 Message-ID: <20181119125357.19449-14-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2582 Create man page for tep_read_number_field() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-field_read.txt | 80 +++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt b/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt new file mode 100644 index 000000000000..8e4ca26b73aa --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-field_read.txt @@ -0,0 +1,80 @@ +libtraceevent(3) +================ + +NAME +---- +tep_read_number_field - Reads a number from a raw data. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_read_number_field*(struct tep_format_field pass:[*]_field_, const void pass:[*]_data_, unsigned long long pass:[*]_value_); +-- + +DESCRIPTION +----------- +The _tep_read_number_field()_ function reads the value of the _field_ from the +raw _data_ and stores it in the _value_. The function sets the _value_ according +to the endianness of the raw data and the current machine. + +RETURN VALUE +------------ +The _tep_read_number_field()_ function retunrs 0 in case of success, or -1 in +case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event *event = tep_find_event_by_name(tep, "timer", "hrtimer_start"); +... +void process_record(struct tep_record *record) +{ + unsigned long long pid; + struct tep_format_field *field_pid = tep_find_common_field(event, "common_pid"); + + if (tep_read_number_field(field_pid, record->data, &pid) != 0) { + /* Failed to get "common_pid" value */ + } +} +... +-- +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 From patchwork Mon Nov 19 12:54:25 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759801 Return-Path: Received: from mail-eopbgr700074.outbound.protection.outlook.com ([40.107.70.74]:19586 "EHLO NAM04-SN1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXSj (ORCPT ); Mon, 19 Nov 2018 18:18:39 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 14/34] tools/lib/traceevent: Man pages for tep_event_common_fields() and tep_event_fields() Date: Mon, 19 Nov 2018 12:54:25 +0000 Message-ID: <20181119125357.19449-15-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3181 Create man pages for tep_event_common_fields() and tep_event_fields() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-fields.txt | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-fields.txt b/tools/lib/traceevent/Documentation/libtraceevent-fields.txt new file mode 100644 index 000000000000..45e1e05cbfb2 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-fields.txt @@ -0,0 +1,99 @@ +libtraceevent(3) +================ + +NAME +---- +tep_event_common_fields,tep_event_fields - Get a list of fields for an event. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_format_field pass:[*]pass:[*]*tep_event_common_fields*(struct tep_event pass:[*]_event_); +struct tep_format_field pass:[*]pass:[*]*tep_event_fields*(struct tep_event pass:[*]_event_); +-- + +DESCRIPTION +----------- +The _tep_event_common_fields()_ function returns an array of pointers to common +fields for the _event_. The array is allocated in the function and must be freed +by free(). The last element of the array is NULL. + +The _tep_event_fields()_ function returns an array of pointers to event specific +fields for the _event_. The array is allocated in the function and must be freed +by free(). The last element of the array is NULL. + +RETURN VALUE +------------ +Both _tep_event_common_fields()_ and _tep_event_fields()_ functions return +an array of pointers to tep_format_field structures in case of success, or +NULL in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +int i; +struct tep_format_field **fields; +struct tep_event *event = tep_find_event_by_name(tep, "kvm", "kvm_exit"); +if (event != NULL) { + fields = tep_event_common_fields(event); + if (fields != NULL) { + i = 0; + while (fields[i]) { + /* walk through the list of the common fields of the kvm_exit event */ + i++; + } + free(fields); + } + fields = tep_event_fields(event); + if (fields != NULL) { + i = 0; + while (fields[i]) { + /* walk through the list of the event specific fields of the kvm_exit event */ + i++; + } + free(fields); + } +} +... +-- + +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 From patchwork Mon Nov 19 12:54:26 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759803 Return-Path: Received: from mail-eopbgr700074.outbound.protection.outlook.com ([40.107.70.74]:19586 "EHLO NAM04-SN1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728922AbeKSXSk (ORCPT ); Mon, 19 Nov 2018 18:18:40 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 15/34] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset() Date: Mon, 19 Nov 2018 12:54:26 +0000 Message-ID: <20181119125357.19449-16-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2644 Create man pages tep_filter_alloc(), tep_filter_free() and tep_filter_reset() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-filter.txt | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt new file mode 100644 index 000000000000..8b51f246b402 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt @@ -0,0 +1,85 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_alloc,tep_filter_free,tep_filter_reset - Create / free / reset an event filter. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_); +void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_); +void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_); +-- + +DESCRIPTION +----------- +The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument +is the trace event parser context. + +The _tep_filter_free()_ function frees an event filter and all resources that it +had used. + +The _tep_filter_reset()_ function removes all rules from an event filter and +resets it. + +RETURN VALUE +------------ +The _tep_filter_alloc()_ function returns a pointer to the newly created event +filter, or NULL in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event_filter *filter = tep_filter_alloc(tep); +if (filter == NULL) { + /* Failed to create the filter */ +} +... +tep_filter_reset(filter); +... +tep_filter_free(filter); +... +-- + +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 From patchwork Mon Nov 19 12:54:27 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759805 Return-Path: Received: from mail-eopbgr700074.outbound.protection.outlook.com ([40.107.70.74]:19586 "EHLO NAM04-SN1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXSk (ORCPT ); Mon, 19 Nov 2018 18:18:40 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 16/34] tools/lib/traceevent: Man page for tep_filter_add_filter_str() Date: Mon, 19 Nov 2018 12:54:27 +0000 Message-ID: <20181119125357.19449-17-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2582 Create man page for tep_filter_add_filter_str() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_add.txt | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt new file mode 100644 index 000000000000..37208be468f8 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_add_filter_str - Adds a new rule to a filter. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_); +-- + +DESCRIPTION +----------- +The _tep_filter_add_filter_str()_ function adds a new rule to the _filter_. The +_filter_str_ argument is the filter string, that contains the rule. + +RETURN VALUE +------------ +The _tep_filter_add_filter_str()_ function returns 0 if the rule was +successfully added or a negative error code. Use _tep_filter_strerror()_ to see +actual error message in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct tep_event_filter *filter = tep_filter_alloc(tep); +... +int ret; +char errstr[200]; +ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1"); +if(ret < 0) { + tep_filter_strerror(filter, ret, errstr, sizeof(errstr)); + /* Failed to add a new rule to the filter, the error string is in errstr */ +} +... +-- + +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)_, _tep_filter_strerror(3)_ + +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 From patchwork Mon Nov 19 12:54:28 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759817 Return-Path: Received: from mail-eopbgr800073.outbound.protection.outlook.com ([40.107.80.73]:62612 "EHLO NAM03-DM3-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728843AbeKSXS7 (ORCPT ); Mon, 19 Nov 2018 18:18:59 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 17/34] tools/lib/traceevent: Man page for tep_filter_strerror() Date: Mon, 19 Nov 2018 12:54:28 +0000 Message-ID: <20181119125357.19449-18-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2553 Create man page for tep_filter_strerror() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_error.txt | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt new file mode 100644 index 000000000000..64e3aa809838 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_strerror - Fills the filter error message in a buffer. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_); +-- + +DESCRIPTION +----------- +The _tep_filter_strerror()_ function copies the _filter_ error buffer into the +given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_ +is copied a string, describing the error _err_. + +RETURN VALUE +------------ +The _tep_filter_strerror()_ function returns 0 if message was filled +successfully, or -1 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct tep_event_filter *filter = tep_filter_alloc(tep); +... +int ret; +char errstr[200]; +ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1"); +if(ret < 0) { + tep_filter_strerror(filter, ret, errstr, sizeof(errstr)); + /* Failed to add a new rule to the filter, the error string is in errstr */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54: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: 10759765 Return-Path: Received: from mail-eopbgr790045.outbound.protection.outlook.com ([40.107.79.45]:56480 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728933AbeKSXSE (ORCPT ); Mon, 19 Nov 2018 18:18:04 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 18/34] tools/lib/traceevent: Man pages for tep_event_filtered() and tep_filter_remove_event() Date: Mon, 19 Nov 2018 12:54:29 +0000 Message-ID: <20181119125357.19449-19-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2646 Create man pages for tep_event_filtered() and tep_filter_remove_event() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_event.txt | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt new file mode 100644 index 000000000000..8b45dd765e02 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt @@ -0,0 +1,84 @@ +libtraceevent(3) +================ + +NAME +---- +tep_event_filtered,tep_filter_remove_event - Checks / removes a filter on an event. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_); +int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_); +-- + +DESCRIPTION +----------- +The _tep_event_filtered()_ function checks if the event with _event_id_ has +_filter_. + +The _tep_filter_remove_event()_ function removes a _filter_ for an event with +_event_id_. + +RETURN VALUE +------------ +The _tep_event_filtered()_ function returns 1 if the filter is found for given +event, or 0 otherwise. + +The _tep_filter_remove_event()_ function returns 1 if the vent was removed, or +0 if the event was not found. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct tep_event_filter *filter = tep_filter_alloc(tep); +... +if (tep_event_filtered(filter, 1857) == 1) { + /* Event 1857 has filter */ +} + +if (tep_filter_remove_event(filter, 1857) == 1) { + /* Event 1857 was removed from the filter */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:30 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759769 Return-Path: Received: from mail-eopbgr790045.outbound.protection.outlook.com ([40.107.79.45]:56480 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728958AbeKSXSH (ORCPT ); Mon, 19 Nov 2018 18:18:07 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 19/34] tools/lib/traceevent: Man page for tep_filter_match() Date: Mon, 19 Nov 2018 12:54:30 +0000 Message-ID: <20181119125357.19449-20-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2973 Create man page for tep_filter_match() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_match.txt | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt new file mode 100644 index 000000000000..61c81d36c54d --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt @@ -0,0 +1,96 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_match - Tests if a record matches a filter. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_); +-- + +DESCRIPTION +----------- +The _tep_filter_match()_ function tests if a _record_ matches given _filter_. + +RETURN VALUE +------------ +The _tep_filter_match()_ function returns _tep_errno_, according to the result: +[verse] +-- +_pass:[TEP_ERRNO__FILTER_MATCH]_ - filter found for event, the record matches. +_pass:[TEP_ERRNO__FILTER_MISS]_ - filter found for event, the record does not match. +_pass:[TEP_ERRNO__FILTER_NOT_FOUND]_ - no filter found for record's event. +_pass:[TEP_ERRNO__NO_FILTER]_ - no rules in the filter. +-- +or any other _tep_errno_, if an error occurred during the test. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct tep_event_filter *filter = tep_filter_alloc(tep); +... +void process_record(struct tep_record *record) +{ + switch (tep_filter_match(filter, record)) { + case TEP_ERRNO__FILTER_MATCH: + /* The filter matches the record */ + break; + case TEP_ERRNO__FILTER_MISS: + /* The filter does not match the record */ + break; + case TEP_ERRNO__FILTER_NOT_FOUND: + /* No filter found for record's event */ + break; + case TEP_ERRNO__NO_FILTER: + /* There are no rules in the filter */ + break + default: + /* An error occurred during the test */ + break; + } +} +... +-- + +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 From patchwork Mon Nov 19 12:54:31 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759771 Return-Path: Received: from mail-eopbgr790045.outbound.protection.outlook.com ([40.107.79.45]:56480 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728882AbeKSXSI (ORCPT ); Mon, 19 Nov 2018 18:18:08 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 20/34] tools/lib/traceevent: Man pages for tep_filter_copy() and tep_filter_compare() Date: Mon, 19 Nov 2018 12:54:31 +0000 Message-ID: <20181119125357.19449-21-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2714 Create man pages for tep_filter_copy() and tep_filter_compare() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_oper.txt | 84 +++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt new file mode 100644 index 000000000000..5ddae5819a99 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt @@ -0,0 +1,84 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_copy,tep_filter_compare - Copy / compare operations with event filters. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_); +int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_); +-- + +DESCRIPTION +----------- +The _tep_filter_copy()_ function copies a _source_ filter into a _dest_ filter. + +The _tep_filter_compare()_ function compares two filers - _filter1_ and _filter2_. + +RETURN VALUE +------------ +The _tep_filter_copy()_ function returns 0 on success or -1 if not all rules + were copied. + +The _tep_filter_compare()_ function returns 1 if the two filters hold the same +content, or 0 if they do not. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_event_filter *filter1 = tep_filter_alloc(tep); +struct tep_event_filter *filter2 = tep_filter_alloc(tep); +... +if (tep_filter_copy(filter1, filter2) != 0) { + /* Failed to copy filter2 in filter1 */ +} +... +if (tep_filter_compare(filter1, filter2) != 1) { + /* Both filters are different */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:32 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759783 Return-Path: Received: from mail-eopbgr790045.outbound.protection.outlook.com ([40.107.79.45]:56480 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728958AbeKSXSV (ORCPT ); Mon, 19 Nov 2018 18:18:21 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 21/34] tools/lib/traceevent: Man page for tep_filter_make_string() Date: Mon, 19 Nov 2018 12:54:32 +0000 Message-ID: <20181119125357.19449-22-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2303 Create man page for tep_filter_make_string() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_show.txt | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt new file mode 100644 index 000000000000..889b9328f87f --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt @@ -0,0 +1,75 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_make_string - Returns a string showing the filter. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_); +-- + +DESCRIPTION +----------- +The _tep_filter_make_string()_ function constructs a string, displaying +the _filter_ contents for given _event_id_. + +RETURN VALUE +------------ +The _tep_filter_make_string()_ function returns a string, which must be freed +with free(), or NULL in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct tep_event_filter *filter = tep_filter_alloc(tep); +... +char *fstring = tep_filter_make_string(filter, 352); +if (fstring != NULL) { + /* The filter for event 352 is in fstring */ + free(fstring); +} +... +-- + +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 From patchwork Mon Nov 19 12:54:33 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759775 Return-Path: Received: from mail-eopbgr790085.outbound.protection.outlook.com ([40.107.79.85]:11680 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728882AbeKSXST (ORCPT ); Mon, 19 Nov 2018 18:18:19 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 22/34] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial() Date: Mon, 19 Nov 2018 12:54:33 +0000 Message-ID: <20181119125357.19449-23-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 4031 Create man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-filter_trivial.txt | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt new file mode 100644 index 000000000000..8afd50b29269 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt @@ -0,0 +1,112 @@ +libtraceevent(3) +================ + +NAME +---- +tep_filter_event_has_trivial,tep_update_trivial,tep_filter_clear_trivial - Check / update / clear trivial rules of given filter. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *tep_filter_trivial_type* { + _TEP_FILTER_TRIVIAL_FALSE_, + _TEP_FILTER_TRIVIAL_TRUE_, + _TEP_FILTER_TRIVIAL_BOTH_, +}; + +int *tep_filter_event_has_trivial*(struct tep_event_filter pass:[*]_filter_, int _event_id_, enum tep_filter_trivial_type _type_); +int *tep_update_trivial*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_, enum tep_filter_trivial_type _type_); +int *tep_filter_clear_trivial*(struct tep_event_filter pass:[*]_filter_, enum tep_filter_trivial_type _type_); +-- + +DESCRIPTION +----------- +The _tep_filter_event_has_trivial()_ function checks if the event with +_event_id_ contains a trivial _filter_ of _type_. + +The _tep_update_trivial()_ function updates the trivial rules with the given +filter. It scans _dest_ for trivial events matching _type_ to replace with +the _source_. + +The _tep_filter_clear_trivial()_ function clears TRUE and FALSE rules. +It removes rules in the _filter_ that only contain a given _type_ boolean arg. + +The trivial _type_, used as argument of these functions can be: +[verse] +-- + _TEP_FILTER_TRIVIAL_FALSE_ - TRUE + _TEP_FILTER_TRIVIAL_TRUE_ - FALSE + _TEP_FILTER_TRIVIAL_BOTH_ - TRUE or FALSE + +-- + +RETURN VALUE +------------ +The _tep_filter_event_has_trivial()_ function returns 1 if the event contains +a matching trivial type, otherwise 0. + +The _tep_update_trivial()_ function returns 0 on success, or -1 if there was +a problem updating, but events may have still been updated on error. + +The _tep_filter_clear_trivial()_ function returns 0 on success, or -1 if there +was a problem. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +struct tep_event_filter *filter1 = tep_filter_alloc(tep); +struct tep_event_filter *filter2 = tep_filter_alloc(tep); +... +if (tep_filter_event_has_trivial(filter1, 1857,TEP_FILTER_TRIVIAL_FALSE) == 0) { + /* There are FALSE rules in filer1 for the event 1857 */ +} + +if (tep_update_trivial(filter1, filter2, TEP_FILTER_TRIVIAL_TRUE) != 0) { + /* Failed to update TRUE trivial rules of filter1 with filter2 */ +} + +if (tep_filter_clear_trivial(filter, TEP_FILTER_TRIVIAL_BOTH) == 0) { + /* Failed to clear TRUE and FALSE trivial rules of filter1 */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:34 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759779 Return-Path: Received: from mail-eopbgr790085.outbound.protection.outlook.com ([40.107.79.85]:11680 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728990AbeKSXST (ORCPT ); Mon, 19 Nov 2018 18:18:19 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 23/34] tools/lib/traceevent: Man pages for tep_find_function() and tep_find_function_address() Date: Mon, 19 Nov 2018 12:54:34 +0000 Message-ID: <20181119125357.19449-24-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3134 Create man pages for tep_find_function() and tep_find_function_address() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-func_find.txt | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt new file mode 100644 index 000000000000..3826269bde6f --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-func_find.txt @@ -0,0 +1,88 @@ +libtraceevent(3) +================ + +NAME +---- +tep_find_function,tep_find_function_address - Find function name / start address. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); +unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_); +-- + +DESCRIPTION +----------- +These functions can be used to find function name and start address, by given +address. The given address does not have to be exact, it will select the function +that would contain it. + +The _tep_find_function()_ function returns the function name, which contains the +given address _addr_. The _tep_ argument is the trace event parser context. + +The _tep_find_function_address()_ function returns the function start address, +by given address _addr_. The _addr_ does not have to be exact, it will select the function +that would contain it. The _tep_ argument is the trace event parser context. + +RETURN VALUE +------------ +The _tep_find_function()_ function returns the function name, or NULL in case +it cannot be found. + +The _tep_find_function_address()_ function returns the function start address, +or 0 in case it cannot be found. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +void show_function( unsigned long long addr) +{ + const char *fname = tep_find_function(tep, addr); + unsigned long long fstart = tep_find_function_address(tep, addr); + + /* addr is in function named fname, starting at fstart address, at offset (addr - fstart) */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:35 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759781 Return-Path: Received: from mail-eopbgr790085.outbound.protection.outlook.com ([40.107.79.85]:11680 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728886AbeKSXSU (ORCPT ); Mon, 19 Nov 2018 18:18:20 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 24/34] tools/lib/traceevent: Man pages for tep_set_function_resolver() and tep_reset_function_resolver() Date: Mon, 19 Nov 2018 12:54:35 +0000 Message-ID: <20181119125357.19449-25-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3497 Create man pages for tep_set_function_resolver() and tep_reset_function_resolver() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-func_resolve.txt | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt b/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt new file mode 100644 index 000000000000..4965cc6c79dc --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt @@ -0,0 +1,96 @@ +libtraceevent(3) +================ + +NAME +---- +tep_set_function_resolver,tep_reset_function_resolver - Set / reset an alternative function resolver + +SYNOPSIS +-------- +[verse] +-- +*#include * + +typedef char pass:[*](*tep_func_resolver_t*)(void pass:[*]_priv_, unsigned long long pass:[*]_addrp_, char pass:[**]_modp_); + +int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_); +void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +Some tools may have already a way to resolve the kernel functions. These APIs +allow them to keep using it instead of duplicating all the entries inside. + +The _tep_set_function_resolver()_ function registers _func_ as an alternative +kernel functions resolver. The _tep_ argument is trace event parser context. +The _priv_ argument is a custom context of the _func_ function. + +The _tep_reset_function_resolver()_ function resets the kernel functions +resolver to the default function. The _tep_ argument is trace event parser +context. + +The _tep_func_resolver_t_ type is the prototype of the alternative kernel +functions resolver. This function receives a pointer to its custom context +(set with the _tep_set_function_resolver()_ call ) and the address of a kernel +function, which has to be resolved. In case of success, it should return +the name of the function and its module (if any) in _modp_. + +RETURN VALUE +------------ +The _tep_set_function_resolver()_ function returns 0 in case of success, or -1 +in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char *my_resolve_kernel_addr(void *context, unsigned long long *addrp, char **modp) +{ + return NULL; +} +... + if (tep_set_function_resolver(tep, my_resolve_kernel_addr, NULL) != 0) { + /* failed to register my_resolve_kernel_addr */ + } +... + tep_reset_function_resolver(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 From patchwork Mon Nov 19 12:54:36 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759785 Return-Path: Received: from mail-eopbgr790085.outbound.protection.outlook.com ([40.107.79.85]:11680 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728990AbeKSXSX (ORCPT ); Mon, 19 Nov 2018 18:18:23 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 25/34] tools/lib/traceevent: Man pages for tep_parse_event() and tep_parse_format() Date: Mon, 19 Nov 2018 12:54:36 +0000 Message-ID: <20181119125357.19449-26-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3271 Create man pages for tep_parse_event() and tep_parse_format() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-parse_event.txt | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt b/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt new file mode 100644 index 000000000000..ceb41cdd6514 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt @@ -0,0 +1,90 @@ +libtraceevent(3) +================ + +NAME +---- +tep_parse_event,tep_parse_format - Parse the event format information + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum tep_errno *tep_parse_event*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_); +enum tep_errno *tep_parse_format*(struct tep_handle pass:[*]_tep_, struct tep_event pass:[*]pass:[*]_eventp_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_); +-- + +DESCRIPTION +----------- +The _tep_parse_event()_ function parses the event format and creates an event +structure to quickly parse raw data for a given event. The _tep_ argument is +the trace event parser context. The created event structure is stored in the +_tep_ context. The _buf_ argument is a buffer with _size_, where the event +format data is. The event format data can be taken from +tracefs/events/.../.../format files. The _sys_ argument is the system of +the event. + +The _tep_parse_format()_ function does the same as _tep_parse_event()_. The only +difference is in the extra _eventp_ argument, where the newly created event +structure is returned. + +RETURN VALUE +------------ +Both _tep_parse_event()_ and _tep_parse_format()_ functions return 0 on success, +or TEP_ERRNO__... in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char *buf; +int size; +struct tep_event *event = NULL; +buf = read_file("/sys/kernel/tracing/events/ftrace/print/format", &size); +if (tep_parse_event(tep, buf, size, "ftrace") != 0) { + /* Failed to parse the ftrace print format */ +} + +if (tep_parse_format(tep, &event, buf, size, "ftrace") != 0) { + /* Failed to parse the ftrace print format */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:38 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759787 Return-Path: Received: from mail-eopbgr790045.outbound.protection.outlook.com ([40.107.79.45]:56480 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728991AbeKSXSY (ORCPT ); Mon, 19 Nov 2018 18:18:24 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 26/34] tools/lib/traceevent: Man page for tep_parse_header_page() Date: Mon, 19 Nov 2018 12:54:38 +0000 Message-ID: <20181119125357.19449-27-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2745 Create man page for tep_parse_header_page() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-parse_head.txt | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt b/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt new file mode 100644 index 000000000000..a5e7295b911c --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt @@ -0,0 +1,82 @@ +libtraceevent(3) +================ + +NAME +---- +tep_parse_header_page - Parses the data stored in the header page. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +int *tep_parse_header_page*(struct tep_handle pass:[*]_tep_, char pass:[*]_buf_, unsigned long _size_, int _long_size_); +-- + +DESCRIPTION +----------- +The _tep_parse_header_page()_ function parses the header page data from _buf_, +and initializes the _tep_, trace event parser context, with it. The buffer +_buf_ is with _size_, and is supposed to be copied from +tracefs/events/header_page. + +Some old kernels do not have header page info, in this case the +_tep_parse_header_page()_ function can be called with _size_ equal to 0. The +_tep_ context is initialized with default values. The _long_size_ can be used in +this use case, to set the size of a long integer to be used. + +RETURN VALUE +------------ +The _tep_parse_header_page()_ function returns 0 in case of success, or -1 +in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +char *buf; +int size; +buf = read_file("/sys/kernel/tracing/events/header_page", &size); +if (tep_parse_header_page(tep, buf, size, sizeof(unsigned long)) != 0) { + /* Failed to parse the header page */ +} +... +-- + +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 From patchwork Mon Nov 19 12:54:39 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759789 Return-Path: Received: from mail-eopbgr790085.outbound.protection.outlook.com ([40.107.79.85]:11680 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728884AbeKSXS2 (ORCPT ); Mon, 19 Nov 2018 18:18:28 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 27/34] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin() Date: Mon, 19 Nov 2018 12:54:39 +0000 Message-ID: <20181119125357.19449-28-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 3383 Create man pages for tep_load_plugins() and tep_unload_plugin() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-plugins.txt | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt new file mode 100644 index 000000000000..7b3acdab3133 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-plugins.txt @@ -0,0 +1,98 @@ +libtraceevent(3) +================ + +NAME +---- +tep_load_plugins,tep_unload_plugins - Load / unload traceevent plugins + +SYNOPSIS +-------- +[verse] +-- +*#include * + +struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_); +void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_); +-- + +DESCRIPTION +----------- +The _tep_load_plugins()_ function loads all plugins, located in the plugin +directories. The _tep_ argument is trace event parser context. +The plugin directories are : +[verse] +-- + - System's plugin directory, defined at the library compile time. It + depends on the library installation prefix and usually is + _(install_preffix)/lib/traceevent/plugins_ + - Directory, defined by the environment variable _TRACEEVENT_PLUGIN_DIR_ + - User's plugin directory, located at _~/.traceevent/plugins_ +-- +Loading of plugins can be controlled by the _tep_flags_, using the +_tep_set_flag()_ API: +[verse] +-- + _TEP_DISABLE_SYS_PLUGINS_ - do not load plugins, located in + the system's plugin directory. + _TEP_DISABLE_PLUGINS_ - do not load any plugins. +-- +The _tep_set_flag()_ API must be called before _tep_load_plugins()_. + +The _tep_unload_plugins()_ function unloads the plugins, previously loaded by +_tep_load_plugins()_. The _tep_ argument is trace event parser context. The +_plugin_list_ is the list of loaded plugins, returned by the _tep_load_plugins()_ +function. + +RETURN VALUE +------------ +The _tep_load_plugins()_ function returns a list of successfully loaded plugins, +or NULL in case no plugins are loaded. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +struct tep_plugin_list *plugins = tep_load_plugins(tep); +if (plugins == NULL) { + /* no plugins are loaded */ +} +... +tep_unload_plugins(plugins, 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)_, _tep_set_flag(3)_ + +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 From patchwork Mon Nov 19 12:54:40 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759791 Return-Path: Received: from mail-eopbgr790045.outbound.protection.outlook.com ([40.107.79.45]:56480 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728846AbeKSXS3 (ORCPT ); Mon, 19 Nov 2018 18:18:29 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 28/34] tools/lib/traceevent: Man page for tep_data_lat_fmt() Date: Mon, 19 Nov 2018 12:54:40 +0000 Message-ID: <20181119125357.19449-29-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2557 Create man page for tep_data_lat_fmt() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-record_lat.txt | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt new file mode 100644 index 000000000000..5c8f5ec0599d --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt @@ -0,0 +1,77 @@ +libtraceevent(3) +================ + +NAME +---- +tep_data_lat_fmt - Parses the data for the latency format. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +void *tep_data_lat_fmt*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_); +-- +DESCRIPTION +----------- +The _tep_data_lat_fmt()_ function parses out the latency format (interrupts +disabled, need rescheduling, in hard/soft interrupt, preempt count and +lock depth) from _record_ and places it into the _s_. The _tep_ argument is +the trace event parser context. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct tep_handle *tep = tep_alloc(); +struct trace_seq seq; +trace_seq_init(&seq); +... +void process_record(struct tep_record *record) +{ + /* Place latency information in the seq */ + tep_data_lat_fmt(tep, &seq, record); +} +... +-- + +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)_,_tep_set_latency_format(3)_ + +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 From patchwork Mon Nov 19 12:54:41 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759793 Return-Path: Received: from mail-eopbgr790085.outbound.protection.outlook.com ([40.107.79.85]:11680 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728828AbeKSXS3 (ORCPT ); Mon, 19 Nov 2018 18:18:29 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 29/34] tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(), tep_data_preempt_count() and tep_data_flags() Date: Mon, 19 Nov 2018 12:54:41 +0000 Message-ID: <20181119125357.19449-30-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 4481 Create man pages for tep_data_type(), tep_data_pid(), tep_data_preempt_count() and tep_data_flags() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-record_parse.txt | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt new file mode 100644 index 000000000000..6b4ca8dbcdfd --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt @@ -0,0 +1,134 @@ +libtraceevent(3) +================ + +NAME +---- +tep_data_type,tep_data_pid,tep_data_preempt_count,tep_data_flags - Extract common fields from a record. + +SYNOPSIS +-------- +[verse] +-- +*#include * + +enum *trace_flag_type* { + _TRACE_FLAG_IRQS_OFF_, + _TRACE_FLAG_IRQS_NOSUPPOR_, + _TRACE_FLAG_NEED_RESCHED_, + _TRACE_FLAG_HARDIRQ_, + _TRACE_FLAG_SOFTIRQ_, +}; + +int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_); +-- + +DESCRIPTION +----------- +This set of functions can be used to extract common fields from a record. + +The _tep_data_type()_ function gets the event id from the record _rec_. It reads +the "common_type" field. The _tep_ argument is the trace event parser context. + +The _tep_data_pid()_ function gets the process id from the record _rec_. It reads +the "common_pid" field. The _tep_ argument is the trace event parser context. + +The _tep_data_preempt_count()_ function gets the preemption count from the record +_rec_. It reads the "common_preempt_count" field. The _tep_ argument is the +trace event parser context. + +The _tep_data_flags()_ function gets the latency flags from the record _rec_. +It reads the "common_flags" field. The _tep_ argument is the trace event parser +context. Supported latency flags are: +[verse] +-- + _TRACE_FLAG_IRQS_OFF_, Interrupts are disabled. + _TRACE_FLAG_IRQS_NOSUPPOR_, Reading IRQ flag is not supported by the architecture. + _TRACE_FLAG_NEED_RESCHED_, Task needs rescheduling. + _TRACE_FLAG_HARDIRQ_, Hard IRQ is running. + _TRACE_FLAG_SOFTIRQ_, Soft IRQ is running. +-- + +RETURN VALUE +------------ +The _tep_data_type()_ function returns an integer, representing the event id. + +The _tep_data_pid()_ function returns an integer, representing the process id + +The _tep_data_preempt_count()_ function returns an integer, representing the +preemption count. + +The _tep_data_flags()_ function returns an integer, representing the latency +flags. Look at the _trace_flag_type_ enum for supported flags. + +All these functions in case of an error return a negative integer. + +EXAMPLE +------- +[source,c] +-- +#include +... +struct tep_handle *tep = tep_alloc(); +... +void process_record(struct tep_record *record) +{ + int data; + + data = tep_data_type(tep, record); + if (data >= 0) { + /* Got the ID of the event */ + } + + data = tep_data_pid(tep, record); + if (data >= 0) { + /* Got the process ID */ + } + + data = tep_data_preempt_count(tep, record); + if (data >= 0) { + /* Got the preemption count */ + } + + data = tep_data_flags(tep, record); + if (data >= 0) { + /* Got the latency flags */ + } +} +... +-- + +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 From patchwork Mon Nov 19 12:54:42 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759807 Return-Path: Received: from mail-eopbgr790084.outbound.protection.outlook.com ([40.107.79.84]:44928 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXSr (ORCPT ); Mon, 19 Nov 2018 18:18:47 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 30/34] tools/lib/traceevent: Man pages for trace_seq_init() and trace_seq_destroy() Date: Mon, 19 Nov 2018 12:54:42 +0000 Message-ID: <20181119125357.19449-31-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2323 Create man pages for trace_seq_init() and trace_seq_destroy() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-tseq.txt | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt new file mode 100644 index 000000000000..1bbfb1556b1c --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq.txt @@ -0,0 +1,76 @@ +libtraceevent(3) +================ + +NAME +---- +trace_seq_init,trace_seq_destroy - Initialize / destroy a trace sequence. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *trace_seq_init*(struct trace_seq pass:[*]_s_); +void *trace_seq_destroy*(struct trace_seq pass:[*]_s_); +-- + +DESCRIPTION +----------- +Trace sequences are used to allow a function to call several other functions +to create a string of data to use. + +The _trace_seq_init()_ function initializes the trace sequence _s_. + +The _trace_seq_destroy()_ function destroys the trace sequence _s_ and frees +all its resources that it had used. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +... +trace_seq_destroy(&seq); +... +-- + +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. +*-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 From patchwork Mon Nov 19 12:54:43 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759809 Return-Path: Received: from mail-eopbgr790084.outbound.protection.outlook.com ([40.107.79.84]:44928 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728880AbeKSXSs (ORCPT ); Mon, 19 Nov 2018 18:18:48 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 31/34] tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and trace_seq_do_printf() Date: Mon, 19 Nov 2018 12:54:43 +0000 Message-ID: <20181119125357.19449-32-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2873 Create man pages for trace_seq_do_fprintf() and trace_seq_do_printf() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-tseq_doprint.txt | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt new file mode 100644 index 000000000000..441afae8ca0c --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt @@ -0,0 +1,89 @@ +libtraceevent(3) +================ + +NAME +---- +trace_seq_do_fprintf,trace_seq_do_printf - Print the trace sequence buffer to a file. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_); +int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_); +-- + +DESCRIPTION +----------- +Trace sequences are used to allow a function to call several other functions +to create a string of data to use. + +The _trace_seq_do_printf()_ function prints the buffer of trace sequence _s_ to +the standard output stdout. + +The _trace_seq_do_fprintf()_ function prints the buffer of trace sequence _s_ +to the given file _fp_. + +RETURN VALUE +------------ +Both _trace_seq_do_printf()_ and _trace_seq_do_fprintf()_ functions return the +number of printed characters, or -1 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +... +if (trace_seq_do_printf(&seq) < 0 ) [ + /* Failed to print the buffer of the trace sequence to the standard output */ +} +... +FILE *fp = fopen("trace.txt", "w"); +if (trace_seq_do_fprintf(&seq, fp) < 0 ) [ + /* Failed to print the buffer of the trace sequence to the trace.txt file */ +} +... +-- + +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. +*-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 From patchwork Mon Nov 19 12:54:44 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759811 Return-Path: Received: from mail-eopbgr790084.outbound.protection.outlook.com ([40.107.79.84]:44928 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728872AbeKSXSt (ORCPT ); Mon, 19 Nov 2018 18:18:49 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 32/34] tools/lib/traceevent: Man pages for trace_seq_printf() and trace_seq_vprintf() Date: Mon, 19 Nov 2018 12:54:44 +0000 Message-ID: <20181119125357.19449-33-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2959 Create man pages for trace_seq_printf() and trace_seq_vprintf() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-tseq_print.txt | 95 +++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt new file mode 100644 index 000000000000..ae1aa44710e7 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt @@ -0,0 +1,95 @@ +libtraceevent(3) +================ + +NAME +---- +trace_seq_printf,trace_seq_vprintf - Print formated string with arguments in a trace sequence. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, _..._); +int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_); +-- + +DESCRIPTION +----------- +Trace sequences are used to allow a function to call several other functions +to create a string of data to use. + +The _trace_seq_printf()_ function puts a formated string _fmt _with +variable arguments _..._ in the trace sequence _s_. + +The _trace_seq_vprintf()_ function puts a formated string _fmt _with +list of arguments _args_ in the trace sequence _s_. + +RETURN VALUE +------------ + +Both _trace_seq_printf()_ and _trace_seq_vprintf()_ functions return non-zero +on success, or 0 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +... +if (trace_seq_printf(&seq, "example print %d", 10) == 0) { + /* Failed to print in the trace sequence */ +} +... +void my_print(char *format, ...) +{ + va_list ap; + va_start(ap, format); + if (trace_seq_printf(&seq, format, ap) == 0) { + /* Failed to print in the trace sequence */ + } + va_end(ap); +} +... +-- + +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. +*-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 From patchwork Mon Nov 19 12:54:45 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759813 Return-Path: Received: from mail-eopbgr790084.outbound.protection.outlook.com ([40.107.79.84]:44928 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728880AbeKSXSu (ORCPT ); Mon, 19 Nov 2018 18:18:50 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 33/34] tools/lib/traceevent: Man pages for trace_seq_putc() and trace_seq_puts() Date: Mon, 19 Nov 2018 12:54:45 +0000 Message-ID: <20181119125357.19449-34-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2765 Create man pages for trace_seq_putc() and trace_seq_puts() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../Documentation/libtraceevent-tseq_put.txt | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt new file mode 100644 index 000000000000..78d2e87dbba8 --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt @@ -0,0 +1,89 @@ +libtraceevent(3) +================ + +NAME +---- +trace_seq_putc,trace_seq_puts - Put string / character in a trace sequence. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_); +int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_); +-- + +DESCRIPTION +----------- +Trace sequences are used to allow a function to call several other functions +to create a string of data to use. + +The _trace_seq_putc()_ function puts a single character _c_ in the trace +sequence _s_. + +The _trace_seq_puts()_ function puts a NULL terminated string _str_ in the +trace sequence _s_. + +RETURN VALUE +------------ +Both _trace_seq_putc()_ and _trace_seq_puts()_ functions return the number of +characters put in the trace sequence, or 0 in case of an error. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +... +if (trace_seq_putc(&seq, ';') != 1) { + /* Failed to put ';' in the trace sequence */ +} +... +char *str = " foo "; +if (trace_seq_puts(&seq, str) != strlen(str)) { + /* Failed to put " foo " in the trace sequence */ +} +... +-- + +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. +*-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 From patchwork Mon Nov 19 12:54:46 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Tzvetomir Stoyanov X-Patchwork-Id: 10759819 Return-Path: Received: from mail-eopbgr790084.outbound.protection.outlook.com ([40.107.79.84]:44928 "EHLO NAM03-CO1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1728828AbeKSXTE (ORCPT ); Mon, 19 Nov 2018 18:19:04 -0500 From: Tzvetomir Stoyanov To: "rostedt@goodmis.org" CC: "linux-trace-devel@vger.kernel.org" Subject: [PATCH 34/34] tools/lib/traceevent: Man pages for trace_seq_reset() and trace_seq_terminate() Date: Mon, 19 Nov 2018 12:54:46 +0000 Message-ID: <20181119125357.19449-35-tstoyanov@vmware.com> References: <20181119125357.19449-1-tstoyanov@vmware.com> In-Reply-To: <20181119125357.19449-1-tstoyanov@vmware.com> Content-Language: en-US MIME-Version: 1.0 Sender: linux-trace-devel-owner@vger.kernel.org List-ID: Content-Length: 2470 Create man pages for trace_seq_reset() and trace_seq_terminate() as part of the libtraceevent APIs. Signed-off-by: Tzvetomir Stoyanov --- .../libtraceevent-tseq_reset.txt | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt diff --git a/tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt b/tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt new file mode 100644 index 000000000000..3951f313d39c --- /dev/null +++ b/tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt @@ -0,0 +1,78 @@ +libtraceevent(3) +================ + +NAME +---- +trace_seq_reset,trace_seq_terminate - Reset / terminate a trace sequence. + +SYNOPSIS +-------- +[verse] +-- +*#include * +*#include * + +void *trace_seq_reset*(struct trace_seq pass:[*]_s_); +void *trace_seq_terminate*(struct trace_seq pass:[*]_s_); +-- + +DESCRIPTION +----------- +Trace sequences are used to allow a function to call several other functions +to create a string of data to use. + +The _trace_seq_reset()_ function re-initializes the trace sequence _s_. All +characters already written in _s_ will be deleted. + +The _trace_seq_terminate()_ function terminates the trace sequence _s_. It puts +the null character pass:['\0'] at the end of the buffer. + +EXAMPLE +------- +[source,c] +-- +#include +#include +... +struct trace_seq seq; +trace_seq_init(&seq); +... +trace_seq_reset(&seq); +... +trace_seq_terminate(&seq); +... +-- +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. +*-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