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 <address@hidden>
> ---
>  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
address@hidden                 http://www.aurel32.net