From patchwork Fri Aug 5 16:59:29 2016 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: 656253 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 3s5Y3j2G5Yz9s9G for ; Sat, 6 Aug 2016 03:01:05 +1000 (AEST) Received: from localhost ([::1]:46279 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bViUZ-0001AH-9M for incoming@patchwork.ozlabs.org; Fri, 05 Aug 2016 13:01:03 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:49875) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bViT9-0008Sd-VM for qemu-devel@nongnu.org; Fri, 05 Aug 2016 12:59:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bViT4-0002vm-K1 for qemu-devel@nongnu.org; Fri, 05 Aug 2016 12:59:34 -0400 Received: from roura.ac.upc.edu ([147.83.33.10]:52920 helo=roura.ac.upc.es) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bViT4-0002vh-4f for qemu-devel@nongnu.org; Fri, 05 Aug 2016 12:59:30 -0400 Received: from gw-3.ac.upc.es (gw-3.ac.upc.es [147.83.30.9]) by roura.ac.upc.es (8.13.8/8.13.8) with ESMTP id u75GxT6A019637; Fri, 5 Aug 2016 18:59:29 +0200 Received: from localhost (unknown [84.88.51.85]) by gw-3.ac.upc.es (Postfix) with ESMTPSA id 3C7C9654; Fri, 5 Aug 2016 18:59:29 +0200 (CEST) From: =?utf-8?b?TGx1w61z?= Vilanova To: qemu-devel@nongnu.org Date: Fri, 5 Aug 2016 18:59:29 +0200 Message-Id: <147041636895.2523.17410454408859217963.stgit@fimbulvetr.bsc.es> X-Mailer: git-send-email 2.8.1 In-Reply-To: <147041636348.2523.2954972609232949598.stgit@fimbulvetr.bsc.es> References: <147041636348.2523.2954972609232949598.stgit@fimbulvetr.bsc.es> 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 u75GxT6A019637 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 147.83.33.10 Subject: [Qemu-devel] [PATCH 1/6] hypertrace: 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: Stefan Hajnoczi Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Lluís Vilanova --- docs/hypertrace.txt | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++ docs/tracing.txt | 3 + 2 files changed, 144 insertions(+) create mode 100644 docs/hypertrace.txt diff --git a/docs/hypertrace.txt b/docs/hypertrace.txt new file mode 100644 index 0000000..4a31bcd --- /dev/null +++ b/docs/hypertrace.txt @@ -0,0 +1,141 @@ += Hypertrace channel = + +The hypertrace channel allows guest code to emit events in QEMU (the host) using +its tracing infrastructure (see "docs/trace.txt"). This works in both 'system' +and 'user' modes. That is, hypertrace is to tracing, what hypercalls are to +system calls. + +You can use this to emit an event on both guest and QEMU (host) traces to easily +synchronize or correlate them. You could also modify you guest's tracing system +to emit all events through the hypertrace channel, providing a unified and fully +synchronized trace log. Another use case is timing the performance of guest code +when optimizing TCG (QEMU traces have a timestamp). + +QEMU provides an example library and Linux kernel module that guest code can use +to interact with the hypertrace channel. + +Hypertrace highlights: + +* Works with 'system' and 'user' mode. + +* Minimal setup for the guest (e.g., 'system' mode with Linux and 'user' mode + work out of the box). + +* Independent of guest architecture; the guest code uses accesses to special + memory regions, as opposed to redefining instruction semantics. + +* Negligible guest overhead; guest operations do not go through any OS + abstraction, except during the setup of the communication channel. + +Warning: The hypertrace channel in 'system' mode is presented as a PCI device, +and thus will only be available on systems with support for PCI. You can get the +list of guests with PCI support with 'grep pci.mak default-configs/*'. + + +== Quick guide == + +1. Set the number of arguments for the hypertrace events: + + mkdir /tmp/qemu-build + cd /tmp/qemu-build + /path/to/qemu-source/configure \ + --with-hypertrace-args=1 \ + --prefix=/tmp/qemu-install + make -j install + +2. Compile the corresponding guest support code: + + make -C /tmp/qemu-build/x86_64-linux-user/hypertrace/guest/user + make -C /tmp/qemu-build/x86_64-softmmu/hypertrace/guest/user + make -C /tmp/qemu-build/x86_64-softmmu/hypertrace/guest/linux-module + + If you need to cross-compile the guest library, set the 'CC' variable (e.g., + for mipsel): + + make -C /tmp/qemu-build/mipsel-linux-user/hypertrace/guest/user CC=mipsel-gnu-linux-gcc + +3. Create a guest application using "qemu-hypertrace.h": + + cat > /tmp/my-hypertrace.c < + #include + #include + #include + #include + + + int main(int argc, char **argv) + { + char *base = NULL; + if (argc > 1) { + base = argv[1]; + } + + /* In 'user' mode this path must be the same we will use to start QEMU. */ + if (qemu_hypertrace_init(base) != 0) { + fprintf(stderr, "error: qemu_hypertrace_init: %s\n", strerror(errno)); + abort(); + } + + /* Set event arguments */ + uint64_t voffset = 0; + uint64_t *data = qemu_hypertrace_data(voffset); + data[0] = 0xcafe; + data[1] = 0xbabe; + data[2] = 0xdead; + data[3] = 0xbeef; + + /* Emit event */ + printf("emitting hypertrace event\n"); + qemu_hypertrace(voffset); + } + EOF + + gcc -o /tmp/my-hypertrace-user /tmp/my-hypertrace.c \ + /tmp/qemu-build/x86_64-linux-user/hypertrace/guest/user/libqemu-hypertrace-guest.a \ + -I/tmp/qemu-install/include + + gcc -o /tmp/my-hypertrace-softmmu /tmp/my-hypertrace.c \ + /tmp/qemu-build/x86_64-softmmu/hypertrace/guest/user/libqemu-hypertrace-guest.a \ + -I/tmp/qemu-install/include + +4. Run a guest with access to QEMU's hypertrace: + + /tmp/qemu-install/bin/qemu-x86_64 \ + -hypertrace /tmp/hypertrace \ + -trace enable=guest* -D /dev/stdout \ + /tmp/my-hypertrace-user /tmp/hypertrace + + Or, to run in 'system' mode: + + /tmp/qemu-install/x86_64-softmmu/qemu-system-x86_64 \ + -device hypertrace \ + -trace enable=guest* -D /dev/stdout \ + ... + + And inside the VM: + + sudo /tmp/my-hypertrace-softmmu + + You can also use hypertrace from Linux's kernel code with the provided module + (see the header in "/tmp/qemu-install/include/linux/qemu-hypertrace.h"): + + sudo insmod /tmp/qemu-build/x86_64-softmmu/hypertrace/guest/linux-module/qemu-hypertrace.ko + +== Details == + +To make it more efficient in terms of guest and host time, hypertrace provides +two different memory areas (channels). + +The control channel is used by the guest to tell QEMU that new data is ready to +be processed in the data channel. Writes to the control channel are intercepted +by QEMU, which emits the "hypertrace" tracing event. + +The data channel is a regular memory buffer used by the guest to write the event +arguments before raising the event through the control channel. + +The data channel is a physical memory region used by all virtual CPUs. To allow +multiple guest threads or virtual CPUs to use hypertrace concurrently, the value +passed on the control channel is used as an index to the data channel (i.e., +each guest thread or virtual CPU must write on a different portion of the data +channel). diff --git a/docs/tracing.txt b/docs/tracing.txt index 29f2f9a..f312596 100644 --- a/docs/tracing.txt +++ b/docs/tracing.txt @@ -5,6 +5,9 @@ This document describes the tracing infrastructure in QEMU and how to use it for debugging, profiling, and observing execution. +See "docs/hypertrace.txt" to correlate guest tracing events with those in the +QEMU host. + == Quickstart == 1. Build with the 'simple' trace backend: