diff --git a/docs/tracing.txt b/docs/tracing.txt index 21183f9a68..a6cc56fd33 100644 --- a/docs/tracing.txt +++ b/docs/tracing.txt @@ -126,6 +126,14 @@ The "nop" backend generates empty trace event functions so that the compiler can optimize out trace events completely. This is the default and imposes no performance penalty. +=== Stderr === + +The "stderr" backend sends trace events directly to standard error. This +effectively turns trace events into debug printfs. + +This is the simplest backend and can be used together with existing code that +uses DPRINTF(). + === Simpletrace === The "simple" backend supports common use cases and comes as part of the QEMU @@ -133,10 +141,10 @@ source tree. It may not be as powerful as platform-specific or third-party trace backends but it is portable. This is the recommended trace backend unless you have specific needs for more advanced backends. -=== Stderr === - -The "stderr" backend sends trace events directly to standard error output -during emulation. +Warning: the "simple" backend is not thread-safe so only enable trace events +that are executed while the global mutex is held. Much of QEMU meets this +requirement but some utility functions like qemu_malloc() or thread-related +code cannot be safely traced using the "simple" backend. ==== Monitor commands ==== @@ -187,3 +195,17 @@ consistent. The "ust" backend uses the LTTng Userspace Tracer library. There are no monitor commands built into QEMU, instead UST utilities should be used to list, enable/disable, and dump traces. + +=== SystemTap === + +The "dtrace" backend uses DTrace sdt probes but has only been tested with +SystemTap. When SystemTap support is detected a .stp file with wrapper probes +is generated to make use in scripts more convenient. This step can also be +performed manually after a build in order to change the binary name in the .stp +probes: + + scripts/tracetool --dtrace --stap \ + --binary path/to/qemu-binary \ + --target-type system \ + --target-arch x86_64 \ + qemu.stp