From mboxrd@z Thu Jan 1 00:00:00 1970 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 From: =?utf-8?b?TGx1w61z?= Vilanova Date: Fri, 5 Aug 2016 18:59:29 +0200 Message-Id: <147041636895.2523.17410454408859217963.stgit@fimbulvetr.bsc.es> In-Reply-To: <147041636348.2523.2954972609232949598.stgit@fimbulvetr.bsc.es> References: <147041636348.2523.2954972609232949598.stgit@fimbulvetr.bsc.es> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Subject: [Qemu-devel] [PATCH 1/6] hypertrace: Add documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Stefan Hajnoczi Signed-off-by: Llu=C3=ADs 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 @@ +=3D Hypertrace channel =3D + +The hypertrace channel allows guest code to emit events in QEMU (the hos= t) using +its tracing infrastructure (see "docs/trace.txt"). This works in both 's= ystem' +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 t= o 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 a= nd fully +synchronized trace log. Another use case is timing the performance of gu= est 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 spe= cial + 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 d= evice, +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/*'. + + +=3D=3D Quick guide =3D=3D + +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=3D1 \ + --prefix=3D/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=3D= mipsel-gnu-linux-gcc + +3. Create a guest application using "qemu-hypertrace.h": + + cat > /tmp/my-hypertrace.c < + #include + #include + #include + #include + =20 + =20 + int main(int argc, char **argv) + { + char *base =3D NULL; + if (argc > 1) { + base =3D argv[1]; + } + + /* In 'user' mode this path must be the same we will use to star= t QEMU. */ + if (qemu_hypertrace_init(base) !=3D 0) { + fprintf(stderr, "error: qemu_hypertrace_init: %s\n", strerro= r(errno)); + abort(); + } + =20 + /* Set event arguments */ + uint64_t voffset =3D 0; + uint64_t *data =3D qemu_hypertrace_data(voffset); + data[0] =3D 0xcafe; + data[1] =3D 0xbabe; + data[2] =3D 0xdead; + data[3] =3D 0xbeef; + =20 + /* 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-hyp= ertrace-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=3Dguest* -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=3Dguest* -D /dev/stdout \ + ... + + And inside the VM: + + sudo /tmp/my-hypertrace-softmmu + + You can also use hypertrace from Linux's kernel code with the provide= d module + (see the header in "/tmp/qemu-install/include/linux/qemu-hypertrace.h= "): + + sudo insmod /tmp/qemu-build/x86_64-softmmu/hypertrace/guest/linux-mo= dule/qemu-hypertrace.ko + +=3D=3D Details =3D=3D + +To make it more efficient in terms of guest and host time, hypertrace pr= ovides +two different memory areas (channels). + +The control channel is used by the guest to tell QEMU that new data is r= eady to +be processed in the data channel. Writes to the control channel are inte= rcepted +by QEMU, which emits the "hypertrace" tracing event. + +The data channel is a regular memory buffer used by the guest to write t= he event +arguments before raising the event through the control channel. + +The data channel is a physical memory region used by all virtual CPUs. T= o allow +multiple guest threads or virtual CPUs to use hypertrace concurrently, t= he 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 th= e 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 us= e it for debugging, profiling, and observing execution. =20 +See "docs/hypertrace.txt" to correlate guest tracing events with those i= n the +QEMU host. + =3D=3D Quickstart =3D=3D =20 1. Build with the 'simple' trace backend: