1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
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).
|
