Commit | Line | Data |
---|---|---|
108fc825 YY |
1 | Trace Agent for virtio-trace |
2 | ============================ | |
3 | ||
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 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 | ||
11 | The 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 | ||
24 | Files | |
25 | ===== | |
26 | ||
27 | README: this file | |
28 | Makefile: Makefile of trace agent for virtio-trace | |
29 | trace-agent.c: includes main function, sets up for operating trace agent | |
30 | trace-agent.h: includes all structures and some macros | |
31 | trace-agent-ctl.c: includes controller function for read/write threads | |
32 | trace-agent-rw.c: includes read/write threads function | |
33 | ||
34 | ||
35 | Setup | |
36 | ===== | |
37 | ||
38 | To use this trace agent for virtio-trace, we need to prepare some virtio-serial | |
39 | I/Fs. | |
40 | ||
41 | 1) Make FIFO in a host | |
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 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 | ||
48 | For example, if a guest use three CPUs, the names are | |
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-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 | ||
68 | If you manage guests with libvirt, add the following tags to domain XML files. | |
69 | Then, 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 | ... | |
82 | Here, chardev names are restricted to trace-path-cpuX and agent-ctl-path. For | |
83 | example, if a guest use three CPUs, chardev names should be trace-path-cpu0, | |
84 | trace-path-cpu1, trace-path-cpu2, and agent-ctl-path. | |
85 | ||
86 | 3) Boot the guest | |
87 | You can find some chardev in /dev/virtio-ports/ in the guest. | |
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/debug/tracing/events/sched/enable | |
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 order from host. If you add -o | |
104 | option, trace data are output via stdout in the guest. | |
105 | ||
106 | 3) Open FIFO in a host | |
107 | # cat /tmp/virtio-trace/trace-path-cpu0.out | |
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 chardev in QEMU. This blocking mode may | |
110 | be solved in the future. | |
111 | ||
112 | 4) 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 | ||
116 | 5) 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 |