diff options
Diffstat (limited to 'introduction.tex')
| -rw-r--r-- | introduction.tex | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/introduction.tex b/introduction.tex new file mode 100644 index 0000000..979881e --- /dev/null +++ b/introduction.tex @@ -0,0 +1,161 @@ +\chapter{Introduction} + +\input{abstract.tex} + +\begin{description} +\item[Straightforward:] Virtio devices use normal bus mechanisms of + interrupts and DMA which should be familiar to any device driver + author. There is no exotic page-flipping or COW mechanism: it's just + a normal device.\footnote{This lack of page-sharing implies that the implementation of the +device (e.g. the hypervisor or host) needs full access to the +guest memory. Communication with untrusted parties (i.e. +inter-guest communication) requires copying. +} + +\item[Efficient:] Virtio devices consist of rings of descriptors + for both input and output, which are neatly laid out to avoid cache + effects from both driver and device writing to the same cache + lines. + +\item[Standard:] Virtio makes no assumptions about the environment in which + it operates, beyond supporting the bus to which device is attached. + In this specification, virtio + devices are implemented over MMIO, Channel I/O and PCI bus transports +\footnote{The Linux implementation further separates the virtio +transport code from the specific virtio drivers: these drivers are shared +between different transports. +}, earlier drafts + have been implemented on other buses not included here. + +\item[Extensible:] Virtio devices contain feature bits which are + acknowledged by the guest operating system during device setup. + This allows forwards and backwards compatibility: the device + offers all the features it knows about, and the driver + acknowledges those it understands and wishes to use. +\end{description} + +\section{Normative References} + +\begin{longtable}{l p{5in}} + \phantomsection\label{intro:rfc2119}\textbf{[RFC2119]} & +Bradner S., ``Key words for use in RFCs to Indicate Requirement +Levels'', BCP 14, RFC 2119, March 1997. \newline\url{http://www.ietf.org/rfc/rfc2119.txt}\\ + \phantomsection\label{intro:S390 PoP}\textbf{[S390 PoP]} & z/Architecture Principles of Operation, IBM Publication SA22-7832, \newline\url{http://publibfi.boulder.ibm.com/epubs/pdf/dz9zr009.pdf}, and any future revisions\\ + \phantomsection\label{intro:S390 Common I/O}\textbf{[S390 Common I/O]} & ESA/390 Common I/O-Device and Self-Description, IBM Publication SA22-7204, \newline\url{http://publibfp.dhe.ibm.com/cgi-bin/bookmgr/BOOKS/dz9ar501/CCONTENTS}, and any future revisions\\ + \phantomsection\label{intro:PCI}\textbf{[PCI]} & + Conventional PCI Specifications, + \newline\url{http://www.pcisig.com/specifications/conventional/}, + PCI-SIG\\ + \phantomsection\label{intro:PCIe}\textbf{[PCIe]} & + PCI Express Specifications + \newline\url{http://www.pcisig.com/specifications/pciexpress/}, + PCI-SIG\\ + \phantomsection\label{intro:IEEE 802}\textbf{[IEEE 802]} & + IEEE Standard for Local and Metropolitan Area Networks: Overview and Architecture, + \newline\url{http://standards.ieee.org/about/get/802/802.html}, + IEEE\\ + \phantomsection\label{intro:SAM}\textbf{[SAM]} & + SCSI Architectural Model, + \newline\url{http://www.t10.org/cgi-bin/ac.pl?t=f&f=sam4r05.pdf}\\ + \phantomsection\label{intro:SCSI MMC}\textbf{[SCSI MMC]} & + SCSI Multimedia Commands, + \newline\url{http://www.t10.org/cgi-bin/ac.pl?t=f&f=mmc6r00.pdf}\\ + +\end{longtable} + +\section{Non-Normative References} + +\begin{longtable}{l p{5in}} + \phantomsection\label{intro:Virtio PCI Draft}\textbf{[Virtio PCI Draft]} & + Virtio PCI Draft Specification + \newline\url{http://ozlabs.org/~rusty/virtio-spec/virtio-0.9.5.pdf}\\ +\end{longtable} + +\section{Terminology}\label{Terminology} + +The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}. + +\subsection{Legacy Interface: Terminology}\label{intro:Legacy +Interface: Terminology} + +Earlier drafts of this specification (i.e. revisions before 1.0, +see e.g. \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}) +defined a similar, but different +interface between the driver and the device. +Since these are widely deployed, this specification +accommodates OPTIONAL features to simplify transition +from these earlier draft interfaces. + +Specifically devices and drivers MAY support: +\begin{description} +\item[Legacy Interface] + is an interface specified by an earlier draft of this specification + (before 1.0) +\item[Legacy Device] + is a device implemented before this specification was released, + and implementing a legacy interface on the host side +\item[Legacy Driver] + is a driver implemented before this specification was released, + and implementing a legacy interface on the guest side +\end{description} + +Legacy devices and legacy drivers are not compliant with this +specification. + +To simplify transition from these earlier draft interfaces, +a device MAY implement: + +\begin{description} +\item[Transitional Device] + a device supporting both drivers conforming to this + specification, and allowing legacy drivers. +\end{description} + +Similarly, a driver MAY implement: +\begin{description} +\item[Transitional Driver] + a driver supporting both devices conforming to this + specification, and legacy devices. +\end{description} + +\begin{note} + Legacy interfaces are not required; ie. don't implement them unless you + have a need for backwards compatibility! +\end{note} + +Devices or drivers with no legacy compatibility are referred to as +non-transitional devices and drivers, respectively. + +\subsection{Transition from earlier specification drafts}\label{sec:Transition from earlier specification drafts} + +For devices and drivers already implementing the legacy +interface, some changes will have to be made to support this +specification. + +In this case, it might be beneficial for the reader to focus on +sections tagged "Legacy Interface" in the section title. +These highlight the changes made since the earlier drafts. + +\section{Structure Specifications} + +Many device and driver in-memory structure layouts are documented using +the C struct syntax. All structures are assumed to be without additional +padding. To stress this, cases where common C compilers are known to insert +extra padding within structures are tagged using the GNU C +__attribute__((packed)) syntax. + +For the integer data types used in the structure definitions, the following +conventions are used: + +\begin{description} +\item[u8, u16, u32, u64] An unsigned integer of the specified length in bits. + +\item[le16, le32, le64] An unsigned integer of the specified length in bits, +in little-endian byte order. + +\item[be16, be32, be64] An unsigned integer of the specified length in bits, +in big-endian byte order. +\end{description} + +\newpage + |