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 <stefanha@linux.vnet.ibm.com>
Signed-off-by: Aurelien Jarno <aurelien@aurel32.net>

diff --git a/docs/tracing.txt b/docs/tracing.txt
index 21183f9a6869dafbd7b66974f06cd65cc8e8df62..a6cc56fd330fb1fb35ecadc7bc44aaf9014018fc 100644 (file)
--- 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 \
+                      <trace-events >qemu.stp