1libtracecmd(3) 2============= 3 4NAME 5---- 6tracecmd_get_traceid, tracecmd_get_guest_cpumap - Manage trace session with multiple trace peers, 7recorded in multiple trace files. 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <trace-cmd.h>* 14 15unsigned long long *tracecmd_get_traceid*(struct tracecmd_input pass:[*]_handle_); 16int *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_); 17-- 18 19DESCRIPTION 20----------- 21This set of APIs can be used to manage a trace session with multiple trace 22peers, for example, tracing both a host and one or more guest virtual machines. 23The trace data of each peer from the session is recorded in separate trace files. 24Information about peers from the session is stored in the metadata of each 25trace file. These APIs use that information to extract and synchronize 26the trace data. 27 28The _tracecmd_get_traceid()_ function returns the trace ID stored in 29the trace file metadata associated with _handle_. Each peer from a trace 30session has an ID unique for that peer and that trace session only. 31This ID is used to match multiple trace files recorded in a same trace 32session. 33 34The _tracecmd_get_guest_cpumap()_ function gets the mapping of guest 35virtual CPUs (VCPU) to the host process that represents those VCPUs and is 36stored in the metadata of the trace file associated with _handle_. This 37information is gathered during a host-guest trace session and is stored 38in the host trace file. The _trace_id_ parameter is the trace ID of the guest 39in this particular trace session. If a guest with that ID was part of that 40session, its VCPU to host process mapping is in the host trace file and the 41information is returned in _name_, _vcpu_count_ and _cpu_pid_ parameters. 42The _name_ parameter contains the name of the guest, the _vcpu_count_ contains 43the count of VCPUs of that guest and the _cpu_pid_ array contains the VCPU to 44host process mapping. The array is of size _vcpu_count_ where the index is VCPU 45and the value is the process ID (PID) of the host process, running that VCPU. 46The _name_, _vcpu_count_ and _cpu_pid_ values must *not* be freed. 47 48RETURN VALUE 49------------ 50The _tracecmd_get_traceid()_ function returns a 64 bit trace ID. 51 52The _tracecmd_get_guest_cpumap()_ function returns -1 in case of 53an error or 0 otherwise. If 0 is returned, then the _name_, _vcpu_count_ 54and _cpu_pid_ parameters contain the requested information. 55 56EXAMPLE 57------- 58[source,c] 59-- 60#include <trace-cmd.h> 61... 62struct tracecmd_input *host = tracecmd_open("trace.dat"); 63 if (!host) { 64 /* Failed to open host trace file */ 65 } 66 67struct tracecmd_input *guest1 = tracecmd_open_head("trace-Guest1.dat"); 68 if (!guest1) { 69 /* Failed to open guest1 trace file */ 70 } 71struct tracecmd_input *guest2 = tracecmd_open_head("trace-Guest2.dat"); 72 if (!guest2) { 73 /* Failed to open guest2 trace file */ 74 } 75 76unsigned long long guest_id_1 = tracecmd_get_traceid(guest1); 77unsigned long long guest_id_2 = tracecmd_get_traceid(guest2); 78int *cpu_pid_1, *cpu_pid_2; 79int vcount_1, vcount_2; 80char *name_1, *name_2; 81 82 if (!tracecmd_get_guest_cpumap(host, guest_id_1, &name_1, &vcount_1, &cpu_pid_1)) { 83 /* The Host and a guest1 with name_1 are part of the same trace session. 84 * Got guest1 VCPU to host PID mapping. 85 */ 86 } 87 if (!tracecmd_get_guest_cpumap(host, guest_id_2, &name_2, &vcount_2, &cpu_pid_2)) { 88 /* The Host and a guest2 with name_2 are part of the same trace session. 89 * Got guest2 VCPU to host PID mapping. 90 */ 91 } 92... 93 tracecmd_close(guest1); 94 tracecmd_close(guest2); 95 tracecmd_close(handle); 96 97-- 98FILES 99----- 100[verse] 101-- 102*trace-cmd.h* 103 Header file to include in order to have access to the library APIs. 104*-ltracecmd* 105 Linker switch to add when building a program that uses the library. 106-- 107 108SEE ALSO 109-------- 110_libtracefs(3)_, 111_libtraceevent(3)_, 112_trace-cmd(1)_ 113_trace-cmd.dat(5)_ 114 115AUTHOR 116------ 117[verse] 118-- 119*Steven Rostedt* <[email protected]> 120*Tzvetomir Stoyanov* <[email protected]> 121-- 122REPORTING BUGS 123-------------- 124Report bugs to <[email protected]> 125 126LICENSE 127------- 128libtracecmd is Free Software licensed under the GNU LGPL 2.1 129 130RESOURCES 131--------- 132https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/ 133 134COPYING 135------- 136Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 137the terms of the GNU Public License (GPL). 138