From patchwork Wed Sep 6 17:26:43 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Llu=C3=ADs_Vilanova?= X-Patchwork-Id: 9941123 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A0CFA60216 for ; Wed, 6 Sep 2017 17:27:54 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 8857C28622 for ; Wed, 6 Sep 2017 17:27:54 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 7BC1B28BFA; Wed, 6 Sep 2017 17:27:54 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 89D7228622 for ; Wed, 6 Sep 2017 17:27:53 +0000 (UTC) Received: from localhost ([::1]:37258 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dpe7E-0000pR-Ib for patchwork-qemu-devel@patchwork.kernel.org; Wed, 06 Sep 2017 13:27:52 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36678) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dpe6P-0000fa-8l for qemu-devel@nongnu.org; Wed, 06 Sep 2017 13:27:03 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dpe6I-00031S-Rj for qemu-devel@nongnu.org; Wed, 06 Sep 2017 13:27:01 -0400 Received: from roura.ac.upc.es ([147.83.33.10]:55283) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dpe6I-00030f-EH for qemu-devel@nongnu.org; Wed, 06 Sep 2017 13:26:54 -0400 Received: from correu-1.ac.upc.es (correu-1.ac.upc.es [147.83.30.91]) by roura.ac.upc.es (8.13.8/8.13.8) with ESMTP id v86HQpdg003765; Wed, 6 Sep 2017 19:26:51 +0200 Received: from localhost (unknown [31.210.187.58]) by correu-1.ac.upc.es (Postfix) with ESMTPSA id B435D7FD; Wed, 6 Sep 2017 19:26:45 +0200 (CEST) From: =?utf-8?b?TGx1w61z?= Vilanova To: qemu-devel@nongnu.org Date: Wed, 6 Sep 2017 20:26:43 +0300 Message-Id: <150471880362.24907.17816085971167173217.stgit@frigg.lan> X-Mailer: git-send-email 2.14.1 In-Reply-To: <150471856141.24907.274176769201097378.stgit@frigg.lan> References: <150471856141.24907.274176769201097378.stgit@frigg.lan> User-Agent: StGit/0.17.1-dirty MIME-Version: 1.0 X-MIME-Autoconverted: from 8bit to quoted-printable by roura.ac.upc.es id v86HQpdg003765 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x [fuzzy] X-Received-From: 147.83.33.10 Subject: [Qemu-devel] [PATCH v4 01/20] instrument: Add documentation 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: "Emilio G. Cota" , =?UTF-8?q?Llu=C3=ADs=20Vilanova?= , Stefan Hajnoczi Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: "Qemu-devel" X-Virus-Scanned: ClamAV using ClamSMTP Signed-off-by: Lluís Vilanova --- MAINTAINERS | 6 ++ docs/instrument.txt | 174 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 docs/instrument.txt diff --git a/MAINTAINERS b/MAINTAINERS index ccee28b12d..edb313c632 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1480,6 +1480,12 @@ F: scripts/tracetool/ F: docs/tracing.txt T: git git://github.com/stefanha/qemu.git tracing +Event instrumentation +M: Lluís Vilanova +M: Stefan Hajnoczi +S: Maintained +F: docs/instrument.txt + Checkpatch S: Odd Fixes F: scripts/checkpatch.pl diff --git a/docs/instrument.txt b/docs/instrument.txt new file mode 100644 index 0000000000..c43ca9c6d0 --- /dev/null +++ b/docs/instrument.txt @@ -0,0 +1,174 @@ += Event instrumentation = + +== Introduction == + +Event instrumentation allows users to execute their own host-native code on a +set of pre-defined events provided by QEMU. QEMU also exposes other +functionality to peek/poke at the guest state (e.g., memory or registers), as +well as interacting with tracing events. For those familiar with the term, this +provides dynamic binary instrumentation, works on all QEMU-supported +architectures, as well as works in both 'user' (standalone application) and +'system' (full-system emulation) modes. + +Look at the headers installed by QEMU on the "qemu-instr" directory for further +information beyond this document. + + +== Loading an instrumentation library == + +Instrumentation code can be bundled into a dynamic library, which can be later +loaded into QEMU: + +* Using the command-line "-instr" argument. + +* Using the "instr-load" and "instr-unload" commands in the HMP and QMP + interfaces. + + +== Example == + +1. Configure QEMU with event instrumentation: + + # instrument guest_cpu_enter and guest_mem_before + mkdir -p /path/to/qemu-build + cd /path/to/qemu-build + /path/to/qemu-source/configure \ + --enable-instrument \ + --prefix=/path/to/qemu-install + +2. Build and install QEMU: + + make install + +3. Create the "Makefile" to build the instrumentation library: + + mkdir -p /tmp/my-instrument + + cat > /tmp/my-instrument/Makefile < /tmp/my-instrument/instrument.c < + #include + + #include /* manipulate events */ + #include /* manipulate tracing */ + #include /* symbol visibility */ + + /* the address for the memory access is not known at translation time */ + void guest_mem_before_trans(QICPU vcpu_trans, QITCGv_cpu vcpu_exec, + QITCGv vaddr, QIMemInfo info) + { + printf("%s: %p %p %p %d %d %d %d\n", __func__, vcpu_trans, vcpu_exec, vaddr, + 1 << info.size_shift, info.sign_extend, info.endianness, info.store); + if (info.store) { + /* generate at execution time only for memory writes */ + qi_event_gen_guest_mem_before_exec(vcpu_exec, vaddr, info); + } + } + + /* called when QEMU executes a memory access */ + void guest_mem_before_exec(QICPU vcpu, uint64_t vaddr, QIMemInfo info) + { + if (info.store) { + /* if called by TCG code, we'll only get writes (see above) */ + printf("%s: %p %lx %d %d %d %d\n", __func__, vcpu, vaddr, + 1 << info.size_shift, info.sign_extend, info.endianness, info.store); + } + } + + /* called every time QEMU hotplugs a CPU */ + void guest_cpu_enter(QICPU vcpu) + { + printf("%s: %p\n", __func__, vcpu); + + /* disable instrumentation and tracing after the first call */ + static bool found = false; + if (found) { + qi_event_set_guest_cpu_enter(NULL); + QITraceEvent *ev = qi_trace_event_name("guest_cpu_enter"); + assert(ev); + qi_trace_event_set_state_dynamic(ev, true); + } else { + found = true; + } + } + + static void fini(void *data) + { + /* diable all tracing events */ + QITraceEventIter iter; + qi_trace_event_iter_init(&iter, NULL); + QITraceEvent *ev; + while ((ev = qi_trace_event_iter_next(&iter)) != NULL) { + if (qi_trace_event_get_state_static(ev)) { + qi_trace_event_set_state_dynamic(ev, false); + } + } + + /* instrumentation callbacks are automatically reset by QEMU */ + } + + /* mandatory initialization function */ + QI_VPUBLIC int main(int argc, const char **argv) + { + int i; + printf("init!\n"); + printf(" argc :: %d\n", argc); + for (i = 0; i < argc; i++) { + printf(" -> %s\n", argv[i]); + } + + qi_set_fini(fini, NULL); + + /* instrument and trace events */ + QITraceEvent *ev; + + qi_event_set_guest_cpu_enter(guest_cpu_enter); + ev = qi_trace_event_name("guest_cpu_enter"); + assert(ev); + qi_trace_event_set_state_dynamic(ev, true); + + qi_event_set_guest_mem_before_trans(guest_mem_before_trans); + ev = qi_trace_event_name("guest_mem_before_trans"); + assert(ev); + qi_trace_event_set_state_dynamic(ev, true); + + qi_event_set_guest_mem_before_exec(guest_mem_before_exec); + ev = qi_trace_event_name("guest_mem_before_exec"); + assert(ev); + qi_trace_event_set_state_dynamic(ev, true); + + return 0; + } + EOF + +5. Compile the instrumentation library: + + make -C /tmp/my-instrument + +6. Start QEMU with the instrumentation library: + + /tmp/qemu-install/bin/qemu-system-x86_64 \ + -instr file=/tmp/my-dinstrument/.libs/libtrace-instrument.so, \ + arg=foo,arg=bar