1LIBTRACECMD(3)                 libtracefs Manual                LIBTRACECMD(3)
2
3
4

NAME

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

SYNOPSIS

12       #include <trace-cmd.h>
13
14       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

DESCRIPTION

24       This set of APIs is used to map host and guest trace files for to
25       facilitate further tracing analysis.
26
27       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
36       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
43       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
49       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
52       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
55       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
58       The tracecmd_map_get_private() retrieves the priv data from map that
59       was set by tracecmd_map_set_private().
60

RETURN VALUE

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
66       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
69       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
75       tracecmd_map_get_host_pid() returns the host process ID for an
76       associated mapping defined by map.
77
78       tracecmd_map_get_guest() returns the guest handle for an associated
79       mapping defined by map.
80
81       tracecmd_map_get_private() returns the private data of a mapping
82       defined by map that was set by tracecmd_map_set_private().
83

EXAMPLE

85           #include <stdlib.h>
86           #include <errno.h>
87           #include <trace-cmd.h>
88
89           int main(int argc, char **argv)
90           {
91                   struct tracecmd_input **handles = NULL;
92                   int nr_handles;
93                   int i;
94
95                   if (argc < 2) {
96                           printf("usage: host_trace.dat guest1_trace.dat [guest2_trace.dat ...]\n");
97                           exit(-1);
98                   }
99
100                   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
113                   tracecmd_map_vcpus(handles, nr_handles);
114
115                   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
121                           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

FILES

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

SEE ALSO

147       libtracefs(3), libtraceevent(3), trace-cmd(1) trace-cmd.dat(5)
148

REPORTING BUGS

150       Report bugs to <linux-trace-devel@vger.kernel.org[1]>
151

LICENSE

153       libtracecmd is Free Software licensed under the GNU LGPL 2.1
154

RESOURCES

156       https://git.kernel.org/pub/scm/utils/trace-cmd/trace-cmd.git/
157

COPYING

159       Copyright (C) 2020 VMware, Inc. Free use of this software is granted
160       under the terms of the GNU Public License (GPL).
161

NOTES

163        1. linux-trace-devel@vger.kernel.org
164           mailto:linux-trace-devel@vger.kernel.org
165
166
167
168libtracefs                        07/20/2023                    LIBTRACECMD(3)
Impressum