virtio spec 0.9.1
diff --git a/virtio.lyx b/virtio.lyx
index 448af76..74634cc 100644
--- a/virtio.lyx
+++ b/virtio.lyx
@@ -56,8 +56,6 @@
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
-\author -608949062 "Rusty Russell,,,"
-\author 1 "Michael S. Tsirkin"
\end_header
\begin_body
@@ -67,13 +65,7 @@
\begin_inset Newline newline
\end_inset
-v0.
-\change_deleted -608949062 1306978879
-8.10
-\change_inserted -608949062 1306978879
-9
-\change_unchanged
- DRAFT
+v0.9.1 DRAFT
\begin_inset Newline newline
\end_inset
@@ -81,29 +73,11 @@
\end_layout
\begin_layout Author
-Rusty Russell <rusty@rustcorp.com.au>
-\change_deleted -608949062 1306978916
-
-\begin_inset Newline newline
-\end_inset
-
-
-\change_unchanged
-IBM Corporation
-\change_inserted -608949062 1306978920
- (Editor)
-\change_unchanged
-
+Rusty Russell <rusty@rustcorp.com.au>IBM Corporation (Editor)
\end_layout
\begin_layout Date
-
-\change_deleted -608949062 1306978900
-2010 October 6.
-\change_inserted -608949062 1306978909
-2011 June 1.
-\change_unchanged
-
+2011 August 22.
\end_layout
\begin_layout Chapter
@@ -306,12 +280,12 @@
\end_layout
\begin_layout Standard
-When the driver wants to send buffers to the device, it puts them in one
- or more slots in the descriptor table, and writes the descriptor indices
- into the available ring.
+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 with the buffers, it writes the descriptors
- into the used ring, and sends an interrupt.
+ When the device has finished a buffer, it writes the descriptor into the
+ used ring, and sends an interrupt.
\end_layout
\begin_layout Chapter
@@ -992,11 +966,7 @@
\begin_layout Plain Layout
\size footnotesize
-Features
-\change_inserted 1 1304329091
- bits 0:31
-\change_unchanged
-
+Features bits 0:31
\end_layout
\end_inset
@@ -1007,11 +977,7 @@
\begin_layout Plain Layout
\size footnotesize
-Features
-\change_inserted 1 1304329086
- bits 0:31
-\change_unchanged
-
+Features bits 0:31
\end_layout
\end_inset
@@ -1093,6 +1059,18 @@
\begin_layout Standard
If MSI-X is enabled for the device, two additional fields immediately follow
this header:
+\begin_inset Foot
+status collapsed
+
+\begin_layout Plain Layout
+ie.
+ once you enable MSI-X on the device, the other fields move.
+ If you turn it off again, they move back!
+\end_layout
+
+\end_inset
+
+
\end_layout
\begin_layout Standard
@@ -1234,15 +1212,11 @@
\end_layout
\begin_layout Standard
-
-\change_inserted 1 1304328924
Finally, if feature bits (VIRTIO_F_FEATURES_HI) this is immediately followed
by two additional fields:
\end_layout
\begin_layout Standard
-
-\change_inserted 1 1304328925
\begin_inset Tabular
<lyxtabular version="3" rows="4" columns="3">
<features tabularvalignment="middle">
@@ -1254,8 +1228,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
Bits
\end_layout
@@ -1265,8 +1237,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
32
\end_layout
@@ -1276,8 +1246,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
32
\end_layout
@@ -1289,8 +1257,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
Read/Write
\end_layout
@@ -1300,8 +1266,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
R
\end_layout
@@ -1311,8 +1275,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
R+W
\end_layout
@@ -1324,8 +1286,6 @@
\begin_inset Text
\begin_layout Plain Layout
-
-\change_inserted 1 1304328925
Purpose
\end_layout
@@ -1336,8 +1296,6 @@
\begin_layout Plain Layout
-\change_inserted 1 1304328925
-
\size footnotesize
Device
\end_layout
@@ -1349,8 +1307,6 @@
\begin_layout Plain Layout
-\change_inserted 1 1304328925
-
\size footnotesize
Guest
\end_layout
@@ -1364,8 +1320,6 @@
\begin_layout Plain Layout
-\change_inserted 1 1304328925
-
\end_layout
\end_inset
@@ -1375,8 +1329,6 @@
\begin_layout Plain Layout
-\change_inserted 1 1304329099
-
\size footnotesize
Features bits 32:63
\end_layout
@@ -1388,8 +1340,6 @@
\begin_layout Plain Layout
-\change_inserted 1 1304329102
-
\size footnotesize
Features bits 32:63
\end_layout
@@ -1544,7 +1494,7 @@
\begin_inset space ~
\end_inset
-(3) Indicates that the driver is set up and ready to drive the device.
+(4) Indicates that the driver is set up and ready to drive the device.
\end_layout
\begin_layout Description
@@ -1567,10 +1517,8 @@
The least significant 31 bits of the first configuration field indicates
the features that the device supports (the high bit is reserved, and will
be used to indicate the presence of future feature bits elsewhere).
-
-\change_inserted 1 1304331636
-If more than 31 feature bits are supported, the device indicates so by setting
- feature bit 31 (see
+ If more than 31 feature bits are supported, the device indicates so by
+ setting feature bit 31 (see
\begin_inset CommandInset ref
LatexCommand ref
reference "cha:Reserved-Feature-Bits"
@@ -1578,9 +1526,7 @@
\end_inset
).
-
-\change_unchanged
-The bits are allocated as follows:
+ The bits are allocated as follows:
\end_layout
\begin_layout Description
@@ -1604,24 +1550,11 @@
\begin_inset space ~
\end_inset
-
-\change_inserted 1 1304329326
-4
-\change_deleted 1 1304329325
-3
-\change_unchanged
-0 Feature bits reserved for extensions to the queue
-\change_inserted 1 1304540448
-and feature negotiation
-\change_unchanged
-mechanism
-\change_inserted 1 1304540449
-s
+40 Feature bits reserved for extensions to the queue and feature negotiation
+ mechanisms
\end_layout
\begin_layout Description
-
-\change_inserted 1 1304329398
41
\begin_inset space ~
\end_inset
@@ -1665,19 +1598,13 @@
support, it will not see that feature bit in the Device Features field
and can go into backwards compatibility mode (or, for poor implementations,
set the FAILED Device Status bit).
-\change_inserted 1 1304329423
-
\end_layout
\begin_layout Standard
-
-\change_inserted 1 1304331742
Access to feature bits 32 to 63 is enabled by Guest by setting feature bit
31.
If this bit is unset, Device must assume that all feature bits > 31 are
unset.
-\change_unchanged
-
\end_layout
\begin_layout Subsubsection
@@ -2162,9 +2089,7 @@
field is currently 0 or 1: 1 indicating that we do not need an interrupt
when the device consumes a descriptor from the available ring.
-
-\change_inserted 1 1306923367
-Alternatively, the guest can ask the device to delay interrupts until an
+ Alternatively, the guest can ask the device to delay interrupts until an
entry with an index specified by the
\begin_inset Quotes eld
\end_inset
@@ -2191,9 +2116,7 @@
\end_inset
).
-
-\change_unchanged
-This interrupt suppression is merely an optimization; it may not suppress
+ This interrupt suppression is merely an optimization; it may not suppress
interrupts entirely.
\end_layout
@@ -2242,17 +2165,11 @@
\begin_layout Plain Layout
u16 ring[qsz]; /* qsz is the Queue Size field read from device */
-\change_inserted 1 1304329945
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304329957
-
u16 used_event;
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
@@ -2276,9 +2193,7 @@
\emph on
available
\emph default
- ring
-\change_inserted 1 1304540575
-.
+ ring.
Alternatively, the
\begin_inset Quotes eld
\end_inset
@@ -2305,11 +2220,7 @@
avail_event + 1
\emph default
).
-
-\change_unchanged
-
-\change_inserted 1 1304540614
-The method employed by the device is controlled by the guest through the
+ The method employed by the device is controlled by the guest through the
VIRTIO_RING_F_EVENT_IDX feature bit (see
\begin_inset CommandInset ref
LatexCommand ref
@@ -2319,27 +2230,16 @@
).
-\change_deleted 1 1304331235
-(the flag is kept here because this is the only part of the virtqueue written
- by the device)
-\change_inserted 1 1304540560
-
\begin_inset Foot
status open
\begin_layout Plain Layout
-
-\change_inserted 1 1304331235
These fields are kept here because this is the only part of the virtqueue
written by the device
-\change_unchanged
-
\end_layout
\end_inset
-
-\change_unchanged
.
\end_layout
@@ -2422,17 +2322,11 @@
\begin_layout Plain Layout
struct vring_used_elem ring[qsz];
-\change_inserted 1 1304330369
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304330380
-
u16 avail_event;
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
@@ -2452,13 +2346,9 @@
\begin_layout Standard
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
-\change_inserted 1 1304342159
-and Red Hat
-\change_unchanged
-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 Appendix A.
+ 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 Appendix A.
\end_layout
\begin_layout Section
@@ -2765,27 +2655,17 @@
\emph default
checking the suppression flag: 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
-\change_inserted 1 1304336099
- or the avail_event field
-\change_unchanged
-.
+ So again, we use a memory barrier here before reading the flags or the
+ avail_event field.
\end_layout
\begin_layout Standard
-If
-\change_inserted 1 1304336234
-the VIRTIO_F_RING_EVENT_IDX feature is not negotiated, and if
-\change_unchanged
-the VRING_USED_F_NOTIFY flag is not set, we go ahead and write to the PCI
- configuration space.
-\change_inserted 1 1304336255
-
+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 write to the PCI configuration
+ space.
\end_layout
\begin_layout Standard
-
-\change_inserted 1 1304336617
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
@@ -2802,24 +2682,18 @@
\end_layout
\begin_layout Standard
-
-\change_inserted 1 1304336524
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
-\change_inserted 1 1304336569
-
(u16)(new_idx - avail_event - 1) < (u16)(new_idx - old_idx)
\end_layout
\end_inset
-\change_unchanged
-
\end_layout
\begin_layout Subsection
@@ -2848,30 +2722,17 @@
\end_layout
\begin_layout Enumerate
-
-\change_inserted 1 1304336736
Determine whether an interrupt is necessary:
\end_layout
\begin_deeper
\begin_layout Enumerate
-
-\change_inserted 1 1306923440
-If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated: check if
-\change_deleted 1 1304336781
-I
-\change_unchanged
-f the VRING_AVAIL_F_NO_INTERRUPT flag is not set in avail\SpecialChar \nobreakdash-
+If the VIRTIO_F_RING_EVENT_IDX feature is not negotiated: check if f the
+ VRING_AVAIL_F_NO_INTERRUPT flag is not set in avail\SpecialChar \nobreakdash-
>flags
-\change_inserted 1 1304336788
-
\end_layout
\begin_layout Enumerate
-
-\change_deleted 1 1304336785
-:
-\change_inserted 1 1306923443
If the VIRTIO_F_RING_EVENT_IDX feature is negotiated: check whether the
used index crossed the
\emph on
@@ -2889,25 +2750,17 @@
\begin_layout Plain Layout
-\change_inserted 1 1304336902
-
(u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx)
\end_layout
\end_inset
-\change_unchanged
-
\end_layout
\end_deeper
\begin_layout Enumerate
-
-\change_inserted 1 1304336714
If an interrupt is necessary:
-\change_unchanged
-
\end_layout
\begin_deeper
@@ -2962,8 +2815,6 @@
\end_layout
\begin_layout Standard
-
-\change_inserted 1 1306923408
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
@@ -2981,68 +2832,42 @@
\begin_layout Plain Layout
-\change_inserted 1 1304342051
-
vring_disable_interrupts(vq);
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341878
-
for (;;) {
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341880
-
- if
-\change_deleted 1 1304341882
-while
-\change_unchanged
-(vq->last_seen_used != vring->used.idx) {
-\change_inserted 1 1304341888
-
+ if (vq->last_seen_used != vring->used.idx) {
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304342047
-
vring_enable_interrupts(vq);
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341986
-
mb();
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341964
-
if (vq->last_seen_used != vring->used.idx)
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341974
-
break;
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341887
-
}
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
@@ -3294,14 +3119,10 @@
\begin_layout Plain Layout
* Copyright 2007, 2009, IBM Corporation
-\change_inserted 1 1304341032
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341075
-
* Copyright 2011, Red Hat, Inc
\end_layout
@@ -3601,17 +3422,11 @@
\begin_layout Plain Layout
uint16_t ring[];
-\change_inserted 1 1304340808
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304340816
-
uint16_t used_event;
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
@@ -3683,17 +3498,11 @@
\begin_layout Plain Layout
struct vring_used_elem ring[];
-\change_inserted 1 1304340824
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304340831
-
uint16_t avail_event;
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
@@ -3831,13 +3640,7 @@
\begin_layout Plain Layout
- * __u16
-\change_inserted 1 1306923408
-EVENT_IDX
-\change_deleted 1 1306923408
-used_idx
-\change_unchanged
-;
+ * __u16 EVENT_IDX;
\end_layout
\begin_layout Plain Layout
@@ -3936,58 +3739,38 @@
\begin_layout Plain Layout
- + sizeof(uint16_t)*
-\change_deleted 1 1304340844
-2
-\change_inserted 1 1304340844
-3
-\change_unchanged
- + sizeof(struct vring_used_elem)*num;
+ + sizeof(uint16_t)*3 + sizeof(struct vring_used_elem)*num;
\end_layout
\begin_layout Plain Layout
}
-\change_inserted 1 1304340918
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304340918
-
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304340987
-
static inline int vring_need_event(uint16_t event_idx, uint16_t new_idx,
uint16_t old_idx)
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304340944
-
{
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304341001
-
return (uint16_t)(new_idx - event_idx - 1) < (uint16_t)(new_idx
- old_idx);
\end_layout
\begin_layout Plain Layout
-\change_inserted 1 1304340938
-
}
-\change_unchanged
-
\end_layout
\begin_layout Plain Layout
@@ -4011,13 +3794,7 @@
\end_layout
\begin_layout Standard
-Currently there are
-\change_inserted 1 1306923235
-five
-\change_deleted 1 1304330657
-three
-\change_unchanged
- device-independent feature bits defined:
+Currently there are five device-independent feature bits defined:
\end_layout
\begin_layout Description
@@ -4027,11 +3804,8 @@
(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
-\change_inserted 1 1304341161
- or the used_event field
-\change_unchanged
-.
+ 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.
@@ -4056,8 +3830,6 @@
\end_layout
\begin_layout Description
-
-\change_inserted 1 1306923206
VIRTIO_F_RING_EVENT_IDX(29) This feature enables the
\emph on
used_event
@@ -4116,13 +3888,9 @@
\end_inset
-\change_inserted 1 1304330854
-
\end_layout
\begin_layout Description
-
-\change_inserted 1 1304330961
VIRTIO_F_FEATURES_HIGH(31) This feature indicates that the device supports
feature bits 32:63.
If unset, feature bits 32:63 are unset.
@@ -4461,9 +4229,25 @@
\end_layout
\begin_layout Enumerate
-If that feature is negotiated, 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.
+If that feature is negotiated
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+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.
+\end_layout
+
+\end_inset
+
+, 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.
@@ -4655,9 +4439,9 @@
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 will be 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.
+ 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.
\end_layout
\end_inset
@@ -4708,7 +4492,7 @@
\end_layout
\begin_layout Itemize
-gso_size is the size of the packet beyond that header (ie.
+gso_size is the maximum size of each packet beyond that header (ie.
MSS).
\end_layout
@@ -5324,14 +5108,6 @@
VIRTIO_BLK_F_FLUSH (9) Cache flush command support.
\end_layout
-\begin_layout Description
-VIRTIO_BLK_F_SECTOR_MAX
-\begin_inset space ~
-\end_inset
-
-(10) Maximum total sectors in an I/O.
-\end_layout
-
\end_deeper
\begin_layout Description
Device
@@ -5403,7 +5179,6 @@
\begin_layout Plain Layout
- u32 sectors_max;
\end_layout
\begin_layout Plain Layout
@@ -5445,12 +5220,6 @@
will fail.
\end_layout
-\begin_layout Enumerate
-If the VIRTIO_BLK_F_SECTOR_MAX feature is negotiated, the sectors_max field
- should be read to determine the maximum I/O size for the driver to use.
- No requests should be submitted which go beyond this limit.
-\end_layout
-
\begin_layout Section*
Device Operation
\end_layout
@@ -6300,13 +6069,7 @@
\begin_layout Plain Layout
-struct virtio_
-\change_inserted -608949062 1305437680
-balloon
-\change_deleted -608949062 1305437671
-console
-\change_unchanged
-_config {
+struct virtio_balloon_config {
\end_layout
\begin_layout Plain Layout
