From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:44760) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cWQDf-00027y-7w for qemu-devel@nongnu.org; Wed, 25 Jan 2017 11:14:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cWQDb-0003WI-US for qemu-devel@nongnu.org; Wed, 25 Jan 2017 11:14:47 -0500 Received: from mx1.redhat.com ([209.132.183.28]:41994) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cWQDb-0003WE-Me for qemu-devel@nongnu.org; Wed, 25 Jan 2017 11:14:43 -0500 From: "Daniel P. Berrange" Date: Wed, 25 Jan 2017 16:14:16 +0000 Message-Id: <20170125161417.31949-8-berrange@redhat.com> In-Reply-To: <20170125161417.31949-1-berrange@redhat.com> References: <20170125161417.31949-1-berrange@redhat.com> Subject: [Qemu-devel] [PATCH v4 7/8] trace: update docs to reflect new code generation approach List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Stefan Hajnoczi , =?UTF-8?q?Llu=C3=ADs=20Vilanova?= , Paolo Bonzini , Eric Blake , "Daniel P. Berrange" Describe use of per-subdir trace events files and how it impacts code generation. Reviewed-by: Stefan Hajnoczi Signed-off-by: Daniel P. Berrange --- docs/tracing.txt | 55 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 11 deletions(-) diff --git a/docs/tracing.txt b/docs/tracing.txt index f351998a..e14bb6d 100644 --- a/docs/tracing.txt +++ b/docs/tracing.txt @@ -27,18 +27,44 @@ for debugging, profiling, and observing execution. == Trace events == -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: +=== Sub-directory setup === - qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p" - qemu_vfree(void *ptr) "ptr %p" - -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". +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. + +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 + + - 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 -- 2.9.3