tools/virtio/virtio-trace/README

Source file repositories/reference/linux-study-clean/tools/virtio/virtio-trace/README

File Facts

System
Linux kernel
Corpus path
tools/virtio/virtio-trace/README
Extension
[no extension]
Size
4278 bytes
Lines
119
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: tools
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

Trace Agent for virtio-trace
============================

Trace agent is a user tool for sending trace data of a guest to a Host in low
overhead. Trace agent has the following functions:
 - splice a page of ring-buffer to read_pipe without memory copying
 - splice the page from write_pipe to virtio-console without memory copying
 - write trace data to stdout by using -o option
 - controlled by start/stop orders from a Host

The trace agent operates as follows:
 1) Initialize all structures.
 2) Create a read/write thread per CPU. Each thread is bound to a CPU.
    The read/write threads hold it.
 3) A controller thread does poll() for a start order of a host.
 4) After the controller of the trace agent receives a start order from a host,
    the controller wake read/write threads.
 5) The read/write threads start to read trace data from ring-buffers and
    write the data to virtio-serial.
 6) If the controller receives a stop order from a host, the read/write threads
    stop to read trace data.


Files
=====

README: this file
Makefile: Makefile of trace agent for virtio-trace
trace-agent.c: includes main function, sets up for operating trace agent
trace-agent.h: includes all structures and some macros
trace-agent-ctl.c: includes controller function for read/write threads
trace-agent-rw.c: includes read/write threads function


Setup
=====

To use this trace agent for virtio-trace, we need to prepare some virtio-serial
I/Fs.

1) Make FIFO in a host
 virtio-trace uses virtio-serial pipe as trace data paths as to the number
of CPUs and a control path, so FIFO (named pipe) should be created as follows:
	# mkdir /tmp/virtio-trace/
	# mkfifo /tmp/virtio-trace/trace-path-cpu{0,1,2,...,X}.{in,out}
	# mkfifo /tmp/virtio-trace/agent-ctl-path.{in,out}

For example, if a guest use three CPUs, the names are
	trace-path-cpu{0,1,2}.{in.out}
and
	agent-ctl-path.{in,out}.

2) Set up of virtio-serial pipe in a host
 Add qemu option to use virtio-serial pipe.

 ##virtio-serial device##
     -device virtio-serial-pci,id=virtio-serial0\
 ##control path##
     -chardev pipe,id=charchannel0,path=/tmp/virtio-trace/agent-ctl-path\
     -device virtserialport,bus=virtio-serial0.0,nr=1,chardev=charchannel0,\
      id=channel0,name=agent-ctl-path\
 ##data path##
     -chardev pipe,id=charchannel1,path=/tmp/virtio-trace/trace-path-cpu0\
     -device virtserialport,bus=virtio-serial0.0,nr=2,chardev=charchannel1,\
      id=channel1,name=trace-path-cpu0\
      ...

If you manage guests with libvirt, add the following tags to domain XML files.
Then, libvirt passes the same command option to qemu.

Annotation

Implementation Notes