[PATCH 0/4] trace-cmd libaray APIs and man pages

[PATCH 0/4] trace-cmd libaray APIs and man pages

[Tzvetomir Stoyanov (VMware)]

Added a few more trace-cmd library APIs and improved examples in the man
pages.

Tzvetomir Stoyanov (VMware) (4):
  trace-cmd library: Export 2 APIs for opening trace file
  trace-cmd: Remove tracecmd_unpair_peer() from internal header
  trace-cmd library man pages: Documented APIs for opening trace file
  trace-cmd library man pages: Extend the examples of reading host-guest
    trace data

 .../libtracecmd/libtracecmd-files.3.txt       | 89 +++++++++++++++++--
 .../libtracecmd/libtracecmd-peer.3.txt        | 56 ++++++++----
 .../libtracecmd/libtracecmd-record.3.txt      | 22 +----
 include/trace-cmd/trace-cmd.h                 |  2 +
 .../include/private/trace-cmd-private.h       |  3 -
 5 files changed, 123 insertions(+), 49 deletions(-)

-- 
2.29.2

[PATCH 1/4] trace-cmd library: Export 2 APIs for opening trace file

[Tzvetomir Stoyanov (VMware)]

Two additional internal functions are exported as trace-cmd library APIs
for opening a trace file:
  tracecmd_open();
  tracecmd_open_fd();
These new APIs complement the existing tracecmd_open_head() API.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 include/trace-cmd/trace-cmd.h                     | 2 ++
 lib/trace-cmd/include/private/trace-cmd-private.h | 2 --
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/trace-cmd/trace-cmd.h b/include/trace-cmd/trace-cmd.h
index 7dc88cb0..5a1ba6ba 100644
--- a/include/trace-cmd/trace-cmd.h
+++ b/include/trace-cmd/trace-cmd.h
@@ -12,6 +12,8 @@
 struct tracecmd_input;
 
 struct tracecmd_input *tracecmd_open_head(const char *file);
+struct tracecmd_input *tracecmd_open(const char *file);
+struct tracecmd_input *tracecmd_open_fd(int fd);
 void tracecmd_close(struct tracecmd_input *handle);
 int tracecmd_pair_peer(struct tracecmd_input *handle,
 		       struct tracecmd_input *peer);
diff --git a/lib/trace-cmd/include/private/trace-cmd-private.h b/lib/trace-cmd/include/private/trace-cmd-private.h
index 64945815..22e20b66 100644
--- a/lib/trace-cmd/include/private/trace-cmd-private.h
+++ b/lib/trace-cmd/include/private/trace-cmd-private.h
@@ -143,8 +143,6 @@ typedef void (*tracecmd_handle_init_func)(struct tracecmd_input *handle,
 
 struct tracecmd_input *tracecmd_alloc(const char *file);
 struct tracecmd_input *tracecmd_alloc_fd(int fd);
-struct tracecmd_input *tracecmd_open(const char *file);
-struct tracecmd_input *tracecmd_open_fd(int fd);
 void tracecmd_unpair_peer(struct tracecmd_input *handle);
 void tracecmd_ref(struct tracecmd_input *handle);
 int tracecmd_read_headers(struct tracecmd_input *handle);
-- 
2.29.2

[PATCH 2/4] trace-cmd: Remove tracecmd_unpair_peer() from internal header

[Tzvetomir Stoyanov (VMware)]

The tracecmd_unpair_peer() is an official API of trace-cmd library,
declared in trace-cmd.h. The declaration should not be duplicated in
trace-cmd internal header.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 lib/trace-cmd/include/private/trace-cmd-private.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/trace-cmd/include/private/trace-cmd-private.h b/lib/trace-cmd/include/private/trace-cmd-private.h
index 22e20b66..012ddba8 100644
--- a/lib/trace-cmd/include/private/trace-cmd-private.h
+++ b/lib/trace-cmd/include/private/trace-cmd-private.h
@@ -143,7 +143,6 @@ typedef void (*tracecmd_handle_init_func)(struct tracecmd_input *handle,
 
 struct tracecmd_input *tracecmd_alloc(const char *file);
 struct tracecmd_input *tracecmd_alloc_fd(int fd);
-void tracecmd_unpair_peer(struct tracecmd_input *handle);
 void tracecmd_ref(struct tracecmd_input *handle);
 int tracecmd_read_headers(struct tracecmd_input *handle);
 int tracecmd_get_parsing_failures(struct tracecmd_input *handle);
-- 
2.29.2

[PATCH 3/4] trace-cmd library man pages: Documented APIs for opening trace file

[Tzvetomir Stoyanov (VMware)]

Documented APIs:
 tracecmd_open()
 tracecmd_open_fd()

Moved tracecmd_init_data() documentation to more appropriate man page.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 .../libtracecmd/libtracecmd-files.3.txt       | 89 +++++++++++++++++--
 .../libtracecmd/libtracecmd-record.3.txt      | 22 +----
 2 files changed, 84 insertions(+), 27 deletions(-)

diff --git a/Documentation/libtracecmd/libtracecmd-files.3.txt b/Documentation/libtracecmd/libtracecmd-files.3.txt
index 75809223..c5f0ad0a 100644
--- a/Documentation/libtracecmd/libtracecmd-files.3.txt
+++ b/Documentation/libtracecmd/libtracecmd-files.3.txt
@@ -3,7 +3,8 @@ libtracecmd(3)
 
 NAME
 ----
-tracecmd_open_head, tracecmd_close - Open and close a trace file.
+tracecmd_open, tracecmd_open_fd, tracecmd_open_head, tracecmd_init_data,
+tracecmd_close - Open and close a trace file.
 
 SYNOPSIS
 --------
@@ -11,7 +12,10 @@ SYNOPSIS
 --
 *#include <trace-cmd.h>*
 
+struct tracecmd_input pass:[*]*tracecmd_open*(const char pass:[*]_file_);
+struct tracecmd_input pass:[*]*tracecmd_open_fd*(int _fd_);
 struct tracecmd_input pass:[*]*tracecmd_open_head*(const char pass:[*]_file_);
+int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
 void *tracecmd_close*(struct tracecmd_input pass:[*]_handle_);
 --
 
@@ -23,32 +27,99 @@ Linux kernel tracer. The opened file is represented by a _tracecmd_input_
 structure, all other library APIs that work with the file require a pointer
 to the structure.
 
-The _tracecmd_open_head()_ function opens a given trace _file_, parses the
-headers from the file, allocates and initializes _tracecmd_input_ structure
-representing the file.
+The _tracecmd_open()_ function opens a given trace _file_, parses the
+metadata headers from the file, allocates and initializes а _tracecmd_input_
+handler structure representing the file. It also initializes the handler
+for reading trace data from the file. The returned handler is ready to be
+used with _tracecmd_read__ APIs.
+
+The _tracecmd_open_fd()_ function does the same as _tracecmd_open()_, but
+works with a file descriptor to a trace file, opened for reading.
+
+The _tracecmd_open_head()_ function is the same as _tracecmd_open()_, but
+does not initialize the handler for reading trace data. It reads and parses
+the metadata headers only. The _tracecmd_init_data()_ should be used before
+using the _tracecmd_read__ APIs.
+
+The _tracecmd_init_data()_ function initializes a _handle_, allocated with
+_tracecmd_open_head()_, for reading trace data from the file associated with
+it. This API must be called before any of the _tracecmd_read__ APIs.
 
 The _tracecmd_close()_ function frees a _handle_, pointer to tracecmd_input
-structure, previously allocated with _tracecmd_open_head()_.
+structure, previously allocated with _tracecmd_open()_, _tracecmd_open_fd()_
+or _tracecmd_open_head()_ APIs.
 
 RETURN VALUE
 ------------
-The _tracecmd_open_head()_ function returns a pointer to tracecmd_input
-structure or NULL in case of an error. The returned structure must be free
-with _tracecmd_close()_.
+The _tracecmd_open()_, _tracecmd_open_fd()_ and _tracecmd_open_head()_
+functions return a pointer to tracecmd_input structure or NULL in case of
+an error. The returned structure must be free with _tracecmd_close()_.
+Note that if _tracecmd_open_fd()_ is used to allocate a tracecmd_input handler,
+when _tracecmd_close()_ is called to close it, that fd will be closed also.
+
+The _tracecmd_init_data()_ function returns -1 in case of an error or
+0 otherwise.
 
 EXAMPLE
 -------
 [source,c]
 --
+The are two different use patterns for opening and reading trace data from
+a trace file, which can be used depending on the use case.
+
+1. Open and initialise the trace file in а single step:
+
 #include <trace-cmd.h>
 ...
-struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+struct tracecmd_input *handle = tracecmd_open("trace.dat");
 	if (!handle) {
 		/* Failed to open trace.dat file */
 	}
+...
+	/* Read tracing data from the file, using the handle */
 ...
 	tracecmd_close(handle);
+...
+int fd;
+ 	fd = = open("trace.dat", O_RDONLY);
+ 	if (fd < 0) {
+ 		/* Failed to open trace file for reading */
+ 	}
+ 	handle = tracecmd_open_fd(fd);
+	if (!handle) {
+		close(fd);
+		/* Failed to initialise handler for reading the trace file */
+	}
+...
+	/* Read tracing data from the file, using the handle */
+...
+	tracecmd_close(handle);
+...
 
+2. Open and initialise the trace file in two steps. This allows to perform
+some processing based on metadata, read from the file, before initialising
+the trace data for reading. Example for such use case is when opening multiple
+trace files recorded in a same trace session. In that case timestamps of all
+trace events must be adjusted based on the information from  the file's metadata
+and before reading the trace data.
+
+#include <trace-cmd.h>
+...
+struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+	if (!handle) {
+		/* Failed to open trace.dat file */
+	}
+...
+	/* do some processing, before initialising the trace data for reading */
+...
+	if (tracecmd_init_data(handle) < 0) {
+		/* Failed to initialize hadle for reading the trace data */
+	}
+...
+	/* Read tracing data from the file, using the handle */
+...
+	tracecmd_close(handle);
+...
 --
 FILES
 -----
diff --git a/Documentation/libtracecmd/libtracecmd-record.3.txt b/Documentation/libtracecmd/libtracecmd-record.3.txt
index f25dd34c..aa1a4a66 100644
--- a/Documentation/libtracecmd/libtracecmd-record.3.txt
+++ b/Documentation/libtracecmd/libtracecmd-record.3.txt
@@ -3,9 +3,8 @@ libtracecmd(3)
 
 NAME
 ----
-tracecmd_init_data, tracecmd_read_cpu_first, tracecmd_read_data,
-tracecmd_read_at, tracecmd_free_record, tracecmd_get_tep
-- Read recorded events from a trace file.
+tracecmd_read_cpu_first, tracecmd_read_data, tracecmd_read_at,
+tracecmd_free_record, tracecmd_get_tep - Read recorded events from a trace file.
 
 SYNOPSIS
 --------
@@ -13,7 +12,6 @@ SYNOPSIS
 --
 *#include <trace-cmd.h>*
 
-int *tracecmd_init_data*(struct tracecmd_input pass:[*]_handle_);
 struct tep_record pass:[*]*tracecmd_read_cpu_first*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
 struct tep_record pass:[*]*tracecmd_read_data*(struct tracecmd_input pass:[*]_handle_, int _cpu_);
 struct tep_record pass:[*]*tracecmd_read_at*(struct tracecmd_input pass:[*]_handle_, unsigned long long _offset_, int pass:[*]_cpu_);
@@ -24,11 +22,7 @@ struct tep_handle pass:[*]*tracecmd_get_tep*(struct tracecmd_input pass:[*]_hand
 DESCRIPTION
 -----------
 This set of APIs can be used to read tracing data from a trace file opened
-with _tracecmd_open_head()(3)_
-
-The _tracecmd_init_data()_ function initializes the _handle_ for reading
-trace data from the file associated with it. This API must be called before
-any of the _tracecmd_read__ APIs.
+with _tracecmd_open()(3)_, _tracecmd_open_fd()(3)_ or _tracecmd_open_head()(3)_.
 
 The _tracecmd_read_cpu_first()_ function reads the first trace record
 for a given _cpu_ from a trace file associated with _handle_. The returned
@@ -54,9 +48,6 @@ _handle_.
 
 RETURN VALUE
 ------------
-The _tracecmd_init_data()_ function returns -1 in case of an error or
-0 otherwise.
-
 The _tracecmd_read_cpu_first()_, _tracecmd_read_data()_ and
 _tracecmd_read_at()_ functions return a pointer to struct tep_record or
 NULL in case of an error.The returned record must be freed with
@@ -72,7 +63,7 @@ EXAMPLE
 --
 #include <trace-cmd.h>
 ...
-struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
+struct tracecmd_input *handle = tracecmd_open("trace.dat");
 	if (!handle) {
 		/* Failed to open trace.dat file */
 	}
@@ -80,11 +71,6 @@ struct tracecmd_input *handle = tracecmd_open_head("trace.dat");
 unsigned long long offset = 0;
 struct tep_record *rec;
 int cpu = 0;
-
-	if (tracecmd_init_data(handle) < 0) {
-		/* Failed to initialize hadle for reading the trace data */
-	}
-
 	rec = tracecmd_read_cpu_first(handle, cpu);
 	while (rec) {
 		...
-- 
2.29.2

[PATCH 4/4] trace-cmd library man pages: Extend the examples of reading host-guest trace data

[Tzvetomir Stoyanov (VMware)]

The trace-cmd library supports reading trace data from a host and
multiple guest machines as a single trace session, if they are recorded
at the same time. Added more relevant example in the man page, showing
that use case.

Signed-off-by: Tzvetomir Stoyanov (VMware) <tz.stoyanov@gmail.com>
---
 .../libtracecmd/libtracecmd-peer.3.txt        | 56 ++++++++++++-------
 1 file changed, 37 insertions(+), 19 deletions(-)

diff --git a/Documentation/libtracecmd/libtracecmd-peer.3.txt b/Documentation/libtracecmd/libtracecmd-peer.3.txt
index 5cb0c4fa..6cf34f9b 100644
--- a/Documentation/libtracecmd/libtracecmd-peer.3.txt
+++ b/Documentation/libtracecmd/libtracecmd-peer.3.txt
@@ -74,36 +74,54 @@ EXAMPLE
 --
 #include <trace-cmd.h>
 ...
-struct tracecmd_input *host = tracecmd_open_head("trace.dat");
+struct tracecmd_input *host = tracecmd_open("trace.dat");
 	if (!host) {
 		/* Failed to open host trace file */
 	}
-	tracecmd_init_data(host);
 
-struct tracecmd_input *guest = tracecmd_open_head("trace-Guest.dat");
-	if (!guest) {
-		/* Failed to open guest trace file */
+struct tracecmd_input *guest1 = tracecmd_open_head("trace-Guest1.dat");
+	if (!guest1) {
+		/* Failed to open guest1 trace file */
+	}
+struct tracecmd_input *guest2 = tracecmd_open_head("trace-Guest2.dat");
+	if (!guest2) {
+		/* Failed to open guest2 trace file */
 	}
 
-unsigned long long guest_id = tracecmd_get_traceid(guest);
-int *cpu_pid;
-char *name;
-int vcount;
+unsigned long long guest_id_1 = tracecmd_get_traceid(guest1);
+unsigned long long guest_id_2 = tracecmd_get_traceid(guest2);
+bool g1 = false, g2 = false;
+int *cpu_pid_1, *cpu_pid_2;
+int vcount_1, vcount_2;
+char *name_1, *name_2;
 
-	if (!tracecmd_get_guest_cpumap(host, guest_id, &name, &vcount, &cpu_pid)) {
-		/* The Host and a guest with name was part of the same trace session.
-		 * Got guest VCPU to host PID mapping.
+	if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name_1, &vcount_1, &cpu_pid_1)) {
+		/* The Host and a guest1 with name_1 are part of the same trace session.
+		 * Got guest1 VCPU to host PID mapping.
 		 */
-		if (!tracecmd_pair_peer(guest, host)) {
-			/* Successfully paired host to the guest handler */
-			tracecmd_init_data(guest);
-			...
-			tracecmd_unpair_peer(guest);
+		if (!tracecmd_pair_peer(guest1, host)) {
+			/* Successfully paired guest1 to the host handler */
+			tracecmd_init_data(guest1);
+			g1 = true;
+		}
+	}
+	if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name_2, &vcount_2, &cpu_pid_2)) {
+		/* The Host and a guest2 with name_2 are part of the same trace session.
+		 * Got guest2 VCPU to host PID mapping.
+		 */
+		if (!tracecmd_pair_peer(guest2, host)) {
+			/* Successfully paired guest2 to the host handler */
+			tracecmd_init_data(guest2);
+			g2 = true;
 		}
 	}
-
 ...
-	tracecmd_close(guest);
+	if (g1)
+		tracecmd_unpair_peer(guest1);
+	if (g2)
+		tracecmd_unpair_peer(guest2);
+	tracecmd_close(guest1);
+	tracecmd_close(guest2);
 	tracecmd_close(handle);
 
 --
-- 
2.29.2