Merge remote-tracking branch 'stefanha/tracing' into staging

1 files changed, 47 insertions, 26 deletions

diff --git a/docs/tracing.txt b/docs/tracing.txt
index c99a0f27cf..4b27ab0c2a 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -12,13 +12,14 @@ for debugging, profiling, and observing execution.
     ./configure --trace-backend=simple
     make
 
-2. Enable trace events you are interested in:
+2. Create a file with the events you want to trace:
 
-    $EDITOR trace-events  # remove "disable" from events you want
+   echo bdrv_aio_readv   > /tmp/events
+   echo bdrv_aio_writev >> /tmp/events
 
 3. Run the virtual machine to produce a trace file:
 
-    qemu ... # your normal QEMU invocation
+    qemu -trace events=/tmp/events ... # your normal QEMU invocation
 
 4. Pretty-print the binary trace file:
 
@@ -38,7 +39,7 @@ generate code for the trace events.  Trace events are invoked directly from
 source code like this:
 
     #include "trace.h"  /* needed for trace event prototype */
-
+    
     void *qemu_malloc(size_t size)
     {
         void *ptr;
@@ -103,10 +104,45 @@ 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" keyword.  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 ==
+
+You can programmatically query and control the dynamic state of trace events
+through a backend-agnostic interface:
+
+* trace_print_events
+
+* trace_event_set_state
+  Enables or disables trace events at runtime inside QEMU.
+  The function returns "true" if the state of the event has been successfully
+  changed, or "false" otherwise:
+
+    #include "trace/control.h"
+    
+    trace_event_set_state("virtio_irq", true); /* enable */
+    [...]
+    trace_event_set_state("virtio_irq", false); /* disable */
+
+Note that some of the backends do not provide an implementation for this
+interface, in which case QEMU will just print a warning.
+
+This functionality is also provided through monitor commands:
+
+* info trace-events
+  View available trace events and their state.  State 1 means enabled, state 0
+  means disabled.
+
+* trace-event NAME on|off
+  Enable/disable a given trace event.
+
+The "-trace events=<file>" command line argument can be used to enable the
+events listed in <file> from the very beginning of the program. This file must
+contain one event name per line.
 
 == Trace backends ==
 
@@ -131,6 +167,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
@@ -157,27 +196,9 @@ unless you have specific needs for more advanced backends.
   flushed and emptied.  This means the 'info trace' will display few or no
   entries if the buffer has just been flushed.
 
-* info trace-events
-  View available trace events and their state.  State 1 means enabled, state 0
-  means disabled.
-
-* trace-event NAME on|off
-  Enable/disable a given trace event.
-
 * trace-file on|off|flush|set <path>
   Enable/disable/flush the trace file or set the trace file name.
 
-==== Enabling/disabling trace events programmatically ====
-
-The st_change_trace_event_state() function can be used to enable or disable trace
-events at runtime inside QEMU:
-
-    #include "trace.h"
-    
-    st_change_trace_event_state("virtio_irq", true); /* enable */
-    [...]
-    st_change_trace_event_state("virtio_irq", false); /* disable */
-
 ==== Analyzing trace files ====
 
 The "simple" backend produces binary trace files that can be formatted with the