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