[PATCH 00/34] A lot of libtraceevent man pages

[PATCH 00/34] A lot of libtraceevent man pages

[Tzvetomir Stoyanov]

34 man pages, describing 71 APIs of the traceevent library

Tzvetomir Stoyanov (34):
  tools/lib/traceevent: Man page for tep_register_trace_clock()
  tools/lib/traceevent: Man pages for tep_register_event_handler() and
    tep_unregister_event_handler()
  tools/lib/traceevent: Man pages for tep_register_function() and
    tep_register_print_string()
  tools/lib/traceevent: Man pages for tep_register_print_function() and
    tep_unregister_print_function()
  tools/lib/traceevent: Man page for tep_read_number()
  tools/lib/traceevent: Man pages for tep_find_event(),
    tep_find_event_by_name() and tep_find_event_by_record()
  tools/lib/traceevent: Man page for tep_list_events()
  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()
  tools/lib/traceevent: Man pages tep_get_first_event() and
    tep_get_events_count()
  tools/lib/traceevent: Man pages tep_find_common_field(),
    tep_find_field() and tep_find_any_field()
  tools/lib/traceevent: Man pages tep_get_any_field_val(),
    tep_get_common_field_val(), tep_get_field_val() and
    tep_get_field_raw()
  tools/lib/traceevent: Man pages for tep_print_field(),
    tep_print_fields(), tep_print_num_field() and tep_print_func_field()
  tools/lib/traceevent: Man page for tep_read_number_field()
  tools/lib/traceevent: Man pages for tep_event_common_fields() and
    tep_event_fields()
  tools/lib/traceevent: Man pages for tep_filter_alloc(),
    tep_filter_free() and tep_filter_reset()
  tools/lib/traceevent: Man page for tep_filter_add_filter_str()
  tools/lib/traceevent: Man page for tep_filter_strerror()
  tools/lib/traceevent: Man pages for tep_event_filtered() and
    tep_filter_remove_event()
  tools/lib/traceevent: Man page for tep_filter_match()
  tools/lib/traceevent: Man pages for tep_filter_copy() and
    tep_filter_compare()
  tools/lib/traceevent: Man page for tep_filter_make_string()
  tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(),
    tep_update_trivial() and tep_filter_clear_trivial()
  tools/lib/traceevent: Man pages for tep_find_function() and
    tep_find_function_address()
  tools/lib/traceevent: Man pages for tep_set_function_resolver() and
    tep_reset_function_resolver()
  tools/lib/traceevent: Man pages for tep_parse_event() and
    tep_parse_format()
  tools/lib/traceevent: Man page for tep_parse_header_page()
  tools/lib/traceevent: Man pages for tep_load_plugins() and
    tep_unload_plugin()
  tools/lib/traceevent: Man page for tep_data_lat_fmt()
  tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(),
    tep_data_preempt_count() and tep_data_flags()
  tools/lib/traceevent: Man pages for trace_seq_init() and
    trace_seq_destroy()
  tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and
    trace_seq_do_printf()
  tools/lib/traceevent: Man pages for trace_seq_printf() and
    trace_seq_vprintf()
  tools/lib/traceevent: Man pages for trace_seq_putc() and
    trace_seq_puts()
  tools/lib/traceevent: Man pages for trace_seq_reset() and
    trace_seq_terminate()

 .../libtraceevent-endian_read.txt             |  76 ++++++++++
 .../libtraceevent-event_find.txt              |  99 +++++++++++++
 .../libtraceevent-event_list.txt              |  94 ++++++++++++
 .../libtraceevent-event_print.txt             | 126 ++++++++++++++++
 .../Documentation/libtraceevent-events.txt    |  87 ++++++++++++
 .../libtraceevent-field_find.txt              |  98 +++++++++++++
 .../libtraceevent-field_get_val.txt           | 117 +++++++++++++++
 .../libtraceevent-field_print.txt             | 120 ++++++++++++++++
 .../libtraceevent-field_read.txt              |  80 +++++++++++
 .../Documentation/libtraceevent-fields.txt    |  99 +++++++++++++
 .../Documentation/libtraceevent-filter.txt    |  85 +++++++++++
 .../libtraceevent-filter_add.txt              |  78 ++++++++++
 .../libtraceevent-filter_error.txt            |  78 ++++++++++
 .../libtraceevent-filter_event.txt            |  84 +++++++++++
 .../libtraceevent-filter_match.txt            |  96 +++++++++++++
 .../libtraceevent-filter_oper.txt             |  84 +++++++++++
 .../libtraceevent-filter_show.txt             |  75 ++++++++++
 .../libtraceevent-filter_trivial.txt          | 112 +++++++++++++++
 .../Documentation/libtraceevent-func_find.txt |  88 ++++++++++++
 .../libtraceevent-func_resolve.txt            |  96 +++++++++++++
 .../libtraceevent-parse_event.txt             |  90 ++++++++++++
 .../libtraceevent-parse_head.txt              |  82 +++++++++++
 .../Documentation/libtraceevent-plugins.txt   |  98 +++++++++++++
 .../libtraceevent-record_lat.txt              |  77 ++++++++++
 .../libtraceevent-record_parse.txt            | 134 ++++++++++++++++++
 .../Documentation/libtraceevent-reg_clock.txt |  77 ++++++++++
 .../libtraceevent-reg_event_handler.txt       | 123 ++++++++++++++++
 .../libtraceevent-reg_funcstr.txt             |  89 ++++++++++++
 .../libtraceevent-reg_print_func.txt          | 128 +++++++++++++++++
 .../Documentation/libtraceevent-tseq.txt      |  76 ++++++++++
 .../libtraceevent-tseq_doprint.txt            |  89 ++++++++++++
 .../libtraceevent-tseq_print.txt              |  95 +++++++++++++
 .../Documentation/libtraceevent-tseq_put.txt  |  89 ++++++++++++
 .../libtraceevent-tseq_reset.txt              |  78 ++++++++++
 tools/lib/traceevent/event-parse.c            |   4 +-
 35 files changed, 3199 insertions(+), 2 deletions(-)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-endian_read.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_find.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_list.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-event_print.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-events.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_find.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_get_val.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_print.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-field_read.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-fields.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_add.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_error.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_event.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_match.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_oper.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_show.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter_trivial.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_find.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-func_resolve.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_event.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-parse_head.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-plugins.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_lat.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-record_parse.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_clock.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_event_handler.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_funcstr.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-reg_print_func.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_doprint.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_print.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_put.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-tseq_reset.txt

-- 
2.19.1

[PATCH 01/34] tools/lib/traceevent: Man page for tep_register_trace_clock()

[Tzvetomir Stoyanov]

Create man page for tep_register_trace_clock()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 02/34] tools/lib/traceevent: Man pages for tep_register_event_handler() and tep_unregister_event_handler()

[Tzvetomir Stoyanov]

Create man pages for tep_register_event_handler() and tep_unregister_event_handler()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 03/34] tools/lib/traceevent: Man pages for tep_register_function() and tep_register_print_string()

[Tzvetomir Stoyanov]

Create man pages for tep_register_function() and tep_register_print_string()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 04/34] tools/lib/traceevent: Man pages for tep_register_print_function() and tep_unregister_print_function()

[Tzvetomir Stoyanov]

Create man pages for tep_register_print_function() and tep_unregister_print_function()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+enum *tep_func_arg_type* {
+	TEP_FUNC_ARG_VOID,
+	TEP_FUNC_ARG_INT,
+	TEP_FUNC_ARG_LONG,
+	TEP_FUNC_ARG_STRING,
+	TEP_FUNC_ARG_PTR,
+	TEP_FUNC_ARG_MAX_TYPES
+};
+
+typedef unsigned long long (*pass:[*]tep_func_handler*)(struct trace_seq pass:[*]s, unsigned long long pass:[*]args);
+
+int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
+int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
+--
+
+DESCRIPTION
+-----------
+Some events may have helper functions in the print format arguments. This allows
+a plugin to dynamically create a way to process one of these functions.
+
+The _tep_register_print_function()_ registers such helper function. The _tep_ 
+argument is the trace event parser context. The _func_ argument is the address
+of the helper function. The _ret_type_ argument is  the return type of the 
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+static long long
+process_custom_helper(struct trace_seq *s, unsigned long long *args)
+{
+	unsigned long long param = args[0];
+	trace_seq_printf(s, "the helper was called, with argument %lld", param);
+	return 0;
+}
+...
+	if ( tep_register_print_function(tep,
+				    process_custom_helper,
+				    TEP_FUNC_ARG_STRING,
+				    "custom_helper",
+				    TEP_FUNC_ARG_LONG,
+				    TEP_FUNC_ARG_VOID) != 0) {
+		/* Failed to register my process_custom_helper function */
+	}
+...
+	if (tep_unregister_print_function(tep, process_custom_helper,
+				      	  "custom_helper") != 0) {
+		/* Failed to unregister my process_custom_helper function */
+	}				    
+--
+
+FILES
+-----
+[verse]
+--
+*event-parse.h*
+	Header file to include in order to have access to the library APIs.
+*trace-seq.h*
+	Header file to include in order to have access to trace sequences related APIs.
+	Trace sequences are used to allow a function to call several other functions 
+	to create a string of data to use.
+*-ltraceevent*
+	Linker switch to add when building a program that uses the library.
+--
+
+SEE ALSO
+--------
+_libtraceevent(3)_, _trace-cmd(1)_
+
+AUTHOR
+------
+[verse]
+--
+*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 05/34] tools/lib/traceevent: Man page for tep_read_number()

[Tzvetomir Stoyanov]

Create man page for tep_read_number() as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 06/34] tools/lib/traceevent: Man pages for tep_find_event(), tep_find_event_by_name() and tep_find_event_by_record()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 07/34] tools/lib/traceevent: Man page for tep_list_events()

[Tzvetomir Stoyanov]

Create man page for tep_list_events() as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[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()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 09/34] tools/lib/traceevent: Man pages tep_get_first_event() and tep_get_events_count()

[Tzvetomir Stoyanov]

Create man pages for tep_get_first_event() and tep_get_events_count()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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<count; i++) {
+		event = (events+i);
+		/* process events[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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 10/34] tools/lib/traceevent: Man pages tep_find_common_field(), tep_find_field() and tep_find_any_field()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[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()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 12/34] tools/lib/traceevent: Man pages for tep_print_field(), tep_print_fields(), tep_print_num_field() and tep_print_func_field()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
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,
-- 
2.19.1

[PATCH 13/34] tools/lib/traceevent: Man page for tep_read_number_field()

[Tzvetomir Stoyanov]

Create man page for tep_read_number_field()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 14/34] tools/lib/traceevent: Man pages for tep_event_common_fields() and tep_event_fields()

[Tzvetomir Stoyanov]

Create man pages for tep_event_common_fields() and tep_event_fields()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 15/34] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset()

[Tzvetomir Stoyanov]

Create man pages tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 16/34] tools/lib/traceevent: Man page for tep_filter_add_filter_str()

[Tzvetomir Stoyanov]

Create man page for tep_filter_add_filter_str()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 17/34] tools/lib/traceevent: Man page for tep_filter_strerror()

[Tzvetomir Stoyanov]

Create man page for tep_filter_strerror()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 18/34] tools/lib/traceevent: Man pages for tep_event_filtered() and tep_filter_remove_event()

[Tzvetomir Stoyanov]

Create man pages for tep_event_filtered() and tep_filter_remove_event()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 19/34] tools/lib/traceevent: Man page for tep_filter_match()

[Tzvetomir Stoyanov]

Create man page for tep_filter_match()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 20/34] tools/lib/traceevent: Man pages for tep_filter_copy() and tep_filter_compare()

[Tzvetomir Stoyanov]

Create man pages for tep_filter_copy() and tep_filter_compare()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 21/34] tools/lib/traceevent: Man page for tep_filter_make_string()

[Tzvetomir Stoyanov]

Create man page for tep_filter_make_string()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 22/34] tools/lib/traceevent: Man pages for tep_filter_event_has_trivial(), tep_update_trivial() and tep_filter_clear_trivial()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 23/34] tools/lib/traceevent: Man pages for tep_find_function() and tep_find_function_address()

[Tzvetomir Stoyanov]

Create man pages for tep_find_function() and tep_find_function_address()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 24/34] tools/lib/traceevent: Man pages for tep_set_function_resolver() and tep_reset_function_resolver()

[Tzvetomir Stoyanov]

Create man pages for tep_set_function_resolver() and tep_reset_function_resolver()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 25/34] tools/lib/traceevent: Man pages for tep_parse_event() and tep_parse_format()

[Tzvetomir Stoyanov]

Create man pages for tep_parse_event() and tep_parse_format()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 26/34] tools/lib/traceevent: Man page for tep_parse_header_page()

[Tzvetomir Stoyanov]

Create man page for tep_parse_header_page()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 27/34] tools/lib/traceevent: Man pages for tep_load_plugins() and tep_unload_plugin()

[Tzvetomir Stoyanov]

Create man pages for tep_load_plugins() and tep_unload_plugin()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 28/34] tools/lib/traceevent: Man page for tep_data_lat_fmt()

[Tzvetomir Stoyanov]

Create man page for tep_data_lat_fmt()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 29/34] tools/lib/traceevent: Man pages for tep_data_type(), tep_data_pid(), tep_data_preempt_count() and tep_data_flags()

[Tzvetomir Stoyanov]

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 <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+
+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 <event-parse.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 30/34] tools/lib/traceevent: Man pages for trace_seq_init() and trace_seq_destroy()

[Tzvetomir Stoyanov]

Create man pages for trace_seq_init() and trace_seq_destroy()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 31/34] tools/lib/traceevent: Man pages for trace_seq_do_fprintf() and trace_seq_do_printf()

[Tzvetomir Stoyanov]

Create man pages for trace_seq_do_fprintf() and trace_seq_do_printf()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 32/34] tools/lib/traceevent: Man pages for trace_seq_printf() and trace_seq_vprintf()

[Tzvetomir Stoyanov]

Create man pages for trace_seq_printf() and trace_seq_vprintf()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 33/34] tools/lib/traceevent: Man pages for trace_seq_putc() and trace_seq_puts()

[Tzvetomir Stoyanov]

Create man pages for trace_seq_putc() and trace_seq_puts()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1

[PATCH 34/34] tools/lib/traceevent: Man pages for trace_seq_reset() and trace_seq_terminate()

[Tzvetomir Stoyanov]

Create man pages for trace_seq_reset() and trace_seq_terminate()
as part of the libtraceevent APIs.

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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 <event-parse.h>*
+*#include <trace-seq.h>*
+
+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 <event-parse.h>
+#include <trace-seq.h>
+...
+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* <rostedt@goodmis.org>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <linux-trace-devel@vger.kernel.org>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
-- 
2.19.1