The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/tools/virtio/virtio-trace/

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

Name Size Last modified (GMT) Description
Back Parent directory 2013-02-02 13:02:19
File Makefile 211 bytes 2012-12-25 01:46:56
File README 4284 bytes 2012-12-25 01:46:56
C file trace-agent-ctl.c 2676 bytes 2012-12-25 01:46:56
C file trace-agent-rw.c 4401 bytes 2012-12-25 01:46:56
C file trace-agent.c 5238 bytes 2012-12-25 01:46:56
C file trace-agent.h 2100 bytes 2012-12-25 01:46:56

    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

[ source navigation ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.