From patchwork Fri Jan 6 15:55:42 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= X-Patchwork-Id: 712050 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3tw9cS6m9zz9t0v for ; Sat, 7 Jan 2017 03:54:00 +1100 (AEDT) Received: from localhost ([::1]:53768 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cPXmA-0007iX-K6 for incoming@patchwork.ozlabs.org; Fri, 06 Jan 2017 11:53:58 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47535) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cPWt9-0005Iz-Vy for qemu-devel@nongnu.org; Fri, 06 Jan 2017 10:57:11 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cPWt8-0005WN-S0 for qemu-devel@nongnu.org; Fri, 06 Jan 2017 10:57:08 -0500 Received: from mx1.redhat.com ([209.132.183.28]:56210) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cPWt8-0005Vz-Jy for qemu-devel@nongnu.org; Fri, 06 Jan 2017 10:57:06 -0500 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id A8C66C04B942 for ; Fri, 6 Jan 2017 15:57:06 +0000 (UTC) Received: from t460.redhat.com (ovpn-116-194.ams2.redhat.com [10.36.116.194]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id v06FtlGj030318; Fri, 6 Jan 2017 10:57:05 -0500 From: "Daniel P. Berrange" To: qemu-devel@nongnu.org Date: Fri, 6 Jan 2017 15:55:42 +0000 Message-Id: <20170106155543.12827-47-berrange@redhat.com> In-Reply-To: <20170106155543.12827-1-berrange@redhat.com> References: <20170106155543.12827-1-berrange@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.31]); Fri, 06 Jan 2017 15:57:06 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2 46/47] trace: update docs to reflect new code generation approach X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Stefan Hajnoczi Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Describe use of per-subdir trace events files and how it impacts code generation. Signed-off-by: Daniel P. Berrange --- 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 :-) - qemu_vmalloc(size_t size, void *ptr) "size %zu ptr %p" - qemu_vfree(void *ptr) "ptr %p" +Any subdirectory which contains a "trace-events" file 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 together into a "trace-events-all" +file, which is also installed into "/usr/share/qemu" with the name "trace-events". +This merge file is to be used by the "simpletrace.py" script to later analyse +traces in the simpletrace data format. + +The Makefile.objs in the subdirectory should have two lines added + + trace-obj-y += trace.o + trace-obj-$(CONFIG_TRACE_DTRACE) += trace-dtrace.o + +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 + - 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 +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 === Trace events are invoked directly from source code like this: @@ -83,6 +116,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 @@ -372,6 +412,9 @@ information. If used together with the "tcg" property, it adds a second "TCGv_env" argument that must point to the per-target global TCG register that points to the vCPU when guest code is executed (usually the "cpu_env" variable). +All "vcpu" events *must* be declared in the top level "trace-events" file. It +is not permitted to have them declared in sub-directories. + The following example events: foo(uint32_t a) "a=%x"