1LIBTRACECMD(3) libtracefs Manual LIBTRACECMD(3)
2
6 tracecmd_map_vcpus, tracecmd_get_cpu_map,
7 tracecmd_map_find_by_host_pid, tracecmd_map_get_host_pid,
8 tracecmd_map_get_guest, tracecmd_map_set_private,
9 tracecmd_map_get_private - Mapping host and guest data
10
12 #include <trace-cmd.h>
13 int tracecmd_map_vcpus(struct tracecmd_input **handles, int nr_handles);
15 struct tracecmd_cpu_map *tracecmd_get_cpu_map(struct tracecmd_input *handle, int cpu);
16 struct tracecmd_cpu_map *tracecmd_map_find_by_host_pid(struct tracecmd_input *handle,
17 int host_pid);
18 int tracecmd_map_get_host_pid(struct tracecmd_cpu_map *map);
19 struct tracecmd_input *tracecmd_map_get_guest(struct tracecmd_cpu_map *map);
20 void tracecmd_map_set_private(struct tracecmd_cpu_map *map, void *priv);
21 void *tracecmd_map_get_private(struct tracecmd_cpu_map *map);
22
24 This set of APIs is used to map host and guest trace files for to
25 facilitate further tracing analysis.
26 The tracecmd_map_vcpus() takes an array of handles where each item in
28 that array was created by one of the tracecmd_open(3) functions, and
29 the number of handles as nr_handles. The first handle in the array of
30 handles is expected to be the descriptor for the host tracing file, and
31 the rest are guest trace files that run on the host, and were created
32 by the trace-cmd record(1) and trace-cmd agent(1) interactions. It
33 returns the number of guests found in handles that were associated with
34 the host, or negative on error.
35 The tracecmd_get_cpu_map() returns a descriptor for a given CPU for a
37 handle. If the handle was a guest defined from tracecmd_map_vcpus()
38 then the mapping created from that function that is associated to this
39 particular vCPU (denoted by cpu) from handle. This destriptor can be
40 used by tarcecmd_map_get_guest(), tracecmd_map_set_private() and
41 tracecmd_map_get_private() functions.
42 The tracecmd_map_find_by_host_pid() will return a mapping for a guest
44 virtual CPU that is handled by the given host_pid. Note, the handle
45 passed in can be either the host handle or one of the guest’s handles
46 for that host that was mapped by tracecmd_map_vcpus(), even if the
47 guest handle does not have the vCPU that the host_pid represents.
48 The tracecmd_map_get_host_pid() will recturn the host_pid for a given
50 map that was retrieved by one of the above functions.
51 The tracecmd_map_get_guest() will recturn the guest_handle for a given
53 map that was retrieved by one of the above functions.
54 The tracecmd_map_set_private() allows the application to assign private
56 data for a given guest vCPU to host thread mapping defined by map.
57 The tracecmd_map_get_private() retrieves the priv data from map that
59 was set by tracecmd_map_set_private().
60
62 tracecmd_map_vcpus() returns the number of guests in the handles array
63 that were mapped to the host handle that is the first entry in handles.
64 It returns -1 on error.
65 tracecmd_get_cpu_map() returns a map created by tracecmd_map_vcpus()
67 for a given cpu for a given handle, or NULL if it is not found.
68 tracecmd_map_find_by_host_pid() returns a map that is associated by the
70 host task with host_pid as its process ID. handle can be either a the
71 host handle, or one of the guest handles that were mapped to the host
72 via tracecmd_map_vcpus(), even if the guest handle is another guest
73 than the one that the mapping is for. It returns NULL if not found.
74 tracecmd_map_get_host_pid() returns the host process ID for an
76 associated mapping defined by map.
77 tracecmd_map_get_guest() returns the guest handle for an associated
79 mapping defined by map.
80 tracecmd_map_get_private() returns the private data of a mapping
82 defined by map that was set by tracecmd_map_set_private().
83
85 #include <stdlib.h>
86 #include <errno.h>
87 #include <trace-cmd.h>
88 int main(int argc, char **argv)
90 {
91 struct tracecmd_input **handles = NULL;
92 int nr_handles;
93 int i;
94 if (argc < 2) {
96 printf("usage: host_trace.dat guest1_trace.dat [guest2_trace.dat ...]\n");
97 exit(-1);
98 }
99 for (i = 1; i < argc; i++) {
101 handles = realloc(handles, sizeof(*handles) * (nr_handles + 1));
102 if (!handles)
103 exit(-1);
104 handles[nr_handles] = tracecmd_open(argv[i], 0);
105 if (!handles[nr_handles]) {
106 perror(argv[1]);
107 exit(-1);
108 }
109 tracecmd_set_private(handles[nr_handles], argv[i]);
110 nr_handles++;
111 }
112 tracecmd_map_vcpus(handles, nr_handles);
114 for (i = 1; i < nr_handles; i++) {
116 struct tracecmd_cpu_map *map;
117 struct tep_handle *tep;
118 const char *file = tracecmd_get_private(handles[i]);
119 int cpus, cpu;
120 printf("Mappings for guest %s:\n", file);
122 tep = tracecmd_get_tep(handles[i]);
123 cpus = tep_get_cpus(tep);
124 for (cpu = 0; cpu < cpus; cpu++) {
125 printf(" [%03d] ", cpu);
126 map = tracecmd_get_cpu_map(handles[i], cpu);
127 if (!map) {
128 printf("Has no mapping!\n");
129 continue;
130 }
131 printf("host_pid: %d\n", tracecmd_map_get_host_pid(map));
132 }
133 }
134 for (i = 0; i < nr_handles; i++)
135 tracecmd_close(handles[i]);
136 free(handles);
137 exit(0);
138 }
139
141 trace-cmd.h
142 Header file to include in order to have access to the library APIs.
143 -ltracecmd
144 Linker switch to add when building a program that uses the library.
145
147 libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)
148
150 Report bugs to <linux-trace-devel@vger.kernel.org[1]>
151
153 libtracecmd is Free Software licensed under the GNU LGPL 2.1
154
156 https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
157
159 Copyright (C) 2020 VMware, Inc. Free use of this software is granted
160 under the terms of the GNU Public License (GPL).
161
163 1. linux-trace-devel@vger.kernel.org
164 mailto:linux-trace-devel@vger.kernel.org
165libtracefs 07/20/2023 LIBTRACECMD(3)