From b48c20f723cba21ffe62fb99094d2fa36739b0cc Mon Sep 17 00:00:00 2001 From: Stefan Hajnoczi Date: Wed, 23 Feb 2011 14:00:21 +0000 Subject: [PATCH] docs: Update stderr and simple backend, add systemtap backend The following additions to the tracing documentation are included: 1. Move "stderr" backend documentation to top-level and out of "simple" backend. Include hints on when this backend is useful. 2. Document the "simple" backend thread-safety limitation. 3. Document the "dtrace" backend for SystemTap. Signed-off-by: Stefan Hajnoczi Signed-off-by: Aurelien Jarno --- docs/tracing.txt | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) 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