* [PATCH 3/4] trace-cmd library man pages: Documented APIs for opening trace file
2021-01-21 10:36 [PATCH 0/4] trace-cmd libaray APIs and man pages Tzvetomir Stoyanov (VMware)
2021-01-21 10:36 ` [PATCH 1/4] trace-cmd library: Export 2 APIs for opening trace file Tzvetomir Stoyanov (VMware)
2021-01-21 10:36 ` [PATCH 2/4] trace-cmd: Remove tracecmd_unpair_peer() from internal header Tzvetomir Stoyanov (VMware)
@ 2021-01-21 10:36 ` Tzvetomir Stoyanov (VMware)
2021-01-21 10:36 ` [PATCH 4/4] trace-cmd library man pages: Extend the examples of reading host-guest trace data Tzvetomir Stoyanov (VMware)
3 siblings, 0 replies; 5+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2021-01-21 10:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
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
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 4/4] trace-cmd library man pages: Extend the examples of reading host-guest trace data
2021-01-21 10:36 [PATCH 0/4] trace-cmd libaray APIs and man pages Tzvetomir Stoyanov (VMware)
` (2 preceding siblings ...)
2021-01-21 10:36 ` [PATCH 3/4] trace-cmd library man pages: Documented APIs for opening trace file Tzvetomir Stoyanov (VMware)
@ 2021-01-21 10:36 ` Tzvetomir Stoyanov (VMware)
3 siblings, 0 replies; 5+ messages in thread
From: Tzvetomir Stoyanov (VMware) @ 2021-01-21 10:36 UTC (permalink / raw)
To: rostedt; +Cc: linux-trace-devel
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
^ permalink raw reply related [flat|nested] 5+ messages in thread