[Qemu-devel] [PATCH] docs: Update stderr and simple backend, add systemtap backend

[Qemu-devel] [PATCH] docs: Update stderr and simple backend, add systemtap backend

[Stefan Hajnoczi]

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>
---
 docs/tracing.txt |   30 ++++++++++++++++++++++++++----
 1 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/docs/tracing.txt b/docs/tracing.txt
index 21183f9..a6cc56f 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 \
+                      <trace-events >qemu.stp
-- 
1.7.2.3

Re: [Qemu-devel] [PATCH] docs: Update stderr and simple backend, add systemtap backend

[Aurelien Jarno]

On Wed, Feb 23, 2011 at 02:00:21PM +0000, Stefan Hajnoczi wrote:
> 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>
> ---
>  docs/tracing.txt |   30 ++++++++++++++++++++++++++----
>  1 files changed, 26 insertions(+), 4 deletions(-)

Thanks, applied.

> diff --git a/docs/tracing.txt b/docs/tracing.txt
> index 21183f9..a6cc56f 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 \
> +                      <trace-events >qemu.stp
> -- 
> 1.7.2.3
> 
> 
> 

-- 
Aurelien Jarno                          GPG: 1024D/F1BCDB73
aurelien@aurel32.net                 http://www.aurel32.net