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