[PATCH 0/7] libtracevent man pages

[PATCH 0/7] libtracevent man pages

[Tzvetomir Stoyanov]

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

-- 
2.17.2

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../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

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
new file mode 100644
index 000000000000..8edf49d2a709
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-header_size.txt
@@ -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* <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-api.c b/tools/lib/traceevent/event-parse-api.c
index 6a1899b378b1..39e0fca2d9a2 100644
--- a/tools/lib/traceevent/event-parse-api.c
+++ b/tools/lib/traceevent/event-parse-api.c
@@ -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)
-- 
2.17.2

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../Documentation/libtraceevent-cpus.txt      | 78 +++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
new file mode 100644
index 000000000000..f9ed0a02d653
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
@@ -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* <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.17.2

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

[Steven Rostedt]

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

On Tue, 6 Nov 2018 13:20:51 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> 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".



> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  .../Documentation/libtraceevent-cpus.txt      | 78 +++++++++++++++++++
>  1 file changed, 78 insertions(+)
>  create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
> 
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
> new file mode 100644
> index 000000000000..f9ed0a02d653
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-cpus.txt
> @@ -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"

> +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 

" function gets the"

> +data recorded. The _tep_ argument is trace event parser context.

 "data recorded in the _tep_ context."

> +
> +The _tep_set_cpus()_ functions sets the number of CPUs, which have tracing 

 " function sets"

> +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


> +
> +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* <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

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../libtraceevent-file_endian.txt             | 87 +++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
new file mode 100644
index 000000000000..403db4e23b3f
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
@@ -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* <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.17.2

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

[Steven Rostedt]

On Tue, 6 Nov 2018 13:20:52 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> This patch implements a man page, which documents
> tep_is_file_bigendian() and tep_set_file_bigendian()
> libtraceevent APIs
> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  .../libtraceevent-file_endian.txt             | 87 +++++++++++++++++++
>  1 file changed, 87 insertions(+)
>  create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
> 
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
> new file mode 100644
> index 000000000000..403db4e23b3f
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-file_endian.txt
> @@ -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


> +
> +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* <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

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../libtraceevent-host_endian.txt             | 85 +++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
new file mode 100644
index 000000000000..23e085db8d54
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
@@ -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* <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.17.2

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

[Steven Rostedt]

On Tue, 6 Nov 2018 13:20:53 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> This patch implements a man page, which documents
> tep_is_host_bigendian() and tep_set_host_bigendian()
> libtraceevent APIs
> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  .../libtraceevent-host_endian.txt             | 85 +++++++++++++++++++
>  1 file changed, 85 insertions(+)
>  create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> 
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> new file mode 100644
> index 000000000000..23e085db8d54
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> @@ -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


> +
> +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* <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

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

[Tzvetomir Stoyanov]

On Wed, Nov 7, 2018 at 2:15 AM Steven Rostedt <rostedt@goodmis.org> wrote:
>
> On Tue, 6 Nov 2018 13:20:53 +0000
> Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:
>
> > This patch implements a man page, which documents
> > tep_is_host_bigendian() and tep_set_host_bigendian()
> > libtraceevent APIs
> >
> > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> > ---
> >  .../libtraceevent-host_endian.txt             | 85 +++++++++++++++++++
> >  1 file changed, 85 insertions(+)
> >  create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> >
> > diff --git a/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> > new file mode 100644
> > index 000000000000..23e085db8d54
> > --- /dev/null
> > +++ b/tools/lib/traceevent/Documentation/libtraceevent-host_endian.txt
> > @@ -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 ?

>
> -- Steve
>
>
> > +
> > +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* <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://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
>


-- 
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../libtraceevent-latency_format.txt          | 98 +++++++++++++++++++
 1 file changed, 98 insertions(+)
 create 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
new file mode 100644
index 000000000000..a7eaed5d1a7e
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
@@ -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* <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.17.2

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

[Steven Rostedt]

On Tue, 6 Nov 2018 13:20:54 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> This patch implements a man page, which documents
> tep_is_latency_format() and tep_set_latency_format()
> libtraceevent APIs
> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  .../libtraceevent-latency_format.txt          | 98 +++++++++++++++++++
>  1 file changed, 98 insertions(+)
>  create 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
> new file mode 100644
> index 000000000000..a7eaed5d1a7e
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-latency_format.txt
> @@ -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 

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

> +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.

> +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.

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

> +
> +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* <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

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../Documentation/libtraceevent-page_size.txt | 79 +++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
new file mode 100644
index 000000000000..d2bad8dca42d
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
@@ -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* <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.17.2

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

[Steven Rostedt]

On Tue, 6 Nov 2018 13:20:56 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> This patch implements a man page, which documents
> tep_get_page_size() and tep_set_page_size()
> libtraceevent APIs
> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  .../Documentation/libtraceevent-page_size.txt | 79 +++++++++++++++++++
>  1 file changed, 79 insertions(+)
>  create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
> 
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
> new file mode 100644
> index 000000000000..d2bad8dca42d
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-page_size.txt
> @@ -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.

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




> +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* <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

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

[Tzvetomir Stoyanov]

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

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 .../Documentation/libtraceevent-strerror.txt  | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-strerror.txt

diff --git a/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
new file mode 100644
index 000000000000..4ac1bb2abe80
--- /dev/null
+++ b/tools/lib/traceevent/Documentation/libtraceevent-strerror.txt
@@ -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* <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.17.2