hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / docs / tracing.txt
1 = Tracing =
2
3 == Introduction ==
4
5 This document describes the tracing infrastructure in QEMU and how to use it
6 for debugging, profiling, and observing execution.
7
8 == Quickstart ==
9
10 1. Build with the 'simple' trace backend:
11
12     ./configure --enable-trace-backends=simple
13     make
14
15 2. Create a file with the events you want to trace:
16
17    echo bdrv_aio_readv   > /tmp/events
18    echo bdrv_aio_writev >> /tmp/events
19
20 3. Run the virtual machine to produce a trace file:
21
22     qemu -trace events=/tmp/events ... # your normal QEMU invocation
23
24 4. Pretty-print the binary trace file:
25
26     ./scripts/simpletrace.py trace-events-all trace-* # Override * with QEMU <pid>
27
28 == Trace events ==
29
30 Each directory in the source tree can declare a set of static trace events
31 in a "trace-events" file. Each trace event declaration names the event, its
32 arguments, and the format string which can be used for pretty-printing:
33
34     qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
35     qemu_vfree(void *ptr) "ptr %p"
36
37 All "trace-events" files must be listed in the "trace-event-y" make variable
38 in the top level Makefile.objs. During build the individual files are combined
39 to create a "trace-events-all" file, which is processed by the "tracetool"
40 script during build to generate code for the trace events. The
41 "trace-events-all" file is also installed into "/usr/share/qemu".
42
43 Trace events are invoked directly from source code like this:
44
45     #include "trace.h"  /* needed for trace event prototype */
46     
47     void *qemu_vmalloc(size_t size)
48     {
49         void *ptr;
50         size_t align = QEMU_VMALLOC_ALIGN;
51      
52         if (size < align) {
53             align = getpagesize();
54         }
55         ptr = qemu_memalign(align, size);
56         trace_qemu_vmalloc(size, ptr);
57         return ptr;
58     }
59
60 === Declaring trace events ===
61
62 The "tracetool" script produces the trace.h header file which is included by
63 every source file that uses trace events.  Since many source files include
64 trace.h, it uses a minimum of types and other header files included to keep the
65 namespace clean and compile times and dependencies down.
66
67 Trace events should use types as follows:
68
69  * Use stdint.h types for fixed-size types.  Most offsets and guest memory
70    addresses are best represented with uint32_t or uint64_t.  Use fixed-size
71    types over primitive types whose size may change depending on the host
72    (32-bit versus 64-bit) so trace events don't truncate values or break
73    the build.
74
75  * Use void * for pointers to structs or for arrays.  The trace.h header
76    cannot include all user-defined struct declarations and it is therefore
77    necessary to use void * for pointers to structs.
78
79  * For everything else, use primitive scalar types (char, int, long) with the
80    appropriate signedness.
81
82 Format strings should reflect the types defined in the trace event.  Take
83 special care to use PRId64 and PRIu64 for int64_t and uint64_t types,
84 respectively.  This ensures portability between 32- and 64-bit platforms.
85
86 === Hints for adding new trace events ===
87
88 1. Trace state changes in the code.  Interesting points in the code usually
89    involve a state change like starting, stopping, allocating, freeing.  State
90    changes are good trace events because they can be used to understand the
91    execution of the system.
92
93 2. Trace guest operations.  Guest I/O accesses like reading device registers
94    are good trace events because they can be used to understand guest
95    interactions.
96
97 3. Use correlator fields so the context of an individual line of trace output
98    can be understood.  For example, trace the pointer returned by malloc and
99    used as an argument to free.  This way mallocs and frees can be matched up.
100    Trace events with no context are not very useful.
101
102 4. Name trace events after their function.  If there are multiple trace events
103    in one function, append a unique distinguisher at the end of the name.
104
105 == Generic interface and monitor commands ==
106
107 You can programmatically query and control the state of trace events through a
108 backend-agnostic interface provided by the header "trace/control.h".
109
110 Note that some of the backends do not provide an implementation for some parts
111 of this interface, in which case QEMU will just print a warning (please refer to
112 header "trace/control.h" to see which routines are backend-dependent).
113
114 The state of events can also be queried and modified through monitor commands:
115
116 * info trace-events
117   View available trace events and their state.  State 1 means enabled, state 0
118   means disabled.
119
120 * trace-event NAME on|off
121   Enable/disable a given trace event or a group of events (using wildcards).
122
123 The "-trace events=<file>" command line argument can be used to enable the
124 events listed in <file> from the very beginning of the program. This file must
125 contain one event name per line.
126
127 If a line in the "-trace events=<file>" file begins with a '-', the trace event
128 will be disabled instead of enabled.  This is useful when a wildcard was used
129 to enable an entire family of events but one noisy event needs to be disabled.
130
131 Wildcard matching is supported in both the monitor command "trace-event" and the
132 events list file. That means you can enable/disable the events having a common
133 prefix in a batch. For example, virtio-blk trace events could be enabled using
134 the following monitor command:
135
136     trace-event virtio_blk_* on
137
138 == Trace backends ==
139
140 The "tracetool" script automates tedious trace event code generation and also
141 keeps the trace event declarations independent of the trace backend.  The trace
142 events are not tightly coupled to a specific trace backend, such as LTTng or
143 SystemTap.  Support for trace backends can be added by extending the "tracetool"
144 script.
145
146 The trace backends are chosen at configure time:
147
148     ./configure --enable-trace-backends=simple
149
150 For a list of supported trace backends, try ./configure --help or see below.
151 If multiple backends are enabled, the trace is sent to them all.
152
153 If no backends are explicitly selected, configure will default to the
154 "log" backend.
155
156 The following subsections describe the supported trace backends.
157
158 === Nop ===
159
160 The "nop" backend generates empty trace event functions so that the compiler
161 can optimize out trace events completely.  This imposes no performance
162 penalty.
163
164 Note that regardless of the selected trace backend, events with the "disable"
165 property will be generated with the "nop" backend.
166
167 === Log ===
168
169 The "log" backend sends trace events directly to standard error.  This
170 effectively turns trace events into debug printfs.
171
172 This is the simplest backend and can be used together with existing code that
173 uses DPRINTF().
174
175 === Simpletrace ===
176
177 The "simple" backend supports common use cases and comes as part of the QEMU
178 source tree.  It may not be as powerful as platform-specific or third-party
179 trace backends but it is portable.  This is the recommended trace backend
180 unless you have specific needs for more advanced backends.
181
182 === Ftrace ===
183
184 The "ftrace" backend writes trace data to ftrace marker. This effectively
185 sends trace events to ftrace ring buffer, and you can compare qemu trace
186 data and kernel(especially kvm.ko when using KVM) trace data.
187
188 if you use KVM, enable kvm events in ftrace:
189
190    # echo 1 > /sys/kernel/debug/tracing/events/kvm/enable
191
192 After running qemu by root user, you can get the trace:
193
194    # cat /sys/kernel/debug/tracing/trace
195
196 Restriction: "ftrace" backend is restricted to Linux only.
197
198 === Syslog ===
199
200 The "syslog" backend sends trace events using the POSIX syslog API. The log
201 is opened specifying the LOG_DAEMON facility and LOG_PID option (so events
202 are tagged with the pid of the particular QEMU process that generated
203 them). All events are logged at LOG_INFO level.
204
205 NOTE: syslog may squash duplicate consecutive trace events and apply rate
206       limiting.
207
208 Restriction: "syslog" backend is restricted to POSIX compliant OS.
209
210 ==== Monitor commands ====
211
212 * trace-file on|off|flush|set <path>
213   Enable/disable/flush the trace file or set the trace file name.
214
215 ==== Analyzing trace files ====
216
217 The "simple" backend produces binary trace files that can be formatted with the
218 simpletrace.py script.  The script takes the "trace-events-all" file and the
219 binary trace:
220
221     ./scripts/simpletrace.py trace-events-all trace-12345
222
223 You must ensure that the same "trace-events-all" file was used to build QEMU,
224 otherwise trace event declarations may have changed and output will not be
225 consistent.
226
227 === LTTng Userspace Tracer ===
228
229 The "ust" backend uses the LTTng Userspace Tracer library.  There are no
230 monitor commands built into QEMU, instead UST utilities should be used to list,
231 enable/disable, and dump traces.
232
233 Package lttng-tools is required for userspace tracing. You must ensure that the
234 current user belongs to the "tracing" group, or manually launch the
235 lttng-sessiond daemon for the current user prior to running any instance of
236 QEMU.
237
238 While running an instrumented QEMU, LTTng should be able to list all available
239 events:
240
241     lttng list -u
242
243 Create tracing session:
244
245     lttng create mysession
246
247 Enable events:
248
249     lttng enable-event qemu:g_malloc -u
250
251 Where the events can either be a comma-separated list of events, or "-a" to
252 enable all tracepoint events. Start and stop tracing as needed:
253
254     lttng start
255     lttng stop
256
257 View the trace:
258
259     lttng view
260
261 Destroy tracing session:
262
263     lttng destroy
264
265 Babeltrace can be used at any later time to view the trace:
266
267     babeltrace $HOME/lttng-traces/mysession-<date>-<time>
268
269 === SystemTap ===
270
271 The "dtrace" backend uses DTrace sdt probes but has only been tested with
272 SystemTap.  When SystemTap support is detected a .stp file with wrapper probes
273 is generated to make use in scripts more convenient.  This step can also be
274 performed manually after a build in order to change the binary name in the .stp
275 probes:
276
277     scripts/tracetool.py --backends=dtrace --format=stap \
278                          --binary path/to/qemu-binary \
279                          --target-type system \
280                          --target-name x86_64 \
281                          <trace-events-all >qemu.stp
282
283 == Trace event properties ==
284
285 Each event in the "trace-events-all" file can be prefixed with a space-separated
286 list of zero or more of the following event properties.
287
288 === "disable" ===
289
290 If a specific trace event is going to be invoked a huge number of times, this
291 might have a noticeable performance impact even when the event is
292 programmatically disabled.
293
294 In this case you should declare such event with the "disable" property. This
295 will effectively disable the event at compile time (by using the "nop" backend),
296 thus having no performance impact at all on regular builds (i.e., unless you
297 edit the "trace-events-all" file).
298
299 In addition, there might be cases where relatively complex computations must be
300 performed to generate values that are only used as arguments for a trace
301 function. In these cases you can use the macro 'TRACE_${EVENT_NAME}_ENABLED' to
302 guard such computations and avoid its compilation when the event is disabled:
303
304     #include "trace.h"  /* needed for trace event prototype */
305     
306     void *qemu_vmalloc(size_t size)
307     {
308         void *ptr;
309         size_t align = QEMU_VMALLOC_ALIGN;
310     
311         if (size < align) {
312             align = getpagesize();
313         }
314         ptr = qemu_memalign(align, size);
315         if (TRACE_QEMU_VMALLOC_ENABLED) { /* preprocessor macro */
316             void *complex;
317             /* some complex computations to produce the 'complex' value */
318             trace_qemu_vmalloc(size, ptr, complex);
319         }
320         return ptr;
321     }
322
323 You can check both if the event has been disabled and is dynamically enabled at
324 the same time using the 'trace_event_get_state' routine (see header
325 "trace/control.h" for more information).
326
327 === "tcg" ===
328
329 Guest code generated by TCG can be traced by defining an event with the "tcg"
330 event property. Internally, this property generates two events:
331 "<eventname>_trans" to trace the event at translation time, and
332 "<eventname>_exec" to trace the event at execution time.
333
334 Instead of using these two events, you should instead use the function
335 "trace_<eventname>_tcg" during translation (TCG code generation). This function
336 will automatically call "trace_<eventname>_trans", and will generate the
337 necessary TCG code to call "trace_<eventname>_exec" during guest code execution.
338
339 Events with the "tcg" property can be declared in the "trace-events" file with a
340 mix of native and TCG types, and "trace_<eventname>_tcg" will gracefully forward
341 them to the "<eventname>_trans" and "<eventname>_exec" events. Since TCG values
342 are not known at translation time, these are ignored by the "<eventname>_trans"
343 event. Because of this, the entry in the "trace-events" file needs two printing
344 formats (separated by a comma):
345
346     tcg foo(uint8_t a1, TCGv_i32 a2) "a1=%d", "a1=%d a2=%d"
347
348 For example:
349
350     #include "trace-tcg.h"
351     
352     void some_disassembly_func (...)
353     {
354         uint8_t a1 = ...;
355         TCGv_i32 a2 = ...;
356         trace_foo_tcg(a1, a2);
357     }
358
359 This will immediately call:
360
361     void trace_foo_trans(uint8_t a1);
362
363 and will generate the TCG code to call:
364
365     void trace_foo(uint8_t a1, uint32_t a2);
366
367 === "vcpu" ===
368
369 Identifies events that trace vCPU-specific information. It implicitly adds a
370 "CPUState*" argument, and extends the tracing print format to show the vCPU
371 information. If used together with the "tcg" property, it adds a second
372 "TCGv_env" argument that must point to the per-target global TCG register that
373 points to the vCPU when guest code is executed (usually the "cpu_env" variable).
374
375 The following example events:
376
377     foo(uint32_t a) "a=%x"
378     vcpu bar(uint32_t a) "a=%x"
379     tcg vcpu baz(uint32_t a) "a=%x", "a=%x"
380
381 Can be used as:
382
383     #include "trace-tcg.h"
384     
385     CPUArchState *env;
386     TCGv_ptr cpu_env;
387     
388     void some_disassembly_func(...)
389     {
390         /* trace emitted at this point */
391         trace_foo(0xd1);
392         /* trace emitted at this point */
393         trace_bar(ENV_GET_CPU(env), 0xd2);
394         /* trace emitted at this point (env) and when guest code is executed (cpu_env) */
395         trace_baz_tcg(ENV_GET_CPU(env), cpu_env, 0xd3);
396     }
397
398 If the translating vCPU has address 0xc1 and code is later executed by vCPU
399 0xc2, this would be an example output:
400
401     // at guest code translation
402     foo a=0xd1
403     bar cpu=0xc1 a=0xd2
404     baz_trans cpu=0xc1 a=0xd3
405     // at guest code execution
406     baz_exec cpu=0xc2 a=0xd3