Skip to contentSkip to conversation

libtracevent man pages

PATCH In review Tzvetomir Stoyanov 2 participants 14 messages Nov 6, 2018 – Nov 8, 2018

lore
Share & tools
lore
#0 lore raw

cover libtracevent man pages

This series of patches implement 7 libtraceveent man pages, describing APIs:
tep_get_header_page_size(), tep_get_cpus(), tep_set_cpus(), tep_is_file_bigendian(), tep_set_file_bigendian(), tep_is_host_bigendian(), tep_set_host_bigendian(), tep_is_latency_format(), and tep_set_latency_format(), tep_get_page_size(), tep_set_page_size()
and tep_strerror().

Tzvetomir Stoyanov (7):
tools/lib/traceevent: Implement libtraceevent man pages tools/lib/traceevent: Implement libtraceevent man pages tools/lib/traceevent: Implement libtraceevent man pages tools/lib/traceevent: Implement libtraceevent man pages tools/lib/traceevent: Implement libtraceevent man pages tools/lib/traceevent: Implement libtraceevent man pages tools/lib/traceevent: Implement libtraceevent man pages

 .../Documentation/libtraceevent-cpus.txt      | 78 +++++++++++++++
 .../libtraceevent-file_endian.txt             | 87 ++++++++++++++++
 .../libtraceevent-header_size.txt             | 73 ++++++++++++++
 .../libtraceevent-host_endian.txt             | 85 ++++++++++++++++
 .../libtraceevent-latency_format.txt          | 98 +++++++++++++++++++
 .../Documentation/libtraceevent-page_size.txt | 79 +++++++++++++++
 .../Documentation/libtraceevent-strerror.txt  | 82 ++++++++++++++++
 tools/lib/traceevent/event-parse-api.c        |  4 +-
 8 files changed, 584 insertions(+), 2 deletions(-)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
Signature · 1 line
2.17.2
#1 lore raw

PATCH 1/7 tools/lib/traceevent: Implement libtraceevent man pages

This patch implements a man page, which documents
tep_get_header_page_size() libtraceevent API

---
 .../libtraceevent-header_size.txt             | 73 +++++++++++++++++++
 tools/lib/traceevent/event-parse-api.c        |  4 +-
 2 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
tools/lib/traceevent/Documentation/libtraceevent-header_size.txt new file +73 -0
new file mode 100644
index 000000000000..8edf49d2a709
@@ -0,0 +1,73 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_header_page_size - Get the size of a long integer, in kernel context.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_);
+
+--
+DESCRIPTION
+-----------
+The _tep_get_header_page_size()_ function returns the size of a long integer,
+in kernel context. The _tep_ argument is trace event parser context.
+This information is retrieved from /sys/kernel/debug/tracing/events/header_page,
+ "commit" field.
+
+RETURN VALUE
+------------
+The _tep_get_header_page_size()_ function returns the size of a long integer, 
+in bytes
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	int lsize = tep_get_header_page_size(tep);
+	printf ("The size of a long in kernel context is %d bytes", lsize);
+...	
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
tools/lib/traceevent/event-parse-api.c +2 -2
index 6a1899b378b1..39e0fca2d9a2 100644
@@ -100,10 +100,10 @@ tep_data2host8(struct tep_handle *pevent, unsigned long long data)
 }
 
 /**
- * tep_get_header_page_size - get size of the header page
+ * tep_get_header_page_size - get the size of a long integer, in kernel context
  * @pevent: a handle to the tep_handle
  *
- * This returns size of the header page
+ * This returns the size of a long integer, in kernel context
  * If @pevent is NULL, 0 is returned.
  */
 int tep_get_header_page_size(struct tep_handle *pevent)
Signature · 1 line
2.17.2
#2 lore raw

PATCH 2/7 tools/lib/traceevent: Implement libtraceevent man pages

In reply to Tzvetomir Stoyanov

This patch implements a man page, which documents tep_get_cpus() and tep_set_cpus() libtraceevent APIs

---
 .../Documentation/libtraceevent-cpus.txt      | 78 +++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +78 -0
new file mode 100644
index 000000000000..f9ed0a02d653
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_cpus,tep_set_cpus - Get / set the numbers of CPUs, which have tracing 
+data recorded.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_cpus*(struct tep_handle pass:[*]_tep_);
+void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_cpus()_ functions gets the number of CPUs, which have tracing 
+data recorded. The _tep_ argument is trace event parser context.
+
+The _tep_set_cpus()_ functions sets the number of CPUs, which have tracing 
+data recorded. The _tep_ argument is trace event parser context. The _cpu_
+argument is the number of CPUs with tracing data. This information is saved 
+in the trace.dat file.
+
+RETURN VALUE
+------------
+The _tep_get_cpus()_ functions returns the number of CPUs, which have tracing 
+data recorded.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_cpus(tep, 5);
+...
+	printf("We have tracing data for %d CPUs", tep_get_cpus(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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
Signature · 1 line
2.17.2
#3 lore raw

Re: [PATCH 2/7] tools/lib/traceevent: Implement libtraceevent man pages

Subject should be: tools/lib/traceevent: Man pages for tep_get_cpus() and tep_set_cpus()

Quoted 2 lines · On Tue, 6 Nov 2018 13:20:51 +0000 Tzvetomir Stoyanov <[email protected]>…

This patch implements a man page, which documents tep_get_cpus() and tep_set_cpus() libtraceevent APIs

BTW, "implements" isn't the right word. Also, it is looked down on to reference "this patch" as people know this is a patch. What I would say instead is:

"Create man pages for tep_get_cpus() and tep_set_cpus() as part of the libtraceevent APIs".

Quoted 13 lines
---
 .../Documentation/libtraceevent-cpus.txt      | 78 +++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +0 -0
new file mode 100644
index 000000000000..f9ed0a02d653

tools/lib/traceevent/Documentation/libtraceevent-cpus.txt line 6

Quoted 6 lines
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +6 -0
@@ -0,0 +1,78 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_cpus,tep_set_cpus - Get / set the numbers of CPUs, which have tracing 

"the number of"

Quoted 5 lines
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +5 -0
+data recorded.
+
+SYNOPSIS
+--------
+[verse]

tools/lib/traceevent/Documentation/libtraceevent-cpus.txt line 21

Quoted 10 lines
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +10 -0
+--
+*#include <event-parse.h>*
+
+int *tep_get_cpus*(struct tep_handle pass:[*]_tep_);
+void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_cpus()_ functions gets the number of CPUs, which have tracing 

" function gets the"

tools/lib/traceevent/Documentation/libtraceevent-cpus.txt line 22

Quoted 1 line
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +1 -0
+data recorded. The _tep_ argument is trace event parser context.

"data recorded in the _tep_ context."

tools/lib/traceevent/Documentation/libtraceevent-cpus.txt line 24

Quoted 2 lines
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +2 -0
+
+The _tep_set_cpus()_ functions sets the number of CPUs, which have tracing 

" function sets"

tools/lib/traceevent/Documentation/libtraceevent-cpus.txt line 27

Quoted 3 lines
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +3 -0
+data recorded. The _tep_ argument is trace event parser context. The _cpu_
+argument is the number of CPUs with tracing data. This information is saved 
+in the trace.dat file.

How is it saved in the trace.dat file?

-- Steve

Quoted 51 lines
tools/lib/traceevent/Documentation/libtraceevent-cpus.txt new file +51 -0
+
+RETURN VALUE
+------------
+The _tep_get_cpus()_ functions returns the number of CPUs, which have tracing 
+data recorded.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_cpus(tep, 5);
+...
+	printf("We have tracing data for %d CPUs", tep_get_cpus(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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
#4 lore raw

PATCH 3/7 tools/lib/traceevent: Implement libtraceevent man pages

In reply to Tzvetomir Stoyanov

This patch implements a man page, which documents tep_is_file_bigendian() and tep_set_file_bigendian() libtraceevent APIs

---
 .../libtraceevent-file_endian.txt             | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt new file +87 -0
new file mode 100644
index 000000000000..403db4e23b3f
@@ -0,0 +1,87 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_is_file_bigendian,tep_set_file_bigendian - Get / set the endianess of the 
+trace.dat file 
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+	TEP_LITTLE_ENDIAN = 0,
+	TEP_BIG_ENDIAN
+};
+
+int *tep_is_file_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+
+--
+DESCRIPTION
+-----------
+The _tep_is_file_bigendian()_ function returns the endianess of the trace.dat file. 
+The _tep_ argument is trace event parser context.
+
+The _tep_set_file_bigendian()_ set the endianess of the trace.dat file.
+The _tep_ argument is trace event parser context. The _endian_ argument is the endianess:
+	_TEP_LITTLE_ENDIAN_ - the file is in little endian format,
+	_TEP_BIG_ENDIAN_ - the file is in big endian format.
+This information is saved in the trace.dat file.
+
+RETURN VALUE
+------------
+The _tep_is_file_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_file_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+	if (TEP_BIG_ENDIAN == tep_is_file_bigendian(tep)) {
+		/* The file is in big endian */
+	} else {
+		/* The file is in little endian */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
Signature · 1 line
2.17.2
#5 lore raw

Re: [PATCH 3/7] tools/lib/traceevent: Implement libtraceevent man pages

Quoted 16 lines · On Tue, 6 Nov 2018 13:20:52 +0000 Tzvetomir Stoyanov <[email protected]>…

This patch implements a man page, which documents tep_is_file_bigendian() and tep_set_file_bigendian() libtraceevent APIs

---
 .../libtraceevent-file_endian.txt             | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt new file +0 -0
new file mode 100644
index 000000000000..403db4e23b3f

tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt line 7

Quoted 7 lines
tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt new file +7 -0
@@ -0,0 +1,87 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_is_file_bigendian,tep_set_file_bigendian - Get / set the endianess of the 
+trace.dat file 

We shouldn't mention trace.dat as libtraceevent isn't associated with that. The trace.dat file is for trace-cmd but not perf, or other tools using this library.

Instead reference it as, is the raw data read big endian or not. The tep_set_file_bigendian means that the raw data being accessed by the tep handler, is big endian. This allows the tep operations know if the data read from the raw data matches the host endianess.

-- Steve

Quoted 80 lines
tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt new file +80 -0
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+	TEP_LITTLE_ENDIAN = 0,
+	TEP_BIG_ENDIAN
+};
+
+int *tep_is_file_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+
+--
+DESCRIPTION
+-----------
+The _tep_is_file_bigendian()_ function returns the endianess of the trace.dat file. 
+The _tep_ argument is trace event parser context.
+
+The _tep_set_file_bigendian()_ set the endianess of the trace.dat file.
+The _tep_ argument is trace event parser context. The _endian_ argument is the endianess:
+	_TEP_LITTLE_ENDIAN_ - the file is in little endian format,
+	_TEP_BIG_ENDIAN_ - the file is in big endian format.
+This information is saved in the trace.dat file.
+
+RETURN VALUE
+------------
+The _tep_is_file_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_file_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+	if (TEP_BIG_ENDIAN == tep_is_file_bigendian(tep)) {
+		/* The file is in big endian */
+	} else {
+		/* The file is in little endian */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
#6 lore raw

PATCH 4/7 tools/lib/traceevent: Implement libtraceevent man pages

In reply to Tzvetomir Stoyanov

This patch implements a man page, which documents tep_is_host_bigendian() and tep_set_host_bigendian() libtraceevent APIs

---
 .../libtraceevent-host_endian.txt             | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file +85 -0
new file mode 100644
index 000000000000..23e085db8d54
@@ -0,0 +1,85 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_is_host_bigendian,tep_set_host_bigendian - Get / set the endianess of the local host.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+	TEP_LITTLE_ENDIAN = 0,
+	TEP_BIG_ENDIAN
+};
+
+int *tep_is_host_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_host_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+--
+
+DESCRIPTION
+-----------
+The _tep_is_host_bigendian()_ function returns the endianess of the local host 
+The _tep_ argument is trace event parser context.
+
+The _tep_set_host_bigendian()_ set the endianess of the local host.
+The _tep_ argument is trace event parser context. The _endian_ argument is the endianess:
+	_TEP_LITTLE_ENDIAN_ - the host is little endian,
+	_TEP_BIG_ENDIAN_ - the host is big endian.
+
+RETURN VALUE
+------------
+The _tep_is_host_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_host_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+	if (TEP_BIG_ENDIAN == tep_is_host_bigendian(tep)) {
+		/* The local host is big endian */
+	} else {
+		/* The local host is little endian */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
Signature · 1 line
2.17.2
#7 lore raw

Re: [PATCH 4/7] tools/lib/traceevent: Implement libtraceevent man pages

Quoted 16 lines · On Tue, 6 Nov 2018 13:20:53 +0000 Tzvetomir Stoyanov <[email protected]>…

This patch implements a man page, which documents tep_is_host_bigendian() and tep_set_host_bigendian() libtraceevent APIs

---
 .../libtraceevent-host_endian.txt             | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file +0 -0
new file mode 100644
index 000000000000..23e085db8d54

tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt line 6

Quoted 6 lines
tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file +6 -0
@@ -0,0 +1,85 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_is_host_bigendian,tep_set_host_bigendian - Get / set the endianess of the local host.

Probably need to state more about the endianness of the machine running the code. That is, the local host represents the machine executing the current code.

-- Steve

Quoted 79 lines
tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file +79 -0
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+	TEP_LITTLE_ENDIAN = 0,
+	TEP_BIG_ENDIAN
+};
+
+int *tep_is_host_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_host_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+--
+
+DESCRIPTION
+-----------
+The _tep_is_host_bigendian()_ function returns the endianess of the local host 
+The _tep_ argument is trace event parser context.
+
+The _tep_set_host_bigendian()_ set the endianess of the local host.
+The _tep_ argument is trace event parser context. The _endian_ argument is the endianess:
+	_TEP_LITTLE_ENDIAN_ - the host is little endian,
+	_TEP_BIG_ENDIAN_ - the host is big endian.
+
+RETURN VALUE
+------------
+The _tep_is_host_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_host_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+	if (TEP_BIG_ENDIAN == tep_is_host_bigendian(tep)) {
+		/* The local host is big endian */
+	} else {
+		/* The local host is little endian */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
#8 lore raw

Re: [PATCH 4/7] tools/lib/traceevent: Implement libtraceevent man pages

Quoted 14 lines · Steven Rostedt
Quoted 10 lines · On Tue, 6 Nov 2018 13:20:53 +0000 Tzvetomir Stoyanov <[email protected]>…

This patch implements a man page, which documents tep_is_host_bigendian() and tep_set_host_bigendian() libtraceevent APIs

---
 .../libtraceevent-host_endian.txt             | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
Quoted 16 lines

tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt line 6

Quoted 12 lines
tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file +6 -0
new file mode 100644
index 000000000000..23e085db8d54
@@ -0,0 +1,85 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_is_host_bigendian,tep_set_host_bigendian - Get / set the endianess of the local host.

Probably need to state more about the endianness of the machine running the code. That is, the local host represents the machine executing the current code.

I'm confused about these two APIs:

       int tep_host_bigendian(void);
       int tep_is_host_bigendian(struct tep_handle *pevent);

Why we need the second one ? Does it work faster than the first API, or there is some special use case ?

Quoted 84 lines

-- Steve

Quoted 79 lines
tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt new file +79 -0
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+enum *tep_endian* {
+     TEP_LITTLE_ENDIAN = 0,
+     TEP_BIG_ENDIAN
+};
+
+int *tep_is_host_bigendian*(struct tep_handle pass:[*]_tep_);
+void *tep_set_host_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
+--
+
+DESCRIPTION
+-----------
+The _tep_is_host_bigendian()_ function returns the endianess of the local host
+The _tep_ argument is trace event parser context.
+
+The _tep_set_host_bigendian()_ set the endianess of the local host.
+The _tep_ argument is trace event parser context. The _endian_ argument is the endianess:
+     _TEP_LITTLE_ENDIAN_ - the host is little endian,
+     _TEP_BIG_ENDIAN_ - the host is big endian.
+
+RETURN VALUE
+------------
+The _tep_is_host_bigendian()_ function returns _TEP_LITTLE_ENDIAN_ or _TEP_BIG_ENDIAN_.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+     tep_set_host_bigendian(tep, TEP_LITTLE_ENDIAN);
+...
+     if (TEP_BIG_ENDIAN == tep_is_host_bigendian(tep)) {
+             /* The local host is big endian */
+     } else {
+             /* The local host is little endian */
+     }
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+LICENSE
+-------
+libtraceevent is Free Software licensed under the GNU LGPL 2.1
+
+RESOURCES
+---------
+https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgit.kernel.org%2Fpub%2Fscm%2Flinux%2Fkernel%2Fgit%2Ftorvalds%2Flinux.git&amp;data=02%7C01%7Ctstoyanov%40vmware.com%7C2264b262e74042761a7408d644463191%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C1%7C0%7C636771465608693415&amp;sdata=FjchU9EnZ007OWjCu%2BxigDoE0IOdwmefZ0y2tdyX5JE%3D&amp;reserved=0
Signature · 3 lines
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center
#9 lore raw

PATCH 5/7 tools/lib/traceevent: Implement libtraceevent man pages

In reply to Tzvetomir Stoyanov

This patch implements a man page, which documents tep_is_latency_format() and tep_set_latency_format() libtraceevent APIs

---
 .../libtraceevent-latency_format.txt          | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +98 -0
new file mode 100644
index 000000000000..a7eaed5d1a7e
@@ -0,0 +1,98 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_set_latency_format,tep_is_latency_format - Get / set "latency output" format.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_);
+int *tep_is_latency_format*(struct tep_handle pass:[*]_tep_);
+
+--
+
+DESCRIPTION
+-----------
+"Latency output" format prints information about interrupts being disabled, 
+soft irq being disabled, the "need_resched" flag being set, preempt count, 
+and big kernel lock. 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:['h'] means that this was called inside
+an interrupt handler. The pass:['1'] is the preemption disabled (preempt_count)
+was set to one.  The two pass:['.']s are "need_resched" flag and kernel lock
+counter. If the "need_resched" flag is set, then that character would be a pass:['N'].
+
+The _tep_is_latency_format()_ function returns if "latency output" is enabled.
+
+RETURN VALUE
+------------
+
+The _tep_is_latency_format()_ function returns non zero if "latency output" 
+is enabled, or zero if it is disabled.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_latency_format(tep, 1);
+...
+	if (tep_is_latency_format(tep)) {
+		/* latency output format is enabled */
+	} else {
+		/* latency output format is disabled */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
Signature · 1 line
2.17.2
#10 lore raw

Re: [PATCH 5/7] tools/lib/traceevent: Implement libtraceevent man pages

Quoted 29 lines · On Tue, 6 Nov 2018 13:20:54 +0000 Tzvetomir Stoyanov <[email protected]>…

This patch implements a man page, which documents tep_is_latency_format() and tep_set_latency_format() libtraceevent APIs

---
 .../libtraceevent-latency_format.txt          | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +13 -0
new file mode 100644
index 000000000000..a7eaed5d1a7e
@@ -0,0 +1,98 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_set_latency_format,tep_is_latency_format - Get / set "latency output" format.
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+

tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt line 23

Quoted 10 lines
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +10 -0
+void *tep_set_latency_format*(struct tep_handle pass:[*]_tep_, int _lat_);
+int *tep_is_latency_format*(struct tep_handle pass:[*]_tep_);
+
+--
+
+DESCRIPTION
+-----------
+"Latency output" format prints information about interrupts being disabled, 
+soft irq being disabled, the "need_resched" flag being set, preempt count, 
+and big kernel lock. This information is recorded with every event, but by 

The "big kernel lock" no longer exists (Yay!!!), we can remove that line.

tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt line 28

Quoted 5 lines
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +5 -0
+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.

Hmm, perhaps we should change that parameter to true or false.

Quoted 4 lines
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +4 -0
+Information is displayed with 6 characters. When a field is zero, or N/A, a pass:['.'] 
+is printed. Example:
+[verse]
+--

tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt line 42

Quoted 10 lines
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +10 -0
+  <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:['h'] means that this was called inside
+an interrupt handler. The pass:['1'] is the preemption disabled (preempt_count)
+was set to one.  The two pass:['.']s are "need_resched" flag and kernel lock
+counter. If the "need_resched" flag is set, then that character would be a pass:['N'].
+
+The _tep_is_latency_format()_ function returns if "latency output" is enabled.

We need to add somewhere in this description about tep_print_event_task() and tep_print_event_time() which is what this affects. As tep_print_event*() creates the string to output and is affected by this format.

We may change this before we release the final output.

-- Steve

Quoted 56 lines
tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt new file +56 -0
+
+RETURN VALUE
+------------
+
+The _tep_is_latency_format()_ function returns non zero if "latency output" 
+is enabled, or zero if it is disabled.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	tep_set_latency_format(tep, 1);
+...
+	if (tep_is_latency_format(tep)) {
+		/* latency output format is enabled */
+	} else {
+		/* latency output format is disabled */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
#11 lore raw

PATCH 6/7 tools/lib/traceevent: Implement libtraceevent man pages

In reply to Tzvetomir Stoyanov

This patch implements a man page, which documents
tep_get_page_size() and tep_set_page_size()
libtraceevent APIs

---
 .../Documentation/libtraceevent-page_size.txt | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
tools/lib/traceevent/Documentation/libtraceevent-page_size.txt new file +79 -0
new file mode 100644
index 000000000000..d2bad8dca42d
@@ -0,0 +1,79 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_page_size,tep_set_page_size - Get / set the size of a memory page on the 
+machine, where the trace is generated 
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);
+void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_page_size()_ function returns the size of a memory page on 
+the machine, where the trace is generated. The _tep_ argument is trace event parser context.
+
+The _tep_set_page_size()_ function sets the size of a memory page on the machine, 
+where the trace is generated. The _tep_ argument is trace event parser context.
+The _page_size_ argument is the size of a memory page, in bytes. 
+This information is saved in the trace.dat file. 
+
+RETURN VALUE
+------------
+The _tep_get_page_size()_ function returns size, in bytes, of the memory page.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	int page_size = 4096;
+	tep_set_page_size(tep, page_size);
+	if ( 4096 != tep_get_page_size(tep)) {
+		/* Something wrong happened, page size is not set as expected */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
Signature · 1 line
2.17.2
#12 lore raw

Re: [PATCH 6/7] tools/lib/traceevent: Implement libtraceevent man pages

Quoted 31 lines · On Tue, 6 Nov 2018 13:20:56 +0000 Tzvetomir Stoyanov <[email protected]>…

This patch implements a man page, which documents
tep_get_page_size() and tep_set_page_size()
libtraceevent APIs

---
 .../Documentation/libtraceevent-page_size.txt | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
tools/lib/traceevent/Documentation/libtraceevent-page_size.txt new file +15 -0
new file mode 100644
index 000000000000..d2bad8dca42d
@@ -0,0 +1,79 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_get_page_size,tep_set_page_size - Get / set the size of a memory page on the 
+machine, where the trace is generated 
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);

tools/lib/traceevent/Documentation/libtraceevent-page_size.txt line 25

Quoted 10 lines
tools/lib/traceevent/Documentation/libtraceevent-page_size.txt new file +10 -0
+void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
+--
+
+DESCRIPTION
+-----------
+The _tep_get_page_size()_ function returns the size of a memory page on 
+the machine, where the trace is generated. The _tep_ argument is trace event parser context.
+
+The _tep_set_page_size()_ function sets the size of a memory page on the machine, 
+where the trace is generated. The _tep_ argument is trace event parser context.

Note, we don't actually set the memory page size of the machine, that's already fixed ;-)

We use tep_set_page_size() to tell the tep handler what the page size is for the raw data it is parsing, and we use tep_get_page_size to retrieve what the page_size is for the handler. The get_page_size is used by plugins that need to know this information.

-- Steve

Quoted 54 lines
tools/lib/traceevent/Documentation/libtraceevent-page_size.txt new file +54 -0
+The _page_size_ argument is the size of a memory page, in bytes. 
+This information is saved in the trace.dat file. 
+
+RETURN VALUE
+------------
+The _tep_get_page_size()_ function returns size, in bytes, of the memory page.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+	int page_size = 4096;
+	tep_set_page_size(tep, page_size);
+	if ( 4096 != tep_get_page_size(tep)) {
+		/* Something wrong happened, page size is not set as expected */
+	}
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
#13 lore raw

PATCH 7/7 tools/lib/traceevent: Implement libtraceevent man pages

In reply to Tzvetomir Stoyanov

This patch implements a man page, which documents
tep_strerror() libtraceevent API

---
 .../Documentation/libtraceevent-strerror.txt  | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
tools/lib/traceevent/Documentation/libtraceevent-strerror.txt new file +82 -0
new file mode 100644
index 000000000000..4ac1bb2abe80
@@ -0,0 +1,82 @@
+libtraceevent(3)
+================
+
+NAME
+----
+tep_strerror - Returns string describing regular errno and tep error number. 
+
+SYNOPSIS
+--------
+[verse]
+--
+*#include <event-parse.h>*
+
+int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_);
+
+--
+DESCRIPTION
+-----------
+The _tep_strerror()_ function converts tep error number into a human readable string.
+The _tep_ argument is trace event parser context. The _errnum_ is a regular errno,
+defined in errno.h, or tep error number. The string, describing this error number 
+is copied in the _buf_ argument. The _buflen_ argument is the size of the _buf_.
+
+RETURN VALUE
+------------
+The _tep_strerror()_ function returns 0, if a valid _errnum_ is passed and the 
+string is copied into _buf_. If _errnum_ is not a valid error number, -1 is returned 
+and _buf_ is not modified.
+
+EXAMPLE
+-------
+[source,c]
+--
+#include <event-parse.h>
+...
+struct tep_handle *tep = tep_alloc();
+...
+char buf[32]; 
+char *pool = calloc(1, 128);
+if (NULL == tep) {
+	tep_strerror(tep, TEP_ERRNO__MEM_ALLOC_FAILED, buf, 32);
+	printf ("The pool is not initialized, %s", buf);
+}
+...
+--
+
+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* <[email protected]>, author of *libtraceevent*.
+*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
+--
+REPORTING BUGS
+--------------
+Report bugs to  <[email protected]>
+
+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
Signature · 1 line
2.17.2