libtracecmd(3) ============= NAME ---- tracecmd_map_vcpus, tracecmd_get_cpu_map, tracecmd_map_find_by_host_pid, tracecmd_map_get_host_pid, tracecmd_map_get_guest, tracecmd_map_set_private, tracecmd_map_get_private - Mapping host and guest data SYNOPSIS -------- [verse] -- *#include * int *tracecmd_map_vcpus*(struct tracecmd_input pass:[**]handles, int nr_handles); struct tracecmd_cpu_map pass:[*]*tracecmd_get_cpu_map*(struct tracecmd_input pass:[*]handle, int cpu); struct tracecmd_cpu_map pass:[*]*tracecmd_map_find_by_host_pid*(struct tracecmd_input pass:[*]handle, int host_pid); int *tracecmd_map_get_host_pid*(struct tracecmd_cpu_map pass:[*]map); struct tracecmd_input pass:[*]*tracecmd_map_get_guest*(struct tracecmd_cpu_map pass:[*]map); void *tracecmd_map_set_private*(struct tracecmd_cpu_map pass:[*]map, void pass:[*]priv); void pass:[*]*tracecmd_map_get_private*(struct tracecmd_cpu_map pass:[*]map); -- DESCRIPTION ----------- This set of APIs is used to map host and guest trace files for to facilitate further tracing analysis. The *tracecmd_map_vcpus()* takes an array of _handles_ where each item in that array was created by one of the *tracecmd_open(3)* functions, and the number of handles as _nr_handles_. The first handle in the array of _handles_ is expected to be the descriptor for the host tracing file, and the rest are guest trace files that run on the host, and were created by the *trace-cmd record(1)* and *trace-cmd agent(1)* interactions. It returns the number of guests found in _handles_ that were associated with the host, or negative on error. The *tracecmd_get_cpu_map()* returns a descriptor for a given CPU for a handle. If the _handle_ was a guest defined from *tracecmd_map_vcpus()* then the mapping created from that function that is associated to this particular vCPU (denoted by _cpu_) from _handle_. This destriptor can be used by *tarcecmd_map_get_guest()*, *tracecmd_map_set_private()* and *tracecmd_map_get_private()* functions. The *tracecmd_map_find_by_host_pid()* will return a mapping for a guest virtual CPU that is handled by the given _host_pid_. Note, the _handle_ passed in can be either the host handle or one of the guest's handles for that host that was mapped by *tracecmd_map_vcpus()*, even if the guest handle does not have the vCPU that the _host_pid_ represents. The *tracecmd_map_get_host_pid()* will recturn the host_pid for a given _map_ that was retrieved by one of the above functions. The *tracecmd_map_get_guest()* will recturn the guest_handle for a given _map_ that was retrieved by one of the above functions. The *tracecmd_map_set_private()* allows the application to assign private data for a given guest vCPU to host thread mapping defined by _map_. The *tracecmd_map_get_private()* retrieves the _priv_ data from _map_ that was set by *tracecmd_map_set_private()*. RETURN VALUE ------------ *tracecmd_map_vcpus()* returns the number of guests in the _handles_ array that were mapped to the host handle that is the first entry in _handles_. It returns -1 on error. *tracecmd_get_cpu_map()* returns a map created by *tracecmd_map_vcpus()* for a given _cpu_ for a given _handle_, or NULL if it is not found. *tracecmd_map_find_by_host_pid()* returns a map that is associated by the host task with _host_pid_ as its process ID. _handle_ can be either a the host handle, or one of the guest handles that were mapped to the host via *tracecmd_map_vcpus()*, even if the guest handle is another guest than the one that the mapping is for. It returns NULL if not found. *tracecmd_map_get_host_pid()* returns the host process ID for an associated mapping defined by _map_. *tracecmd_map_get_guest()* returns the guest handle for an associated mapping defined by _map_. *tracecmd_map_get_private()* returns the private data of a mapping defined by _map_ that was set by *tracecmd_map_set_private()*. EXAMPLE ------- [source,c] -- #include #include #include int main(int argc, char **argv) { struct tracecmd_input **handles = NULL; int nr_handles; int i; if (argc < 2) { printf("usage: host_trace.dat guest1_trace.dat [guest2_trace.dat ...]\n"); exit(-1); } for (i = 1; i < argc; i++) { handles = realloc(handles, sizeof(*handles) * (nr_handles + 1)); if (!handles) exit(-1); handles[nr_handles] = tracecmd_open(argv[i], 0); if (!handles[nr_handles]) { perror(argv[1]); exit(-1); } tracecmd_set_private(handles[nr_handles], argv[i]); nr_handles++; } tracecmd_map_vcpus(handles, nr_handles); for (i = 1; i < nr_handles; i++) { struct tracecmd_cpu_map *map; struct tep_handle *tep; const char *file = tracecmd_get_private(handles[i]); int cpus, cpu; printf("Mappings for guest %s:\n", file); tep = tracecmd_get_tep(handles[i]); cpus = tep_get_cpus(tep); for (cpu = 0; cpu < cpus; cpu++) { printf(" [%03d] ", cpu); map = tracecmd_get_cpu_map(handles[i], cpu); if (!map) { printf("Has no mapping!\n"); continue; } printf("host_pid: %d\n", tracecmd_map_get_host_pid(map)); } } for (i = 0; i < nr_handles; i++) tracecmd_close(handles[i]); free(handles); exit(0); } -- 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)* REPORTING BUGS -------------- Report bugs to 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).