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