0001 Trace Agent for virtio-trace
0002 ============================
0003
0004 Trace agent is a user tool for sending trace data of a guest to a Host in low
0005 overhead. Trace agent has the following functions:
0006 - splice a page of ring-buffer to read_pipe without memory copying
0007 - splice the page from write_pipe to virtio-console without memory copying
0008 - write trace data to stdout by using -o option
0009 - controlled by start/stop orders from a Host
0010
0011 The trace agent operates as follows:
0012 1) Initialize all structures.
0013 2) Create a read/write thread per CPU. Each thread is bound to a CPU.
0014 The read/write threads hold it.
0015 3) A controller thread does poll() for a start order of a host.
0016 4) After the controller of the trace agent receives a start order from a host,
0017 the controller wake read/write threads.
0018 5) The read/write threads start to read trace data from ring-buffers and
0019 write the data to virtio-serial.
0020 6) If the controller receives a stop order from a host, the read/write threads
0021 stop to read trace data.
0022
0023
0024 Files
0025 =====
0026
0027 README: this file
0028 Makefile: Makefile of trace agent for virtio-trace
0029 trace-agent.c: includes main function, sets up for operating trace agent
0030 trace-agent.h: includes all structures and some macros
0031 trace-agent-ctl.c: includes controller function for read/write threads
0032 trace-agent-rw.c: includes read/write threads function
0033
0034
0035 Setup
0036 =====
0037
0038 To use this trace agent for virtio-trace, we need to prepare some virtio-serial
0039 I/Fs.
0040
0041 1) Make FIFO in a host
0042 virtio-trace uses virtio-serial pipe as trace data paths as to the number
0043 of CPUs and a control path, so FIFO (named pipe) should be created as follows:
0044 # mkdir /tmp/virtio-trace/
0045 # mkfifo /tmp/virtio-trace/trace-path-cpu{0,1,2,...,X}.{in,out}
0046 # mkfifo /tmp/virtio-trace/agent-ctl-path.{in,out}
0047
0048 For example, if a guest use three CPUs, the names are
0049 trace-path-cpu{0,1,2}.{in.out}
0050 and
0051 agent-ctl-path.{in,out}.
0052
0053 2) Set up of virtio-serial pipe in a host
0054 Add qemu option to use virtio-serial pipe.
0055
0056 ##virtio-serial device##
0057 -device virtio-serial-pci,id=virtio-serial0\
0058 ##control path##
0059 -chardev pipe,id=charchannel0,path=/tmp/virtio-trace/agent-ctl-path\
0060 -device virtserialport,bus=virtio-serial0.0,nr=1,chardev=charchannel0,\
0061 id=channel0,name=agent-ctl-path\
0062 ##data path##
0063 -chardev pipe,id=charchannel1,path=/tmp/virtio-trace/trace-path-cpu0\
0064 -device virtserialport,bus=virtio-serial0.0,nr=2,chardev=charchannel0,\
0065 id=channel1,name=trace-path-cpu0\
0066 ...
0067
0068 If you manage guests with libvirt, add the following tags to domain XML files.
0069 Then, libvirt passes the same command option to qemu.
0070
0071 <channel type='pipe'>
0072 <source path='/tmp/virtio-trace/agent-ctl-path'/>
0073 <target type='virtio' name='agent-ctl-path'/>
0074 <address type='virtio-serial' controller='0' bus='0' port='0'/>
0075 </channel>
0076 <channel type='pipe'>
0077 <source path='/tmp/virtio-trace/trace-path-cpu0'/>
0078 <target type='virtio' name='trace-path-cpu0'/>
0079 <address type='virtio-serial' controller='0' bus='0' port='1'/>
0080 </channel>
0081 ...
0082 Here, chardev names are restricted to trace-path-cpuX and agent-ctl-path. For
0083 example, if a guest use three CPUs, chardev names should be trace-path-cpu0,
0084 trace-path-cpu1, trace-path-cpu2, and agent-ctl-path.
0085
0086 3) Boot the guest
0087 You can find some chardev in /dev/virtio-ports/ in the guest.
0088
0089
0090 Run
0091 ===
0092
0093 0) Build trace agent in a guest
0094 $ make
0095
0096 1) Enable ftrace in the guest
0097 <Example>
0098 # echo 1 > /sys/kernel/debug/tracing/events/sched/enable
0099
0100 2) Run trace agent in the guest
0101 This agent must be operated as root.
0102 # ./trace-agent
0103 read/write threads in the agent wait for start order from host. If you add -o
0104 option, trace data are output via stdout in the guest.
0105
0106 3) Open FIFO in a host
0107 # cat /tmp/virtio-trace/trace-path-cpu0.out
0108 If a host does not open these, trace data get stuck in buffers of virtio. Then,
0109 the guest will stop by specification of chardev in QEMU. This blocking mode may
0110 be solved in the future.
0111
0112 4) Start to read trace data by ordering from a host
0113 A host injects read start order to the guest via virtio-serial.
0114 # echo 1 > /tmp/virtio-trace/agent-ctl-path.in
0115
0116 5) Stop to read trace data by ordering from a host
0117 A host injects read stop order to the guest via virtio-serial.
0118 # echo 0 > /tmp/virtio-trace/agent-ctl-path.in
