diff options
Diffstat (limited to 'docs/devel')
| -rw-r--r-- | docs/devel/tracing.rst | 57 |
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 ------------------ |