aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorStefan Hajnoczi <stefanha@redhat.com>2021-01-12 16:58:59 +0000
committerStefan Hajnoczi <stefanha@redhat.com>2021-02-01 11:23:04 +0000
commit0dfb3ca73c54fc105ab78e37e31ab05bed1360aa (patch)
tree8ad159f55a3d842a3051a9a55ab01e90e3741af5
parent3faf22ef4465d064617dee524c97afa8d4400d9c (diff)
downloadqemu-arm-0dfb3ca73c54fc105ab78e37e31ab05bed1360aa.tar.gz
trace: update docs with meson build information
The documentation still refers to the makefile and the old sub-directory layout. Meson works differently: tracetool output is placed into the builddir with mangled filenames like <builddir>/trace/trace-accel_kvm.h for the accel/kvm/ trace.h definition. This meson setup also requires a manually-created accel/kvm/trace.h file that #includes the <builddir>/trace/trace-accel_kvm.h file. Document this! Reported-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20210112165859.225534-3-stefanha@redhat.com Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
-rw-r--r--docs/devel/tracing.rst57
1 files changed, 34 insertions, 23 deletions
diff --git a/docs/devel/tracing.rst b/docs/devel/tracing.rst
index e8f9b82c5e..ba83954899 100644
--- a/docs/devel/tracing.rst
+++ b/docs/devel/tracing.rst
@@ -39,40 +39,51 @@ Trace events
Sub-directory setup
-------------------
-Each directory in the source tree can declare a set of static trace events
-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.
+Each directory in the source tree can declare a set of trace events in a local
+"trace-events" file. All directories which contain "trace-events" files must be
+listed in the "trace_events_subdirs" variable in the top level meson.build
+file. 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 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.
-In the sub-directory the following files will be automatically generated
+The following files are automatically generated in <builddir>/trace/ during the
+build:
- - 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
+ - trace-<subdir>.c - the trace event state declarations
+ - trace-<subdir>.h - the trace event enums and probe functions
+ - trace-dtrace-<subdir>.h - DTrace event probe specification
+ - trace-dtrace-<subdir>.dtrace - DTrace event probe helper declaration
+ - trace-dtrace-<subdir>.o - binary DTrace provider (generated by dtrace)
+ - trace-ust-<subdir>.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::
+Here <subdir> is the sub-directory path with '/' replaced by '_'. For example,
+"accel/kvm" becomes "accel_kvm" and the final filename for "trace-<subdir>.c"
+becomes "trace-accel_kvm.c".
+
+Source files in the source tree do not directly include generated files in
+"<builddir>/trace/". Instead they #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 file's 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/trace-root" instead of just "trace". This is to avoid ambiguity between
-a trace.h in the current directory, vs the top level directory.
+The "io/trace.h" file must be created manually with an #include of the
+corresponding "trace/trace-<subdir>.h" file that will be generated in the
+builddir::
+
+ $ echo '#include "trace/trace-io.h"' >io/trace.h
+
+While it is possible to include a trace.h file from outside a source file's 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/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
------------------