summaryrefslogtreecommitdiff
path: root/virtio-v1.0-wd01-part1-specification.txt
diff options
context:
space:
mode:
Diffstat (limited to 'virtio-v1.0-wd01-part1-specification.txt')
-rw-r--r--virtio-v1.0-wd01-part1-specification.txt4219
1 files changed, 0 insertions, 4219 deletions
diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
deleted file mode 100644
index ba3ecae..0000000
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ /dev/null
@@ -1,4219 +0,0 @@
-1. INTRODUCTION
-===============
-
-This document describes the specifications of the “virtio” family of
-devices. These are devices are found in virtual environments, yet by
-design they are not all that different from physical devices, and this
-document treats them as such. This allows the guest to use standard
-drivers and discovery mechanisms.
-
-The purpose of virtio and this specification is that virtual
-environments and guests should have a straightforward, efficient,
-standard and extensible mechanism for virtual devices, rather
-than boutique per-environment or per-OS mechanisms.
-
- 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.[1]
-
- Efficient: Virtio devices consist of rings of descriptors
- for input and output, which are neatly separated to avoid cache
- effects from both guest and device writing to the same cache
- lines.
-
- Standard: Virtio makes no assumptions about the environment in which
- it operates, beyond supporting the bus attaching the device. Virtio
- devices are implemented over PCI and other buses, and earlier drafts
- been implemented on other buses not included in this spec.[2]
-
- Extensible: Virtio PCI 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.
-
-1.1.1. Key words
------------------
-
-The key words must, must not, required, shall, shall not, should,
-should not, recommended, may, and optional are to be interpreted as
-described in [RFC 2119]. Note that for reasons of style, these words
-are not capitalized in this document.
-
-1.1.2. Definitions
--------------------
-
-term
- Definition
-
-1.1.3. Key concepts
---------------------
-
-Guest
- Definition...
-
-Host
- Definition
-
-Device
- Definition
-
-Driver
- Definition
-
-1.2. Normative References
-=========================
-
-[RFC 2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt IETF (Internet Engineering Task Force) RFC 2119, March 1997.
-
-[S390 PoP] z/Architecture Principles of Operation, IBM Publication SA22-7832
-
-[S390 Common I/O] ESA/390 Common I/O-Device and Self-Description, IBM Publication SA22-7204
-
-1.3. Non-Normative References
-=========================
-
-
-
-2. The Virtio Standard
-=========================
-
-2.1. Basic Facilities of a Virtio Device
-=======================================
-
-A virtio device is discovered and identified by a bus-specific method
-(see the bus specific sections: "2.3.1. Virtio Over PCI Bus",
-"2.3.2. Virtio Over MMIO" and "2.3.3. Virtio over channel I/O"). Each
-device consists of the following parts:
-
-o Device Status field
-o Feature bits
-o Configuration space
-o One or more virtqueues
-
-Unless explicitly specified otherwise, all multi-byte fields are little-endian.
-To reinforce this the examples use typenames like "le16" instead of "uint16_t".
-
-2.1.1. Device Status Field
--------------------------
-
-The Device Status field is updated by the guest to indicate its
-progress. This provides a simple low-level diagnostic: it's most
-useful to imagine them hooked up to traffic lights on the console
-indicating the status of each device.
-
-This field is 0 upon reset, otherwise at least one bit should be set:
-
- ACKNOWLEDGE (1) Indicates that the guest OS has found the
- device and recognized it as a valid virtio device.
-
- DRIVER (2) Indicates that the guest OS knows how to drive the
- device. Under Linux, drivers can be loadable modules so there
- may be a significant (or infinite) delay before setting this
- bit.
-
- FEATURES_OK (8) Indicates that the driver has acknowledged all the
- features it understands, and feature negotiation is complete.
-
- DRIVER_OK (4) Indicates that the driver is set up and ready to
- drive the device.
-
- FAILED (128) Indicates that something went wrong in the guest,
- and it has given up on the device. This could be an internal
- error, or the driver didn't like the device for some reason, or
- even a fatal error during device operation. The device must be
- reset before attempting to re-initialize.
-
-2.1.2. Feature Bits
-------------------
-
-Each virtio device lists all the features it understands. During
-device initialization, the guest reads this and tells the device the
-subset that it understands. The only way to renegotiate is to reset
-the device.
-
-This allows for forwards and backwards compatibility: if the device is
-enhanced with a new feature bit, older guests will not write that
-feature bit back to the device and it can go into backwards
-compatibility mode. Similarly, if a guest is enhanced with a feature
-that the device doesn't support, it see the new feature is not offered
-and can go into backwards compatibility mode (or, for poor
-implementations, set the FAILED Device Status bit).
-
-Feature bits are allocated as follows:
-
- 0 to 23: Feature bits for the specific device type
-
- 24 to 32: Feature bits reserved for extensions to the queue and
- feature negotiation mechanisms
-
- 33 and above: Feature bits reserved for future extensions.
-
-For example, feature bit 0 for a network device (i.e. Subsystem
-Device ID 1) indicates that the device supports checksumming of
-packets.
-
-In particular, new fields in the device configuration space are
-indicated by offering a feature bit, so the guest can check
-before accessing that part of the configuration space.
-
-2.1.2.1. Legacy Interface: A Note on transitions from earlier drafts
---------------------------------------
-
-Earlier drafts of this specification (up to 0.9.X) defined a similar, but
-different interface between the hypervisor and the guest.
-Since these are widely deployed, this specification
-accommodates optional features to simplify transition
-from these earlier draft interfaces. Specifically:
-
-Legacy Interface
- is an interface specified by an earlier draft of this specification
- (up to 0.9.X)
-Legacy Device
- is a device implemented before this specification was released,
- and implementing a legacy interface on the host side
-Legacy Driver
- is a driver implemented before this specification was released,
- and implementing a legacy interface on the guest side
-
-Legacy devices and legacy drivers are not compliant with this
-specification.
-
-To simplify transition from these earlier draft interfaces,
-it is possible to implement:
-
-Transitional Device
- a device supporting both drivers conforming to this
- specification, and allowing legacy drivers.
-
-Transitional Driver
- a driver supporting both devices conforming to this
- specification, and legacy devices.
-
-Transitional devices and transitional drivers can be compliant with
-this specification (ie. when not operating in legacy mode).
-
-Devices or drivers with no legacy compatibility are referred to as
-non-transitional devices and drivers, respectively.
-
-Transitional Drivers can detect Legacy Devices by detecting that
-the feature bit VIRTIO_F_VERSION_1 is not offered.
-Transitional devices can detect Legacy drivers by detecting that
-VIRTIO_F_VERSION_1 has not been acknowledged by the driver.
-In this case device is used through the legacy interface.
-
-To make them easier to locate, specification sections documenting
-these transitional features are explicitly marked with 'Legacy
-Interface' in the section title.
-
-2.1.3. Configuration Space
--------------------------
-
-Configuration space is generally used for rarely-changing or
-initialization-time parameters. Drivers must not assume reads from
-fields greater than 32 bits wide are atomic, nor or reads from
-multiple fields.
-
-Each transport provides a generation count for the configuration
-space, which must change whenever there is a possibility that two
-accesses to the configuration space can see different versions of that
-space.
-
-Thus drivers should read configuration space fields like so:
-
- u32 before, after;
- do {
- before = get_config_generation(device);
- // read config entry/entries.
- after = get_config_generation(device);
- } while (after != before);
-
-Note that configuration space generally uses the little-endian format
-for multi-byte fields.
-
-Note that future versions of this specification will likely
-extend the configuration space for devices by adding extra fields
-at the tail end of some structures in configuration space.
-
-To allow forward compatibility with such extensions, drivers must
-not limit structure size and configuration space size. Instead,
-drivers should only check that configuration space is *large enough* to
-contain the fields required for device operation.
-
-For example, if the specification states that configuration
-space 'includes a single 8-bit field' drivers should understand this to mean that
-the configuration space can also include an arbitrary amount of
-tail padding, and accept any configuration space size equal to or
-greater than the specified 8-bit size.
-
-100.100.4.1. Legacy Interface: A Note on Configuration Space endian-ness
---------------------------------------
-
-Note that for legacy interfaces, configuration space is generally the
-guest's native endian, rather than PCI's little-endian.
-
-2.1.3.1. Legacy Interface: Configuration Space
--------------------------
-
-Legacy devices did not have a configuration generation field, thus are
-susceptible to race conditions if configuration is updated. This
-effects the block capacity and network mac fields; best practice is to
-read these fields multiple times until two reads generate a consistent
-result.
-
-2.1.4. Virtqueues
-----------------
-
-The mechanism for bulk data transport on virtio devices is
-pretentiously called a virtqueue. Each device can have zero or more
-virtqueues: for example, the simplest network device has one for
-transmit and one for receive. Each queue has a 16-bit queue size
-parameter, which sets the number of entries and implies the total size
-of the queue.
-
-Each virtqueue consists of three parts:
-
- Descriptor Table
-
- Available Ring
-
- Used Ring
-
-where each part is physically-contiguous in guest memory,
-and has different alignment requirements.
-
-The memory aligment and size requirements, in bytes, of each part of the
-virtqueue are summarized in the following table:
-
-+------------+-----------------------------------------+
-| Virtqueue Part | Alignment | Size |
-+------------+-----------------------------------------+
-+------------+-----------------------------------------+
-| Descriptor Table | 16 | 16 * (Queue Size) |
-+------------+-----------------------------------------+
-| Available Ring | 2 | 6 + 2 * (Queue Size) |
-+------------+-----------------------------------------+
-| Used Ring | 4 | 6 + 4 * (Queue Size) |
-+------------+-----------------------------------------+
-
-The Alignment column gives the miminum alignment: for each part
-of the virtqueue, the physical address of the first byte of it
-must be a multiple of the specified alignment value.
-
-The Size column gives the total number of bytes required for each
-part of the virtqueue.
-
-Queue Size corresponds to the maximum number of buffers in the
-virtqueue. For example, if Queue Size is 4 then at most 4 buffers
-can be queued at any given time. Queue Size value is always a
-power of 2. The maximum Queue Size value is 32768. This value
-is specified in a bus-specific way.
-
-When the driver wants to send a buffer to the device, it fills in
-a slot in the descriptor table (or chains several together), and
-writes the descriptor index into the available ring. It then
-notifies the device. When the device has finished a buffer, it
-writes the descriptor into the used ring, and sends an interrupt.
-
-
-2.1.4.1. Legacy Interfaces: A Note on Virtqueue Layout
---------------------------------------
-
-For Legacy Interfaces, several additional
-restrictions are placed on the virtqueue layout:
-
-Each virtqueue occupies two or more physically-contiguous pages
-(usually defined as 4096 bytes, but depending on the transport)
-and consists of three parts:
-
-+-------------------+-----------------------------------+-----------+
-| Descriptor Table | Available Ring (padding) | Used Ring |
-+-------------------+-----------------------------------+-----------+
-
-The bus-specific Queue Size field controls the total number of bytes
-required for the virtqueue according to the following formula:
-
- #define ALIGN(x) (((x) + PAGE_SIZE) & ~PAGE_SIZE)
- static inline unsigned vring_size(unsigned int qsz)
- {
- return ALIGN(sizeof(struct vring_desc)*qsz + sizeof(u16)*(3 + qsz))
- + ALIGN(sizeof(u16)*3 + sizeof(struct vring_used_elem)*qsz);
- }
-
-This wastes some space with padding.
-The legacy virtqueue layout structure therefore looks like this:
-
- struct vring {
- // The actual descriptors (16 bytes each)
- struct vring_desc desc[ Queue Size ];
-
- // A ring of available descriptor heads with free-running index.
- struct vring_avail avail;
-
- // Padding to the next PAGE_SIZE boundary.
- char pad[ Padding ];
-
- // A ring of used descriptor heads with free-running index.
- struct vring_used used;
- };
-
-2.1.4.100. Legacy Interfaces: A Note on Virtqueue Endianness
---------------------------------------
-
-Note that the endian of fields and in the virtqueue is the native
-endian of the guest, not little-endian as specified by this standard.
-It is assumed that the host is already aware of the guest endian.
-
-2.1.4.2. Message Framing
------------------------
-The message framing (the particular layout of descriptors) is
-independent of the contents of the buffers. For example, a network
-transmit buffer consists of a 12 byte header followed by the network
-packet. This could be most simply placed in the descriptor table as a
-12 byte output descriptor followed by a 1514 byte output descriptor,
-but it could also consist of a single 1526 byte output descriptor in
-the case where the header and packet are adjacent, or even three or
-more descriptors (possibly with loss of efficiency in that case).
-
-Note that, some implementations may have large-but-reasonable
-restrictions on total descriptor size (such as based on IOV_MAX in the
-host OS). This has not been a problem in practice: little sympathy
-will be given to drivers which create unreasonably-sized descriptors
-such as by dividing a network packet into 1500 single-byte
-descriptors!
-
-2.1.4.2.1. Legacy Interface: Message Framing
------------------------
-
-Regrettably, initial driver implementations used simple layouts, and
-devices came to rely on it, despite this specification wording. In
-addition, the specification for virtio_blk SCSI commands required
-intuiting field lengths from frame boundaries (see
- "2.4.2.5.1. Legacy Interface: Device Operation")
-
-It is thus recommended that when using legacy interfaces, transitional
-drivers be conservative in their assumptions, unless the
-VIRTIO_F_ANY_LAYOUT feature is accepted.
-
-2.1.4.3. The Virtqueue Descriptor Table
---------------------------------------
-
-The descriptor table refers to the buffers the guest is using for
-the device. The addresses are physical addresses, and the buffers
-can be chained via the next field. Each descriptor describes a
-buffer which is read-only or write-only, but a chain of
-descriptors can contain both read-only and write-only buffers.
-
-The actual contents of the memory offered to the device depends on the
-device type. Most common is to begin the data with a header
-(containing little-endian fields) for the device to read, and postfix
-it with a status tailer for the device to write.
-
-No descriptor chain may be more than 2^32 bytes long in total.
-
- struct vring_desc {
- /* Address (guest-physical). */
- le64 addr;
- /* Length. */
- le32 len;
-
- /* This marks a buffer as continuing via the next field. */
- #define VRING_DESC_F_NEXT 1
- /* This marks a buffer as write-only (otherwise read-only). */
- #define VRING_DESC_F_WRITE 2
- /* This means the buffer contains a list of buffer descriptors. */
- #define VRING_DESC_F_INDIRECT 4
- /* The flags as indicated above. */
- le16 flags;
- /* Next field if flags & NEXT */
- le16 next;
- };
-
-The number of descriptors in the table is defined by the queue size
-for this virtqueue.
-
-2.1.4.3.1. Indirect Descriptors
-------------------------------
-
-Some devices benefit by concurrently dispatching a large number
-of large requests. The VIRTIO_RING_F_INDIRECT_DESC feature can be
-used to allow this (see "2.6. Reserved Feature Bits"). To increase
-ring capacity it is possible to store a table of indirect
-descriptors anywhere in memory, and insert a descriptor in main
-virtqueue (with flags&VRING_DESC_F_INDIRECT on) that refers to memory buffer
-containing this indirect descriptor table; fields addr and len
-refer to the indirect table address and length in bytes,
-respectively. The indirect table layout structure looks like this
-(len is the length of the descriptor that refers to this table,
-which is a variable, so this code won't compile):
-
- struct indirect_descriptor_table {
- /* The actual descriptors (16 bytes each) */
- struct vring_desc desc[len / 16];
- };
-
-The first indirect descriptor is located at start of the indirect
-descriptor table (index 0), additional indirect descriptors are
-chained by next field. An indirect descriptor without next field
-(with flags&VRING_DESC_F_NEXT off) signals the end of the descriptor.
-An
-indirect descriptor can not refer to another indirect descriptor
-table (flags&VRING_DESC_F_INDIRECT must be off). A single indirect descriptor
-table can include both read-only and write-only descriptors;
-write-only flag (flags&VRING_DESC_F_WRITE) in the descriptor that refers to it
-is ignored.
-
-2.1.4.4. The Virtqueue Available Ring
-------------------------------------
-
-The available ring refers to what descriptor chains we are offering the
-device: each entry refers to the head of a descriptor chain. The “flags” field
-is currently 0 or 1: 1 indicating that we do not need an interrupt
-when the device consumes a descriptor chain from the available
-ring. Alternatively, the guest can ask the device to delay interrupts
-until an entry with an index specified by the “used_event” field is
-written in the used ring (equivalently, until the idx field in the
-used ring will reach the value used_event + 1). The method employed by
-the device is controlled by the VIRTIO_RING_F_EVENT_IDX feature bit
-(see "2.6. Reserved Feature Bits"). This interrupt suppression is
-merely an optimization; it may not suppress interrupts entirely.
-
-The “idx” field indicates where we would put the next descriptor
-entry (modulo the queue size). This starts at 0, and increases.
-
- struct vring_avail {
- #define VRING_AVAIL_F_NO_INTERRUPT 1
- le16 flags;
- le16 idx;
- le16 ring[ /* Queue Size */ ];
- le16 used_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
- };
-
-2.1.4.5. The Virtqueue Used Ring
--------------------------------
-
-The used ring is where the device returns buffers once it is done
-with them. The flags field can be used by the device to hint that
-no notification is necessary when the guest adds to the available
-ring. Alternatively, the “avail_event” field can be used by the
-device to hint that no notification is necessary until an entry
-with an index specified by the “avail_event” is written in the
-available ring (equivalently, until the idx field in the
-available ring will reach the value avail_event + 1). The method
-employed by the device is controlled by the guest through the
-VIRTIO_RING_F_EVENT_IDX feature bit (
-see "2.6. Reserved Feature Bits").[7]
-
-Each entry in the ring is a pair: the head entry of the
-descriptor chain describing the buffer (this matches an entry
-placed in the available ring by the guest earlier), and the total
-of bytes written into the buffer. The latter is extremely useful
-for guests using untrusted buffers: if you do not know exactly
-how much has been written by the device, you usually have to zero
-the buffer to ensure no data leakage occurs.
-
- /* le32 is used here for ids for padding reasons. */
- struct vring_used_elem {
- /* Index of start of used descriptor chain. */
- le32 id;
- /* Total length of the descriptor chain which was used (written to) */
- le32 len;
- };
-
- struct vring_used {
- #define VRING_USED_F_NO_NOTIFY 1
- le16 flags;
- le16 idx;
- struct vring_used_elem ring[ /* Queue Size */];
- le16 avail_event; /* Only if VIRTIO_RING_F_EVENT_IDX */
- };
-
-2.1.4.6. Helpers for Operating Virtqueues
-----------------------------------------
-
-The Linux Kernel Source code contains the definitions above and
-helper routines in a more usable form, in
-include/linux/virtio_ring.h. This was explicitly licensed by IBM
-and Red Hat under the (3-clause) BSD license so that it can be
-freely used by all other projects, and is reproduced (with slight
-variation to remove Linux assumptions) in "2.6. virtio_ring.h".
-
-2.2. General Initialization And Device Operation
-===============================================
-
-We start with an overview of device initialization, then expand on the
-details of the device and how each step is preformed. This section
-should be read along with the bus-specific section which describes
-how to communicate with the specific device.
-
-2.2.1. Device Initialization
----------------------------
-
-1. Reset the device.
-
-2. The ACKNOWLEDGE status bit is set: we have noticed the device.
-
-3. The DRIVER status bit is set: we know how to drive the device.
-
-4. Device feature bits are read, and the the subset of feature bits
- understood by the OS and driver is written to the device.
-
-5. The FEATURES_OK status bit is set.
-
-6. The status byte is re-read to ensure the FEATURES_OK bit is still
- set: otherwise, the device does not support our subset of features
- and the device is unusable.
-
-7. Device-specific setup, including discovery of virtqueues for the
- device, optional per-bus setup, reading and possibly writing the
- device's virtio configuration space, and population of virtqueues.
-
-8. The DRIVER_OK status bit is set. At this point the device is
- "live".
-
-If any of these steps go irrecoverably wrong, the guest should
-set the FAILED status bit to indicate that it has given up on the
-device (it can reset the device later to restart if desired).
-
-The device must not consume buffers before DRIVER_OK, and the driver
-must not notify the device before it sets DRIVER_OK.
-
-Devices should support all valid combinations of features, but we know
-that implementations may well make assuptions that they will only be
-used by fully-optimized drivers. The resetting of the FEATURES_OK flag
-provides a semi-graceful failure mode for this case.
-
-2.2.1.1. Legacy Interface: Device Initialization
----------------------------
-Legacy devices do not support the FEATURES_OK status bit, and thus did
-not have a graceful way for the device to indicate unsupported feature
-combinations. It also did not provide a clear mechanism to end
-feature negotiation, which meant that devices finalized features on
-first-use, and no features could be introduced which radically changed
-the initial operation of the device.
-
-Legacy device implementations often used the device before setting the
-DRIVER_OK bit.
-
-The result was the steps 5 and 6 were omitted, and steps 7 and 8
-were conflated.
-
-2.2.2. Device Operation
-----------------------
-
-There are two parts to device operation: supplying new buffers to
-the device, and processing used buffers from the device. As an
-example, the simplest virtio network device has two virtqueues: the
-transmit virtqueue and the receive virtqueue. The driver adds
-outgoing (read-only) packets to the transmit virtqueue, and then
-frees them after they are used. Similarly, incoming (write-only)
-buffers are added to the receive virtqueue, and processed after
-they are used.
-
-2.2.2.1. Supplying Buffers to The Device
----------------------------------------
-
-Actual transfer of buffers from the guest OS to the device
-operates as follows:
-
-1. Place the buffer(s) into free descriptor(s).
-
-2. Place the id of the buffer in the next ring entry of the
- available ring.
-
-3. The steps (1) and (2) may be performed repeatedly if batching
- is possible.
-
-4. A memory barrier should be executed to ensure the device sees
- the updated descriptor table and available ring before the next
- step.
-
-5. The available “idx” field should be increased by the number of
- entries added to the available ring.
-
-6. A memory barrier should be executed to ensure that we update
- the idx field before checking for notification suppression.
-
-7. If notifications are not suppressed, the device should be
- notified of the new buffers.
-
-Note that the above code does not take precautions against the
-available ring buffer wrapping around: this is not possible since
-the ring buffer is the same size as the descriptor table, so step
-(1) will prevent such a condition.
-
-In addition, the maximum queue size is 32768 (it must be a power
-of 2 which fits in 16 bits), so the 16-bit “idx” value can always
-distinguish between a full and empty buffer.
-
-Here is a description of each stage in more detail.
-
-2.2.2.1.1. Placing Buffers Into The Descriptor Table
----------------------------------------------------
-
-A buffer consists of zero or more read-only physically-contiguous
-elements followed by zero or more physically-contiguous
-write-only elements (it must have at least one element). This
-algorithm maps it into the descriptor table:
-
-for each buffer element, b:
-
- (a) Get the next free descriptor table entry, d
-
- (b) Set d.addr to the physical address of the start of b
-
- (c) Set d.len to the length of b.
-
- (d) If b is write-only, set d.flags to VRING_DESC_F_WRITE,
- otherwise 0.
-
- (e) If there is a buffer element after this:
-
- i. Set d.next to the index of the next free descriptor
- element.
-
- ii. Set the VRING_DESC_F_NEXT bit in d.flags.
-
-In practice, the d.next fields are usually used to chain free
-descriptors, and a separate count kept to check there are enough
-free descriptors before beginning the mappings.
-
-2.2.2.1.2. Updating The Available Ring
--------------------------------------
-
-The head of the buffer we mapped is the first d in the algorithm
-above. A naive implementation would do the following (with the
-appropriate conversion to-and-from little-endian assumed):
-
- avail->ring[avail->idx % qsz] = head;
-
-However, in general we can add many descriptor chains before we update
-the “idx” field (at which point they become visible to the
-device), so we keep a counter of how many we've added:
-
- avail->ring[(avail->idx + added++) % qsz] = head;
-
-2.2.2.1.3. Updating The Index Field
-----------------------------------
-
-Once the index field of the virtqueue is updated, the device will
-be able to access the descriptor chains we've created and the
-memory they refer to. This is why a memory barrier is generally
-used before the index update, to ensure it sees the most up-to-date
-copy.
-
-The index field always increments, and we let it wrap naturally at
-65536:
-
- avail->idx += added;
-
-2.2.2.1.4. Notifying The Device
-------------------------------
-
-The actual method of device notification is bus-specific, but generally
-it can be expensive. So the device can suppress such notifications if it
-doesn't need them. We have to be careful to expose the new index
-value before checking if notifications are suppressed: it's OK to notify
-gratuitously, but not to omit a required notification. So again,
-we use a memory barrier here before reading the flags or the
-avail_event field.
-
-If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated, and if the
-VRING_USED_F_NOTIFY flag is not set, we go ahead and notify the
-device.
-
-If the VIRTIO_F_RING_EVENT_IDX feature is negotiated, we read the
-avail_event field in the available ring structure. If the
-available index crossed_the avail_event field value since the
-last notification, we go ahead and write to the PCI configuration
-space. The avail_event field wraps naturally at 65536 as well,
-iving the following algorithm for calculating whether a device needs
-notification:
-
- (u16)(new_idx - avail_event - 1) < (u16)(new_idx - old_idx)
-
-2.2.2.2. Receiving Used Buffers From The Device
-----------------------------------------------
-
-Once the device has used a buffer (read from or written to it, or
-parts of both, depending on the nature of the virtqueue and the
-device), it sends an interrupt, following an algorithm very
-similar to the algorithm used for the driver to send the device a
-buffer:
-
-1. Write the head descriptor number to the next field in the used
- ring.
-
-2. Update the used ring index.
-
-3. Deliver an interrupt if necessary:
-
- (a) If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated:
- check if the VRING_AVAIL_F_NO_INTERRUPT flag is not set in
- avail->flags.
-
- (b) If the VIRTIO_F_RING_EVENT_IDX feature is negotiated: check
- whether the used index crossed the used_event field value
- since the last update. The used_event field wraps naturally
- at 65536 as well:
- (u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx)
-
-For each ring, guest should then disable interrupts by writing
-VRING_AVAIL_F_NO_INTERRUPT flag in avail structure, if required.
-It can then process used ring entries finally enabling interrupts
-by clearing the VRING_AVAIL_F_NO_INTERRUPT flag or updating the
-EVENT_IDX field in the available structure. The guest should then
-execute a memory barrier, and then recheck the ring empty
-condition. This is necessary to handle the case where after the
-last check and before enabling interrupts, an interrupt has been
-suppressed by the device:
-
- vring_disable_interrupts(vq);
-
- for (;;) {
- if (vq->last_seen_used != le16_to_cpu(vring->used.idx)) {
- vring_enable_interrupts(vq);
- mb();
-
- if (vq->last_seen_used != le16_to_cpu(vring->used.idx))
- break;
- }
-
- struct vring_used_elem *e = vring.used->ring[vq->last_seen_used%vsz];
- process_buffer(e);
- vq->last_seen_used++;
- }
-
-2.2.2.3. Notification of Device Configuration Changes
-----------------------------------------------------
-
-For devices where the configuration information can be changed, an
-interrupt is delivered when a configuration change occurs.
-
-
-
-2.3. Virtio Transport Options
-============================
-
-Virtio can use various different busses, thus the standard is split
-into virtio general and bus-specific sections.
-
-2.3.1. Virtio Over PCI Bus
--------------------------
-
-Virtio devices are commonly implemented as PCI devices.
-
-2.3.1.1. PCI Device Discovery
-----------------------------
-
-Any PCI device with Vendor ID 0x1AF4, and Device ID 0x1000 through
-0x103F inclusive is a virtio device[3].
-
-The Subsystem Device ID indicates which virtio device is
-supported by the device. The Subsystem Vendor ID should reflect
-the PCI Vendor ID of the environment (it's currently only used
-for informational purposes by the guest).
-
-All Drivers must match devices with any Revision ID, this
-is to allow devices to be versioned without breaking drivers.
-
-2.3.1.1.1. Legacy Interfaces: A Note on PCI Device Discovery
--------------------------
-Transitional devices must have a Revision ID of 0 to match
-legacy drivers.
-
-Non-transitional devices must have a Revision ID of 1 or higher.
-
-Both transitional and non-transitional drivers must match
-any Revision ID value.
-
-2.3.1.2. PCI Device Layout
--------------------------
-
-To configure the device,
-use I/O and/or memory regions and/or PCI configuration space of the PCI device.
-These contain the virtio header registers, the notification register, the
-ISR status register and device specific registers, as specified by Virtio
-+ Structure PCI Capabilities
-
-There may be different widths of accesses to the I/O region; the
-“natural” access method for each field must be
-used (i.e. 32-bit accesses for 32-bit fields, etc).
-
-PCI Device Configuration Layout includes the common configuration,
-ISR, notification and device specific configuration
-structures.
-
-Unless explicitly specified otherwise, all multi-byte fields are little-endian.
-
-2.3.1.2.1. Common configuration structure layout
--------------------------
-Common configuration structure layout is documented below:
-
- struct virtio_pci_common_cfg {
- /* About the whole device. */
- le32 device_feature_select; /* read-write */
- le32 device_feature; /* read-only */
- le32 guest_feature_select; /* read-write */
- le32 guest_feature; /* read-write */
- le16 msix_config; /* read-write */
- le16 num_queues; /* read-only */
- u8 device_status; /* read-write */
- u8 config_generation; /* read-only */
-
- /* About a specific virtqueue. */
- le16 queue_select; /* read-write */
- le16 queue_size; /* read-write, power of 2, or 0. */
- le16 queue_msix_vector; /* read-write */
- le16 queue_enable; /* read-write */
- le16 queue_notify_off; /* read-only */
- le64 queue_desc; /* read-write */
- le64 queue_avail; /* read-write */
- le64 queue_used; /* read-write */
- };
-
-device_feature_select
-
- Selects which Feature Bits does device_feature field refer to.
- Value 0x0 selects Feature Bits 0 to 31
- Value 0x1 selects Feature Bits 32 to 63
- All other values cause reads from device_feature to return 0.
-
-device_feature
-
- Used by Device to report Feature Bits to Driver.
- Device Feature Bits selected by device_feature_select.
-
-guest_feature_select
-
- Selects which Feature Bits does guest_feature field refer to.
- Value 0x0 selects Feature Bits 0 to 31
- Value 0x1 selects Feature Bits 32 to 63
- When set to any other value, reads from guest_feature
- return 0, writing 0 into guest_feature has no effect, and
- writing any other value into guest_feature is an error.
-
-guest_feature
-
- Used by Driver to acknowledge Feature Bits to Device.
- Guest Feature Bits selected by guest_feature_select.
-
-msix_config
-
- Configuration Vector for MSI-X.
-
-num_queues
-
- Specifies the maximum number of virtqueues supported by device.
-
-device_status
-
- Device Status field. Writing 0 into this field resets the
- device.
-
-config_generation
-
- Configuration atomicity value. Changes every time the
- configuration noticeably changes. This means the device may
- only change the value after a configuration read operation,
- but it must change if there is any risk of a device seeing an
- inconsistent configuration state.
-
-queue_select
-
- Queue Select. Selects which virtqueue do other fields refer to.
-
-queue_size
-
- Queue Size. On reset, specifies the maximum queue size supported by
- the hypervisor. This can be modified by driver to reduce memory requirements.
- Set to 0 if this virtqueue is unused.
-
-queue_msix_vector
-
- Queue Vector for MSI-X.
-
-queue_enable
-
- Used to selectively prevent host from executing requests from this virtqueue.
- 1 - enabled; 0 - disabled
-
-queue_notify_off
-
- Used to calculate the offset from start of Notification structure at
- which this virtqueue is located.
- Note: this is *not* an offset in bytes. See notify_off_multiplier below.
-
-queue_desc
-
- Physical address of Descriptor Table.
-
-queue_avail
-
- Physical address of Available Ring.
-
-queue_used
-
- Physical address of Used Ring.
-
-2.3.1.2.2. ISR status structure layout
--------------------------
-ISR status structure includes a single 8-bit ISR status field.
-
-2.3.1.2.3. Notification structure layout
--------------------------
-Notification structure is always a multiple of 2 bytes in size.
-It includes 2-byte Queue Notify fields for each virtqueue of
-the device. Note that multiple virtqueues can use the same
-Queue Notify field, if necessary.
-
-2.3.1.2.4. Device specific structure
--------------------------
-
-Device specific structure is optional.
-
-2.3.1.2.5. Legacy Interfaces: A Note on PCI Device Layout
--------------------------
-
-Transitional devices should present part of configuration
-registers in a legacy configuration structure in BAR0 in the first I/O
-region of the PCI device, as documented below.
-
-There may be different widths of accesses to the I/O region; the
-“natural” access method for each field in the virtio header must be
-used (i.e. 32-bit accesses for 32-bit fields, etc), but
-when accessed through the legacy interface the
-device-specific region can be accessed using any width accesses, and
-should obtain the same results.
-
-Note that this is possible because while the virtio header is PCI
-(i.e. little) endian, when using the legacy interface the device-specific
-region is encoded in the native endian of the guest (where such distinction is
-applicable).
-
-When used through the legacy interface, the virtio header looks as follows:
-
-+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+
-| Bits || 32 | 32 | 32 | 16 | 16 | 16 | 8 | 8 |
-+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+
-| Read/Write || R | R+W | R+W | R | R+W | R+W | R+W | R |
-+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+
-| Purpose || Device | Guest | Queue | Queue | Queue | Queue | Device | ISR |
-| || Features bits 0:31 | Features bits 0:31 | Address | Size | Select | Notify | Status | Status |
-+------------++---------------------+---------------------+----------+--------+---------+---------+---------+--------+
-
-
-If MSI-X is enabled for the device, two additional fields
-immediately follow this header:
-
-
-+------------++----------------+--------+
-| Bits || 16 | 16 |
-+------------++----------------+--------+
-| Read/Write || R+W | R+W |
-+------------++----------------+--------+
-| Purpose || Configuration | Queue |
-| (MSI-X) || Vector | Vector |
-+------------++----------------+--------+
-
-Note: When MSI-X capability is enabled, device specific configuration starts at
-byte offset 24 in virtio header structure. When MSI-X capability is not
-enabled, device specific configuration starts at byte offset 20 in virtio
-header. ie. once you enable MSI-X on the device, the other fields move.
-If you turn it off again, they move back!
-
-Immediately following these general headers, there may be
-device-specific headers:
-
-+------------++--------------------+
-| Bits || Device Specific |
-+------------++--------------------+
-| Read/Write || Device Specific |
-+------------++--------------------+
-| Purpose || Device Specific... |
-| || |
-+------------++--------------------+
-
-Note that only Feature Bits 0 to 31 are accessible through the
-Legacy Interface. When used through the Legacy Interface,
-Transitional Devices must assume that Feature Bits 32 to 63
-are not acknowledged by Driver.
-
-As legacy devices had no configuration generation field,
-see "2.1.3.1. Legacy Interface: Configuration Space" for workarounds.
-
-2.3.1.3. PCI-specific Initialization And Device Operation
---------------------------------------------------------
-
-2.3.1.3.1. Device Initialization
--------------------------------
-
-This documents PCI-specific steps executed during Device Initialization.
-As the first step, driver must detect device configuration layout
-to locate configuration fields in memory,I/O or configuration space of the
-device.
-
-100.100.1.3.1.1. Virtio Device Configuration Layout Detection
--------------------------------
-
-As a prerequisite to device initialization, driver executes a
-PCI capability list scan, detecting virtio configuration layout using Virtio
-Structure PCI capabilities.
-
-Virtio Device Configuration Layout includes virtio configuration header, Notification
-and ISR Status and device configuration structures.
-Each structure can be mapped by a Base Address register (BAR) belonging to
-the function, located beginning at 10h in Configuration Space,
-or accessed though PCI configuration space.
-
-Actual location of each structure is specified using vendor-specific PCI capability located
-on capability list in PCI configuration space of the device.
-This virtio structure capability uses little-endian format; all bits are
-read-only:
-
- struct virtio_pci_cap {
- u8 cap_vndr; /* Generic PCI field: PCI_CAP_ID_VNDR */
- u8 cap_next; /* Generic PCI field: next ptr. */
- u8 cap_len; /* Generic PCI field: capability length */
- u8 cfg_type; /* Identifies the structure. */
- u8 bar; /* Where to find it. */
- u8 padding[3]; /* Pad to full dword. */
- le32 offset; /* Offset within bar. */
- le32 length; /* Length of the structure, in bytes. */
- };
-
-This structure can optionally followed by extra data, depending on
-other fields, as documented below.
-
-Note that future versions of this specification will likely
-extend devices by adding extra fields at the tail end of some structures.
-
-To allow forward compatibility with such extensions, drivers must
-not limit structure size. Instead, drivers should only
-check that structures are *large enough* to contain the fields
-required for device operation.
-
-For example, if the specification states 'structure includes a
-single 8-bit field' drivers should understand this to mean that
-the structure can also include an arbitrary amount of tail padding,
-and accept any structure size equal to or greater than the
-specified 8-bit size.
-
-The fields are interpreted as follows:
-
-cap_vndr
- 0x09; Identifies a vendor-specific capability.
-
-cap_next
- Link to next capability in the capability list in the configuration space.
-
-cap_len
- Length of the capability structure, including the whole of
- struct virtio_pci_cap, and extra data if any.
- This length might include padding, or fields unused by the driver.
-
-cfg_type
- identifies the structure, according to the following table.
-
- /* Common configuration */
- #define VIRTIO_PCI_CAP_COMMON_CFG 1
- /* Notifications */
- #define VIRTIO_PCI_CAP_NOTIFY_CFG 2
- /* ISR Status */
- #define VIRTIO_PCI_CAP_ISR_CFG 3
- /* Device specific configuration */
- #define VIRTIO_PCI_CAP_DEVICE_CFG 4
- /* PCI configuration access */
- #define VIRTIO_PCI_CAP_PCI_CFG 5
-
- Any other value - reserved for future use. Drivers must
- ignore any vendor-specific capability structure which has
- a reserved cfg_type value.
-
- More than one capability can identify the same structure - this makes it
- possible for the device to expose multiple interfaces to drivers. The order of
- the capabilities in the capability list specifies the order of preference
- suggested by the device; drivers should use the first interface that they can
- support. For example, on some hypervisors, notifications using IO accesses are
- faster than memory accesses. In this case, hypervisor can expose two
- capabilities with cfg_type set to VIRTIO_PCI_CAP_NOTIFY_CFG:
- the first one addressing an I/O BAR, the second one addressing a memory BAR.
- Driver will use the I/O BAR if I/O resources are available, and fall back on
- memory BAR when I/O resources are unavailable.
-
-bar
- values 0x0 to 0x5 specify a Base Address register (BAR) belonging to
- the function located beginning at 10h in Configuration Space
- and used to map the structure into Memory or I/O Space.
- The BAR is permitted to be either 32-bit or 64-bit, it can map Memory Space
- or I/O Space.
-
- Any other value - reserved for future use. Drivers must
- ignore any vendor-specific capability structure which has
- a reserved bar value.
-
-offset
- indicates where the structure begins relative to the base address associated
- with the BAR.
-
-length
- indicates the length of the structure.
- This size might include padding, or fields unused by the driver.
- Drivers are also recommended to only map part of configuration structure
- large enough for device operation.
- For example, a future device might present a large structure size of several
- MBytes.
- As current devices never utilize structures larger than 4KBytes in size,
- driver can limit the mapped structure size to e.g.
- 4KBytes to allow forward compatibility with such devices without loss of
- functionality and without wasting resources.
-
-
-If cfg_type is VIRTIO_PCI_CAP_NOTIFY_CFG this structure is immediately followed
-by additional fields:
-
- struct virtio_pci_notify_cap {
- struct virtio_pci_cap cap;
- le32 notify_off_multiplier; /* Multiplier for queue_notify_off. */
- };
-
-notify_off_multiplier
-
- Virtqueue offset multiplier, in bytes. Must be even and either a power of two, or 0.
- Value 0x1 is reserved.
- For a given virtqueue, the address to use for notifications is calculated as follows:
-
- queue_notify_off * notify_off_multiplier + offset
-
- If notify_off_multiplier is 0, all virtqueues use the same address in
- the Notifications structure!
-
-If cfg_type is VIRTIO_PCI_CAP_PCI_CFG the fields bar, offset and length are RW
-and this structure is immediately followed by an additional field:
-
- struct virtio_pci_cfg_cap {
- __u8 pci_cfg_data[4]; /* Data for BAR access. */
- };
-
-pci_cfg_data
-
- This RW field allows an indirect access to any BAR on the
- device using PCI configuration accesses.
-
- The BAR to access is selected using the bar field.
- The length of the access is specified by the length
- field, which can be set to 1, 2 and 4.
- The offset within the BAR is specified by the offset
- field, which must be aligned to length bytes.
-
- After this field is written by driver, the first length
- bytes in pci_cfg_data are written at the selected
- offset in the selected BAR.
-
- When this field is read by driver, length bytes at the
- selected offset in the selected BAR are read into pci_cfg_data.
-
-100.100.1.3.1.1.1. Legacy Interface: A Note on Device Layout Detection
--------------------------------
-
-Legacy drivers skipped Device Layout Detection step, assuming legacy
-configuration space in BAR0 in I/O space unconditionally.
-
-Legacy devices did not have the Virtio PCI Capability in their
-capability list.
-
-Therefore:
-
-Transitional devices should expose the Legacy Interface in I/O
-space in BAR0.
-
-Transitional drivers should look for the Virtio PCI
-Capabilities on the capability list.
-If these are not present, driver should assume a legacy device.
-
-Non-transitional drivers should look for the Virtio PCI
-Capabilities on the capability list.
-If these are not present, driver should assume a legacy device,
-and fail gracefully.
-
-Non-transitional devices, on a platform where a legacy driver for
-a legacy device with the same ID might have previously existed,
-must take the following steps to fail gracefully when a legacy
-driver attempts to drive them:
-
-1) Present an I/O BAR in BAR0, and
-2) Respond to a single-byte zero write to offset 18
- (corresponding to Device Status register in the legacy layout)
- of BAR0 by presenting zeroes on every BAR and ignoring writes.
-
-2.3.1.3.1.1. Queue Vector Configuration
---------------------------------------
-
-When MSI-X capability is present and enabled in the device
-(through standard PCI configuration space) Configuration/Queue
-MSI-X Vector registers are used to map configuration change and queue
-interrupts to MSI-X vectors. In this case, the ISR Status is unused.
-
-Writing a valid MSI-X Table entry number, 0 to 0x7FF, to one of
-Configuration/Queue Vector registers, maps interrupts triggered
-by the configuration change/selected queue events respectively to
-the corresponding MSI-X vector. To disable interrupts for a
-specific event type, unmap it by writing a special NO_VECTOR
-value:
-
- /* Vector value used to disable MSI for queue */
- #define VIRTIO_MSI_NO_VECTOR 0xffff
-
-Reading these registers returns vector mapped to a given event,
-or NO_VECTOR if unmapped. All queue and configuration change
-events are unmapped by default.
-
-Note that mapping an event to vector might require allocating
-internal device resources, and might fail. Devices report such
-failures by returning the NO_VECTOR value when the relevant
-Vector field is read. After mapping an event to vector, the
-driver must verify success by reading the Vector field value: on
-success, the previously written value is returned, and on
-failure, NO_VECTOR is returned. If a mapping failure is detected,
-the driver can retry mapping with fewervectors, or disable MSI-X.
-
-2.3.1.3.1.2. Virtqueue Configuration
------------------------------------
-
-As a device can have zero or more virtqueues for bulk data
-transport (for example, the simplest network device has two), the driver
-needs to configure them as part of the device-specific
-configuration.
-
-This is done as follows, for each virtqueue a device has:
-
-1. Write the virtqueue index (first queue is 0) to the Queue
- Select field.
-
-2. Read the virtqueue size from the Queue Size field, which is
- always a power of 2. This controls how big the virtqueue is
- (see "2.1.4. Virtqueues"). If this field is 0, the virtqueue does not exist.
-
-3. Optionally, select a smaller virtqueue size and write it in the Queue Size
- field.
-
-4. Allocate and zero Descriptor Table, Available and Used rings for the
- virtqueue in contiguous physical memory.
-
-5. Optionally, if MSI-X capability is present and enabled on the
- device, select a vector to use to request interrupts triggered
- by virtqueue events. Write the MSI-X Table entry number
- corresponding to this vector in Queue Vector field. Read the
- Queue Vector field: on success, previously written value is
- returned; on failure, NO_VECTOR value is returned.
-
-100.100.1.3.1.4.1. Legacy Interface: A Note on Virtqueue Configuration
------------------------------------
-When using the legacy interface, the page size for a virtqueue on a PCI virtio
-device is defined as 4096 bytes. Driver writes the physical address, divided
-by 4096 to the Queue Address field [6].
-
-2.3.1.3.2. Notifying The Device
-------------------------------
-
-Device notification occurs by writing the 16-bit virtqueue index
-of this virtqueue to the Queue Notify field.
-
-2.3.1.3.3. Virtqueue Interrupts From The Device
-----------------------------------------------
-
-If an interrupt is necessary:
-
- (a) If MSI-X capability is disabled:
-
- i. Set the lower bit of the ISR Status field for the device.
-
- ii. Send the appropriate PCI interrupt for the device.
-
- (b) If MSI-X capability is enabled:
-
- i. Request the appropriate MSI-X interrupt message for the
- device, Queue Vector field sets the MSI-X Table entry
- number.
-
- ii. If Queue Vector field value is NO_VECTOR, no interrupt
- message is requested for this event.
-
-The guest interrupt handler should:
-
-1. If MSI-X capability is disabled: read the ISR Status field,
- which will reset it to zero. If the lower bit is zero, the
- interrupt was not for this device. Otherwise, the guest driver
- should look through the used rings of each virtqueue for the
- device, to see if any progress has been made by the device
- which requires servicing.
-
-2. If MSI-X capability is enabled: look through the used rings of
- each virtqueue mapped to the specific MSI-X vector for the
- device, to see if any progress has been made by the device
- which requires servicing.
-
-2.3.1.3.4. Notification of Device Configuration Changes
-------------------------------------------------------
-
-Some virtio PCI devices can change the device configuration
-state, as reflected in the virtio header in the PCI configuration
-space. In this case:
-
-1. If MSI-X capability is disabled: an interrupt is delivered and
- the second highest bit is set in the ISR Status field to
- indicate that the driver should re-examine the configuration
- space. Note that a single interrupt can indicate both that one
- or more virtqueue has been used and that the configuration
- space has changed: even if the config bit is set, virtqueues
- must be scanned.
-
-2. If MSI-X capability is enabled: an interrupt message is
- requested. The Configuration Vector field sets the MSI-X Table
- entry number to use. If Configuration Vector field value is
- NO_VECTOR, no interrupt message is requested for this event.
-
-2.3.2. Virtio Over MMIO
------------------------
-
-Virtual environments without PCI support (a common situation in
-embedded devices models) might use simple memory mapped device
-("virtio-mmio") instead of the PCI device.
-
-The memory mapped virtio device behaviour is based on the PCI
-device specification. Therefore most of operations like device
-initialization, queues configuration and buffer transfers are
-nearly identical. Existing differences are described in the
-following sections.
-
-2.3.2.1. MMIO Device Discovery
-------------------------------
-
-Unlike PCI, MMIO provides no generic device discovery. For
-systems using Flattened Device Trees the suggested format is:
-
- virtio_block@1e000 {
- compatible = "virtio,mmio";
- reg = <0x1e000 0x100>;
- interrupts = <42>;
- }
-
-2.3.2.2. MMIO Device Layout
----------------------------
-
-MMIO virtio devices provides a set of memory mapped control
-registers, all 32 bits wide, followed by device-specific
-configuration space. The following list presents their layout:
-
-* Offset from the device base address | Direction | Name
- Description
-
-* 0x000 | R | MagicValue
- Magic value. Must be 0x74726976 (a Little Endian equivalent
- of a "virt" string).
-
-* 0x004 | R | Version
- Device version number. Devices compliant with this specification
- must return value 0x2.
-
-* 0x008 | R | DeviceID
- Virtio Subsystem Device ID.
- See "2.4. Device Types" for possible values. Value zero (0x0)
- is invalid and devices returning this ID must be ignored
- by the guest.
-
-* 0x00c | R | VendorID
- Virtio Subsystem Vendor ID.
-
-* 0x010 | R | HostFeatures
- Flags representing features the device supports.
- Reading from this register returns 32 consecutive flag bits,
- first bit depending on the last value written to the
- HostFeaturesSel register. Access to this register returns
- bits HostFeaturesSel*32 to (HostFeaturesSel*32)+31, eg.
- feature bits 0 to 31 if HostFeaturesSel is set to 0 and
- features bits 32 to 63 if HostFeaturesSel is set to 1.
- Also see "2.1.2. Feature Bits".
-
-* 0x014 | W | HostFeaturesSel
- Device (Host) features word selection.
- Writing to this register selects a set of 32 device feature bits
- accessible by reading from the HostFeatures register. Device driver
- must write a value to the HostFeaturesSel register before
- reading from the HostFeatures register.
-
-* 0x020 | W | GuestFeatures
- Flags representing device features understood and activated by
- the driver.
- Writing to this register sets 32 consecutive flag bits, first
- bit depending on the last value written to the GuestFeaturesSel
- register. Access to this register sets bits GuestFeaturesSel*32
- to (GuestFeaturesSel*32)+31, eg. feature bits 0 to 31 if
- GuestFeaturesSel is set to 0 and features bits 32 to 63 if
- GuestFeaturesSel is set to 1. Also see "2.1.2. Feature Bits".
-
-* 0x024 | W | GuestFeaturesSel
- Activated (Guest) features word selection.
- Writing to this register selects a set of 32 activated feature
- bits accessible by writing to the GuestFeatures register.
- Device driver must write a value to the GuestFeaturesSel
- register before writing to the GuestFeatures register.
-
-* 0x030 | W | QueueSel
- Virtual queue index (first queue is 0).
- Writing to this register selects the virtual queue that the
- following operations on the QueueNumMax, QueueNum, QueueReady,
- QueueDescLow, QueueDescHigh, QueueAvailLow, QueueAvailHigh,
- QueueUsedLow and QueueUsedHigh registers apply to.
-
-* 0x034 | R | QueueNumMax
- Maximum virtual queue size.
- Reading from the register returns the maximum size of the queue
- the Host is ready to process or zero (0x0) if the queue is not
- available. This applies to the queue selected by writing to
- QueueSel and is allowed only when QueueReady is set to zero
- (0x0), so when the queue is not in use.
-
-* 0x038 | W | QueueNum
- Virtual queue size.
- Queue size is the number of elements in the queue, therefore size
- of the Descriptor Table and both Available and Used rings.
- Writing to this register notifies the Host what size of the
- queue the Guest will use. This applies to the queue selected by
- writing to QueueSel and is allowed only when QueueReady is set
- to zero (0x0), so when the queue is not in use.
-
-* 0x03c | RW | QueueReady
- Virtual queue ready bit.
- Writing one (0x1) to this register notifies the Host that the
- virtual queue is ready to be used. Reading from this register
- returns the last value written to it. Both read and write
- accesses apply to the queue selected by writing to QueueSel.
- When the Guest wants to stop using the queue it must write
- zero (0x0) to this register and read the value back to
- ensure synchronisation.
-
-* 0x050 | W | QueueNotify
- Queue notifier.
- Writing a queue index to this register notifies the Host that
- there are new buffers to process in the queue.
-
-* 0x60 | R | InterruptStatus
- Interrupt status.
- Reading from this register returns a bit mask of interrupts
- asserted by the device. An interrupt is asserted if the
- corresponding bit is set, ie. equals one (1).
-
- – Bit 0 | Used Ring Update
- This interrupt is asserted when the Host has updated the Used
- Ring in at least one of the active virtual queues.
-
- – Bit 1 | Configuration change
- This interrupt is asserted when configuration of the device has
- changed.
-
-* 0x064 | W | InterruptACK
- Interrupt acknowledge.
- Writing to this register notifies the Host that the Guest
- finished handling interrupts. Set bits in the value clear
- the corresponding bits of the InterruptStatus register.
-
-* 0x070 | RW | Status
- Device status.
- Reading from this register returns the current device status
- flags.
- Writing non-zero values to this register sets the status flags,
- indicating the Guest progress. Writing zero (0x0) to this
- register triggers a device reset, including clearing all
- bits in the InterruptStatus register and ready bits in the
- QueueReady register for all queues in the device.
- See also p. "2.3.2.3.1. Device Initialization".
-
-* 0x080 | W | QueueDescLow
- 0x084 | W | QueueDescHigh
- Virtual queue's Descriptor Table 64 bit long physical address.
- Writing to these two registers (lower 32 bits of the address
- to QueueDescLow, higher 32 bits to QueueDescHigh) notifies
- the host about location of the Descriptor Table of the queue
- selected by writing to the QueueSel register. It is allowed
- only when QueueReady is set to zero (0x0), so when the queue
- is not in use.
-
-* 0x090 | W | QueueAvailLow
- 0x094 | W | QueueAvailHigh
- Virtual queue's Available Ring 64 bit long physical address.
- Writing to these two registers (lower 32 bits of the address
- to QueueAvailLow, higher 32 bits to QueueAvailHigh) notifies
- the host about location of the Available Ring of the queue
- selected by writing to the QueueSel register. It is allowed
- only when QueueReady is set to zero (0x0), so when the queue
- is not in use.
-
-* 0x0a0 | W | QueueUsedLow
- 0x0a4 | W | QueueUsedHigh
- Virtual queue's Used Ring 64 bit long physical address.
- Writing to these two registers (lower 32 bits of the address
- to QueueUsedLow, higher 32 bits to QueueUsedHigh) notifies
- the host about location of the Used Ring of the queue
- selected by writing to the QueueSel register. It is allowed
- only when QueueReady is set to zero (0x0), so when the queue
- is not in use.
-
-* 0x0fc | R | ConfigGeneration
- Configuration atomicity value.
- Changes every time the configuration noticeably changes. This
- means the device may only change the value after a configuration
- read operation, but it must change if there is any risk of a
- device seeing an inconsistent configuration state.
-
-* 0x100+ | RW | Config
- Device-specific configuration space starts at an offset 0x100
- and is accessed with byte alignment. Its meaning and size
- depends on the device and the driver.
-
-All register values are organized as Little Endian.
-
-Accessing memory locations not explicitly described above (or
-- in case of the configuration space - described in the device
-specification), writing to the registers described as "R" and
-reading from registers described as "W" is not permitted and
-can cause undefined behavior.
-
-2.3.2.3. MMIO-specific Initialization And Device Operation
-----------------------------------------------------------
-
-2.3.2.3.1. Device Initialization
---------------------------------
-
-The guest must start the device initialization by reading and
-checking values from the MagicValue and the Version registers.
-If both values are valid, it must read the DeviceID register
-and if its value is zero (0x0) must abort initialization and
-must not access any other register.
-
-Further initialization must follow the procedure described in
-p. "2.2.1. Device Initialization".
-
-2.3.2.3.2. Virtqueue Configuration
-----------------------------------
-
-1. Select the queue writing its index (first queue is 0) to the
- QueueSel register.
-
-2. Check if the queue is not already in use: read the QueueReady
- register, returned value should be zero (0x0).
-
-3. Read maximum queue size (number of elements) from the
- QueueNumMax register. If the returned value is zero (0x0) the
- queue is not available.
-
-4. Allocate and zero the queue pages, making sure the memory
- is physically contiguous. It is recommended to align the
- Used Ring to an optimal boundary (usually page size).
- Size of the allocated queue may be smaller than or equal to
- the maximum size returned by the Host.
-
-5. Notify the Host about the queue size by writing the size to
- the QueueNum register.
-
-6. Write physical addresses of the queue's Descriptor Table,
- Available Ring and Used Ring to (respectively) the QueueDescLow/
- QueueDescHigh, QueueAvailLow/QueueAvailHigh and QueueUsedLow/
- QueueUsedHigh register pairs.
-
-7. Write 0x1 to the QueueReady register.
-
-2.3.2.3.3. Notifying The Device
--------------------------------
-
-The device is notified about new buffers available in a queue by
-writing the queue index to the QueueNum register.
-
-2.3.2.3.4. Notifications From The Device
-----------------------------------------
-
-The memory mapped virtio device is using single, dedicated
-interrupt signal, which is raised when at least one of the
-interrupts described in the InterruptStatus register
-description is asserted. After receiving an interrupt, the
-driver must read the InterruptStatus register to check what
-caused the interrupt (see the register description). After the
-interrupt is handled, the driver must acknowledge it by writing
-a bit mask corresponding to the serviced interrupt to the
-InterruptACK register.
-
-As documented in the InterruptStatus register description,
-the device may notify the driver about a new used buffer being
-available in the queue or about a change in the device
-configuration.
-
-2.3.2.4. Legacy interface
--------------------------
-
-The legacy MMIO transport used page-based addressing, resulting
-in a slightly different control register layout, the device
-initialization and the virtual queue configuration procedure.
-
-The following list presents control registers layout, omitting
-descriptions of registers which did not change their function
-nor behaviour:
-
-* Offset from the device base address | Direction | Name
- Description
-
-* 0x000 | R | MagicValue
-
-* 0x004 | R | Version
- Device version number. Legacy devices must return value 0x1.
-
-* 0x008 | R | DeviceID
-
-* 0x00c | R | VendorID
-
-* 0x010 | R | HostFeatures
-
-* 0x014 | W | HostFeaturesSel
-
-* 0x020 | W | GuestFeatures
-
-* 0x024 | W | GuestFeaturesSel
-
-* 0x028 | W | GuestPageSize
- Guest page size.
- Device driver must write the guest page size in bytes to the
- register during initialization, before any queues are used.
- This value must be a power of 2 and is used by the Host to
- calculate the Guest address of the first queue page
- (see QueuePFN).
-
-* 0x030 | W | QueueSel
- Virtual queue index (first queue is 0).
- Writing to this register selects the virtual queue that the
- following operations on the QueueNumMAx, QueueNum, QueueAlign
- and QueuePFN registers apply to.
-
-* 0x034 | R | QueueNumMax
- Maximum virtual queue size.
- Reading from the register returns the maximum size of the queue
- the Host is ready to process or zero (0x0) if the queue is not
- available. This applies to the queue selected by writing to the
- QueueSel and is allowed only when the QueuePFN is set to zero
- (0x0), so when the queue is not actively used.
-
-* 0x038 | W | QueueNum
- Virtual queue size.
- Queue size is the number of elements in the queue, therefore size
- of the descriptor table and both available and used rings.
- Writing to this register notifies the Host what size of the
- queue the Guest will use. This applies to the queue selected by
- writing to the QueueSel register.
-
-* 0x03c | W | QueueAlign
- Used Ring alignment in the virtual queue.
- Writing to this register notifies the Host about alignment
- boundary of the Used Ring in bytes. This value must be a power
- of 2 and applies to the queue selected by writing to the QueueSel
- register.
-
-* 0x040 | RW | QueuePFN
- Guest physical page number of the virtual queue.
- Writing to this register notifies the host about location of the
- virtual queue in the Guest's physical address space. This value
- is the index number of a page starting with the queue
- Descriptor Table. Value zero (0x0) means physical address zero
- (0x00000000) and is illegal. When the Guest stops using the
- queue it must write zero (0x0) to this register.
- Reading from this register returns the currently used page
- number of the queue, therefore a value other than zero (0x0)
- means that the queue is in use.
- Both read and write accesses apply to the queue selected by
- writing to the QueueSel register.
-
-* 0x050 | W | QueueNotify
-
-* 0x060 | R | InterruptStatus
-
-* 0x064 | W | InterruptACK
-
-* 0x070 | RW | Status
- Device status.
- Reading from this register returns the current device status
- flags.
- Writing non-zero values to this register sets the status flags,
- indicating the Guest progress. Writing zero (0x0) to this
- register triggers a device reset. This should include
- setting QueuePFN to zero (0x0) for all queues in the device.
- Also see "2.2.1. Device Initialization".
-
-* 0x100+ | RW | Config
-
-The virtual queue page size is defined by writing to the GuestPageSize
-register, as written by the guest. This must be done before the
-virtual queues are configured.
-
-The virtual queue layout follows
-p. "2.1.4.1. Legacy Interfaces: A Note on Virtqueue Layout",
-with the alignment defined in the QueueAlign register.
-
-The virtual queue is configured as follows:
-
-1. Select the queue writing its index (first queue is 0) to the
- QueueSel register.
-
-2. Check if the queue is not already in use: read the QueuePFN
- register, returned value should be zero (0x0).
-
-3. Read maximum queue size (number of elements) from the
- QueueNumMax register. If the returned value is zero (0x0) the
- queue is not available.
-
-4. Allocate and zero the queue pages in contiguous virtual
- memory, aligning the Used Ring to an optimal boundary (usually
- page size). Size of the allocated queue may be smaller than or
- equal to the maximum size returned by the Host.
-
-5. Notify the Host about the queue size by writing the size to
- the QueueNum register.
-
-6. Notify the Host about the used alignment by writing its value
- in bytes to the QueueAlign register.
-
-7. Write the physical number of the first page of the queue to
- the QueuePFN register.
-
-Notification mechanisms did not change.
-
-2.3.3. Virtio over channel I/O
-------------------------------
-
-S/390 based virtual machines support neither PCI nor MMIO, so a
-different transport is needed there.
-
-virtio-ccw uses the standard channel I/O based mechanism used for
-the majority of devices on S/390. A virtual channel device with a
-special control unit type acts as proxy to the virtio device
-(similar to the way virtio-pci uses a PCI device) and
-configuration and operation of the virtio device is accomplished
-(mostly) via channel commands. This means virtio devices are
-discoverable via standard operating system algorithms, and adding
-virtio support is mainly a question of supporting a new control
-unit type.
-
-As the S/390 is a big endian machine, the data structures transmitted
-via channel commands are big-endian: this is made clear by use of
-the types be16, be32 and be64.
-
-2.3.3.1. Basic Concepts
------------------------
-
-As a proxy device, virtio-ccw uses a channel-attached I/O control
-unit with a special control unit type (0x3832) and a control unit
-model corresponding to the attached virtio device's subsystem
-device ID, accessed via a virtual I/O subchannel and a virtual
-channel path of type 0x32. This proxy device is discoverable via
-normal channel subsystem device discovery (usually a STORE
-SUBCHANNEL loop) and answers to the basic channel commands, most
-importantly SENSE ID.
-
-For a virtio-ccw proxy device, SENSE ID will return the following
-information:
-
-+-------+--------------------------------------------+
-| Bytes | Contents |
-|-------|--------------------------------------------|
-| 0 | reserved | 0xff |
-|-------|-----------------------|--------------------|
-| 1-2 | control unit type | 0x3832 |
-|-------|-----------------------|--------------------|
-| 3 | control unit model | <virtio device id> |
-|-------|-----------------------|--------------------|
-| 4-5 | device type | zeroes (unset) |
-|-------|-----------------------|--------------------|
-| 6 | device model | zeroes (unset) |
-|-------|-----------------------|--------------------|
-| 7-255 | extended SenseId data | zeroes (unset) |
-+-------+--------------------------------------------+
-
-A driver for virtio-ccw devices MUST check for a control unit
-type of 0x3832 and MUST ignore the device type and model.
-
-In addition to the basic channel commands, virtio-ccw defines a
-set of channel commands related to configuration and operation of
-virtio:
-
- #define CCW_CMD_SET_VQ 0x13
- #define CCW_CMD_VDEV_RESET 0x33
- #define CCW_CMD_SET_IND 0x43
- #define CCW_CMD_SET_CONF_IND 0x53
- #define CCW_CMD_SET_IND_ADAPTER 0x73
- #define CCW_CMD_READ_FEAT 0x12
- #define CCW_CMD_WRITE_FEAT 0x11
- #define CCW_CMD_READ_CONF 0x22
- #define CCW_CMD_WRITE_CONF 0x21
- #define CCW_CMD_WRITE_STATUS 0x31
- #define CCW_CMD_READ_VQ_CONF 0x32
- #define CCW_CMD_SET_VIRTIO_REV 0x83
-
-The virtio-ccw device acts like a normal channel device, as specified
-in [S390 PoP] and [S390 Common I/O]. In particular:
-
-- A device must post a unit check with command reject for any command
- it does not support.
-
-- If a driver did not suppress length checks for a channel command,
- the device must present a subchannel status as detailed in the
- architecture when the actual length did not match the expected length.
-
-- If a driver did suppress length checks for a channel command, the
- device must present a check condition if the transmitted data does
- not contain enough data to process the command. If the driver submitted
- a buffer that was too long, the device should accept the command.
- The driver should attempt to provide the correct length even if it
- suppresses length checks.
-
-2.3.3.2. Device Initialization
-------------------------------
-
-virtio-ccw uses several channel commands to set up a device.
-
-2.3.3.2.1. Setting the Virtio Revision
---------------------------------------
-
-CCW_CMD_SET_VIRTIO_REV is issued by the driver to set the revision of
-the virtio-ccw transport it intends to drive the device with. It uses the
-following communication structure:
-
- struct virtio_rev_info {
- __u16 revision;
- __u16 length;
- __u8 data[];
- };
-
-revision contains the desired revision id, length the length of the
-data portion and data revision-dependent additional desired options.
-
-The following values are supported:
-
-+----------+--------+-----------+--------------------------------+
-| revision | length | data | remarks |
-|----------|--------|-----------|--------------------------------|
-| 0 | 0 | <empty> | legacy interface; transitional |
-| | | | devices only |
-|----------|--------|-----------|--------------------------------|
-| 1 | 0 | <empty> | Virtio 1.0 |
-|----------|--------|-----------|--------------------------------|
-| 2-n | | | reserved for later revisions |
-+----------+--------+-----------+--------------------------------+
-
-Note that a change in the virtio standard does not neccessarily
-correspond to a change in the virtio-ccw revision.
-
-A device must post a unit check with command reject for any revision
-it does not support. For any invalid combination of revision, length
-and data, it must post a unit check with command reject as well. A
-non-transitional device must reject revision id 0.
-
-A driver should start with trying to set the highest revision it
-supports and continue with lower revisions if it gets a command reject.
-
-A driver must not issue any other virtio-ccw specific channel commands
-prior to setting the revision.
-
-A device must answer with command reject to any virtio-ccw specific
-channel command that is not contained in the revision selected by the
-driver.
-
-After a revision has been successfully selected by the driver, it
-must not attempt to select a different revision. A device must answer
-to any such attempt with a command reject.
-
-A device must treat the revision as unset from the time the associated
-subchannel has been enabled until a revision has been successfully set
-by the driver. This implies that revisions are not persistent across
-disabling and enabling of the associated subchannel.
-
-2.3.3.2.1.1. Legacy Interfaces: A Note on Setting the Virtio Revision
----------------------------------------------------------------------
-
-A legacy device will not support the CCW_CMD_SET_VIRTIO_REV and answer
-with a command reject. A non-transitional driver must stop trying to
-operate this device in that case. A transitional driver must operate
-the device as if it had been able to set revision 0.
-
-A legacy driver will not issue the CCW_CMD_SET_VIRTIO_REV prior to
-issueing other virtio-ccw specific channel commands. A non-transitional
-device therefore must answer any such attempts with a command reject.
-A transitional device must assume in this case that the driver is a
-legacy driver and continue as if the driver selected revision 0. This
-implies that the device must reject any command not valid for revision
-0, including a subsequent CCW_CMD_SET_VIRTIO_REV.
-
-2.3.3.2.2. Configuring a Virtqueue
-----------------------------------
-
-CCW_CMD_READ_VQ_CONF is issued by the guest to obtain information
-about a queue. It uses the following structure for communicating:
-
- struct vq_config_block {
- be16 index;
- be16 max_num;
- } __attribute__ ((packed));
-
-The requested number of buffers for queue index is returned in
-max_num.
-
-Afterwards, CCW_CMD_SET_VQ is issued by the guest to inform the
-host about the location used for its queue. The transmitted
-structure is
-
- struct vq_info_block {
- be64 desc;
- be32 res0;
- be16 index;
- be16 num;
- be64 avail;
- be64 used;
- } __attribute__ ((packed));
-
-desc, avail and used contain the guest addresses for the descriptor table,
-available ring and used ring for queue index, respectively. The actual
-virtqueue size (number of allocated buffers) is transmitted in num.
-res0 is reserved and must be ignored by the device.
-
-2.3.3.2.2.1. Legacy Interface: A Note on Configuring a Virtqueue
-----------------------------------------------------------------
-
-For a legacy driver or for a driver that selected revision 0,
-CCW_CMD_SET_VQ uses the following communication block:
-
- struct vq_info_block_legacy {
- be64 queue;
- be32 align;
- be16 index;
- be16 num;
- } __attribute__ ((packed));
-
-queue contains the guest address for queue index, num the number of buffers
-and align the alignment.
-
-100.3.3.2.2. Virtqueue Layout
-------------------------------
-
-The virtqueue is physically contiguous, with padded added to make the
-used ring meet the align value:
-
-+-------------------+-----------------------------------+-----------+
-| Descriptor Table | Available Ring (padding) | Used Ring |
-+-------------------+-----------------------------------+-----------+
-
-The calculation for total size is as follows:
-
- #define ALIGN(x) (((x) + align) & ~align)
- static inline unsigned vring_size(unsigned int num)
- {
- return ALIGN(sizeof(struct vring_desc)*num
- + sizeof(u16)*(3 + num))
- + ALIGN(sizeof(u16)*3 + sizeof(struct vring_used_elem)*num);
- }
-
-2.3.3.2.3. Communicating Status Information
--------------------------------------------
-
-The guest can change the status of a device via the
-CCW_CMD_WRITE_STATUS command, which transmits an 8 bit status
-value.
-
-2.3.3.2.4. Handling Device Features
------------------------------------
-
-Feature bits are arranged in an array of 32 bit values, making
-for a total of 8192 feature bits. Feature bits are in
-little-endian byte order.
-
-The CCW commands dealing with features use the following
-communication block:
-
- struct virtio_feature_desc {
- be32 features;
- u8 index;
- } __attribute__ ((packed));
-
-features are the 32 bits of features currently accessed, while
-index describes which of the feature bit values is to be
-accessed.
-
-The guest may obtain the host's device feature set via the
-CCW_CMD_READ_FEAT command. The host stores the features at index
-to features.
-
-For communicating its device features to the host, the guest may
-use the CCW_CMD_WRITE_FEAT command, denoting a features/index
-combination.
-
-2.3.3.2.5. Device Configuration
--------------------------------
-
-The device's configuration space is located in host memory. It is
-the same size as the standard PCI configuration space.
-
-To obtain information from the configuration space, the guest may
-use CCW_CMD_READ_CONF, specifying the guest memory for the host
-to write to.
-
-For changing configuration information, the guest may use
-CCW_CMD_WRITE_CONF, specifying the guest memory for the host to
-read from.
-
-In both cases, the complete configuration space is transmitted. This
-allows the guest to compare the new configuration space with the old
-version, and keep a generation count internally whenever it changes.
-
-2.3.3.2.6. Setting Up Indicators
---------------------------------
-
-In order to set up the indicator bits for host->guest notification,
-the driver uses different channel commands depending on whether it
-wishes to use traditional I/O interrupts tied to a subchannel or
-adapter I/O interrupts for virtqueue notifications. For any given
-device, the two mechanisms are mutually exclusive.
-
-For the configuration change indicators, only a mechanism using
-traditional I/O interrupts is provided, regardless of whether
-traditional or adapter I/O interrupts are used for virtqueue
-notifications.
-
-2.3.3.2.6.1. Setting Up Classic Queue Indicators
-------------------------------------------------
-
-Indicators for notification via classic I/O interrupts are contained
-in a 64 bit value per virtio-ccw proxy device.
-
-To communicate the location of the indicator bits for host->guest
-notification, the guest uses the CCW_CMD_SET_IND command,
-pointing to a location containing the guest address of the
-indicators in a 64 bit value.
-
-If the driver has already set up two-staged queue indicators via the
-CCW_CMD_SET_IND_ADAPTER command, the device MUST post a unit check
-with command reject to any subsequent CCW_CMD_SET_IND command.
-
-2.3.3.2.6.2. Setting Up Configuration Change Indicators
--------------------------------------------------------
-
-Indicators for configuration change host->guest notification are
-contained in a 64 bit value per virtio-ccw proxy device.
-
-To communicate the location of the indicator bits used in the
-configuration change host->guest notification, the driver issues the
-CCW_CMD_SET_CONF_IND command, pointing to a location containing the
-guest address of the indicators in a 64 bit value.
-
-2.3.3.2.6.3. Setting Up Two-Stage Queue Indicators
---------------------------------------------------
-
-Indicators for notification via adapter I/O interrupts consist of
-two stages:
-- a summary indicator byte covering the virtqueues for one or more
- virtio-ccw proxy devices
-- a set of contigous indicator bits for the virtqueues for a
- virtio-ccw proxy device
-
-To communicate the location of the summary and queue indicator bits,
-the driver uses the CCW_CMD_SET_IND_ADAPTER command with the following
-payload:
-
- struct virtio_thinint_area {
- be64 summary_indicator;
- be64 indicator;
- be64 bit_nr;
- u8 isc;
- } __attribute__ ((packed));
-
-summary_indicator contains the guest address of the 8 bit summary
-indicator.
-indicator contains the guest address of an area wherin the indicators
-for the devices are contained, starting at bit_nr, one bit per
-virtqueue of the device. Bit numbers start at the left.
-isc contains the I/O interruption subclass to be used for the adapter
-I/O interrupt. It may be different from the isc used by the proxy
-virtio-ccw device's subchannel.
-
-If the driver has already set up classic queue indicators via the
-CCW_CMD_SET_IND command, the device MUST post a unit check with
-command reject to any subsequent CCW_CMD_SET_IND_ADAPTER command.
-
-2.3.3.2.6.4. Legacy Interfaces: A Note on Setting Up Indicators
----------------------------------------------------------------
-
-Legacy devices will only support classic queue indicators; they will
-reject CCW_CMD_SET_IND_ADAPTER as they don't know that command.
-
-2.3.3.3. Device Operation
--------------------------
-
-2.3.3.3.1. Host->Guest Notification
------------------------------------
-
-There are two modes of operation regarding host->guest notifcation,
-classic I/O interrupts and adapter I/O interrupts. The mode to be
-used is determined by the driver by using CCW_CMD_SET_IND respectively
-CCW_CMD_SET_IND_ADAPTER to set up queue indicators.
-
-For configuration changes, the driver will always use classic I/O
-interrupts.
-
-2.3.3.3.1.1. Notification via Classic I/O Interrupts
-----------------------------------------------------
-
-If the driver used the CCW_CMD_SET_IND command to set up queue
-indicators, the device will use classic I/O interrupts for
-host->guest notification about virtqueue activity.
-
-For notifying the guest of virtqueue buffers, the host sets the
-corresponding bit in the guest-provided indicators. If an
-interrupt is not already pending for the subchannel, the host
-generates an unsolicited I/O interrupt.
-
-If the host wants to notify the guest about configuration
-changes, it sets bit 0 in the configuration indicators and
-generates an unsolicited I/O interrupt, if needed. This also
-applies if adapter I/O interrupts are used for queue notifications.
-
-2.3.3.3.1.2. Notification via Adapter I/O Interrupts
-----------------------------------------------------
-
-If the driver used the CCW_CMD_SET_IND_ADAPTER command to set up
-queue indicators, the device will use adapter I/O interrupts for
-host->guest notification about virtqueue activity.
-
-For notifying the guest of virtqueue buffers, the host sets the
-bit in the guest-provided indicator area at the corresponding offset.
-The guest-provided summary indicator is also set. An adapter I/O
-interrupt for the corresponding interruption subclass is generated.
-The device SHOULD only generate an adapter I/O interrupt if the
-summary indicator had not been set prior to notification. The driver
-MUST clear the summary indicator after receiving an adapter I/O
-interrupt before it processes the queue indicators.
-
-2.3.3.3.1.3. Legacy Interfaces: A Note on Host->Guest Notification
-------------------------------------------------------------------
-
-As legacy devices and drivers support only classic queue indicators,
-host->guest notification will always be done via classic I/O interrupts.
-
-2.3.3.3.2. Guest->Host Notification
------------------------------------
-
-For notifying the host of virtqueue buffers, the guest
-unfortunately can't use a channel command (the asynchronous
-characteristics of channel I/O interact badly with the host block
-I/O backend). Instead, it uses a diagnose 0x500 call with subcode
-3 specifying the queue, as follows:
-
-+------+-------------------+--------------+
-| GPR | Input Value | Output Value |
-+------+-------------------+--------------+
-+------+-------------------+--------------+
-| 1 | 0x3 | |
-+------+-------------------+--------------+
-| 2 | Subchannel ID | Host Cookie |
-+------+-------------------+--------------+
-| 3 | Virtqueue number | |
-+------+-------------------+--------------+
-| 4 | Host Cookie | |
-+------+-------------------+--------------+
-
-Host cookie is an optional per-virtqueue 64 bit value that can be
-used by the hypervisor to speed up the notification execution.
-For each notification, the output value is returned in GPR2 and
-should be passed in GPR4 for the next notification:
-
- info->cookie = do_notify(schid,
- virtqueue_get_queue_index(vq),
- info->cookie);
-
-2.3.3.3.3. Early printk for Virtio Consoles
--------------------------------------------
-
-For the early printk mechanism, diagnose 0x500 with subcode 0 is
-used.
-
-2.3.3.3.4. Resetting Devices
-----------------------------
-
-In order to reset a device, a guest may send the
-CCW_CMD_VDEV_RESET command.
-
-
-2.4. Device Types
-================
-
-On top of the queues, config space and feature negotiation facilities
-built into virtio, several specific devices are defined.
-
-The following device IDs are used to identify different types of virtio
-devices. Some device IDs are reserved for devices which are not currently
-defined in this standard.
-
-Discovering what devices are available and their type is bus-dependent.
-
-+------------+--------------------+
-| Device ID | Virtio Device |
-+------------+--------------------+
-+------------+--------------------+
-| 0 | reserved (invalid) |
-+------------+--------------------+
-| 1 | network card |
-+------------+--------------------+
-| 2 | block device |
-+------------+--------------------+
-| 3 | console |
-+------------+--------------------+
-| 4 | entropy source |
-+------------+--------------------+
-| 5 | memory ballooning |
-+------------+--------------------+
-| 6 | ioMemory |
-+------------+--------------------+
-| 7 | rpmsg |
-+------------+--------------------+
-| 8 | SCSI host |
-+------------+--------------------+
-| 9 | 9P transport |
-+------------+--------------------+
-| 10 | mac80211 wlan |
-+------------+--------------------+
-| 11 | rproc serial |
-+------------+--------------------+
-| 12 | virtio CAIF |
-+------------+--------------------+
-
-2.4.1. Network Device
-====================
-
-The virtio network device is a virtual ethernet card, and is the
-most complex of the devices supported so far by virtio. It has
-enhanced rapidly and demonstrates clearly how support for new
-features should be added to an existing device. Empty buffers are
-placed in one virtqueue for receiving packets, and outgoing
-packets are enqueued into another for transmission in that order.
-A third command queue is used to control advanced filtering
-features.
-
-2.4.1.1. Device ID
------------------
-
- 1
-
-2.4.1.2. Virtqueues
-------------------
-
- 0:receiveq. 1:transmitq. 2:controlq
-
- Virtqueue 2 only exists if VIRTIO_NET_F_CTRL_VQ set.
-
-2.4.1.3. Feature bits
---------------------
-
- VIRTIO_NET_F_CSUM (0) Device handles packets with partial checksum
-
- VIRTIO_NET_F_GUEST_CSUM (1) Guest handles packets with partial checksum
-
- VIRTIO_NET_F_CTRL_GUEST_OFFLOADS (2) Control channel offloads
- reconfiguration support.
-
- VIRTIO_NET_F_MAC (5) Device has given MAC address.
-
- VIRTIO_NET_F_GUEST_TSO4 (7) Guest can receive TSOv4.
-
- VIRTIO_NET_F_GUEST_TSO6 (8) Guest can receive TSOv6.
-
- VIRTIO_NET_F_GUEST_ECN (9) Guest can receive TSO with ECN.
-
- VIRTIO_NET_F_GUEST_UFO (10) Guest can receive UFO.
-
- VIRTIO_NET_F_HOST_TSO4 (11) Device can receive TSOv4.
-
- VIRTIO_NET_F_HOST_TSO6 (12) Device can receive TSOv6.
-
- VIRTIO_NET_F_HOST_ECN (13) Device can receive TSO with ECN.
-
- VIRTIO_NET_F_HOST_UFO (14) Device can receive UFO.
-
- VIRTIO_NET_F_MRG_RXBUF (15) Guest can merge receive buffers.
-
- VIRTIO_NET_F_STATUS (16) Configuration status field is
- available.
-
- VIRTIO_NET_F_CTRL_VQ (17) Control channel is available.
-
- VIRTIO_NET_F_CTRL_RX (18) Control channel RX mode support.
-
- VIRTIO_NET_F_CTRL_VLAN (19) Control channel VLAN filtering.
-
- VIRTIO_NET_F_GUEST_ANNOUNCE(21) Guest can send gratuitous
- packets.
-
-2.4.1.3.1. Legacy Interface: Feature bits
---------------------
-VIRTIO_NET_F_GSO (6) Device handles packets with any GSO type.
-
-This was supposed to indicate segmentation offload support, but
-upon further investigation it became clear that multiple bits
-were required.
-
-100.4.1.4. Device configuration layout
----------------------
-
-Two configuration fields are currently defined. The mac address field
-always exists (though is only valid if VIRTIO_NET_F_MAC is set), and
-the status field only exists if VIRTIO_NET_F_STATUS is set. Two
-read-only bits are currently defined for the status field:
-VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE.
-
- #define VIRTIO_NET_S_LINK_UP 1
- #define VIRTIO_NET_S_ANNOUNCE 2
-
- struct virtio_net_config {
- u8 mac[6];
- le16 status;
- };
-
-100.4.1.4.1. Legacy Interface: Device configuration layout
---------------------
-For legacy devices, the status field in struct virtio_net_config is the
-native endian of the guest rather than (necessarily) little-endian.
-
-
-2.4.1.4. Device Initialization
------------------------------
-
-1. The initialization routine should identify the receive and
- transmission virtqueues.
-
-2. If the VIRTIO_NET_F_MAC feature bit is set, the configuration
- space “mac” entry indicates the “physical” address of the the
- network card, otherwise a private MAC address should be
- assigned. All guests are expected to negotiate this feature if
- it is set.
-
-3. If the VIRTIO_NET_F_CTRL_VQ feature bit is negotiated,
- identify the control virtqueue.
-
-4. If the VIRTIO_NET_F_STATUS feature bit is negotiated, the link
- status can be read from the bottom bit of the “status” config
- field. Otherwise, the link should be assumed active.
-
-5. The receive virtqueue should be filled with receive buffers.
- This is described in detail below in “Setting Up Receive
- Buffers”.
-
-6. A driver can indicate that it will generate checksumless
- packets by negotating the VIRTIO_NET_F_CSUM feature. This “
- checksum offload” is a common feature on modern network cards.
-
-7. If that feature is negotiated[13], a driver can use TCP or UDP
- segmentation offload by negotiating the VIRTIO_NET_F_HOST_TSO4 (IPv4
- TCP), VIRTIO_NET_F_HOST_TSO6 (IPv6 TCP) and VIRTIO_NET_F_HOST_UFO
- (UDP fragmentation) features. It should not send TCP packets
- requiring segmentation offload which have the Explicit Congestion
- Notification bit set, unless the VIRTIO_NET_F_HOST_ECN feature is
- negotiated.[14]
-
-8. The converse features are also available: a driver can save
- the virtual device some work by negotiating these features.[15]
- The VIRTIO_NET_F_GUEST_CSUM feature indicates that partially
- checksummed packets can be received, and if it can do that then
- the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6,
- VIRTIO_NET_F_GUEST_UFO and VIRTIO_NET_F_GUEST_ECN are the input
- equivalents of the features described above.
- See "2.4.1.5.2. Setting Up Receive Buffers" and "2.4.1.5.2.1. Packet Receive Interrupt" below.
-
-2.4.1.5. Device Operation
-------------------------
-
-Packets are transmitted by placing them in the transmitq, and
-buffers for incoming packets are placed in the receiveq. In each
-case, the packet itself is preceeded by a header:
-
- struct virtio_net_hdr {
- #define VIRTIO_NET_HDR_F_NEEDS_CSUM 1
- u8 flags;
- #define VIRTIO_NET_HDR_GSO_NONE 0
- #define VIRTIO_NET_HDR_GSO_TCPV4 1
- #define VIRTIO_NET_HDR_GSO_UDP 3
- #define VIRTIO_NET_HDR_GSO_TCPV6 4
- #define VIRTIO_NET_HDR_GSO_ECN 0x80
- u8 gso_type;
- le16 hdr_len;
- le16 gso_size;
- le16 csum_start;
- le16 csum_offset;
- /* Only if VIRTIO_NET_F_MRG_RXBUF: */
- le16 num_buffers;
- };
-
-The controlq is used to control device features such as
-filtering.
-
-100.4.1.5.1. Legacy Interface: Device Operation
-------------------------
-For legacy devices, the fields in struct virtio_net_hdr are the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.4.1.5.1. Packet Transmission
------------------------------
-
-Transmitting a single packet is simple, but varies depending on
-the different features the driver negotiated.
-
-1. If the driver negotiated VIRTIO_NET_F_CSUM, and the packet has
- not been fully checksummed, then the virtio_net_hdr's fields
- are set as follows. Otherwise, the packet must be fully
- checksummed, and flags is zero.
-
- • flags has the VIRTIO_NET_HDR_F_NEEDS_CSUM set,
-
- • csum_start is set to the offset within the packet to begin checksumming,
- and
-
- • csum_offset indicates how many bytes after the csum_start the
- new (16 bit ones' complement) checksum should be placed.[16]
-
-2. If the driver negotiated
- VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO, and the packet requires
- TCP segmentation or UDP fragmentation, then the “gso_type”
- field is set to VIRTIO_NET_HDR_GSO_TCPV4, TCPV6 or UDP.
- (Otherwise, it is set to VIRTIO_NET_HDR_GSO_NONE). In this
- case, packets larger than 1514 bytes can be transmitted: the
- metadata indicates how to replicate the packet header to cut it
- into smaller packets. The other gso fields are set:
-
- • hdr_len is a hint to the device as to how much of the header
- needs to be kept to copy into each packet, usually set to the
- length of the headers, including the transport header.[17]
-
- • gso_size is the maximum size of each packet beyond that
- header (ie. MSS).
-
- • If the driver negotiated the VIRTIO_NET_F_HOST_ECN feature,
- the VIRTIO_NET_HDR_GSO_ECN bit may be set in “gso_type” as
- well, indicating that the TCP packet has the ECN bit set.[18]
-
-3. If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature,
- the num_buffers field is set to zero.
-
-4. The header and packet are added as one output buffer to the
- transmitq, and the device is notified of the new entry
- (see "2.4.1.4. Notifying The Device").[19]
-
-2.4.1.5.1.1. Packet Transmission Interrupt
------------------------------------------
-
-Often a driver will suppress transmission interrupts using the
-VRING_AVAIL_F_NO_INTERRUPT flag
- (see "2.4.2. Receiving Used Buffers From The Device")
-and check for used packets in the transmit path of following
-packets.
-
-The normal behavior in this interrupt handler is to retrieve and
-new descriptors from the used ring and free the corresponding
-headers and packets.
-
-2.4.1.5.2. Setting Up Receive Buffers
------------------------------------------
-
-It is generally a good idea to keep the receive virtqueue as
-fully populated as possible: if it runs out, network performance
-will suffer.
-
-If the VIRTIO_NET_F_GUEST_TSO4, VIRTIO_NET_F_GUEST_TSO6 or
-VIRTIO_NET_F_GUEST_UFO features are used, the Guest will need to
-accept packets of up to 65550 bytes long (the maximum size of a
-TCP or UDP packet, plus the 14 byte ethernet header), otherwise
-1514. bytes. So unless VIRTIO_NET_F_MRG_RXBUF is negotiated, every
-buffer in the receive queue needs to be at least this length [20]
-
-If VIRTIO_NET_F_MRG_RXBUF is negotiated, each buffer must be at
-least the size of the struct virtio_net_hdr.
-
-2.4.1.5.2.1. Packet Receive Interrupt
-------------------------------------
-
-When a packet is copied into a buffer in the receiveq, the
-optimal path is to disable further interrupts for the receiveq
-(see 2.2.2.2. Receiving Used Buffers From The Device) and process
-packets until no more are found, then re-enable them.
-
-Processing packet involves:
-
-1. If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature,
- then the “num_buffers” field indicates how many descriptors
- this packet is spread over (including this one). This allows
- receipt of large packets without having to allocate large
- buffers. In this case, there will be at least “num_buffers” in
- the used ring, and they should be chained together to form a
- single packet. The other buffers will not begin with a struct
- virtio_net_hdr.
-
-2. If the VIRTIO_NET_F_MRG_RXBUF feature was not negotiated, or
- the “num_buffers” field is one, then the entire packet will be
- contained within this buffer, immediately following the struct
- virtio_net_hdr.
-
-3. If the VIRTIO_NET_F_GUEST_CSUM feature was negotiated, the
- VIRTIO_NET_HDR_F_NEEDS_CSUM bit in the “flags” field may be
- set: if so, the checksum on the packet is incomplete and the “
- csum_start” and “csum_offset” fields indicate how to calculate
- it (see Packet Transmission point 1).
-
-4. If the VIRTIO_NET_F_GUEST_TSO4, TSO6 or UFO options were
- negotiated, then the “gso_type” may be something other than
- VIRTIO_NET_HDR_GSO_NONE, and the “gso_size” field indicates the
- desired MSS (see Packet Transmission point 2).
-
-2.4.1.5.3. Control Virtqueue
----------------------------
-
-The driver uses the control virtqueue (if VIRTIO_NET_F_VTRL_VQ is
-negotiated) to send commands to manipulate various features of
-the device which would not easily map into the configuration
-space.
-
-All commands are of the following form:
-
- struct virtio_net_ctrl {
- u8 class;
- u8 command;
- u8 command-specific-data[];
- u8 ack;
- };
-
- /* ack values */
- #define VIRTIO_NET_OK 0
- #define VIRTIO_NET_ERR 1
-
-The class, command and command-specific-data are set by the
-driver, and the device sets the ack byte. There is little it can
-do except issue a diagnostic if the ack byte is not
-VIRTIO_NET_OK.
-
-2.4.1.5.3.1. Packet Receive Filtering
-------------------------------------
-
-If the VIRTIO_NET_F_CTRL_RX feature is negotiated, the driver can
-send control commands for promiscuous mode, multicast receiving,
-and filtering of MAC addresses.
-
-Note that in general, these commands are best-effort: unwanted
-packets may still arrive.
-
-Setting Promiscuous Mode
-
- #define VIRTIO_NET_CTRL_RX 0
- #define VIRTIO_NET_CTRL_RX_PROMISC 0
- #define VIRTIO_NET_CTRL_RX_ALLMULTI 1
-
-The class VIRTIO_NET_CTRL_RX has two commands:
-VIRTIO_NET_CTRL_RX_PROMISC turns promiscuous mode on and off, and
-VIRTIO_NET_CTRL_RX_ALLMULTI turns all-multicast receive on and
-off. The command-specific-data is one byte containing 0 (off) or
-1 (on).
-
-2.4.1.5.3.2. Setting MAC Address Filtering
------------------------------------------
-
- struct virtio_net_ctrl_mac {
- le32 entries;
- u8 macs[entries][ETH_ALEN];
- };
-
- #define VIRTIO_NET_CTRL_MAC 1
- #define VIRTIO_NET_CTRL_MAC_TABLE_SET 0
-
-The device can filter incoming packets by any number of destination
-MAC addresses.[21] This table is set using the class
-VIRTIO_NET_CTRL_MAC and the command VIRTIO_NET_CTRL_MAC_TABLE_SET. The
-command-specific-data is two variable length tables of 6-byte MAC
-addresses. The first table contains unicast addresses, and the second
-contains multicast addresses.
-
-2.4.1.5.3.2.1. Legacy Interface: Setting MAC Address Filtering
------------------------------------------
-For legacy devices, the entries field in struct virtio_net_ctrl_mac is the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.4.1.5.3.3. VLAN Filtering
---------------------------
-
-If the driver negotiates the VIRTION_NET_F_CTRL_VLAN feature, it
-can control a VLAN filter table in the device.
-
- #define VIRTIO_NET_CTRL_VLAN 2
- #define VIRTIO_NET_CTRL_VLAN_ADD 0
- #define VIRTIO_NET_CTRL_VLAN_DEL 1
-
-Both the VIRTIO_NET_CTRL_VLAN_ADD and VIRTIO_NET_CTRL_VLAN_DEL
-command take a little-endian 16-bit VLAN id as the command-specific-data.
-
-2.4.1.5.3.3.1. Legacy Interface: VLAN Filtering
------------------------------------------
-For legacy devices, the VLAN id is in the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.4.1.5.3.4. Gratuitous Packet Sending
--------------------------------------
-
-If the driver negotiates the VIRTIO_NET_F_GUEST_ANNOUNCE (depends
-on VIRTIO_NET_F_CTRL_VQ), it can ask the guest to send gratuitous
-packets; this is usually done after the guest has been physically
-migrated, and needs to announce its presence on the new network
-links. (As hypervisor does not have the knowledge of guest
-network configuration (eg. tagged vlan) it is simplest to prod
-the guest in this way).
-
- #define VIRTIO_NET_CTRL_ANNOUNCE 3
- #define VIRTIO_NET_CTRL_ANNOUNCE_ACK 0
-
-The Guest needs to check VIRTIO_NET_S_ANNOUNCE bit in status
-field when it notices the changes of device configuration. The
-command VIRTIO_NET_CTRL_ANNOUNCE_ACK is used to indicate that
-driver has recevied the notification and device would clear the
-VIRTIO_NET_S_ANNOUNCE bit in the status filed after it received
-this command.
-
-Processing this notification involves:
-
-1. Sending the gratuitous packets or marking there are pending
- gratuitous packets to be sent and letting deferred routine to
- send them.
-
-2. Sending VIRTIO_NET_CTRL_ANNOUNCE_ACK command through control
- vq.
-
-2.4.1.5.3.5. Offloads State Configuration
--------------------------------------
-
-If the VIRTIO_NET_F_CTRL_GUEST_OFFLOADS feature is negotiated, the driver can
-send control commands for dynamic offloads state configuration.
-
-2.4.1.5.4.3.1. Setting Offloads State
--------------------------------------
-
- le64 offloads;
-
- #define VIRTIO_NET_F_GUEST_CSUM 1
- #define VIRTIO_NET_F_GUEST_TSO4 7
- #define VIRTIO_NET_F_GUEST_TSO6 8
- #define VIRTIO_NET_F_GUEST_ECN 9
- #define VIRTIO_NET_F_GUEST_UFO 10
-
- #define VIRTIO_NET_CTRL_GUEST_OFFLOADS 5
- #define VIRTIO_NET_CTRL_GUEST_OFFLOADS_SET 0
-
-The class VIRTIO_NET_CTRL_GUEST_OFFLOADS has one command:
-VIRTIO_NET_CTRL_GUEST_OFFLOADS_SET applies the new offloads configuration.
-
-le64 value passed as command data is a bitmask, bits set define
-offloads to be enabled, bits cleared - offloads to be disabled.
-
-There is a corresponding device feature for each offload. Upon feature
-negotiation corresponding offload gets enabled to preserve backward
-compartibility.
-
-Corresponding feature must be negotiated at startup in order to allow dynamic
-change of specific offload state.
-
-
-2.4.1.5.4.3.1.1. Legacy Interface: Setting Offloads State
--------------------------------------
-For legacy devices, the offloads field is the
-native endian of the guest rather than (necessarily) little-endian.
-
-
-2.4.2. Block Device
-==================
-
-The virtio block device is a simple virtual block device (ie.
-disk). Read and write requests (and other exotic requests) are
-placed in the queue, and serviced (probably out of order) by the
-device except where noted.
-
-2.4.2.1. Device ID
------------------
- 2
-
-2.4.2.2. Virtqueues
-------------------
- 0:requestq
-
-2.4.2.3. Feature bits
---------------------
-
- VIRTIO_BLK_F_SIZE_MAX (1) Maximum size of any single segment is
- in “size_max”.
-
- VIRTIO_BLK_F_SEG_MAX (2) Maximum number of segments in a
- request is in “seg_max”.
-
- VIRTIO_BLK_F_GEOMETRY (4) Disk-style geometry specified in “
- geometry”.
-
- VIRTIO_BLK_F_RO (5) Device is read-only.
-
- VIRTIO_BLK_F_BLK_SIZE (6) Block size of disk is in “blk_size”.
-
- VIRTIO_BLK_F_TOPOLOGY (10) Device exports information on optimal I/O
- alignment.
-
-2.4.2.3.1. Legacy Interface: Feature bits
---------------------
- VIRTIO_BLK_F_BARRIER (0) Host supports request barriers.
-
- VIRTIO_BLK_F_SCSI (7) Device supports scsi packet commands.
-
- VIRTIO_BLK_F_FLUSH (9) Cache flush command support.
-
- VIRTIO_BLK_F_CONFIG_WCE (11) Device can toggle its cache between writeback
- and writethrough modes.
-
-VIRTIO_BLK_F_FLUSH was also called VIRTIO_BLK_F_WCE: Legacy drivers
-should only negotiate this feature if they are capable of sending
-VIRTIO_BLK_T_FLUSH commands.
-
-100.2.4.2.5. Device configuration layout
---------------------
-
-The capacity of the device (expressed in 512-byte sectors) is always
-present. The availability of the others all depend on various feature
-bits as indicated above.
-
- struct virtio_blk_config {
- le64 capacity;
- le32 size_max;
- le32 seg_max;
- struct virtio_blk_geometry {
- le16 cylinders;
- u8 heads;
- u8 sectors;
- } geometry;
- le32 blk_size;
- struct virtio_blk_topology {
- // # of logical blocks per physical block (log2)
- u8 physical_block_exp;
- // offset of first aligned logical block
- u8 alignment_offset;
- // suggested minimum I/O size in blocks
- le16 min_io_size;
- // optimal (suggested maximum) I/O size in blocks
- le32 opt_io_size;
- } topology;
- u8 reserved;
- };
-
-
-100.2.4.2.5.1. Legacy Interface: Device configuration layout
---------------------
-For legacy devices, the fields in struct virtio_blk_config are the
-native endian of the guest rather than (necessarily) little-endian.
-
-
-2.4.2.4. Device Initialization
------------------------------
-
-1. The device size should be read from the “capacity”
- configuration field. No requests should be submitted which goes
- beyond this limit.
-
-2. If the VIRTIO_BLK_F_BLK_SIZE feature is negotiated, the
- blk_size field can be read to determine the optimal sector size
- for the driver to use. This does not affect the units used in
- the protocol (always 512 bytes), but awareness of the correct
- value can affect performance.
-
-3. If the VIRTIO_BLK_F_RO feature is set by the device, any write
- requests will fail.
-
-4. If the VIRTIO_BLK_F_TOPOLOGY feature is negotiated, the fields in the
- topology struct can be read to determine the physical block size and optimal
- I/O lengths for the driver to use. This also does not affect the units
- in the protocol, only performance.
-
-2.4.2.4.1. Legacy Interface: Device Initialization
------------------------------
-
-The reserved field used to be called writeback. If the
-VIRTIO_BLK_F_CONFIG_WCE feature is offered, the cache mode should be
-read from the writeback field of the configuration if available; the
-driver can also write to the field in order to toggle the cache
-between writethrough (0) and writeback (1) mode. If the feature is
-not available, the driver can instead look at the result of
-negotiating VIRTIO_BLK_F_FLUSH: the cache will be in writeback mode
-after reset if and only if VIRTIO_BLK_F_FLUSH is negotiated.
-
-Some older legacy devices did not operate in writethrough mode even
-after a guest announced lack of support for VIRTIO_BLK_F_FLUSH.
-
-2.4.2.5. Device Operation
-------------------------
-
-The driver queues requests to the virtqueue, and they are used by
-the device (not necessarily in order). Each request is of form:
-
- struct virtio_blk_req {
- le32 type;
- le32 reserved;
- le64 sector;
- char data[][512];
- u8 status;
- };
-
-The type of the request is either a read (VIRTIO_BLK_T_IN), a write
-(VIRTIO_BLK_T_OUT), or a flush (VIRTIO_BLK_T_FLUSH or
-VIRTIO_BLK_T_FLUSH_OUT[23]).
-
- #define VIRTIO_BLK_T_IN 0
- #define VIRTIO_BLK_T_OUT 1
- #define VIRTIO_BLK_T_FLUSH 4
- #define VIRTIO_BLK_T_FLUSH_OUT 5
-
-The sector number indicates the offset (multiplied by 512) where
-the read or write is to occur. This field is unused and set to 0
-for scsi packet commands and for flush commands.
-
-The final status byte is written by the device: either
-VIRTIO_BLK_S_OK for success, VIRTIO_BLK_S_IOERR for host or guest
-error or VIRTIO_BLK_S_UNSUPP for a request unsupported by host:
-
- #define VIRTIO_BLK_S_OK 0
- #define VIRTIO_BLK_S_IOERR 1
- #define VIRTIO_BLK_S_UNSUPP 2
-
-Any writes completed before the submission of the flush command should
-be committed to non-volatile storage by the device.
-
-2.4.2.5.1. Legacy Interface: Device Operation
-------------------------
-For legacy devices, the fields in struct virtio_blk_req are the
-native endian of the guest rather than (necessarily) little-endian.
-
-The 'reserved' field was previously called ioprio. The ioprio field
-is a hint about the relative priorities of requests to the device:
-higher numbers indicate more important requests.
-
- #define VIRTIO_BLK_T_BARRIER 0x80000000
-
-If the device has VIRTIO_BLK_F_BARRIER
-feature the high bit (VIRTIO_BLK_T_BARRIER) indicates that this
-request acts as a barrier and that all preceeding requests must be
-complete before this one, and all following requests must not be
-started until this is complete. Note that a barrier does not flush
-caches in the underlying backend device in host, and thus does not
-serve as data consistency guarantee. Driver must use FLUSH request to
-flush the host cache.
-
-If the device has VIRTIO_BLK_F_SCSI feature, it can also support
-scsi packet command requests, each of these requests is of form:
-
- /* All fields are in guest's native endian. */
- struct virtio_scsi_pc_req {
- u32 type;
- u32 ioprio;
- u64 sector;
- char cmd[];
- char data[][512];
- #define SCSI_SENSE_BUFFERSIZE 96
- u8 sense[SCSI_SENSE_BUFFERSIZE];
- u32 errors;
- u32 data_len;
- u32 sense_len;
- u32 residual;
- u8 status;
- };
-
-A request type can also be a scsi packet command (VIRTIO_BLK_T_SCSI_CMD or
-VIRTIO_BLK_T_SCSI_CMD_OUT). The two types are equivalent, the device
-does not distinguish between them:
-
- #define VIRTIO_BLK_T_SCSI_CMD 2
- #define VIRTIO_BLK_T_SCSI_CMD_OUT 3
-
-The cmd field is only present for scsi packet command requests,
-and indicates the command to perform. This field must reside in a
-single, separate read-only buffer; command length can be derived
-from the length of this buffer.
-
-Note that these first three (four for scsi packet commands)
-fields are always read-only: the data field is either read-only
-or write-only, depending on the request. The size of the read or
-write can be derived from the total size of the request buffers.
-
-The sense field is only present for scsi packet command requests,
-and indicates the buffer for scsi sense data.
-
-The data_len field is only present for scsi packet command
-requests, this field is deprecated, and should be ignored by the
-driver. Historically, devices copied data length there.
-
-The sense_len field is only present for scsi packet command
-requests and indicates the number of bytes actually written to
-the sense buffer.
-
-The residual field is only present for scsi packet command
-requests and indicates the residual size, calculated as data
-length - number of bytes actually transferred.
-
-Historically, devices assumed that the fields type, ioprio and
-sector reside in a single, separate read-only buffer; the fields
-errors, data_len, sense_len and residual reside in a single,
-separate write-only buffer; the sense field in a separate
-write-only buffer of size 96 bytes, by itself; the fields errors,
-data_len, sense_len and residual in a single write-only buffer;
-and the status field is a separate read-only buffer of size 1
-byte, by itself.
-
-
-2.4.3. Console Device
-====================
-
-The virtio console device is a simple device for data input and
-output. A device may have one or more ports. Each port has a pair
-of input and output virtqueues. Moreover, a device has a pair of
-control IO virtqueues. The control virtqueues are used to
-communicate information between the device and the driver about
-ports being opened and closed on either side of the connection,
-indication from the host about whether a particular port is a
-console port, adding new ports, port hot-plug/unplug, etc., and
-indication from the guest about whether a port or a device was
-successfully added, port open/close, etc.. For data IO, one or
-more empty buffers are placed in the receive queue for incoming
-data and outgoing characters are placed in the transmit queue.
-
-2.4.3.1. Device ID
------------------
-
- 3
-
-2.4.3.2. Virtqueues
-------------------
-
- 0:receiveq(port0). 1:transmitq(port0), 2:control receiveq, 3:control transmitq, 4:receiveq(port1), 5:transmitq(port1),
- ...
-
- Ports 2 onwards only exist if VIRTIO_CONSOLE_F_MULTIPORT is set.
-
-2.4.3.3. Feature bits
---------------------
-
- VIRTIO_CONSOLE_F_SIZE (0) Configuration cols and rows fields
- are valid.
-
- VIRTIO_CONSOLE_F_MULTIPORT(1) Device has support for multiple
- ports; configuration fields nr_ports and max_nr_ports are
- valid and control virtqueues will be used.
-
-2.4.3.4. Device configuration layout
------------------------------------
-
- The size of the console is supplied
- in the configuration space if the VIRTIO_CONSOLE_F_SIZE feature
- is set. Furthermore, if the VIRTIO_CONSOLE_F_MULTIPORT feature
- is set, the maximum number of ports supported by the device can
- be fetched.
-
- struct virtio_console_config {
- le16 cols;
- le16 rows;
- le32 max_nr_ports;
- };
-
-2.4.3.4.1. Legacy Interface: Device configuration layout
------------------------------------
-For legacy devices, the fields in struct virtio_console_config are the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.4.3.5. Device Initialization
------------------------------
-
-1. If the VIRTIO_CONSOLE_F_SIZE feature is negotiated, the driver
- can read the console dimensions from the configuration fields.
-
-2. If the VIRTIO_CONSOLE_F_MULTIPORT feature is negotiated, the
- driver can spawn multiple ports, not all of which may be
- attached to a console. Some could be generic ports. In this
- case, the control virtqueues are enabled and according to the
- max_nr_ports configuration-space value, the appropriate number
- of virtqueues are created. A control message indicating the
- driver is ready is sent to the host. The host can then send
- control messages for adding new ports to the device. After
- creating and initializing each port, a
- VIRTIO_CONSOLE_PORT_READY control message is sent to the host
- for that port so the host can let us know of any additional
- configuration options set for that port.
-
-3. The receiveq for each port is populated with one or more
- receive buffers.
-
-2.4.3.6. Device Operation
-------------------------
-
-1. For output, a buffer containing the characters is placed in
- the port's transmitq.[24]
-
-2. When a buffer is used in the receiveq (signalled by an
- interrupt), the contents is the input to the port associated
- with the virtqueue for which the notification was received.
-
-3. If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a
- configuration change interrupt may occur. The updated size can
- be read from the configuration fields.
-
-4. If the driver negotiated the VIRTIO_CONSOLE_F_MULTIPORT
- feature, active ports are announced by the host using the
- VIRTIO_CONSOLE_PORT_ADD control message. The same message is
- used for port hot-plug as well.
-
-5. If the host specified a port `name', a sysfs attribute is
- created with the name filled in, so that udev rules can be
- written that can create a symlink from the port's name to the
- char device for port discovery by applications in the guest.
-
-6. Changes to ports' state are effected by control messages.
- Appropriate action is taken on the port indicated in the
- control message. The layout of the structure of the control
- buffer and the events associated are:
-
- struct virtio_console_control {
- le32 id; /* Port number */
- le16 event; /* The kind of control event */
- le16 value; /* Extra information for the event */
- };
-
- /* Some events for the internal messages (control packets) */
- #define VIRTIO_CONSOLE_DEVICE_READY 0
- #define VIRTIO_CONSOLE_PORT_ADD 1
- #define VIRTIO_CONSOLE_PORT_REMOVE 2
- #define VIRTIO_CONSOLE_PORT_READY 3
- #define VIRTIO_CONSOLE_CONSOLE_PORT 4
- #define VIRTIO_CONSOLE_RESIZE 5
- #define VIRTIO_CONSOLE_PORT_OPEN 6
- #define VIRTIO_CONSOLE_PORT_NAME 7
-
-2.4.3.6.1. Legacy Interface: Device Operation
-------------------------
-For legacy devices, the fields in struct virtio_console_control are the
-native endian of the guest rather than (necessarily) little-endian.
-
-
-2.4.4. Entropy Device
-====================
-
-The virtio entropy device supplies high-quality randomness for
-guest use.
-
-2.4.4.1. Device ID
------------------
- 4
-
-2.4.4.2. Virtqueues
-------------------
- 0:requestq.
-
-2.4.4.3. Feature bits
---------------------
- None currently defined
-
-2.4.4.4. Device configuration layout
------------------------------------
- None currently defined.
-
-2.4.4.5. Device Initialization
------------------------------
-
-1. The virtqueue is initialized
-
-2.4.4.6. Device Operation
-------------------------
-
-When the driver requires random bytes, it places the descriptor
-of one or more buffers in the queue. It will be completely filled
-by random data by the device.
-
-2.4.5. Memory Balloon Device
-===========================
-
-The virtio memory balloon device is a primitive device for
-managing guest memory: the device asks for a certain amount of
-memory, and the guest supplies it (or withdraws it, if the device
-has more than it asks for). This allows the guest to adapt to
-changes in allowance of underlying physical memory. If the
-feature is negotiated, the device can also be used to communicate
-guest memory statistics to the host.
-
-2.4.5.1. Device ID
------------------
- 5
-
-2.4.5.2. Virtqueues
-------------------
- 0:inflateq. 1:deflateq. 2:statsq.
-
- Virtqueue 2 only exists if VIRTIO_BALLON_F_STATS_VQ set.
-
-2.4.5.3. Feature bits
---------------------
- VIRTIO_BALLOON_F_MUST_TELL_HOST (0) Host must be told before
- pages from the balloon are used.
-
- VIRTIO_BALLOON_F_STATS_VQ (1) A virtqueue for reporting guest
- memory statistics is present.
-
-2.4.5.4. Device configuration layout
------------------------------------
- Both fields of this configuration
- are always available.
-
- struct virtio_balloon_config {
- le32 num_pages;
- le32 actual;
- };
-
-2.4.5.4.1. Legacy Interface: Device configuration layout
------------------------------------
-Note that these fields are always little endian, despite convention
-that legacy device fields are guest endian.
-
-2.4.5.5. Device Initialization
------------------------------
-
-1. The inflate and deflate virtqueues are identified.
-
-2. If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated:
-
- (a) Identify the stats virtqueue.
-
- (b) Add one empty buffer to the stats virtqueue and notify the
- host.
-
-Device operation begins immediately.
-
-2.4.5.6. Device Operation
-------------------------
-
-Memory Ballooning The device is driven by the receipt of a
-configuration change interrupt.
-
-1. The “num_pages” configuration field is examined. If this is
- greater than the “actual” number of pages, memory must be given
- to the balloon. If it is less than the “actual” number of
- pages, memory may be taken back from the balloon for general
- use.
-
-2. To supply memory to the balloon (aka. inflate):
-
- (a) The driver constructs an array of addresses of unused memory
- pages. These addresses are divided by 4096[25] and the descriptor
- describing the resulting 32-bit array is added to the inflateq.
-
-3. To remove memory from the balloon (aka. deflate):
-
- (a) The driver constructs an array of addresses of memory pages
- it has previously given to the balloon, as described above.
- This descriptor is added to the deflateq.
-
- (b) If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
- guest may not use these requested pages until that descriptor
- in the deflateq has been used by the device.
-
- (c) Otherwise, the guest may begin to re-use pages previously
- given to the balloon before the device has acknowledged their
- withdrawl. [26]
-
-4. In either case, once the device has completed the inflation or
- deflation, the “actual” field of the configuration should be
- updated to reflect the new number of pages in the balloon.[27]
-
-2.4.5.6.1. Memory Statistics
----------------------------
-
-The stats virtqueue is atypical because communication is driven
-by the device (not the driver). The channel becomes active at
-driver initialization time when the driver adds an empty buffer
-and notifies the device. A request for memory statistics proceeds
-as follows:
-
-1. The device pushes the buffer onto the used ring and sends an
- interrupt.
-
-2. The driver pops the used buffer and discards it.
-
-3. The driver collects memory statistics and writes them into a
- new buffer.
-
-4. The driver adds the buffer to the virtqueue and notifies the
- device.
-
-5. The device pops the buffer (retaining it to initiate a
- subsequent request) and consumes the statistics.
-
- Memory Statistics Format Each statistic consists of a 16 bit
- tag and a 64 bit value. All statistics are optional and the
- driver may choose which ones to supply. To guarantee backwards
- compatibility, unsupported statistics should be omitted.
-
- struct virtio_balloon_stat {
- #define VIRTIO_BALLOON_S_SWAP_IN 0
- #define VIRTIO_BALLOON_S_SWAP_OUT 1
- #define VIRTIO_BALLOON_S_MAJFLT 2
- #define VIRTIO_BALLOON_S_MINFLT 3
- #define VIRTIO_BALLOON_S_MEMFREE 4
- #define VIRTIO_BALLOON_S_MEMTOT 5
- le16 tag;
- le64 val;
- } __attribute__((packed));
-
-2.4.5.6.1.1. Legacy Interface: Memory Statistics
----------------------------
-For legacy devices, the fields in struct virtio_balloon_stat are the
-native endian of the guest rather than (necessarily) little-endian.
-
-
-2.4.5.6.2. Memory Statistics Tags
---------------------------------
-
- VIRTIO_BALLOON_S_SWAP_IN The amount of memory that has been
- swapped in (in bytes).
-
- VIRTIO_BALLOON_S_SWAP_OUT The amount of memory that has been
- swapped out to disk (in bytes).
-
- VIRTIO_BALLOON_S_MAJFLT The number of major page faults that
- have occurred.
-
- VIRTIO_BALLOON_S_MINFLT The number of minor page faults that
- have occurred.
-
- VIRTIO_BALLOON_S_MEMFREE The amount of memory not being used
- for any purpose (in bytes).
-
- VIRTIO_BALLOON_S_MEMTOT The total amount of memory available
- (in bytes).
-
-
-2.4.6. SCSI Host Device
-======================
-
-The virtio SCSI host device groups together one or more virtual
-logical units (such as disks), and allows communicating to them
-using the SCSI protocol. An instance of the device represents a
-SCSI host to which many targets and LUNs are attached.
-
-The virtio SCSI device services two kinds of requests:
-
-• command requests for a logical unit;
-
-• task management functions related to a logical unit, target or
- command.
-
-The device is also able to send out notifications about added and
-removed logical units. Together, these capabilities provide a
-SCSI transport protocol that uses virtqueues as the transfer
-medium. In the transport protocol, the virtio driver acts as the
-initiator, while the virtio SCSI host provides one or more
-targets that receive and process the requests.
-
-2.4.6.1. Device ID
------------------
- 8
-
-2.4.6.2. Virtqueues
-------------------
- 0:controlq; 1:eventq; 2..n:request queues.
-
-2.4.6.3. Feature bits
---------------------
-
- VIRTIO_SCSI_F_INOUT (0) A single request can include both
- read-only and write-only data buffers.
-
- VIRTIO_SCSI_F_HOTPLUG (1) The host should enable
- hot-plug/hot-unplug of new LUNs and targets on the SCSI bus.
-
- VIRTIO_SCSI_F_CHANGE (2) The host will report changes to LUN
- parameters via a VIRTIO_SCSI_T_PARAM_CHANGE event.
-
-2.4.6.4. Device configuration layout
------------------------------------
-
- All fields of this configuration are always available. sense_size
- and cdb_size are writable by the guest.
-
- struct virtio_scsi_config {
- le32 num_queues;
- le32 seg_max;
- le32 max_sectors;
- le32 cmd_per_lun;
- le32 event_info_size;
- le32 sense_size;
- le32 cdb_size;
- le16 max_channel;
- le16 max_target;
- le32 max_lun;
- };
-
- num_queues is the total number of request virtqueues exposed by
- the device. The driver is free to use only one request queue,
- or it can use more to achieve better performance.
-
- seg_max is the maximum number of segments that can be in a
- command. A bidirectional command can include seg_max input
- segments and seg_max output segments.
-
- max_sectors is a hint to the guest about the maximum transfer
- size it should use.
-
- cmd_per_lun is a hint to the guest about the maximum number of
- linked commands it should send to one LUN. The actual value
- to be used is the minimum of cmd_per_lun and the virtqueue
- size.
-
- event_info_size is the maximum size that the device will fill
- for buffers that the driver places in the eventq. The driver
- should always put buffers at least of this size. It is
- written by the device depending on the set of negotated
- features.
-
- sense_size is the maximum size of the sense data that the
- device will write. The default value is written by the device
- and will always be 96, but the driver can modify it. It is
- restored to the default when the device is reset.
-
- cdb_size is the maximum size of the CDB that the driver will
- write. The default value is written by the device and will
- always be 32, but the driver can likewise modify it. It is
- restored to the default when the device is reset.
-
- max_channel, max_target and max_lun can be used by the driver
- as hints to constrain scanning the logical units on the
- host.h
-
-2.4.6.4.1. Legacy Interface: Device configuration layout
------------------------------------
-For legacy devices, the fields in struct virtio_scsi_config are the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.4.6.5. Device Initialization
------------------------------
-
-The initialization routine should first of all discover the
-device's virtqueues.
-
-If the driver uses the eventq, it should then place at least a
-buffer in the eventq.
-
-The driver can immediately issue requests (for example, INQUIRY
-or REPORT LUNS) or task management functions (for example, I_T
-RESET).
-
-2.4.6.6. Device Operation
-------------------------
-
-Device operation consists of operating request queues, the control
-queue and the event queue.
-
-2.4.6.6.1. Device Operation: Request Queues
-------------------------------------------
-
-The driver queues requests to an arbitrary request queue, and
-they are used by the device on that same queue. It is the
-responsibility of the driver to ensure strict request ordering
-for commands placed on different queues, because they will be
-consumed with no order constraints.
-
-Requests have the following format:
-
- struct virtio_scsi_req_cmd {
- // Read-only
- u8 lun[8];
- le64 id;
- u8 task_attr;
- u8 prio;
- u8 crn;
- char cdb[cdb_size];
- char dataout[];
- // Write-only part
- le32 sense_len;
- le32 residual;
- le16 status_qualifier;
- u8 status;
- u8 response;
- u8 sense[sense_size];
- char datain[];
- };
-
-
- /* command-specific response values */
- #define VIRTIO_SCSI_S_OK 0
- #define VIRTIO_SCSI_S_OVERRUN 1
- #define VIRTIO_SCSI_S_ABORTED 2
- #define VIRTIO_SCSI_S_BAD_TARGET 3
- #define VIRTIO_SCSI_S_RESET 4
- #define VIRTIO_SCSI_S_BUSY 5
- #define VIRTIO_SCSI_S_TRANSPORT_FAILURE 6
- #define VIRTIO_SCSI_S_TARGET_FAILURE 7
- #define VIRTIO_SCSI_S_NEXUS_FAILURE 8
- #define VIRTIO_SCSI_S_FAILURE 9
-
- /* task_attr */
- #define VIRTIO_SCSI_S_SIMPLE 0
- #define VIRTIO_SCSI_S_ORDERED 1
- #define VIRTIO_SCSI_S_HEAD 2
- #define VIRTIO_SCSI_S_ACA 3
-
-The lun field addresses a target and logical unit in the
-virtio-scsi device's SCSI domain. The only supported format for
-the LUN field is: first byte set to 1, second byte set to target,
-third and fourth byte representing a single level LUN structure,
-followed by four zero bytes. With this representation, a
-virtio-scsi device can serve up to 256 targets and 16384 LUNs per
-target.
-
-The id field is the command identifier (“tag”).
-
-task_attr, prio and crn should be left to zero. task_attr defines
-the task attribute as in the table above, but all task attributes
-may be mapped to SIMPLE by the device; crn may also be provided
-by clients, but is generally expected to be 0. The maximum CRN
-value defined by the protocol is 255, since CRN is stored in an
-8-bit integer.
-
-All of these fields are defined in SAM. They are always
-read-only, as are the cdb and dataout field. The cdb_size is
-taken from the configuration space.
-
-sense and subsequent fields are always write-only. The sense_len
-field indicates the number of bytes actually written to the sense
-buffer. The residual field indicates the residual size,
-calculated as “data_length - number_of_transferred_bytes”, for
-read or write operations. For bidirectional commands, the
-number_of_transferred_bytes includes both read and written bytes.
-A residual field that is less than the size of datain means that
-the dataout field was processed entirely. A residual field that
-exceeds the size of datain means that the dataout field was
-processed partially and the datain field was not processed at
-all.
-
-The status byte is written by the device to be the status code as
-defined in SAM.
-
-The response byte is written by the device to be one of the
-following:
-
- VIRTIO_SCSI_S_OK when the request was completed and the status
- byte is filled with a SCSI status code (not necessarily
- "GOOD").
-
- VIRTIO_SCSI_S_OVERRUN if the content of the CDB requires
- transferring more data than is available in the data buffers.
-
- VIRTIO_SCSI_S_ABORTED if the request was cancelled due to an
- ABORT TASK or ABORT TASK SET task management function.
-
- VIRTIO_SCSI_S_BAD_TARGET if the request was never processed
- because the target indicated by the lun field does not exist.
-
- VIRTIO_SCSI_S_RESET if the request was cancelled due to a bus
- or device reset (including a task management function).
-
- VIRTIO_SCSI_S_TRANSPORT_FAILURE if the request failed due to a
- problem in the connection between the host and the target
- (severed link).
-
- VIRTIO_SCSI_S_TARGET_FAILURE if the target is suffering a
- failure and the guest should not retry on other paths.
-
- VIRTIO_SCSI_S_NEXUS_FAILURE if the nexus is suffering a failure
- but retrying on other paths might yield a different result.
-
- VIRTIO_SCSI_S_BUSY if the request failed but retrying on the
- same path should work.
-
- VIRTIO_SCSI_S_FAILURE for other host or guest error. In
- particular, if neither dataout nor datain is empty, and the
- VIRTIO_SCSI_F_INOUT feature has not been negotiated, the
- request will be immediately returned with a response equal to
- VIRTIO_SCSI_S_FAILURE.
-
-2.4.6.6.1.1. Legacy Interface: Device Operation: Request Queues
-------------------------------------------
-For legacy devices, the fields in struct virtio_scsi_req_cmd are the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.4.6.6.2. Device Operation: controlq
-------------------------------------
-
-The controlq is used for other SCSI transport operations.
-Requests have the following format:
-
- struct virtio_scsi_ctrl {
- le32 type;
- ...
- u8 response;
- };
-
- /* response values valid for all commands */
- #define VIRTIO_SCSI_S_OK 0
- #define VIRTIO_SCSI_S_BAD_TARGET 3
- #define VIRTIO_SCSI_S_BUSY 5
- #define VIRTIO_SCSI_S_TRANSPORT_FAILURE 6
- #define VIRTIO_SCSI_S_TARGET_FAILURE 7
- #define VIRTIO_SCSI_S_NEXUS_FAILURE 8
- #define VIRTIO_SCSI_S_FAILURE 9
- #define VIRTIO_SCSI_S_INCORRECT_LUN 12
-
-The type identifies the remaining fields.
-
-The following commands are defined:
-
- Task management function
- #define VIRTIO_SCSI_T_TMF 0
-
- #define VIRTIO_SCSI_T_TMF_ABORT_TASK 0
- #define VIRTIO_SCSI_T_TMF_ABORT_TASK_SET 1
- #define VIRTIO_SCSI_T_TMF_CLEAR_ACA 2
- #define VIRTIO_SCSI_T_TMF_CLEAR_TASK_SET 3
- #define VIRTIO_SCSI_T_TMF_I_T_NEXUS_RESET 4
- #define VIRTIO_SCSI_T_TMF_LOGICAL_UNIT_RESET 5
- #define VIRTIO_SCSI_T_TMF_QUERY_TASK 6
- #define VIRTIO_SCSI_T_TMF_QUERY_TASK_SET 7
-
- struct virtio_scsi_ctrl_tmf
- {
- // Read-only part
- le32 type;
- le32 subtype;
- u8 lun[8];
- le64 id;
- // Write-only part
- u8 response;
- }
-
- /* command-specific response values */
- #define VIRTIO_SCSI_S_FUNCTION_COMPLETE 0
- #define VIRTIO_SCSI_S_FUNCTION_SUCCEEDED 10
- #define VIRTIO_SCSI_S_FUNCTION_REJECTED 11
-
- The type is VIRTIO_SCSI_T_TMF; the subtype field defines. All
- fields except response are filled by the driver. The subtype
- field must always be specified and identifies the requested
- task management function.
-
- Other fields may be irrelevant for the requested TMF; if so,
- they are ignored but they should still be present. The lun
- field is in the same format specified for request queues; the
- single level LUN is ignored when the task management function
- addresses a whole I_T nexus. When relevant, the value of the id
- field is matched against the id values passed on the requestq.
-
- The outcome of the task management function is written by the
- device in the response field. The command-specific response
- values map 1-to-1 with those defined in SAM.
-
- Asynchronous notification query
-
- #define VIRTIO_SCSI_T_AN_QUERY 1
-
- struct virtio_scsi_ctrl_an {
- // Read-only part
- le32 type;
- u8 lun[8];
- le32 event_requested;
- // Write-only part
- le32 event_actual;
- u8 response;
- }
-
- #define VIRTIO_SCSI_EVT_ASYNC_OPERATIONAL_CHANGE 2
- #define VIRTIO_SCSI_EVT_ASYNC_POWER_MGMT 4
- #define VIRTIO_SCSI_EVT_ASYNC_EXTERNAL_REQUEST 8
- #define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE 16
- #define VIRTIO_SCSI_EVT_ASYNC_MULTI_HOST 32
- #define VIRTIO_SCSI_EVT_ASYNC_DEVICE_BUSY 64
-
- By sending this command, the driver asks the device which
- events the given LUN can report, as described in paragraphs 6.6
- and A.6 of the SCSI MMC specification. The driver writes the
- events it is interested in into the event_requested; the device
- responds by writing the events that it supports into
- event_actual.
-
- The type is VIRTIO_SCSI_T_AN_QUERY. The lun and event_requested
- fields are written by the driver. The event_actual and response
- fields are written by the device.
-
- No command-specific values are defined for the response byte.
-
- Asynchronous notification subscription
- #define VIRTIO_SCSI_T_AN_SUBSCRIBE 2
-
- struct virtio_scsi_ctrl_an {
- // Read-only part
- le32 type;
- u8 lun[8];
- le32 event_requested;
- // Write-only part
- le32 event_actual;
- u8 response;
- }
-
- By sending this command, the driver asks the specified LUN to
- report events for its physical interface, again as described in
- the SCSI MMC specification. The driver writes the events it is
- interested in into the event_requested; the device responds by
- writing the events that it supports into event_actual.
-
- Event types are the same as for the asynchronous notification
- query message.
-
- The type is VIRTIO_SCSI_T_AN_SUBSCRIBE. The lun and
- event_requested fields are written by the driver. The
- event_actual and response fields are written by the device.
-
- No command-specific values are defined for the response byte.
-
-2.4.6.6.2.1. Legacy Interface: Device Operation: controlq
-------------------------------------------
-
-For legacy devices, the fields in struct virtio_scsi_ctrl, struct
-virtio_scsi_ctrl_tmf, struct virtio_scsi_ctrl_an and struct
-virtio_scsi_ctrl_an are the native endian of the guest rather than
-(necessarily) little-endian.
-
-
-2.4.6.6.3. Device Operation: eventq
-----------------------------------
-
-The eventq is used by the device to report information on logical
-units that are attached to it. The driver should always leave a
-few buffers ready in the eventq. In general, the device will not
-queue events to cope with an empty eventq, and will end up
-dropping events if it finds no buffer ready. However, when
-reporting events for many LUNs (e.g. when a whole target
-disappears), the device can throttle events to avoid dropping
-them. For this reason, placing 10-15 buffers on the event queue
-should be enough.
-
-Buffers are placed in the eventq and filled by the device when
-interesting events occur. The buffers should be strictly
-write-only (device-filled) and the size of the buffers should be
-at least the value given in the device's configuration
-information.
-
-Buffers returned by the device on the eventq will be referred to
-as "events" in the rest of this section. Events have the
-following format:
-
- #define VIRTIO_SCSI_T_EVENTS_MISSED 0x80000000
-
- struct virtio_scsi_event {
- // Write-only part
- le32 event;
- u8 lun[8];
- le32 reason;
- }
-
-If bit 31 is set in the event field, the device failed to report
-an event due to missing buffers. In this case, the driver should
-poll the logical units for unit attention conditions, and/or do
-whatever form of bus scan is appropriate for the guest operating
-system.
-
-The meaning of the reason field depends on the
-contents of the event field. The following events are defined:
-
- No event
- #define VIRTIO_SCSI_T_NO_EVENT 0
-
- This event is fired in the following cases:
-
- • When the device detects in the eventq a buffer that is
- shorter than what is indicated in the configuration field, it
- might use it immediately and put this dummy value in the
- event field. A well-written driver will never observe this
- situation.
-
- • When events are dropped, the device may signal this event as
- soon as the drivers makes a buffer available, in order to
- request action from the driver. In this case, of course, this
- event will be reported with the VIRTIO_SCSI_T_EVENTS_MISSED
- flag.
-
- Transport reset
- #define VIRTIO_SCSI_T_TRANSPORT_RESET 1
-
- #define VIRTIO_SCSI_EVT_RESET_HARD 0
- #define VIRTIO_SCSI_EVT_RESET_RESCAN 1
- #define VIRTIO_SCSI_EVT_RESET_REMOVED 2
-
- By sending this event, the device signals that a logical unit
- on a target has been reset, including the case of a new device
- appearing or disappearing on the bus.The device fills in all
- fields. The event field is set to
- VIRTIO_SCSI_T_TRANSPORT_RESET. The lun field addresses a
- logical unit in the SCSI host.
-
- The reason value is one of the three #define values appearing
- above:
-
- • VIRTIO_SCSI_EVT_RESET_REMOVED (“LUN/target removed”) is used
- if the target or logical unit is no longer able to receive
- commands.
-
- • VIRTIO_SCSI_EVT_RESET_HARD (“LUN hard reset”) is used if the
- logical unit has been reset, but is still present.
-
- • VIRTIO_SCSI_EVT_RESET_RESCAN (“rescan LUN/target”) is used if
- a target or logical unit has just appeared on the device.
-
- The “removed” and “rescan” events, when sent for LUN 0, may
- apply to the entire target. After receiving them the driver
- should ask the initiator to rescan the target, in order to
- detect the case when an entire target has appeared or
- disappeared. These two events will never be reported unless the
- VIRTIO_SCSI_F_HOTPLUG feature was negotiated between the host
- and the guest.
-
- Events will also be reported via sense codes (this obviously
- does not apply to newly appeared buses or targets, since the
- application has never discovered them):
-
- • “LUN/target removed” maps to sense key ILLEGAL REQUEST, asc
- 0x25, ascq 0x00 (LOGICAL UNIT NOT SUPPORTED)
-
- • “LUN hard reset” maps to sense key UNIT ATTENTION, asc 0x29
- (POWER ON, RESET OR BUS DEVICE RESET OCCURRED)
-
- • “rescan LUN/target” maps to sense key UNIT ATTENTION, asc
- 0x3f, ascq 0x0e (REPORTED LUNS DATA HAS CHANGED)
-
- The preferred way to detect transport reset is always to use
- events, because sense codes are only seen by the driver when it
- sends a SCSI command to the logical unit or target. However, in
- case events are dropped, the initiator will still be able to
- synchronize with the actual state of the controller if the
- driver asks the initiator to rescan of the SCSI bus. During the
- rescan, the initiator will be able to observe the above sense
- codes, and it will process them as if it the driver had
- received the equivalent event.
-
- Asynchronous notification
- #define VIRTIO_SCSI_T_ASYNC_NOTIFY 2
-
- By sending this event, the device signals that an asynchronous
- event was fired from a physical interface.
-
- All fields are written by the device. The event field is set to
- VIRTIO_SCSI_T_ASYNC_NOTIFY. The lun field addresses a logical
- unit in the SCSI host. The reason field is a subset of the
- events that the driver has subscribed to via the "Asynchronous
- notification subscription" command.
-
- When dropped events are reported, the driver should poll for
- asynchronous events manually using SCSI commands.
-
- LUN parameter change
- #define VIRTIO_SCSI_T_PARAM_CHANGE 3
-
- By sending this event, the device signals that the configuration parameters
- (for example the capacity) of a logical unit have changed.
- The event field is set to VIRTIO_SCSI_T_PARAM_CHANGE.
- The lun field addresses a logical unit in the SCSI host.
-
- The same event is also reported as a unit attention condition.
- The reason field contains the additional sense code and additional sense code qualifier,
- respectively in bits 0..7 and 8..15.
- For example, a change in capacity will be reported as asc 0x2a, ascq 0x09
- (CAPACITY DATA HAS CHANGED).
-
- For MMC devices (inquiry type 5) there would be some overlap between this
- event and the asynchronous notification event.
- For simplicity, as of this version of the specification the host must
- never report this event for MMC devices.
-
-2.4.6.6.3.1. Legacy Interface: Device Operation: eventq
-----------------------------------
-For legacy devices, the fields in struct virtio_scsi_event are the
-native endian of the guest rather than (necessarily) little-endian.
-
-2.5. Reserved Feature Bits
-=========================
-
-Currently there are four device-independent feature bits defined:
-
- VIRTIO_F_RING_INDIRECT_DESC (28) Negotiating this feature indicates
- that the driver can use descriptors with the VRING_DESC_F_INDIRECT
- flag set, as described in "2.1.4.3.1. Indirect Descriptors".
-
- VIRTIO_F_RING_EVENT_IDX(29) This feature enables the used_event
- and the avail_event fields. If set, it indicates that the
- device should ignore the flags field in the available ring
- structure. Instead, the used_event field in this structure is
- used by guest to suppress device interrupts. Further, the
- driver should ignore the flags field in the used ring
- structure. Instead, the avail_event field in this structure is
- used by the device to suppress notifications. If unset, the
- driver should ignore the used_event field; the device should
- ignore the avail_event field; the flags field is used
-
- VIRTIO_F_VERSION_1(32) This feature must be offered by any device
- compliant with this specification, and acknowledged by all device
- drivers.
-
-In addition, bit 30 is used by qemu's implementation to check for experimental
-early versions of virtio which did not perform correct feature negotiation,
-and should not be used.
-
-2.5.1. Legacy Interface: Reserved Feature Bits
---------------------------------------------
-
-Legacy or transitional devices may offer the following:
-
-VIRTIO_F_NOTIFY_ON_EMPTY (24) Negotiating this feature
- indicates that the driver wants an interrupt if the device runs
- out of available descriptors on a virtqueue, even though
- interrupts are suppressed using the VRING_AVAIL_F_NO_INTERRUPT
- flag or the used_event field. An example of this is the
- networking driver: it doesn't need to know every time a packet
- is transmitted, but it does need to free the transmitted
- packets a finite time after they are transmitted. It can avoid
- using a timer if the device interrupts it when all the packets
- are transmitted.
-
-VIRTIO_F_ANY_LAYOUT (27) This feature indicates that the device
- accepts arbitrary descriptor layouts, as described in Section
- "2.1.4.2.1. Legacy Interface: Message Framing".
-
-2.6. virtio_ring.h
-=================
-
-#ifndef VIRTIO_RING_H
-#define VIRTIO_RING_H
-/* An interface for efficient virtio implementation.
- *
- * This header is BSD licensed so anyone can use the definitions
- * to implement compatible drivers/servers.
- *
- * Copyright 2007, 2009, IBM Corporation
- * Copyright 2011, Red Hat, Inc
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the distribution.
- * 3. Neither the name of IBM nor the names of its contributors
- * may be used to endorse or promote products derived from this software
- * without specific prior written permission.
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND
- * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL IBM OR CONTRIBUTORS BE LIABLE
- * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- * SUCH DAMAGE.
- */
-#include <stdint.h>
-
-/* This marks a buffer as continuing via the next field. */
-#define VRING_DESC_F_NEXT 1
-/* This marks a buffer as write-only (otherwise read-only). */
-#define VRING_DESC_F_WRITE 2
-/* This means the buffer contains a list of buffer descriptors. */
-#define VRING_DESC_F_INDIRECT 4
-
-/* The Host uses this in used->flags to advise the Guest: don't kick me
- * when you add a buffer. It's unreliable, so it's simply an
- * optimization. Guest will still kick if it's out of buffers. */
-#define VRING_USED_F_NO_NOTIFY 1
-/* The Guest uses this in avail->flags to advise the Host: don't
- * interrupt me when you consume a buffer. It's unreliable, so it's
- * simply an optimization. */
-#define VRING_AVAIL_F_NO_INTERRUPT 1
-
-/* Support for indirect descriptors */
-#define VIRTIO_RING_F_INDIRECT_DESC 28
-
-/* Support for avail_idx and used_idx fields */
-#define VIRTIO_RING_F_EVENT_IDX 29
-
-/* Arbitrary descriptor layouts. */
-#define VIRTIO_F_ANY_LAYOUT 27
-
-/* Virtio ring descriptors: 16 bytes.
- * These can chain together via "next". */
-struct vring_desc {
- /* Address (guest-physical). */
- le64 addr;
- /* Length. */
- le32 len;
- /* The flags as indicated above. */
- le16 flags;
- /* We chain unused descriptors via this, too */
- le16 next;
-};
-
-struct vring_avail {
- le16 flags;
- le16 idx;
- le16 ring[];
- /* Only if VIRTIO_RING_F_EVENT_IDX: le16 used_event; */
-};
-
-/* le32 is used here for ids for padding reasons. */
-struct vring_used_elem {
- /* Index of start of used descriptor chain. */
- le32 id;
- /* Total length of the descriptor chain which was written to. */
- le32 len;
-};
-
-struct vring_used {
- le16 flags;
- le16 idx;
- struct vring_used_elem ring[];
- /* Only if VIRTIO_RING_F_EVENT_IDX: le16 avail_event; */
-};
-
-struct vring {
- unsigned int num;
-
- struct vring_desc *desc;
- struct vring_avail *avail;
- struct vring_used *used;
-};
-
-/* The standard layout for the ring is a continuous chunk of memory which
- * looks like this. We assume num is a power of 2.
- *
- * struct vring {
- * // The actual descriptors (16 bytes each)
- * struct vring_desc desc[num];
- *
- * // A ring of available descriptor heads with free-running index.
- * le16 avail_flags;
- * le16 avail_idx;
- * le16 available[num];
- * le16 used_event_idx; // Only if VIRTIO_RING_F_EVENT_IDX
- *
- * // Padding to the next align boundary.
- * char pad[];
- *
- * // A ring of used descriptor heads with free-running index.
- * le16 used_flags;
- * le16 used_idx;
- * struct vring_used_elem used[num];
- * le16 avail_event_idx; // Only if VIRTIO_RING_F_EVENT_IDX
- * };
- * Note: for virtio PCI, align is 4096.
- */
-static inline void vring_init(struct vring *vr, unsigned int num, void *p,
- unsigned long align)
-{
- vr->num = num;
- vr->desc = p;
- vr->avail = p + num*sizeof(struct vring_desc);
- vr->used = (void *)(((unsigned long)&vr->avail->ring[num] + sizeof(le16)
- + align-1)
- & ~(align - 1));
-}
-
-static inline unsigned vring_size(unsigned int num, unsigned long align)
-{
- return ((sizeof(struct vring_desc)*num + sizeof(le16)*(3+num)
- + align - 1) & ~(align - 1))
- + sizeof(le16)*3 + sizeof(struct vring_used_elem)*num;
-}
-
-static inline int vring_need_event(uint16_t event_idx, uint16_t new_idx, uint16_t old_idx)
-{
- return (uint16_t)(new_idx - event_idx - 1) < (uint16_t)(new_idx - old_idx);
-}
-
-/* Get location of event indices (only with VIRTIO_RING_F_EVENT_IDX) */
-static inline le16 *vring_used_event(struct vring *vr)
-{
- /* For backwards compat, used event index is at *end* of avail ring. */
- return &vr->avail->ring[vr->num];
-}
-
-static inline le16 *vring_avail_event(struct vring *vr)
-{
- /* For backwards compat, avail event index is at *end* of used ring. */
- return (le16 *)&vr->used->ring[vr->num];
-}
-#endif /* VIRTIO_RING_H */
-
-
-
-2.7. Creating New Device Types
-==============================
-
-Various considerations are necessary when creating a new device
-type.
-
-2.7.1. How Many Virtqueues?
----------------------------
-
-It is possible that a very simple device will operate entirely
-through its configuration space, but most will need at least one
-virtqueue in which it will place requests. A device with both
-input and output (eg. console and network devices described here)
-need two queues: one which the driver fills with buffers to
-receive input, and one which the driver places buffers to
-transmit output.
-
-2.7.2. What Configuration Space Layout?
----------------------------------------
-
-Configuration space should only be used for initialization-time
-parameters. It is a limited resource with no synchronization between
-writable fields, so for most uses it is better to use a virtqueue to update
-configuration information (the network device does this for filtering,
-otherwise the table in the config space could potentially be very
-large).
-
-Devices must not assume that configuration fields over 32 bits wide
-are atomically writable.
-
-2.7.3. What Device Number?
---------------------------
-
-Currently device numbers are assigned quite freely: a simple
-request mail to the author of this document or the Linux
-virtualization mailing list[9] will be sufficient to secure a unique one.
-
-Meanwhile for experimental drivers, use 65535 and work backwards.
-
-2.7.4. How many MSI-X vectors? (for PCI)
------------------------------------------
-
-Using the optional MSI-X capability devices can speed up
-interrupt processing by removing the need to read ISR Status
-register by guest driver (which might be an expensive operation),
-reducing interrupt sharing between devices and queues within the
-device, and handling interrupts from multiple CPUs. However, some
-systems impose a limit (which might be as low as 256) on the
-total number of MSI-X vectors that can be allocated to all
-devices. Devices and/or device drivers should take this into
-account, limiting the number of vectors used unless the device is
-expected to cause a high volume of interrupts. Devices can
-control the number of vectors used by limiting the MSI-X Table
-Size or not presenting MSI-X capability in PCI configuration
-space. Drivers can control this by mapping events to as small
-number of vectors as possible, or disabling MSI-X capability
-altogether.
-
-2.7.5. Device Improvements
---------------------------
-
-Any change to configuration space, or new virtqueues, or
-behavioural changes, should be indicated by negotiation of a new
-feature bit. This establishes clarity[11] and avoids future expansion problems.
-
-Clusters of functionality which are always implemented together
-can use a single bit, but if one feature makes sense without the
-others they should not be gratuitously grouped together to
-conserve feature bits.
-
-
-FOOTNOTES:
-==========
-
-[1] 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.
-
-[2] The Linux implementation further separates the PCI virtio code
-from the specific virtio drivers: these drivers are shared with
-the non-PCI implementations (currently lguest and S/390).
-
-[3] The actual value within this range is ignored
-
-[6] The 4096 is based on the x86 page size, but it's also large
-enough to ensure that the separate parts of the virtqueue are on
-separate cache lines.
-
-[7] These fields are kept here because this is the only part of the
-virtqueue written by the device
-
-[9] https://lists.linux-foundation.org/mailman/listinfo/virtualization
-
-[11] Even if it does mean documenting design or implementation
-mistakes!
-
-[13] ie. VIRTIO_NET_F_HOST_TSO* and VIRTIO_NET_F_HOST_UFO are
-dependent on VIRTIO_NET_F_CSUM; a dvice which offers the offload
-features must offer the checksum feature, and a driver which
-accepts the offload features must accept the checksum feature.
-Similar logic applies to the VIRTIO_NET_F_GUEST_TSO4 features
-depending on VIRTIO_NET_F_GUEST_CSUM.
-
-[14] This is a common restriction in real, older network cards.
-
-[15] For example, a network packet transported between two guests on
-the same system may not require checksumming at all, nor segmentation,
-if both guests are amenable.
-
-[16] For example, consider a partially checksummed TCP (IPv4) packet.
-It will have a 14 byte ethernet header and 20 byte IP header
-followed by the TCP header (with the TCP checksum field 16 bytes
-into that header). csum_start will be 14+20 = 34 (the TCP
-checksum includes the header), and csum_offset will be 16. The
-value in the TCP checksum field should be initialized to the sum
-of the TCP pseudo header, so that replacing it by the ones'
-complement checksum of the TCP header and body will give the
-correct result.
-
-[17] Due to various bugs in implementations, this field is not useful
-as a guarantee of the transport header size.
-
-[18] This case is not handled by some older hardware, so is called out
-specifically in the protocol.
-
-[19] Note that the header will be two bytes longer for the
-VIRTIO_NET_F_MRG_RXBUF case.
-
-[20] Obviously each one can be split across multiple descriptor
-elements.
-
-[21] Since there are no guarentees, it can use a hash filter or
-silently switch to allmulti or promiscuous mode if it is given too
-many addresses.
-
-[23] The FLUSH and FLUSH_OUT types are equivalent, the device does not
-distinguish between them
-
-[24] Because this is high importance and low bandwidth, the current
-Linux implementation polls for the buffer to be used, rather than
-waiting for an interrupt, simplifying the implementation
-significantly. However, for generic serial ports with the
-O_NONBLOCK flag set, the polling limitation is relaxed and the
-consumed buffers are freed upon the next write or poll call or
-when a port is closed or hot-unplugged.
-
-[25] This is historical, and independent of the guest page size
-
-[26] In this case, deflation advice is merely a courtesy
-
-[27] As updates to configuration space are not atomic, this field
-isn't particularly reliable, but can be used to diagnose buggy guests.