1Trace Agent for virtio-trace 2============================ 3 4Trace agent is a user tool for sending trace data of a guest to a Host in low 5overhead. Trace agent has the following functions: 6 - splice a page of ring-buffer to read_pipe without memory copying 7 - splice the page from write_pipe to virtio-console without memory copying 8 - write trace data to stdout by using -o option 9 - controlled by start/stop orders from a Host 10 11The trace agent operates as follows: 12 1) Initialize all structures. 13 2) Create a read/write thread per CPU. Each thread is bound to a CPU. 14 The read/write threads hold it. 15 3) A controller thread does poll() for a start order of a host. 16 4) After the controller of the trace agent receives a start order from a host, 17 the controller wake read/write threads. 18 5) The read/write threads start to read trace data from ring-buffers and 19 write the data to virtio-serial. 20 6) If the controller receives a stop order from a host, the read/write threads 21 stop to read trace data. 22 23 24Files 25===== 26 27README: this file 28Makefile: Makefile of trace agent for virtio-trace 29trace-agent.c: includes main function, sets up for operating trace agent 30trace-agent.h: includes all structures and some macros 31trace-agent-ctl.c: includes controller function for read/write threads 32trace-agent-rw.c: includes read/write threads function 33 34 35Setup 36===== 37 38To use this trace agent for virtio-trace, we need to prepare some virtio-serial 39I/Fs. 40 411) Make FIFO in a host 42 virtio-trace uses virtio-serial pipe as trace data paths as to the number 43of CPUs and a control path, so FIFO (named pipe) should be created as follows: 44 # mkdir /tmp/virtio-trace/ 45 # mkfifo /tmp/virtio-trace/trace-path-cpu{0,1,2,...,X}.{in,out} 46 # mkfifo /tmp/virtio-trace/agent-ctl-path.{in,out} 47 48For example, if a guest use three CPUs, the names are 49 trace-path-cpu{0,1,2}.{in.out} 50and 51 agent-ctl-path.{in,out}. 52 532) Set up of virtio-serial pipe in a host 54 Add qemu option to use virtio-serial pipe. 55 56 ##virtio-serial device## 57 -device virtio-serial-pci,id=virtio-serial0\ 58 ##control path## 59 -chardev pipe,id=charchannel0,path=/tmp/virtio-trace/agent-ctl-path\ 60 -device virtserialport,bus=virtio-serial0.0,nr=1,chardev=charchannel0,\ 61 id=channel0,name=agent-ctl-path\ 62 ##data path## 63 -chardev pipe,id=charchannel1,path=/tmp/virtio-trace/trace-path-cpu0\ 64 -device virtserialport,bus=virtio-serial0.0,nr=2,chardev=charchannel0,\ 65 id=channel1,name=trace-path-cpu0\ 66 ... 67 68If you manage guests with libvirt, add the following tags to domain XML files. 69Then, libvirt passes the same command option to qemu. 70 71 <channel type='pipe'> 72 <source path='/tmp/virtio-trace/agent-ctl-path'/> 73 <target type='virtio' name='agent-ctl-path'/> 74 <address type='virtio-serial' controller='0' bus='0' port='0'/> 75 </channel> 76 <channel type='pipe'> 77 <source path='/tmp/virtio-trace/trace-path-cpu0'/> 78 <target type='virtio' name='trace-path-cpu0'/> 79 <address type='virtio-serial' controller='0' bus='0' port='1'/> 80 </channel> 81 ... 82Here, chardev names are restricted to trace-path-cpuX and agent-ctl-path. For 83example, if a guest use three CPUs, chardev names should be trace-path-cpu0, 84trace-path-cpu1, trace-path-cpu2, and agent-ctl-path. 85 863) Boot the guest 87 You can find some chardev in /dev/virtio-ports/ in the guest. 88 89 90Run 91=== 92 930) Build trace agent in a guest 94 $ make 95 961) Enable ftrace in the guest 97 <Example> 98 # echo 1 > /sys/kernel/debug/tracing/events/sched/enable 99 1002) Run trace agent in the guest 101 This agent must be operated as root. 102 # ./trace-agent 103read/write threads in the agent wait for start order from host. If you add -o 104option, trace data are output via stdout in the guest. 105 1063) Open FIFO in a host 107 # cat /tmp/virtio-trace/trace-path-cpu0.out 108If a host does not open these, trace data get stuck in buffers of virtio. Then, 109the guest will stop by specification of chardev in QEMU. This blocking mode may 110be solved in the future. 111 1124) Start to read trace data by ordering from a host 113 A host injects read start order to the guest via virtio-serial. 114 # echo 1 > /tmp/virtio-trace/agent-ctl-path.in 115 1165) Stop to read trace data by ordering from a host 117 A host injects read stop order to the guest via virtio-serial. 118 # echo 0 > /tmp/virtio-trace/agent-ctl-path.in 119