Describe use of per-subdir trace events files and how it impacts
code generation.
Signed-off-by: Daniel P. Berrange <berra...@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
