138 lines
4.3 KiB
Plaintext
138 lines
4.3 KiB
Plaintext
|
libtracecmd(3)
|
||
|
|
=============
|
||
|
|
|
||
|
|
NAME
|
||
|
|
----
|
||
|
|
tracecmd_get_traceid, tracecmd_get_guest_cpumap - Manage trace session with multiple trace peers,
|
||
|
|
recorded in multiple trace files.
|
||
|
|
|
||
|
|
SYNOPSIS
|
||
|
|
--------
|
||
|
|
[verse]
|
||
|
|
--
|
||
|
|
*#include <trace-cmd.h>*
|
||
|
|
|
||
|
|
unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_);
|
||
|
|
int *tracecmd_get_guest_cpumap*(struct tracecmd_input pass:[*]_handle_, unsigned long long _trace_id_, const char pass:[*]pass:[*]_name_, int pass:[*]_vcpu_count_, const int pass:[*]pass:[*]_cpu_pid_);
|
||
|
|
--
|
||
|
|
|
||
|
|
DESCRIPTION
|
||
|
|
-----------
|
||
|
|
This set of APIs can be used to manage a trace session with multiple trace
|
||
|
|
peers, for example, tracing both a host and one or more guest virtual machines.
|
||
|
|
The trace data of each peer from the session is recorded in separate trace files.
|
||
|
|
Information about peers from the session is stored in the metadata of each
|
||
|
|
trace file. These APIs use that information to extract and synchronize
|
||
|
|
the trace data.
|
||
|
|
|
||
|
|
The _tracecmd_get_traceid()_ function returns the trace ID stored in
|
||
|
|
the trace file metadata associated with _handle_. Each peer from a trace
|
||
|
|
session has an ID unique for that peer and that trace session only.
|
||
|
|
This ID is used to match multiple trace files recorded in a same trace
|
||
|
|
session.
|
||
|
|
|
||
|
|
The _tracecmd_get_guest_cpumap()_ function gets the mapping of guest
|
||
|
|
virtual CPUs (VCPU) to the host process that represents those VCPUs and is
|
||
|
|
stored in the metadata of the trace file associated with _handle_. This
|
||
|
|
information is gathered during a host-guest trace session and is stored
|
||
|
|
in the host trace file. The _trace_id_ parameter is the trace ID of the guest
|
||
|
|
in this particular trace session. If a guest with that ID was part of that
|
||
|
|
session, its VCPU to host process mapping is in the host trace file and the
|
||
|
|
information is returned in _name_, _vcpu_count_ and _cpu_pid_ parameters.
|
||
|
|
The _name_ parameter contains the name of the guest, the _vcpu_count_ contains
|
||
|
|
the count of VCPUs of that guest and the _cpu_pid_ array contains the VCPU to
|
||
|
|
host process mapping. The array is of size _vcpu_count_ where the index is VCPU
|
||
|
|
and the value is the process ID (PID) of the host process, running that VCPU.
|
||
|
|
The _name_, _vcpu_count_ and _cpu_pid_ values must *not* be freed.
|
||
|
|
|
||
|
|
RETURN VALUE
|
||
|
|
------------
|
||
|
|
The _tracecmd_get_traceid()_ function returns a 64 bit trace ID.
|
||
|
|
|
||
|
|
The _tracecmd_get_guest_cpumap()_ function returns -1 in case of
|
||
|
|
an error or 0 otherwise. If 0 is returned, then the _name_, _vcpu_count_
|
||
|
|
and _cpu_pid_ parameters contain the requested information.
|
||
|
|
|
||
|
|
EXAMPLE
|
||
|
|
-------
|
||
|
|
[source,c]
|
||
|
|
--
|
||
|
|
#include <trace-cmd.h>
|
||
|
|
...
|
||
|
|
struct tracecmd_input *host = tracecmd_open("trace.dat");
|
||
|
|
if (!host) {
|
||
|
|
/* Failed to open host 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_1 = tracecmd_get_traceid(guest1);
|
||
|
|
unsigned long long guest_id_2 = tracecmd_get_traceid(guest2);
|
||
|
|
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_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_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.
|
||
|
|
*/
|
||
|
|
}
|
||
|
|
...
|
||
|
|
tracecmd_close(guest1);
|
||
|
|
tracecmd_close(guest2);
|
||
|
|
tracecmd_close(handle);
|
||
|
|
|
||
|
|
--
|
||
|
|
FILES
|
||
|
|
-----
|
||
|
|
[verse]
|
||
|
|
--
|
||
|
|
*trace-cmd.h*
|
||
|
|
Header file to include in order to have access to the library APIs.
|
||
|
|
*-ltracecmd*
|
||
|
|
Linker switch to add when building a program that uses the library.
|
||
|
|
--
|
||
|
|
|
||
|
|
SEE ALSO
|
||
|
|
--------
|
||
|
|
_libtracefs(3)_,
|
||
|
|
_libtraceevent(3)_,
|
||
|
|
_trace-cmd(1)_
|
||
|
|
_trace-cmd.dat(5)_
|
||
|
|
|
||
|
|
AUTHOR
|
||
|
|
------
|
||
|
|
[verse]
|
||
|
|
--
|
||
|
|
*Steven Rostedt* <rostedt@goodmis.org>
|
||
|
|
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
|
||
|
|
--
|
||
|
|
REPORTING BUGS
|
||
|
|
--------------
|
||
|
|
Report bugs to <linux-trace-devel@vger.kernel.org>
|
||
|
|
|
||
|
|
LICENSE
|
||
|
|
-------
|
||
|
|
libtracecmd is Free Software licensed under the GNU LGPL 2.1
|
||
|
|
|
||
|
|
RESOURCES
|
||
|
|
---------
|
||
|
|
https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
|
||
|
|
|
||
|
|
COPYING
|
||
|
|
-------
|
||
|
|
Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
|
||
|
|
the terms of the GNU Public License (GPL).
|