[PATCH 0/2] Fixed outdated libtraceevent man pages.

[PATCH 0/2] Fixed outdated libtraceevent man pages.

[Tzvetomir Stoyanov (VMware)]

The main libtraceevent man page is not up to date with the latest
changes in the library APIs.

Tzvetomir Stoyanov (VMware) (2):
  tools/lib/traceevent: Man pages fix, rename tep_ref_get() to
    tep_get_ref()
  tools/lib/traceevent: Man pages fix, changes in event printing APIs

 .../Documentation/libtraceevent-handle.txt    |   8 +-
 .../libtraceevent-latency_format.txt          | 154 ------------------
 .../Documentation/libtraceevent.txt           |  15 +-
 3 files changed, 6 insertions(+), 171 deletions(-)
 delete mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt

-- 
2.21.0

[PATCH 1/2] tools/lib/traceevent: Man pages fix, rename tep_ref_get() to tep_get_ref()

[Tzvetomir Stoyanov (VMware)]

The tep_ref_get() was renamed to tep_get_ref(), to be more consistent with
the other tep_ref_* APIs. However, in the man pages the API is still with
the old name. The documentation is fixed to reflect the actual name of the API.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 .../lib/traceevent/Documentation/libtraceevent-handle.txt | 8 ++++----
 tools/lib/traceevent/Documentation/libtraceevent.txt      | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-handle.txt b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt
index 8d568316847d..45b20172e262 100644
--- a/tools/lib/traceevent/Documentation/libtraceevent-handle.txt
+++ b/tools/lib/traceevent/Documentation/libtraceevent-handle.txt
@@ -3,7 +3,7 @@ libtraceevent(3)
 
 NAME
 ----
-tep_alloc, tep_free,tep_ref, tep_unref,tep_ref_get - Create, destroy, manage
+tep_alloc, tep_free,tep_ref, tep_unref,tep_get_ref - Create, destroy, manage
 references of trace event parser context.
 
 SYNOPSIS
@@ -16,7 +16,7 @@ struct tep_handle pass:[*]*tep_alloc*(void);
 void *tep_free*(struct tep_handle pass:[*]_tep_);
 void *tep_ref*(struct tep_handle pass:[*]_tep_);
 void *tep_unref*(struct tep_handle pass:[*]_tep_);
-int *tep_ref_get*(struct tep_handle pass:[*]_tep_);
+int *tep_get_ref*(struct tep_handle pass:[*]_tep_);
 --
 
 DESCRIPTION
@@ -57,9 +57,9 @@ EXAMPLE
 ...
 struct tep_handle *tep = tep_alloc();
 ...
-int ref = tep_ref_get(tep);
+int ref = tep_get_ref(tep);
 tep_ref(tep);
-if ( (ref+1) != tep_ref_get(tep)) {
+if ( (ref+1) != tep_get_ref(tep)) {
 	/* Something wrong happened, the counter is not incremented by 1 */
 }
 tep_unref(tep);
diff --git a/tools/lib/traceevent/Documentation/libtraceevent.txt b/tools/lib/traceevent/Documentation/libtraceevent.txt
index d71fc61ea759..7a3310168ef6 100644
--- a/tools/lib/traceevent/Documentation/libtraceevent.txt
+++ b/tools/lib/traceevent/Documentation/libtraceevent.txt
@@ -16,7 +16,7 @@ Management of tep handler data structure and access of its members:
 	void *tep_free*(struct tep_handle pass:[*]_tep_);
 	void *tep_ref*(struct tep_handle pass:[*]_tep_);
 	void *tep_unref*(struct tep_handle pass:[*]_tep_);
-	int *tep_ref_get*(struct tep_handle pass:[*]_tep_);
+	int *tep_get_ref*(struct tep_handle pass:[*]_tep_);
 	void *tep_set_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_);
 	void *tep_clear_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_);
 	bool *tep_test_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flags_);
-- 
2.21.0

[PATCH 2/2] tools/lib/traceevent: Man pages fix, changes in event printing APIs

[Tzvetomir Stoyanov (VMware)]

APIs for printing various trace event information were redesigned to
be more simple. However, the main libtraceevent man page was not updated
with those changes. The documentation is updated to describe the new
event print API.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 .../libtraceevent-latency_format.txt          | 154 ------------------
 .../Documentation/libtraceevent.txt           |  13 +-
 2 files changed, 1 insertion(+), 166 deletions(-)
 delete mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
deleted file mode 100644
index 3a3c9e9866ec..000000000000
--- a/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
+++ /dev/null
@@ -1,154 +0,0 @@
-libtraceevent(3)
-================
-
-NAME
-----
-tep_set_latency_format, tep_is_latency_format, tep_data_latency_format -
-"latency output" format APIs.
-
-SYNOPSIS
---------
-[verse]
---
-*#include <event-parse.h>*
-
-void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_);
-bool *tep_is_latency_format*(struct tep_handle pass:[*]_tep_);
-void *tep_data_latency_format*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_);
-
---
-
-DESCRIPTION
------------
-"Latency output" format prints information about interrupts being disabled,
-soft irq being disabled, the "need_resched" flag being set and preempt count.
-This information is recorded with every event, but by default is not printed.
-
-The _tep_set_latency_format()_ function enables the "latency output" printing.
-The _tep_ argument is trace event parser context. The _lat_ argument can be
-zero, for "latency output" disabled, or non zero for "latency output" enabled.
-Information is displayed with 6 characters. When a field is zero, or N/A,
-a pass:['.'] is printed. Example:
-[verse]
---
-  <idle>-0       0d.h1 106467.859747: function:    ktime_get <-- tick_check_idle
---
-The 0d.h1. denotes this information. The first character is never a pass:['.']
-and represents what CPU the trace was recorded on (CPU 0). The pass:['d']
-denotes that interrupts were disabled. The pass:['.'] is "need_resched" flag.
-If it is set, the character ['N'] would be displayed. The pass:['h'] means that
-this was called inside an interrupt handler. The pass:['1'] is the preemption
-disabled (preempt_count) was set to one. See 'LATENCY FORMAT' section.
-
-The _tep_is_latency_format()_ function gets if "latency output" is enabled.
-
-The _tep_data_latency_format()_ function parses out the latency format from
-_record_ and writes it into _s_. The _tep_ argument is the trace event parser
-context.
-
-This "Latency output" setting affects output of _tep_print_event_task()_
-and _tep_print_event_time()_ APIs.
-
-LATENCY FORMAT
---------------
-The latency format displays 5 or more fields:
-[verse]
---
-CPU #, interrupt state, scheduling state, current context, and preemption count.
-
-Field 1 is the CPU number (starting with zero).
-
-Field 2 is the interrupt enabled state:
-  d : Interrupts are disabled
-  . : Interrupts are enabled
-  X : The architecture does not support this information
-
-Field 3 is the "need resched" state.
-  N : The task is set to call the scheduler when possible, as another
-      higher priority task may need to be scheduled in.
-  . : The task is not set to call the scheduler.
-
-Field 4 is the context state.
-  . : Normal context
-  s : Soft interrupt context
-  h : Hard interrupt context
-  H : Hard interrupt context which triggered during soft interrupt context.
-  z : NMI context
-  Z : NMI context which triggered during hard interrupt context
-
-Field 5 is the preemption count.
-  . : The preempt count is zero.
-
-  On preemptible kernels (where the task can be scheduled out in
-  arbitrary locations while in kernel context), The preempt count,
-  when non zero, will prevent the kernel from scheduling out the
-  current task. The preempt count number is displayed when it is not
-  zero.
---
-Depending on the kernel, it may show other fields (lock depth,
-or migration disabled, which are unique to specialized kernels).
-
-RETURN VALUE
-------------
-
-The _tep_is_latency_format()_ function returns true if "latency output"
-is enabled, or false if it is disabled.
-
-EXAMPLE
--------
-[source,c]
---
-#include <event-parse.h>
-...
-struct tep_handle *tep = tep_alloc();
-struct trace_seq seq;
-trace_seq_init(&seq);
-...
-	tep_set_latency_format(tep, 1);
-...
-	if (tep_is_latency_format(tep)) {
-		/* latency output format is enabled */
-	} else {
-		/* latency output format is disabled */
-	}
-...
-void process_record(struct tep_record *record)
-{
-	/* Write latency information in seq */
-	tep_data_latency_format(tep, &seq, 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)_, tep_print_event_task(3),
-tep_print_event_time(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
diff --git a/tools/lib/traceevent/Documentation/libtraceevent.txt b/tools/lib/traceevent/Documentation/libtraceevent.txt
index 7a3310168ef6..ad36939aef50 100644
--- a/tools/lib/traceevent/Documentation/libtraceevent.txt
+++ b/tools/lib/traceevent/Documentation/libtraceevent.txt
@@ -26,15 +26,12 @@ Management of tep handler data structure and access of its members:
 	void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_);
 	int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);
 	void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
-	bool *tep_is_latency_format*(struct tep_handle pass:[*]_tep_);
-	void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_);
 	int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_);
 	int *tep_get_header_timestamp_size*(struct tep_handle pass:[*]_tep_);
 	bool *tep_is_old_format*(struct tep_handle pass:[*]_tep_);
 	int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_);
 
 Register / unregister APIs:
-	int *tep_register_trace_clock*(struct tep_handle pass:[*]_tep_, const char pass:[*]_trace_clock_);
 	int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
 	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_);
@@ -57,14 +54,7 @@ Event related APIs:
 	int *tep_get_events_count*(struct tep_handle pass:[*]_tep_);
 	struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
 	struct tep_event pass:[*]pass:[*]*tep_list_events_copy*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
-
-Event printing:
-	void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, bool _use_trace_clock_);
-	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_event_info*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, struct tep_record pass:[*]_record_);
-	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_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_set_print_raw*(struct tep_handle pass:[*]_tep_, int _print_raw_);
+	void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, const char pass:[*]_fmt_, _..._);
 
 Event finding:
 	struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_);
@@ -116,7 +106,6 @@ Filter management:
 	int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);
 
 Parsing various data from the records:
-	void *tep_data_latency_format*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_);
 	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_);
-- 
2.21.0