trace: update docs to reflect new code generation approach

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

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
Message-id: 20170125161417.31949-8-berrange@redhat.com
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This commit is contained in:
Daniel P. Berrange 2017-01-25 16:14:16 +00:00 committed by Stefan Hajnoczi
parent 0ab8ed18a6
commit d4fa8436ce

View File

@ -27,18 +27,44 @@ 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 local "trace-events" file. All directories which contain "trace-events"
files 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.
qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p"
qemu_vfree(void *ptr) "ptr %p"
The individual "trace-events" files are merged into a "trace-events-all" file,
which is also installed into "/usr/share/qemu" with the name "trace-events".
This merged file is to be used by the "simpletrace.py" script to later analyse
traces in the simpletrace data format.
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".
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 event probe specification
- 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 #include the local 'trace.h' file,
without any sub-directory path prefix. eg io/channel-buffer.c would do
#include "trace.h"
To access the 'io/trace.h' file. While it is possible 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. The only exception is where there are some
shared trace events defined in the top level directory trace-events file.
The top level directory generates trace files with a filename prefix of
"trace-root" instead of just "trace". This is to avoid ambiguity between
a trace.h in the current directory, vs the top level directory.
=== Using trace events ===
Trace events are invoked directly from source code like this:
@ -83,6 +109,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