'\" t
.\" Title: libtracecmd
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 02/10/2024
.\" Manual: libtracefs Manual
.\" Source: libtracefs
.\" Language: English
.\"
.TH "LIBTRACECMD" "3" "02/10/2024" "libtracefs" "libtracefs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "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
.SH "SYNOPSIS"
.sp
.nf
\fB#include \fR
int \fBtracecmd_map_vcpus\fR(struct tracecmd_input **handles, int nr_handles);
struct tracecmd_cpu_map *\fBtracecmd_get_cpu_map\fR(struct tracecmd_input *handle, int cpu);
struct tracecmd_cpu_map *\fBtracecmd_map_find_by_host_pid\fR(struct tracecmd_input *handle,
int host_pid);
int \fBtracecmd_map_get_host_pid\fR(struct tracecmd_cpu_map *map);
struct tracecmd_input *\fBtracecmd_map_get_guest\fR(struct tracecmd_cpu_map *map);
void \fBtracecmd_map_set_private\fR(struct tracecmd_cpu_map *map, void *priv);
void *\fBtracecmd_map_get_private\fR(struct tracecmd_cpu_map *map);
.fi
.SH "DESCRIPTION"
.sp
This set of APIs is used to map host and guest trace files for to facilitate further tracing analysis\&.
.sp
The \fBtracecmd_map_vcpus()\fR takes an array of \fIhandles\fR where each item in that array was created by one of the \fBtracecmd_open(3)\fR functions, and the number of handles as \fInr_handles\fR\&. The first handle in the array of \fIhandles\fR 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 \fBtrace\-cmd record(1)\fR and \fBtrace\-cmd agent(1)\fR interactions\&. It returns the number of guests found in \fIhandles\fR that were associated with the host, or negative on error\&.
.sp
The \fBtracecmd_get_cpu_map()\fR returns a descriptor for a given CPU for a handle\&. If the \fIhandle\fR was a guest defined from \fBtracecmd_map_vcpus()\fR then the mapping created from that function that is associated to this particular vCPU (denoted by \fIcpu\fR) from \fIhandle\fR\&. This destriptor can be used by \fBtarcecmd_map_get_guest()\fR, \fBtracecmd_map_set_private()\fR and \fBtracecmd_map_get_private()\fR functions\&.
.sp
The \fBtracecmd_map_find_by_host_pid()\fR will return a mapping for a guest virtual CPU that is handled by the given \fIhost_pid\fR\&. Note, the \fIhandle\fR passed in can be either the host handle or one of the guest\(cqs handles for that host that was mapped by \fBtracecmd_map_vcpus()\fR, even if the guest handle does not have the vCPU that the \fIhost_pid\fR represents\&.
.sp
The \fBtracecmd_map_get_host_pid()\fR will recturn the host_pid for a given \fImap\fR that was retrieved by one of the above functions\&.
.sp
The \fBtracecmd_map_get_guest()\fR will recturn the guest_handle for a given \fImap\fR that was retrieved by one of the above functions\&.
.sp
The \fBtracecmd_map_set_private()\fR allows the application to assign private data for a given guest vCPU to host thread mapping defined by \fImap\fR\&.
.sp
The \fBtracecmd_map_get_private()\fR retrieves the \fIpriv\fR data from \fImap\fR that was set by \fBtracecmd_map_set_private()\fR\&.
.SH "RETURN VALUE"
.sp
\fBtracecmd_map_vcpus()\fR returns the number of guests in the \fIhandles\fR array that were mapped to the host handle that is the first entry in \fIhandles\fR\&. It returns \-1 on error\&.
.sp
\fBtracecmd_get_cpu_map()\fR returns a map created by \fBtracecmd_map_vcpus()\fR for a given \fIcpu\fR for a given \fIhandle\fR, or NULL if it is not found\&.
.sp
\fBtracecmd_map_find_by_host_pid()\fR returns a map that is associated by the host task with \fIhost_pid\fR as its process ID\&. \fIhandle\fR can be either a the host handle, or one of the guest handles that were mapped to the host via \fBtracecmd_map_vcpus()\fR, even if the guest handle is another guest than the one that the mapping is for\&. It returns NULL if not found\&.
.sp
\fBtracecmd_map_get_host_pid()\fR returns the host process ID for an associated mapping defined by \fImap\fR\&.
.sp
\fBtracecmd_map_get_guest()\fR returns the guest handle for an associated mapping defined by \fImap\fR\&.
.sp
\fBtracecmd_map_get_private()\fR returns the private data of a mapping defined by \fImap\fR that was set by \fBtracecmd_map_set_private()\fR\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#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 \&.\&.\&.]\en");
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:\en", 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!\en");
continue;
}
printf("host_pid: %d\en", tracecmd_map_get_host_pid(map));
}
}
for (i = 0; i < nr_handles; i++)
tracecmd_close(handles[i]);
free(handles);
exit(0);
}
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBtrace\-cmd\&.h\fR
Header file to include in order to have access to the library APIs\&.
\fB\-ltracecmd\fR
Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBlibtracefs(3)\fR, \fBlibtraceevent(3)\fR, \fBtrace\-cmd(1)\fR \fBtrace\-cmd\&.dat(5)\fR
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
.SH "LICENSE"
.sp
libtracecmd is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/utils/trace\-cmd/trace\-cmd\&.git/\fR\m[]
.SH "COPYING"
.sp
Copyright (C) 2020 VMware, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.
.SH "NOTES"
.IP " 1." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE