xref: /external/trace-cmd/Documentation/libtracecmd/libtracecmd-maps.txt

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 <trace-cmd.h>*

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 <stdlib.h>
#include <errno.h>
#include <trace-cmd.h>

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  <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).