Re: [Qemu-devel] [PATCH v3 1/6] hypertrace: Add documentation

[Lluís Vilanova]

Daniel P Berrange writes:

> On Wed, Sep 28, 2016 at 03:05:36PM +0200, Lluís Vilanova wrote:
>> Signed-off-by: Lluís Vilanova <address@hidden>
>> ---
>> docs/hypertrace.txt |  232 
>> +++++++++++++++++++++++++++++++++++++++++++++++++++
>> docs/tracing.txt    |    3 +
>> 2 files changed, 235 insertions(+)
>> create mode 100644 docs/hypertrace.txt

>> +== Quick guide ==
>> +
>> +This shows an example of using the hypertrace channel to trace the guest 
>> memory
>> +accesses only in a specific guest code region, which is identified by calls 
>> to
>> +the hypertrace channel.
>> +
>> +We are going to trace memory accesses to disk using QEMU's "log" backend, 
>> and
>> +will use QEMU's "dtrace" (SystemTap) backend to ensure memory accesses are 
>> only
>> +traced in the guest code region of interest. The first time the guest code
>> +invokes the hypertrace channel, we will start tracing the
>> +"guest_mem_before_exec" event using dtrace, and then will disable it the 
>> second
>> +time around.
>> +
>> +Tracing is done with "log" because it is more efficient than using "dtrace" 
>> in
>> +high-volume events like memory accesses. If the event rate is low, you can
>> +ignore the "log" backend and simply use "dtrace"'s printf, while still 
>> using the
>> +hypertrace events to identify guest semantics.
>> +
>> +1. Set the tracing backends and number of arguments for the hypertrace 
>> events:
>> +
>> +    mkdir /tmp/qemu-build
>> +    cd /tmp/qemu-build
>> +    /path/to/qemu-source/configure              \
>> +        --enable-trace-backends=dtrace,log      \
>> +        --with-hypertrace-args=4                \
>> +        --prefix=/tmp/qemu-install
>> +    make -j install
>> +
>> +2. Enable the event "guest_mem_before_exec":
>> +
>> +    sed -i -e 's/disable vcpu tcg guest_mem_before/vcpu tcg 
>> guest_mem_before/g' /path/to/qemu-source/trace-events
>> +
>> +3. Compile the 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:
>> +
>> +    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" to interact with the
>> +   hypertrace channel:
>> +
>> +    cat > /tmp/my-hypertrace.c <<\EOF
>> +    #include <stdio.h>
>> +    #include <errno.h>
>> +    #include <stdlib.h>
>> +    #include <string.h>
>> +    #include <qemu-hypertrace.h>
>> +    
>> +    
>> +    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) {
>> +            perror("error: qemu_hypertrace_init");
>> +            abort();
>> +        }
>> +    
>> +        /* Set additional event arguments */
>> +        uint64_t client  = 0;

> IIUC, 'client' is the field that the host uses to distinguish
> between different guest applications or different guest threads.

> How are applications expected to assign themselves a unique
> value for this field ? 

> It feels that life would be easier if you made this field be
> 128-bits instead of 64-bit, as then you could encode a UUID
> in it, making it much easier to guarnatee uniqueness without
> having to have a central authority.

I intentionally left this completely up to the guest applications.

We cannot use UUIDs because the client ID is used as an index to the control
channel memory region (qemu_hypertrace()) (*).

This allows us to have clients write into their own index to trigger the event,
without having to synchronize. Otherwise, we'd need the write in
qemu_hypertrace() to be atomic, either through locks (adding more "noise" to the
guest) or atomic memory stores (difficult to enforce in an architecture-agnostic
way, specially if they're 128-bit).

(*) It's also used as an index to the data channel memory region
    (qemu_hypertrace_data()), but that's less important now.


>> +        uint64_t *data = qemu_hypertrace_data(client);
>> +        data[0] = 0xcafe;
>> +        data[1] = 0xdead;
>> +        data[2] = 0xbeef;
>> +    
>> +        /* Emit event to start tracing */
>> +        qemu_hypertrace(client, 1);
>> +
>> +        /* Computation in between */
>> +        printf("Some computation...\n");
>> +
>> +        /* Emit event to stop tracing */
>> +        qemu_hypertrace(client, 0);
>> +    }
>> +    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 -lpthread
>> +
>> +    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 -lpthread

> Regards,
> Daniel

Thanks,
  Lluis