From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=45063 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PsFGv-00076G-3Z for qemu-devel@nongnu.org; Wed, 23 Feb 2011 09:00:57 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PsFGq-0006fS-UU for qemu-devel@nongnu.org; Wed, 23 Feb 2011 09:00:50 -0500 Received: from mtagate3.uk.ibm.com ([194.196.100.163]:37134) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PsFGq-0006dN-N9 for qemu-devel@nongnu.org; Wed, 23 Feb 2011 09:00:48 -0500 Received: from d06nrmr1707.portsmouth.uk.ibm.com (d06nrmr1707.portsmouth.uk.ibm.com [9.149.39.225]) by mtagate3.uk.ibm.com (8.13.1/8.13.1) with ESMTP id p1NE0ie7022432 for ; Wed, 23 Feb 2011 14:00:44 GMT Received: from d06av08.portsmouth.uk.ibm.com (d06av08.portsmouth.uk.ibm.com [9.149.37.249]) by d06nrmr1707.portsmouth.uk.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id p1NE0rx41822878 for ; Wed, 23 Feb 2011 14:00:53 GMT Received: from d06av08.portsmouth.uk.ibm.com (loopback [127.0.0.1]) by d06av08.portsmouth.uk.ibm.com (8.14.4/8.13.1/NCO v10.0 AVout) with ESMTP id p1NE0ikR029528 for ; Wed, 23 Feb 2011 14:00:44 GMT From: Stefan Hajnoczi Date: Wed, 23 Feb 2011 14:00:21 +0000 Message-Id: <1298469621-23393-1-git-send-email-stefanha@linux.vnet.ibm.com> Subject: [Qemu-devel] [PATCH] docs: Update stderr and simple backend, add systemtap backend List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: 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 --- 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 \ + qemu.stp -- 1.7.2.3