From 0dfb3ca73c54fc105ab78e37e31ab05bed1360aa Mon Sep 17 00:00:00 2001 From: Stefan Hajnoczi Date: Tue, 12 Jan 2021 16:58:59 +0000 Subject: 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 /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 /trace/trace-accel_kvm.h file. Document this! Reported-by: Peter Maydell Signed-off-by: Stefan Hajnoczi Message-id: 20210112165859.225534-3-stefanha@redhat.com Signed-off-by: Stefan Hajnoczi --- docs/devel/tracing.rst | 57 ++++++++++++++++++++++++++++++-------------------- 1 file 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 /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-.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:: +Here is the sub-directory path with '/' replaced by '_'. For example, +"accel/kvm" becomes "accel_kvm" and the final filename for "trace-.c" +becomes "trace-accel_kvm.c". + +Source files in the source tree do not directly include generated files in +"/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-.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 ------------------ -- cgit v1.2.3-55-g7522