[Qemu-devel] [PATCH RFC 2/4] trace-instrument: Add documentation

[Lluís Vilanova]

Signed-off-by: Lluís Vilanova <address@hidden>
---
 docs/instrumentation.txt |  142 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/tracing.txt         |    9 +++
 2 files changed, 151 insertions(+), 0 deletions(-)
 create mode 100644 docs/instrumentation.txt

diff --git a/docs/instrumentation.txt b/docs/instrumentation.txt
new file mode 100644
index 0000000..f9f3ce1
--- /dev/null
+++ b/docs/instrumentation.txt
@@ -0,0 +1,142 @@
+= Trace instrumentation =
+
+== Introduction ==
+
+This document describes how the events provided by the tracing infrastructure
+described in the document "tracing.txt" can be extended with user-defined code
+that is compiled into QEMU.
+
+The "instrument" property provides means to statically override and/or wrap the
+backend-specific tracing code on a per-event basis when compiling QEMU
+(regardless of the tracing backend).
+
+As opposed to using tracing backends that can dynamically load user-defined 
code
+into the tracing events (e.g., "dtrace"), trace instrumentation is performed at
+compile time and thus provides means for the tracing hooks to directly interact
+with QEMU internals.
+
+Static trace instrumentation trades the ease and flexibility of existing 
tracing
+backends with the ability to directly interact with the internal routines of
+QEMU, as well as the ability to embed highly performant and ad-hoc analyses
+based on QEMU's tracing events directly into QEMU itself.
+
+
+== Quickstart ==
+
+1. Declare which tracing events to instrument:
+
+    sed -i -e "s/qemu_vmalloc(/instrument qemu_vmalloc(/g" trace-events
+
+2. Create the trace instrumentation header ("trace-instrument.h") with the
+   headers for the instrumented tracing events:
+
+    cat > /tmp/my-instrument/trace-instrument.h <<EOF
+    void qemu_vmalloc(size_t size, void *ptr);
+    EOF
+
+3. Create the "Makefile" to build the trace intrumentation library:
+
+    cat > /tmp/my-intrument/Makefile <<EOF
+    include $(BUILD_DIR)/config-host.mak
+    include $(BUILD_DIR)/$(TARGET_DIR)../config-target.mak
+    include $(SRC_PATH)/rules.mak
+    
+    vpath %.c /tmp/my-instrument
+    
+    libtrace-instrument.a: instrument.o
+    
+    # Include automatically generated dependency files
+    -include $(wildcard *.d)
+    EOF
+
+4. Create the necessary source code files to implement the event 
instrumentation:
+
+    cat > /tmp/my-instrument/instrument.c <<EOF
+    #include "trace.h"
+    
+    void trace_qemu_vmalloc(size_t size, void *ptr)
+    {
+        /* ... */
+    }
+    EOF
+
+5. Build QEMU with trace intrumentation enabled:
+
+    ./configure --with-trace-instrument=/tmp/my-instrument
+    make
+
+
+== Compilation notes ==
+
+The instrumentation library is compiled during the compilation of the
+target-dependant code. This means that the instrumentation code is able to use
+any target-specific code and access target-specific vCPU state. This includes
+access to a per-vCPU opaque pointer ("instrument") that is reserved for the use
+of the instrumentation code.
+
+In addition, the path to the static trace instrumentation library is added into
+the list of directories to search for includes, so that any user-provided
+headers can be included from the instrumentation headers, as well as any other
+header from QEMU itself can be included in the intrumentation code.
+
+
+== User-provided headers ==
+
+The user must provide a set of headers in the directory identified by the
+'--with-trace-instrument' configure option. These headers establish how and 
what
+to do when a tracing routine for an instrumented event is invoked.
+
+=== "trace-instrument.h" ===
+
+This file is included from the "trace.h" file whenever instrumentation is 
enabled.
+
+Usually, this file will only contain a declaration of the tracing routines for
+the instrumented events, just as the "trace.h" would do if an event was not
+instrumented.
+
+Still, if some part of the instrumentation is performance-critical, the header
+could provide an inlined implementation of the fast path in the header, and
+implement the slow path in the instrumentation library itself:
+
+    void trace_qemu_vmalloc_slow(size_t size, void *ptr);
+    
+    static inline void trace_qemu_vmalloc(size_t size, void *ptr)
+    {
+        if (/* ... performance-critical condition ... */) {
+            /* ... performance-critical code ... */
+        } else {
+            trace_qemu_vmalloc_slow(size, ptr);
+        }
+    }
+
+
+== Mixing existing tracing backends and instrumentation ==
+
+When enabling static trace instrumentation, you can still use the currently
+selected tracing backend by invoking the tracing function with the '_backend'
+suffix.
+
+Note that some of the tracing backends provide an interface for 
programmatically
+controlling the tracing state of each event. Thus you can provide code to
+control when the tracing must take place:
+
+    void trace_qemu_vmalloc(size_t size, void *ptr)
+    {
+        /* only trace one malloc every 10 */
+        /* note that this code is not thread-safe */
+        static int i = 0;
+        static bool state = true;
+        if (i++ % 10 == 0) {
+            trace_event_set_state("qemu_vmalloc", state);
+            state = !state;
+        }
+    
+        /* call the original backend-specific tracing routine */
+        trace_qemu_vmalloc_backend(size, ptr);
+    }
+
+
+== Performance notes ==
+
+The "trace-instrument.h" header can be used to inline the implementation of the
+tracing routines for those events that have the "instrument" property.
diff --git a/docs/tracing.txt b/docs/tracing.txt
index a92716f..a1d3ce2 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -268,3 +268,12 @@ guard such computations and avoid its compilation when the 
event is disabled:
         }
         return ptr;
     }
+
+=== "instrument" ===
+
+When compiling QEMU with trace instrumentation enabled, the "instrument"
+property will force the user to provide an implementation for that trace
+event. This implementation can override and/or wrap the backend-specific 
tracing
+code at compile time (regardless of the tracing backend).
+
+See the document "instrumentation.txt" for more information.