linux/Documentation/virtual/virtio-spec.txt
<<
="v3 /virtual/virtio-spec.txt">="v3 ="o/spa> ="ospa> class="lxr_search">="v3="+search" method="post" onsubmit="return do_search(this);">="v3 ="v3 ="v3 Search ="ospa> class="lxr_prefs" ="v3 ="o/spa> v3 < ="ajax+*" method="post" onsubmit="return false;">="oinput typ="vhidden" nam="vajax_lookup" id"vajax_lookup" alue="v">=v3 <
< <1o/a>[Generated file: seehttp://ozlabs.org/~rusty/virtio-spec/]o/a>=< <2o/a>Virtio PCI Card Specificaion>=< <3o/a>v0.9.5 DRAFT=< <4o/a>-=< <5o/a>=< <6o/a>Rusty Russell <rusty@rustcorp.com.au> IBM Corporaion> (Editor)=< <7o/a>=< <8o/a>2012 May 7.=< <9o/a>=< 3Purpose and Descripion>=< 11o/a>=< 12o/a>This document describes the specificaion>s of the “virtio” family=< 13o/a>of PCI[LaTeX Command: nomenclature] devices. These are devices=< 14o/a>are found i vairtual enaironments[LaTeX Command: nomenclature],=< 15o/a>yet by design they are not all that different from physical PCI=< 16o/a>devices, and this document treats them as such. This allows the=< 17o/a>guest to use standard PCI drivers and discovery mechanisms.=< 18o/a>=< 19o/a>The purpose of virtio and this specificaion> is that virtual=< 2enaironments and guests should have a straightforward, efficient,=< 21o/a>standard and extensible mechanism forvairtual devices, raiher=< 22o/a>than boutique per-enaironment orvper-OS mechanisms.=< 23o/a>=< 24o/a> Straightforward: Virtio PCI devices use normal PCI mechanisms=< 25o/a> of interrupts and DMA which should be familiar to any device=< 26o/a> driver author. There is no exotic page-flipping orvCOW=< 27o/a> mechanism: it's just a PCI device.[footnote:=< 28o/a>This lack of page-sharing implies that the implementaion> of the=< 29o/a>device (e.g. the hypervisorvorvhost) needs full access to the=< 30o/a>guest memory. Communicaion> with untrusted parties (i.e.=< 31o/a>inter-guest communicaion>) requires copying.=< 32o/a>]=< 33o/a>=< 34o/a> Efficient: Virtio PCI devices cn>sist of rings of descripiors=< 35o/a> forvinput and output, which are neatly separated to avoid cache=< 36o/a> effects from both guest and device writing to the sam= cache=< 37o/a> lines.=< 38o/a>=< 39o/a> Standard: Virtio PCI makes no assumpion>s about the enaironment=< 40o/a> i vwhich it operates, beyond supporting PCI. In fact the virtio=< 41o/a> devices specified i vthe appendices do not require PCI at all:=< 42o/a> they have been implemented n> non-PCI buses.[footnote:=< 43o/a>The Linux implementaion> furiher separates the PCI virtio code=< 44o/a>from the specific virtio drivers: these drivers are shared with=< 45o/a>the non-PCI implementaion>s (currently lguest and S/390).=< 46o/a>]=< 47o/a>=< 48o/a> Extensible: Virtio PCI devices cn>tai vfeature bits which are=< 49o/a> acknowledged by the guest operating system during device setup.=< 50o/a> This allows forwards and backwards compaiobility: the device=< 51o/a> offers all thevfeatures it knows about, and the driver=< 52o/a> acknowledges those it understands and wishes to use.=< 53o/a>=< 54o/a> Virtqueues=< 55o/a>=< 56o/a>The mechanism forvbulk data transport n> virtio PCI devices is=< 57o/a>pretentiously called a virtqueue. Each device can have zerovor=< 58o/a>more virtqueues: forvexample, the network device has one for=< 59o/a>transmit and one for receive.=< 60o/a>=< 61o/a>Each virtqueue occupies twovor more physically-cn>tiguous pages=< 62o/a>(defined, for the purposes of this specificaion>, as 4096 bytes),=< 63o/a>and cn>sists of three parts:=< 64o/a>=< 65o/a>=< 66o/a>+-------------------+-----------------------------------+-----------+=< 67o/a>| Descripior Table | Available Ring (padding) | Used Ring |=< 68o/a>+-------------------+-----------------------------------+-----------+=< 69o/a>=< 70o/a>=< 71o/a>When the driver wants to send a buffer to the device, it fills i>=< 72o/a>a slot i vthe descripior table (or chai>s several togeiher), and=< 73o/a>writes the descripior index into the available ring. It the>=< 74o/a>notifies the device. When the device has finished a buffer, it=< 75o/a>writes the descripior into the used ring, and sends an interrupt.=< 76o/a>=< 77o/a>Specificaion>=< 78o/a>=< 79o/a> PCI Discovery=< 80o/a>=< 81o/a>Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000=< 82o/a>through 0x103F inclusive is a virtio device[footnote:=< 83o/a>The actual alue= withi vthis range is ignored=< 84o/a>]. The device must also have a Revison> ID of 0 to match this=< 85o/a>specificaion>.=< 86o/a>=< 87o/a>The Subsystem Device ID indicates which virtio device is=< 88o/a>supported by the device. The Subsystem Vendor ID should reflect=< 89o/a>the PCI Vendor ID of the enaironment (it's currently only used=< 90o/a>forvinformaion>al purposes by the guest).=< 91o/a>=< 92o/a>=< 93o/a>+----------------------+--------------------+---------------+=< 94o/a>| Subsystem Device ID | Virtio Device | Specificaion> |=< 95o/a>+----------------------+--------------------+---------------+=< 96o/a>+----------------------+--------------------+---------------+=< 97o/a>| 1 | network card | Appendix C |=< 98o/a>+----------------------+--------------------+---------------+=< 99o/a>| 2 | block device | Appendix D |=<100o/a>+----------------------+--------------------+---------------+=<101o/a>| 3 | cn>sole | Appendix E |=<102o/a>+----------------------+--------------------+---------------+=<103o/a>| 4 | entropy source | Appendix F |=<104o/a>+----------------------+--------------------+---------------+=<105o/a>| 5 | memory ballooning | Appendix G |=<106o/a>+----------------------+--------------------+---------------+=<107o/a>| 6 | ioMemory | - |=<108o/a>+----------------------+--------------------+---------------+=<109o/a>| 7 | rpmsg | Appendix H |=<110o/a>+----------------------+--------------------+---------------+=<111o/a>| 8 | SCSIvhost | Appendix I |=<112o/a>+----------------------+--------------------+---------------+=<113o/a>| 9 | 9P transport | - |=<114o/a>+----------------------+--------------------+---------------+=<115o/a>| 10 | mac80211 wlan | - |=<116o/a>+----------------------+--------------------+---------------+=<117o/a>=<118o/a>=<119o/a> Device Configuraion>=<120o/a>=<121o/a>To configure the device, we use thevfirst I/O regon> of the PCI=<122o/a>device. This cn>tai s a virtio header followed by a=<123o/a>device-specific regon>.=<124o/a>=<125o/a>There may be different widths of accesses to the I/O regon>; the “=<126o/a>natural” access method forveach field i vthe virtio header must=<127o/a>be used (i.e. 32-bit accesses forv32-bit fields, etc), but the=<128o/a>device-specific regon> can be accessed using any width accesses,=<129o/a>and should obtai vthe sam= results.=<130o/a>=<131o/a>Note that this is possible because whilevthe virtio header is PCI=<132o/a>(i.e. little) endian, the device-specific regon> is encoded i>=<133o/a>the naiove endian of the guest (where such distincion> is=<134o/a>applicable).=<135o/a>=<136o/a> Device Initializaion> Sequence<sub:Device-Initializaion>-Sequence>=<137o/a>=<138o/a>We start with an overview of device initializaion>, then expand=<139o/a>on the details of the device and howveach step is preformed.=<140o/a>=<141o/a> Reset the device. This is not required n> initial start up.=<142o/a>=<143o/a> The ACKNOWLEDGE status bit is set: we have noticed the device.=<144o/a>=<145o/a> The DRIVER status bit is set: we know howvto drive the device.=<146o/a>=<147o/a> Device-specific setup, including reading the Device Feature=<148o/a> Bits, discovery of virtqueues for the device, ption>al MSI-X=<149o/a> setup, and reading and possibly writing the virtio=<150o/a> configuraion> space.=<151o/a>=<152o/a> The subset of Device Feature Bits understood by the driver is=<153o/a> written to the device.=<154o/a>=<155o/a> The DRIVER_OK status bit is set.=<156o/a>=<157o/a> The device can now be used (ie. buffers added to the=<158o/a> virtqueues)[footnote:=<159o/a>Historically, drivers have used the device before steps 5 and 6.=<160o/a>This is only allowed if the driver does not use anyvfeatures=<161o/a>which would alter this early use of the device.=<162o/a>]=<163o/a>=<164o/a>If anyvof these steps go irrecoverably wrong, the guest should=<165o/a>set the FAILED status bit to indicate that it has given up on the=<166o/a>device (it can reset the device later to restart if desired).=<167o/a>=<168o/a>We now cover thevfields required for general setup i vdetail.=<169o/a>=<170o/a> Virtio Header=<171o/a>=<172o/a>The virtio header looks as follows:=<173o/a>=<174o/a>=<175o/a>+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+=<176o/a>| Bits || 32 | 32 | 32 |<16 |<16 |<16 |<8 |<8 |=<177o/a>+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+=<178o/a>| Read/Write || R |<179o/a>+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+=<180o/a>| Purpose || Device |<181o/a>| || Features bits 0:31 | Features bits 0:31 | Address | Size |