summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorLluís <xscript@gmx.net>2011-08-31 20:31:38 +0200
committerStefan Hajnoczi <stefanha@linux.vnet.ibm.com>2011-09-01 10:34:54 +0100
commitdd215f646c72b4cf680097b13aeb8b0c589dceb2 (patch)
tree97e05a66abda7a327a3377c80652392bbca9e03c /docs
parent23d15e860b33819ad76092fbb32577542fe0c44d (diff)
trace: always use the "nop" backend on events with the "disable" keyword
Any event with the keyword/property "disable" generates an empty trace event using the "nop" backend, regardless of the current backend. Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu>
Diffstat (limited to 'docs')
-rw-r--r--docs/tracing.txt25
1 files changed, 15 insertions, 10 deletions
diff --git a/docs/tracing.txt b/docs/tracing.txt
index 455da37969..85793cf173 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -12,15 +12,11 @@ for debugging, profiling, and observing execution.
./configure --trace-backend=simple
make
-2. Enable trace events you are interested in:
-
- $EDITOR trace-events # remove "disable" from events you want
-
-3. Run the virtual machine to produce a trace file:
+2. Run the virtual machine to produce a trace file:
qemu ... # your normal QEMU invocation
-4. Pretty-print the binary trace file:
+3. Pretty-print the binary trace file:
./simpletrace.py trace-events trace-*
@@ -103,10 +99,11 @@ portability macros, ensure they are preceded and followed by double quotes:
4. Name trace events after their function. If there are multiple trace events
in one function, append a unique distinguisher at the end of the name.
-5. Declare trace events with the "disable" property. Some trace events can
- produce a lot of output and users are typically only interested in a subset
- of trace events. Marking trace events disabled by default saves the user
- from having to manually disable noisy trace events.
+5. If specific trace events are going to be called a huge number of times, this
+ might have a noticeable performance impact even when the trace events are
+ programmatically disabled. In this case you should declare the trace event
+ with the "disable" property, which will effectively disable it at compile
+ time (using the "nop" backend).
== Generic interface and monitor commands ==
@@ -165,6 +162,9 @@ 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.
+Note that regardless of the selected trace backend, events with the "disable"
+property will be generated with the "nop" backend.
+
=== Stderr ===
The "stderr" backend sends trace events directly to standard error. This
@@ -173,6 +173,11 @@ effectively turns trace events into debug printfs.
This is the simplest backend and can be used together with existing code that
uses DPRINTF().
+Note that with this backend trace events cannot be programmatically
+enabled/disabled. Thus, in order to trim down the amount of output and the
+performance impact of tracing, you might want to add the "disable" property in
+the "trace-events" file for those events you are not interested in.
+
=== Simpletrace ===
The "simple" backend supports common use cases and comes as part of the QEMU