[Qemu-devel] [PATCH for-2.8 v1 60/60] trace: update docs to reflect new code generation approach

["Daniel P. Berrange" <berrange@redhat.com>]

Describe use of per-subdir trace events files and how it impacts
code generation.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
---
 docs/tracing.txt | 61 +++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 9 deletions(-)

diff --git a/docs/tracing.txt b/docs/tracing.txt
index 29f2f9a..b7ba179 100644
--- a/docs/tracing.txt
+++ b/docs/tracing.txt
@@ -27,18 +27,51 @@ for debugging, profiling, and observing execution.
 
 == Trace events ==
 
+=== Sub-directory setup ===
+
 Each directory in the source tree can declare a set of static trace events
-in a "trace-events" file. Each trace event declaration names the event, its
-arguments, and the format string which can be used for pretty-printing:
+in a "trace-events" file. The first (non-comment) statement in the file
+must be "@id_offset(NN)" where NN is an integer that is unique among all
+"trace-events" files in the QEMU source tree. The IDs can be arbitrarily
+chosen, but extra fun the current "trace-events" files use values from the
+"powerful number" integer sequence :-)
 
-    qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
-    qemu_vfree(void *ptr) "ptr %p"
+Any subdirectory which contains a "trace-events" file must be listed in the
+"trace-events-subdirs" make variable in the top level Makefile.objs. During
+build, the "trace-events" file in each listed subdirectory will be processed
+by the "tracetool" script to generate code for the trace events.
+
+The individual "trace-events" files are merged together into a "trace-events-all"
+file, which is also installed into "/usr/share/qemu" with the name "trace-events".
+This merge file is to be used by the "simpletrace.py" script to later analyse
+traces in the simpletrace data format.
+
+The Makefile.objs in the subdirectory should have two lines added
+
+  trace-obj-y += trace.o
+  trace-obj-$(CONFIG_TRACE_DTRACE) += trace-dtrace.o
+
+In the sub-directory the following files will be automatically generated
+
+ - trace.c - the trace event state declarations
+ - trace.h - the trace event enums and probe functions
+ - trace-dtrace.h - DTrace speci
+ - trace-dtrace.dtrace - DTrace event probe helper declaration
+ - trace-dtrace.o - binary DTrace provider (generated by dtrace)
+ - trace-ust.h - UST event probe helper declarations
+
+Source files in the sub-directory should only #include the 'trace.h'
+file and use the full sub-directory path. eg io/channel-buffer.c
+would do
 
-All "trace-events" files must be listed in the "trace-event-y" make variable
-in the top level Makefile.objs. During build the individual files are combined
-to create a "trace-events-all" file, which is processed by the "tracetool"
-script during build to generate code for the trace events. The
-"trace-events-all" file is also installed into "/usr/share/qemu".
+  #include "io/trace.h"
+
+While it is permited to include a trace.h file from outside a source
+files' own sub-directory, this is discouraged in general. It is strongly
+preferred that all events be declared directly in the sub-directory that
+uses them.
+
+=== Using trace events ===
 
 Trace events are invoked directly from source code like this:
 
@@ -83,6 +116,13 @@ Format strings should reflect the types defined in the trace event.  Take
 special care to use PRId64 and PRIu64 for int64_t and uint64_t types,
 respectively.  This ensures portability between 32- and 64-bit platforms.
 
+Each event declaration will start with the event name, then its arguments,
+finally a format string for pretty-printing. For example:
+
+    qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
+    qemu_vfree(void *ptr) "ptr %p"
+
+
 === Hints for adding new trace events ===
 
 1. Trace state changes in the code.  Interesting points in the code usually
@@ -357,6 +397,9 @@ information. If used together with the "tcg" property, it adds a second
 "TCGv_env" argument that must point to the per-target global TCG register that
 points to the vCPU when guest code is executed (usually the "cpu_env" variable).
 
+All "vcpu" events *must* be declared in the top level "trace-events" file. It
+is not permitted to have them declared in sub-directories.
+
 The following example events:
 
     foo(uint32_t a) "a=%x"
-- 
2.7.4