Re: [Qemu-devel] [PATCH v2 46/47] trace: update docs to reflect new code generation approach

[Eric Blake]

On 01/06/2017 09:55 AM, Daniel P. Berrange wrote:
> Describe use of per-subdir trace events files and how it impacts
> code generation.
> 
> Signed-off-by: Daniel P. Berrange <address@hidden>
> ---
>  docs/tracing.txt | 61 
> +++++++++++++++++++++++++++++++++++++++++++++++---------
>  1 file changed, 52 insertions(+), 9 deletions(-)
> 
> diff --git a/docs/tracing.txt b/docs/tracing.txt
> index f351998a..3262a61 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 for extra fun the current "trace-events" files use values from
> +the "powerful number" integer sequence :-)

Is this true? I don't see an @id_offset() comment in any of your earlier
patches, or in the unpatched tree.


> +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

s/speci/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 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

s/permited/permitted/

> +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 ===
>  

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature