README 4.2 KB

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