diff options
| -rw-r--r-- | feedback/6.txt | 69 | ||||
| -rw-r--r-- | feedback/7.txt | 851 |
2 files changed, 289 insertions, 631 deletions
diff --git a/feedback/6.txt b/feedback/6.txt index 21d9583..64706f3 100644 --- a/feedback/6.txt +++ b/feedback/6.txt @@ -80,10 +80,10 @@ device" or "read-only for the driver" throughout the specification. Proposal: diff --git a/content.tex b/content.tex -index 2eb0b26..4a5e868 100644 +index 7e77740..ca155ec 100644 --- a/content.tex +++ b/content.tex -@@ -289,7 +289,7 @@ struct vring { +@@ -286,7 +286,7 @@ struct vring { struct vring_avail avail; // Padding to the next PAGE_SIZE boundary. @@ -92,7 +92,7 @@ index 2eb0b26..4a5e868 100644 // A ring of used descriptor heads with free-running index. struct vring_used used; -@@ -337,8 +337,11 @@ VIRTIO_F_ANY_LAYOUT feature is accepted. +@@ -334,8 +334,11 @@ VIRTIO_F_ANY_LAYOUT feature is accepted. The descriptor table refers to the buffers the driver is using for the device. The addresses are physical addresses, and the buffers can be chained via the next field. Each descriptor describes a @@ -106,7 +106,7 @@ index 2eb0b26..4a5e868 100644 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 -@@ -357,7 +360,7 @@ struct vring_desc { +@@ -355,7 +358,7 @@ struct vring_desc { /* This marks a buffer as continuing via the next field. */ #define VRING_DESC_F_NEXT 1 @@ -115,7 +115,7 @@ index 2eb0b26..4a5e868 100644 #define VRING_DESC_F_WRITE 2 /* This means the buffer contains a list of buffer descriptors. */ #define VRING_DESC_F_INDIRECT 4 -@@ -403,7 +406,7 @@ chained by next field. An indirect descriptor without next field +@@ -401,7 +404,7 @@ chained by next field. An indirect descriptor without next field An indirect descriptor can not refer to another indirect descriptor table (flags\&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor @@ -124,7 +124,7 @@ index 2eb0b26..4a5e868 100644 the device MUST ignore the write-only flag (flags\&VRING_DESC_F_WRITE) in the descriptor that refers to it. \subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring} -@@ -574,8 +577,8 @@ There are two parts to device operation: supplying new buffers to +@@ -575,8 +578,8 @@ 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 @@ -135,7 +135,7 @@ index 2eb0b26..4a5e868 100644 buffers are added to the receive virtqueue, and processed after they are used. -@@ -620,9 +623,9 @@ Here is a description of each stage in more detail. +@@ -621,9 +624,9 @@ Here is a description of each stage in more detail. \subsubsection{Placing Buffers Into The Descriptor Table}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Placing Buffers Into The Descriptor Table} @@ -147,7 +147,7 @@ index 2eb0b26..4a5e868 100644 algorithm maps it into the descriptor table to form a descriptor chain: -@@ -632,7 +635,7 @@ for each buffer element, b: +@@ -633,7 +636,7 @@ for each buffer element, b: \item Get the next free descriptor table entry, d \item Set d.addr to the physical address of the start of b \item Set d.len to the length of b. @@ -156,7 +156,7 @@ index 2eb0b26..4a5e868 100644 otherwise 0. \item If there is a buffer element after this: \begin{enumerate} -@@ -707,7 +710,7 @@ notification: +@@ -708,7 +711,7 @@ notification: \subsection{Receiving Used Buffers From The Device}\label{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device} @@ -165,7 +165,7 @@ index 2eb0b26..4a5e868 100644 parts of both, depending on the nature of the virtqueue and the device), it SHOULD send an interrupt, following an algorithm very similar to the algorithm used for the driver to send the device a -@@ -842,20 +845,20 @@ Common configuration structure layout is documented below: +@@ -946,20 +949,20 @@ The device MUST present at least one common configuration capability. struct virtio_pci_common_cfg { /* About the whole device. */ le32 device_feature_select; /* read-write */ @@ -190,16 +190,7 @@ index 2eb0b26..4a5e868 100644 le64 queue_desc; /* read-write */ le64 queue_avail; /* read-write */ le64 queue_used; /* read-write */ -@@ -1044,7 +1047,7 @@ 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: -+read-only for the driver: - - \begin{lstlisting} - struct virtio_pci_cap { -@@ -2342,6 +2345,13 @@ Device ID & Virtio Device \\ +@@ -2351,6 +2354,13 @@ Device ID & Virtio Device \\ \hline \end{tabular} @@ -213,7 +204,7 @@ index 2eb0b26..4a5e868 100644 \section{Network Device}\label{sec:Device Types / Network Device} The virtio network device is a virtual ethernet card, and is the -@@ -2753,7 +2763,7 @@ off. The command-specific-data is one byte containing 0 (off) or +@@ -2764,7 +2774,7 @@ off. The command-specific-data is one byte containing 0 (off) or \begin{lstlisting} struct virtio_net_ctrl_mac { le32 entries; @@ -222,7 +213,7 @@ index 2eb0b26..4a5e868 100644 }; #define VIRTIO_NET_CTRL_MAC 1 -@@ -3077,7 +3087,7 @@ struct virtio_blk_req { +@@ -3090,7 +3100,7 @@ struct virtio_blk_req { le32 type; le32 reserved; le64 sector; @@ -231,7 +222,7 @@ index 2eb0b26..4a5e868 100644 u8 status; }; \end{lstlisting} -@@ -3142,8 +3152,8 @@ struct virtio_scsi_pc_req { +@@ -3155,8 +3165,8 @@ struct virtio_scsi_pc_req { u32 type; u32 ioprio; u64 sector; @@ -242,7 +233,7 @@ index 2eb0b26..4a5e868 100644 #define SCSI_SENSE_BUFFERSIZE 96 u8 sense[SCSI_SENSE_BUFFERSIZE]; u32 errors; -@@ -3169,8 +3179,8 @@ single, separate read-only buffer; command length can be derived +@@ -3182,8 +3192,8 @@ 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) @@ -253,7 +244,7 @@ index 2eb0b26..4a5e868 100644 write can be derived from the total size of the request buffers. The sense field is only present for scsi packet command requests, -@@ -3189,12 +3199,12 @@ requests and indicates the residual size, calculated as data +@@ -3202,12 +3212,12 @@ requests and indicates the residual size, calculated as data length - number of bytes actually transferred. Historically, devices assumed that the fields type, ioprio and @@ -270,7 +261,7 @@ index 2eb0b26..4a5e868 100644 byte, by itself. -@@ -3229,7 +3239,8 @@ data and outgoing characters are placed in the transmit queue. +@@ -3242,7 +3252,8 @@ data and outgoing characters are placed in the transmit queue. \item[\ldots] \end{description} @@ -280,7 +271,7 @@ index 2eb0b26..4a5e868 100644 \subsection{Feature bits}\label{sec:Device Types / Console Device / Feature bits} -@@ -3291,7 +3302,7 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -3305,7 +3316,7 @@ native endian of the guest rather than (necessarily) little-endian. 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 device @@ -289,7 +280,7 @@ index 2eb0b26..4a5e868 100644 configuration options set for that port. \item The receiveq for each port is populated with one or more -@@ -3317,22 +3328,21 @@ when a port is closed or hot-unplugged. +@@ -3331,22 +3342,21 @@ when a port is closed or hot-unplugged. \item If the driver negotiated the VIRTIO_CONSOLE_F_SIZE feature, a configuration change interrupt may occur. The updated size can @@ -319,8 +310,8 @@ index 2eb0b26..4a5e868 100644 +control messages is: \begin{lstlisting} - struct virtio_console_control { -@@ -3340,18 +3350,45 @@ struct virtio_console_control { + /* Note: LEGACY version was not little endian! */ +@@ -3355,18 +3365,45 @@ struct virtio_console_control { le16 event; /* The kind of control event */ le16 value; /* Extra information for the event */ }; @@ -376,7 +367,7 @@ index 2eb0b26..4a5e868 100644 \subsubsection{Legacy Interface: Device Operation}\label{sec:Device Types / Console Device / Device Operation / Legacy Interface: Device Operation} For legacy devices, the fields in struct virtio_console_control are the -@@ -3600,7 +3637,7 @@ targets that receive and process the requests. +@@ -3616,7 +3653,7 @@ targets that receive and process the requests. \begin{description} \item[VIRTIO_SCSI_F_INOUT (0)] A single request can include both @@ -385,9 +376,9 @@ index 2eb0b26..4a5e868 100644 \item[VIRTIO_SCSI_F_HOTPLUG (1)] The host should enable hot-plug/hot-unplug of new LUNs and targets on the SCSI bus. -@@ -3700,22 +3737,22 @@ Requests have the following format: - +@@ -3718,22 +3755,22 @@ Requests have the following format: \begin{lstlisting} + /* Note: LEGACY version was not little endian! */ struct virtio_scsi_req_cmd { - // Read-only + // Device-readable part @@ -413,7 +404,7 @@ index 2eb0b26..4a5e868 100644 }; -@@ -3756,10 +3793,10 @@ value defined by the protocol is 255, since CRN is stored in an +@@ -3774,10 +3811,10 @@ 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 @@ -426,8 +417,8 @@ index 2eb0b26..4a5e868 100644 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 -@@ -3861,12 +3898,12 @@ The following commands are defined: - +@@ -3880,12 +3917,12 @@ The following commands are defined: + /* Note: LEGACY version was not little endian! */ struct virtio_scsi_ctrl_tmf { - // Read-only part @@ -441,7 +432,7 @@ index 2eb0b26..4a5e868 100644 u8 response; } -@@ -3898,11 +3935,11 @@ struct virtio_scsi_ctrl_tmf +@@ -3917,11 +3954,11 @@ struct virtio_scsi_ctrl_tmf #define VIRTIO_SCSI_T_AN_QUERY 1 struct virtio_scsi_ctrl_an { @@ -455,7 +446,7 @@ index 2eb0b26..4a5e868 100644 le32 event_actual; u8 response; } -@@ -3933,11 +3970,11 @@ struct virtio_scsi_ctrl_an { +@@ -3952,11 +3989,11 @@ struct virtio_scsi_ctrl_an { #define VIRTIO_SCSI_T_AN_SUBSCRIBE 2 struct virtio_scsi_ctrl_an { @@ -469,7 +460,7 @@ index 2eb0b26..4a5e868 100644 le32 event_actual; u8 response; } -@@ -3992,7 +4029,7 @@ following format: +@@ -4011,7 +4048,7 @@ following format: #define VIRTIO_SCSI_T_EVENTS_MISSED 0x80000000 struct virtio_scsi_event { diff --git a/feedback/7.txt b/feedback/7.txt index 441cfbf..a0adf9a 100644 --- a/feedback/7.txt +++ b/feedback/7.txt @@ -57,7 +57,7 @@ index 1f6fad2..671757b 100644 +% How we format a field name +\newcommand{\field}[1]{\emph{#1}} diff --git a/content.tex b/content.tex -index 37850c8..b75d77d 100644 +index 27a957d..2adc393 100644 --- a/content.tex +++ b/content.tex @@ -6,21 +6,21 @@ A virtio device is discovered and identified by a bus-specific method @@ -95,10 +95,10 @@ index 37850c8..b75d77d 100644 -can be chained via the next field. Each descriptor describes a +the device. \field{addr} is a physical address, and the buffers +can be chained via \field{next}. 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. - -@@ -375,8 +375,8 @@ Some devices benefit by concurrently dispatching a large number + buffer which is read-only for the device (``device-readable'') or write-only for the device (``device-writable''), but a chain of + descriptors can contain both device-readable and device-writable buffers. + A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT +@@ -378,8 +378,8 @@ Some devices benefit by concurrently dispatching a large number of large requests. The VIRTIO_RING_F_INDIRECT_DESC feature allows this (see \ref{sec:virtio-ring.h}~\nameref{sec:virtio-ring.h}). To increase ring capacity the driver can store a table of indirect descriptors anywhere in memory, and insert a descriptor in main @@ -109,7 +109,7 @@ index 37850c8..b75d77d 100644 refer to the indirect table address and length in bytes, respectively. -@@ -384,7 +384,7 @@ The driver MUST NOT set the VRING_DESC_F_INDIRECT flag unless the +@@ -387,7 +387,7 @@ The driver MUST NOT set the VRING_DESC_F_INDIRECT flag unless the VIRTIO_RING_F_INDIRECT_DESC feature was negotiated. The indirect table layout structure looks like this @@ -118,7 +118,7 @@ index 37850c8..b75d77d 100644 which is a variable, so this code won't compile): \begin{lstlisting} -@@ -396,13 +396,13 @@ struct indirect_descriptor_table { +@@ -399,13 +399,13 @@ struct indirect_descriptor_table { The first indirect descriptor is located at start of the indirect descriptor table (index 0), additional indirect descriptors are @@ -130,13 +130,13 @@ index 37850c8..b75d77d 100644 indirect descriptor can not refer to another indirect descriptor -table (flags\&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor +table (\field{flags}\&VRING_DESC_F_INDIRECT MUST be off). A single indirect descriptor - table can include both read-only and write-only descriptors; + table can include both device-readable and device-writable descriptors; -the device MUST ignore the write-only flag (flags\&VRING_DESC_F_WRITE) in the descriptor that refers to it. +the device MUST ignore the write-only flag (\field{flags}\&VRING_DESC_F_WRITE) in the descriptor that refers to it. \subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring} -@@ -421,21 +421,21 @@ The driver uses the available ring to offer buffers to the +@@ -424,21 +424,21 @@ The driver uses the available ring to offer buffers to the device: each ring entry refers to the head of a descriptor chain. It is only written by the driver and read by the device. @@ -144,9 +144,9 @@ index 37850c8..b75d77d 100644 +\field{idx} field indicates where the driver would put the next descriptor entry in the ring (modulo the queue size). This starts at 0, and increases. --If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, the +-If the VIRTIO_RING_F_EVENT_IDX feature bit is not negotiated, the -“flags” field offers a crude interrupt control mechanism. The driver -+If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, ++If the VIRTIO_RING_F_EVENT_IDX feature bit is not negotiated, +\field{flags} field offers a crude interrupt control mechanism. The driver MUST set this to 0 or 1: 1 indicates that the device SHOULD NOT send an interrupt when it consumes a descriptor chain from the available @@ -167,7 +167,7 @@ index 37850c8..b75d77d 100644 The driver MUST handle spurious interrupts: either form of interrupt suppression is merely an optimization; it may not suppress interrupts -@@ -466,27 +466,27 @@ struct vring_used_elem { +@@ -469,27 +469,27 @@ struct vring_used_elem { The used ring is where the device returns buffers once it is done with them: it is only written to by the device, and read by the driver. @@ -181,9 +181,9 @@ index 37850c8..b75d77d 100644 how much has been written by the device, you usually have to zero the buffer to ensure no data leakage occurs. --If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, the +-If the VIRTIO_RING_F_EVENT_IDX feature bit is not negotiated, the -“flags” field offers a crude interrupt control mechanism. The driver -+If the VIRTIO_RING_F_INDIRECT_DESC feature bit is not negotiated, ++If the VIRTIO_RING_F_EVENT_IDX feature bit is not negotiated, +\field{flags} offers a crude interrupt control mechanism. The driver MUST initialize this to 0, the device MUST set this to 0 or 1: 1 indicates that the driver SHOULD NOT send an notification when it adds @@ -204,7 +204,7 @@ index 37850c8..b75d77d 100644 1). The device MUST handle spurious notification: either form of -@@ -530,7 +530,7 @@ The driver MUST follow this sequence to initialize a device: +@@ -533,7 +533,7 @@ The driver MUST follow this sequence to initialize a device: \item\label{itm:General Initialization And Device Operation / Device Initialization / Set FEATURES-OK} Set the FEATURES_OK status bit. The driver MUST not accept new feature bits after this step. @@ -213,7 +213,7 @@ index 37850c8..b75d77d 100644 set: otherwise, the device does not support our subset of features and the device is unusable. -@@ -598,11 +598,11 @@ The driver offers buffers to one of the device's virtqueues as follows: +@@ -601,11 +601,11 @@ The driver offers buffers to one of the device's virtqueues as follows: the updated descriptor table and available ring before the next step. @@ -227,7 +227,7 @@ index 37850c8..b75d77d 100644 \item If notifications are not suppressed, the driver MUST notify the device of the new available buffers. -@@ -614,7 +614,7 @@ the ring buffer is the same size as the descriptor table, so step +@@ -617,7 +617,7 @@ 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 @@ -236,16 +236,16 @@ index 37850c8..b75d77d 100644 distinguish between a full and empty buffer. Here is a description of each stage in more detail. -@@ -631,19 +631,19 @@ for each buffer element, b: +@@ -634,19 +634,19 @@ for each buffer element, b: \begin{enumerate} \item Get the next free descriptor table entry, d -\item Set d.addr to the physical address of the start of b -\item Set d.len to the length of b. --\item If b is write-only, set d.flags to VRING_DESC_F_WRITE, +-\item If b is device-writable, set d.flags to VRING_DESC_F_WRITE, +\item Set \field{d.addr} to the physical address of the start of b +\item Set \field{d.len} to the length of b. -+\item If b is write-only, set \field{d.flags} to VRING_DESC_F_WRITE, ++\item If b is device-writable, set \field{d.flags} to VRING_DESC_F_WRITE, otherwise 0. \item If there is a buffer element after this: \begin{enumerate} @@ -262,7 +262,7 @@ index 37850c8..b75d77d 100644 descriptors, and a separate count kept to check there are enough free descriptors before beginning the mappings. -@@ -659,22 +659,22 @@ avail->ring[avail->idx % qsz] = head; +@@ -662,22 +662,22 @@ avail->ring[avail->idx % qsz] = head; \end{lstlisting} However, in general the driver can add many descriptor chains before it updates @@ -290,7 +290,7 @@ index 37850c8..b75d77d 100644 65536: \begin{lstlisting} -@@ -685,20 +685,20 @@ avail->idx += added; +@@ -688,20 +688,20 @@ avail->idx += added; The actual method of device notification is bus-specific, but generally it can be expensive. So the device MAY suppress such notifications if it @@ -318,7 +318,7 @@ index 37850c8..b75d77d 100644 giving the following algorithm for calculating whether a device needs notification: -@@ -715,21 +715,21 @@ similar to the algorithm used for the driver to send the device a +@@ -718,21 +718,21 @@ similar to the algorithm used for the driver to send the device a buffer: \begin{enumerate} @@ -345,7 +345,7 @@ index 37850c8..b75d77d 100644 at 65536 as well: \begin{lstlisting} (u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx) -@@ -738,10 +738,10 @@ buffer: +@@ -741,10 +741,10 @@ buffer: \end{enumerate} For each ring, the driver MAY then disable interrupts by writing @@ -359,7 +359,7 @@ index 37850c8..b75d77d 100644 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 -@@ -780,7 +780,7 @@ A driver MUST NOT alter descriptor table entries which have been +@@ -783,7 +783,7 @@ A driver MUST NOT alter descriptor table entries which have been exposed in the available ring (and not marked consumed by the device in the used ring) of a live virtqueue. @@ -368,187 +368,126 @@ index 37850c8..b75d77d 100644 there is no way to "unexpose" buffers). Thus a driver MUST ensure a virtqueue isn't live (by device reset) before removing exposed buffers. -@@ -809,35 +809,138 @@ All drivers MUST match devices with any Revision ID, this - is to allow devices to be versioned without breaking drivers. - - \subsubsection{Legacy Interfaces: A Note on PCI Device Discovery}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Discovery / Legacy Interfaces: A Note on PCI Device Discovery} --Transitional devices must have a Revision ID of 0 to match -+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. -+Non-transitional devices MUST have a Revision ID of 1 or higher. - --Both transitional and non-transitional drivers must match -+Both transitional and non-transitional drivers MUST match - any Revision ID value. - - \subsection{PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout} - - The device is configured via I/O and/or memory regions (though see --VIRTIO_PCI_CAP_PCI_CFG for access via the PCI configuration space). -+\ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} for access via the PCI configuration space). - --These regions 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 driver -+MUST access each field using the “natural” access method (i.e. 32-bit accesses for 32-bit fields, etc). All multi-byte fields are little-endian. +@@ -854,25 +854,25 @@ struct virtio_pci_cap { + \end{lstlisting} --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). -+\subsection{Virtio Structure PCI Capabilities}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / Virtio Structure PCI Capabilities} -+ -+The virtio device configuration layout includes a common configuration header, notification area, ISR status area and a device-specific configuration area. -+ -+Each structure can be mapped by a Base Address register (BAR) belonging to -+the function, or accessed via the special VIRTIO_PCI_CAP_PCI_CFG field in the PCI configuration space. - --PCI Device Configuration Layout includes the common configuration, --ISR, notification and device specific configuration --structures. -+The location of each structure is specified using a vendor-specific PCI capability located -+on the capability list in PCI configuration space of the device. -+This virtio structure capability uses little-endian format; all fields are -+read-only unless stated otherwise: - --All multi-byte fields are little-endian. -+\begin{lstlisting} -+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. */ -+}; -+\end{lstlisting} -+ -+This structure can be followed by extra data, depending on + This structure can be followed by extra data, depending on +-cfg_type, as documented below. The device MAY append extra data +-or padding to any structure beyond that, the device MUST accept a cap_len field +\field{cfg_type}, as documented below. The device MAY append extra data +or padding to any structure beyond that, the device MUST accept a \field{cap_len} value -+which is larger than specified here. -+ -+The fields are interpreted as follows: -+ -+\begin{description} + which is larger than specified here. + + The fields are interpreted as follows: + + \begin{description} +-\item[cap_vndr] +\item[\field{cap_vndr}] -+ 0x09; Identifies a vendor-specific capability. -+ + 0x09; Identifies a vendor-specific capability. + +-\item[cap_next] +\item[\field{cap_next}] -+ Link to next capability in the capability list in the configuration space. -+ + Link to next capability in the capability list in the configuration space. + +-\item[cap_len] +\item[\field{cap_len}] -+ Length of this capability structure, including the whole of -+ struct virtio_pci_cap, and extra data if any. -+ This length MAY include padding, or fields unused by the driver. -+ + Length of this capability structure, including the whole of + struct virtio_pci_cap, and extra data if any. + This length MAY include padding, or fields unused by the driver. + +-\item[cfg_type] +\item[\field{cfg_type}] -+ identifies the structure, according to the following table: -+ -+\begin{lstlisting} -+/* 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 -+\end{lstlisting} -+ -+ Any other value - reserved for future use. Drivers MUST -+ ignore any vendor-specific capability structure which has + identifies the structure, according to the following table: + + \begin{lstlisting} +@@ -890,7 +890,7 @@ The fields are interpreted as follows: + + Any other value - reserved for future use. Drivers MUST + ignore any vendor-specific capability structure which has +- a reserved cfg_type value. + a reserved \field{cfg_type} value. -+ -+ The device MAY offer more than one structure of any type - 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, the device would expose two + + The device MAY offer more than one structure of any type - this makes it + possible for the device to expose multiple interfaces to drivers. The order of +@@ -898,14 +898,14 @@ The fields are interpreted as follows: + 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, the device would expose two +- capabilities with cfg_type set to VIRTIO_PCI_CAP_NOTIFY_CFG: + capabilities with \field{cfg_type} set to VIRTIO_PCI_CAP_NOTIFY_CFG: -+ the first one addressing an I/O BAR, the second one addressing a memory BAR. -+ In this example, the driver SHOULD use the I/O BAR if I/O resources are available, and fall back on -+ memory BAR when I/O resources are unavailable. -+ -+ Each structure is detailed individually below. -+ + the first one addressing an I/O BAR, the second one addressing a memory BAR. + In this example, the driver SHOULD use the I/O BAR if I/O resources are available, and fall back on + memory BAR when I/O resources are unavailable. + + Each structure is detailed individually below. + +-\item[bar] +\item[\field{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 is reserved for future use. Drivers MUST -+ ignore any vendor-specific capability structure which has + 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. +@@ -914,21 +914,21 @@ The fields are interpreted as follows: + + Any other value is reserved for future use. Drivers MUST + ignore any vendor-specific capability structure which has +- a reserved bar value. + a reserved \field{bar} value. -+ + +-\item[offset] +\item[\field{offset}] -+ indicates where the structure begins relative to the base address associated -+ with the BAR. -+ + indicates where the structure begins relative to the base address associated + with the BAR. + +-\item[length] +\item[\field{length}] -+ indicates the length of the structure. -+ + indicates the length of the structure. + +- length MAY include padding, or fields unused by the driver, or + \field{length} MAY include padding, or fields unused by the driver, or -+ future extensions. -+ -+ Drivers SHOULD only map part of configuration structure -+ large enough for device operation. Drivers MUST handle + future extensions. + + Drivers SHOULD only map part of configuration structure + large enough for device operation. Drivers MUST handle +- unexpectedly large length fields, but MAY check that length + an unexpectedly large \field{length}, but MAY check that \field{length} -+ is 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. -+\end{description} + is large enough for device operation. + + For example, a future device might present a large structure size of several +@@ -941,7 +941,7 @@ The fields are interpreted as follows: \subsubsection{Common configuration structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout} --Common configuration structure layout is documented below: -+ + +-The common configuration structure is found at the bar and offset within the VIRTIO_PCI_CAP_COMMON_CFG capability; its layout is below. +The common configuration structure is found at the \field{bar} and \field{offset} within the VIRTIO_PCI_CAP_COMMON_CFG capability; its layout is below. -+ -+The device MUST present at least one common configuration capability. - \begin{lstlisting} - struct virtio_pci_common_cfg { -@@ -864,90 +967,160 @@ struct virtio_pci_common_cfg { + The device MUST present at least one common configuration capability. + +@@ -970,76 +970,76 @@ struct virtio_pci_common_cfg { \end{lstlisting} \begin{description} -\item[device_feature_select] -- The driver uses this to select which Feature Bits the device_feature field shows. +- The driver uses this to select which feature bits the device_feature field shows. +\item[\field{device_feature_select}] + The driver uses this to select which feature bits \field{device_feature} shows. Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63. -- The device MUST present 0 on device_feature for any other value. +- The device MUST present 0 on device_feature for any other value, but the driver MUST NOT rely on this. + The device MUST present 0 on \field{device_feature} for any other value, but the driver MUST NOT rely on this. -\item[device_feature] -- The device uses this to report Feature Bits to the driver. -- Device Feature Bits selected by device_feature_select. +\item[\field{device_feature}] -+ The device uses this to report which feature bits it is -+ offering to the driver: the driver writes to + The device uses this to report which feature bits it is + offering to the driver: the driver writes to +- device_feature_select to select which are presented. + \field{device_feature_select} to select which are presented. -\item[driver_feature_select] -- The driver uses this to select which Feature Bits the driver_feature field shows. +- The driver uses this to select which feature bits the driver_feature field shows. +\item[\field{driver_feature_select}] + The driver uses this to select which feature bits \field{driver_feature} shows. Value 0x0 selects Feature Bits 0 to 31, 0x1 selects Feature Bits 32 to 63. -- When set to any other value, reads from driver_feature -- return 0, writing 0 into driver_feature has no effect. The driver +- When set to any other value, the device MUST return 0 on reads from driver_feature +- return 0, and ignore writing of 0 into driver_feature. The driver - MUST not write any other value into driver_feature (a corollary of + When set to any other value, the device MUST return 0 on reads from \field{driver_feature} + return 0, and ignore writing of 0 into \field{driver_feature}. The driver @@ -611,8 +550,7 @@ index 37850c8..b75d77d 100644 +\item[\field{queue_notify_off}] The driver reads this 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. -+ Note: this is *not* an offset in bytes. See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} below. + Note: this is *not* an offset in bytes. See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} below. -\item[queue_desc] +\item[\field{queue_desc}] @@ -627,99 +565,70 @@ index 37850c8..b75d77d 100644 The driver writes the physical address of Used Ring here. \end{description} --\subsubsection{ISR status structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status structure layout} --ISR status structure includes a single 8-bit ISR status field. -+\subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} -+ -+The device MUST present at least one notification capability. -+ -+The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG -+capability. This capability is immediately followed by an additional -+field, like so: -+ -+\begin{lstlisting} -+struct virtio_pci_notify_cap { -+ struct virtio_pci_cap cap; -+ le32 notify_off_multiplier; /* Multiplier for queue_notify_off. */ -+}; -+\end{lstlisting} -+ +@@ -1058,24 +1058,24 @@ struct virtio_pci_notify_cap { + }; + \end{lstlisting} + +-The device MUST present an even cap.length of at least 2. +The device MUST present an even \field{cap.length} of at least 2. -+ + +-The device MUST present notify_off_multiplier as an even power of 2, +-or 0. The device MUST ignore a capability with notify_off_multiplier +The device MUST present \field{notify_off_multiplier} as an even power of 2, +or 0. The device MUST ignore a capability with \field{notify_off_multiplier} -+of 1. -+ + of 1. + +-notify_off_multiplier field is combined with the queue_notify_off to +\field{notify_off_multiplier} is combined with the \field{queue_notify_off} to -+derive the Queue Notify address within a BAR for a specific queue: -+ -+\begin{lstlisting} -+ cap.offset + queue_notify_off * notify_off_multiplier -+\end{lstlisting} -+ + derive the Queue Notify address within a BAR for a specific queue: + + \begin{lstlisting} + cap.offset + queue_notify_off * notify_off_multiplier + \end{lstlisting} + +-The BAR, offset and notify_off_multiplier are taken from the +-notification capability structure above, and the queue_notify_off is +The \field{bar}, \field{offset} and \field{notify_off_multiplier} are taken from the +notification capability structure above, and the \field{queue_notify_off} is -+taken from the common configuration structure. -+ -+For example, if \field{notifier_off_multiplier} is 0, all queues will use the same -+Queue Notify address. -+ -+\subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} + taken from the common configuration structure. --\subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / 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: see notify_off_multiplier below. -+The device MUST present at least one VIRTIO_PCI_CAP_ISR_CFG capability. This -+refers to at least a single byte, which contains the 8-bit ISR status field. +-For example, if notifier_off_multiplier is 0, all queues will use the same ++For example, if \field{notifier_off_multiplier} is 0, all queues will use the same + Queue Notify address. - \subsubsection{Device specific structure}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Device specific structure} + \subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability} +@@ -1107,23 +1107,23 @@ To access a device region, the driver writes into the capability + structure (ie. within the PCI configuration space) as follows: --Device specific structure is optional. -+The device MAY present at least one VIRTIO_PCI_CAP_DEVICE_CFG capability (some -+devices may not have any device specific structure). -+ -+\subsubsection{PCI configuration access capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / PCI configuration access capability} -+ -+The device MUST present at least one VIRTIO_PCI_CAP_PCI_CFG. This -+creates an alternative (and likely suboptimal) access method to the -+common configuration, notification, ISR and device-specific regions. -+ -+The capability is immediately followed by an additional field like so: -+ -+\begin{lstlisting} -+struct virtio_pci_cfg_cap { -+ struct virtio_pci_cap cap; -+ u8 pci_cfg_data[4]; /* Data for BAR access. */ -+}; -+\end{lstlisting} -+ -+To access a device region, the driver writes into the capability -+structure (ie. within the PCI configuration space) as follows: -+ -+\begin{itemize} + \begin{itemize} +-\item The driver sets the BAR to access by writing to the cap.bar field. +\item The driver sets the BAR to access by writing to \field{cap.bar}. -+ -+\item The driver sets the size of the access by writing 1, 2 or 4 to + + \item The driver sets the size of the access by writing 1, 2 or 4 to +- the cap.length field. + \field{cap.length}. -+ + +-\item The driver sets the offset within the BAR by writing to the +- cap.offset field. The driver MUST NOT write an offset which is not +- a multiple of cap.length (ie. all accesses must be aligned). +\item The driver sets the offset within the BAR by writing to + \field{cap.offset}. The driver MUST NOT write an offset which is not + a multiple of \field{cap.length} (ie. all accesses must be aligned). -+\end{itemize} -+ -+At that point, the pci_cfg_data field will provide a window of size + \end{itemize} + + At that point, the pci_cfg_data field will provide a window of size +-cap.length into the given cap.bar at offset cap.offset: writes will +\field{cap.length} into the given \field{cap.bar} at offset \field{cap.offset}: writes will -+have the same effect as writes into the BAR, and reads will have the -+same effect and return the same value as reads from the BAR. -+ -+The driver MUST perform reads/writes from/to pci_cfg_data of the same + have the same effect as writes into the BAR, and reads will have the + same effect and return the same value as reads from the BAR. + + The driver MUST perform reads/writes from/to pci_cfg_data of the same +-width as given by cap.length. +width as given by \field{cap.length}. \subsubsection{Legacy Interfaces: A Note on PCI Device Layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Legacy Interfaces: A Note on PCI Device Layout} -@@ -976,7 +1149,7 @@ When used through the legacy interface, the virtio header looks as follows: +@@ -1152,7 +1152,7 @@ When used through the legacy interface, the virtio header looks as follows: Read / Write & R & R+W & R+W & R & R+W & R+W & R+W & R \\ \hline Purpose & Device Features bits 0:31 & Driver Features bits 0:31 & @@ -728,7 +637,7 @@ index 37850c8..b75d77d 100644 Device Status & ISR \newline Status \\ \hline \end{tabularx} -@@ -990,7 +1163,7 @@ Bits & 16 & 16 \\ +@@ -1166,7 +1166,7 @@ Bits & 16 & 16 \\ \hline Read/Write & R+W & R+W \\ \hline @@ -737,7 +646,7 @@ index 37850c8..b75d77d 100644 \hline \end{tabular} -@@ -1018,7 +1191,7 @@ Legacy Interface. When used through the Legacy Interface, +@@ -1194,7 +1194,7 @@ Legacy Interface. When used through the Legacy Interface, Transitional Devices must assume that Feature Bits 32 to 63 are not acknowledged by Driver. @@ -746,199 +655,7 @@ index 37850c8..b75d77d 100644 see \ref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space}~\nameref{sec:Basic Facilities of a Virtio Device / Configuration Space / Legacy Interface: Configuration Space} for workarounds. \subsection{PCI-specific Initialization And Device Operation}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation} -@@ -1032,179 +1205,13 @@ device. - - \paragraph{Virtio Device Configuration Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection} - --As a prerequisite to device initialization, driver executes a --PCI capability list scan, detecting virtio configuration layout using Virtio -+As a prerequisite to device initialization, the driver scans the -+PCI capability list, detecting virtio configuration layout using the 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: -- --\begin{lstlisting} --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. */ --}; --\end{lstlisting} -- --This structure can optionally be 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: -- --\begin{description} --\item[cap_vndr] -- 0x09; Identifies a vendor-specific capability. -- --\item[cap_next] -- Link to next capability in the capability list in the configuration space. -- --\item[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. -- --\item[cfg_type] -- identifies the structure, according to the following table. -- --\begin{lstlisting} --/* 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 --\end{lstlisting} -- -- 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. -- --\item[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 is reserved for future use. Drivers MUST -- ignore any vendor-specific capability structure which has -- a reserved bar value. -- --\item[offset] -- indicates where the structure begins relative to the base address associated -- with the BAR. -- --\item[length] -- indicates the length of the structure. -- This size might include padding, or fields unused by the driver. -- Drivers SHOULD 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. --\end{description} -- --If cfg_type is VIRTIO_PCI_CAP_NOTIFY_CFG this structure is immediately followed --by additional fields: -- --\begin{lstlisting} --struct virtio_pci_notify_cap { -- struct virtio_pci_cap cap; -- le32 notify_off_multiplier; /* Multiplier for queue_notify_off. */ --}; --\end{lstlisting} -- --\begin{description} --\item[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! --\end{description} -- --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: -- --\begin{lstlisting} --struct virtio_pci_cfg_cap { -- __u8 pci_cfg_data[4]; /* Data for BAR access. */ --}; --\end{lstlisting} -- --\begin{description} --\item[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. --\end{description} -- - \subparagraph{Legacy Interface: A Note on Device Layout Detection}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Virtio Device Configuration Layout Detection / Legacy Interface: A Note on Device Layout Detection} - --Legacy drivers skipped Device Layout Detection step, assuming legacy -+Legacy drivers skipped the 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 -@@ -1226,7 +1233,7 @@ 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 -+MUST take the following steps to fail gracefully when a legacy - driver attempts to drive them: - - \begin{enumerate} -@@ -1239,12 +1246,11 @@ driver attempts to drive them: +@@ -1249,12 +1249,11 @@ driver attempts to drive them: \paragraph{Queue Vector Configuration}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Device Initialization / Queue Vector Configuration} When MSI-X capability is present and enabled in the device @@ -954,7 +671,7 @@ index 37850c8..b75d77d 100644 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 -@@ -1278,15 +1284,13 @@ configuration. +@@ -1288,15 +1287,13 @@ configuration. The driver does this as follows, for each virtqueue a device has: \begin{enumerate} @@ -973,7 +690,7 @@ index 37850c8..b75d77d 100644 \item Allocate and zero Descriptor Table, Available and Used rings for the virtqueue in contiguous physical memory. -@@ -1294,8 +1298,8 @@ The driver does this as follows, for each virtqueue a device has: +@@ -1304,8 +1301,8 @@ The driver does this as follows, for each virtqueue a device has: \item 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 @@ -984,28 +701,16 @@ index 37850c8..b75d77d 100644 returned; on failure, NO_VECTOR value is returned. \end{enumerate} -@@ -1305,16 +1309,16 @@ device is defined as 4096 bytes. Driver writes the physical address, divided - by 4096 to the Queue Address field\footnote{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. --}. -+}. There was no mechanism to negotiate the queue size. - - \subsubsection{Notifying The Device}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notifying The Device} - --Device notification occurs by writing the 16-bit virtqueue index --of this virtqueue to the Queue Notify field. -+The driver notifies the device by writing the 16-bit virtqueue index -+of this virtqueue to the Queue Notify address. See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} for how to calculate this address. +@@ -1324,7 +1321,7 @@ of this virtqueue to the Queue Notify address. See \ref{sec:Virtio Transport Op \subsubsection{Virtqueue Interrupts From The Device}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Virtqueue Interrupts From The Device} --If an interrupt is necessary: +-If an interrupt is necessary, the device SHOULD: +If an interrupt is necessary for a virtqueue, the device SHOULD: \begin{itemize} \item If MSI-X capability is disabled: -@@ -1327,26 +1331,27 @@ If an interrupt is necessary: +@@ -1337,10 +1334,10 @@ If an interrupt is necessary, the device SHOULD: \item If MSI-X capability is enabled: \begin{enumerate} \item Request the appropriate MSI-X interrupt message for the @@ -1014,60 +719,22 @@ index 37850c8..b75d77d 100644 number. - \item If Queue Vector field value is NO_VECTOR, no interrupt -- message is requested for this event. + \item If the vector field value is NO_VECTOR, no interrupt -+ message is requested for this event, so the device MUST NOT -+ deliver an interrupt. + message is requested for this event, so the device MUST NOT + deliver an interrupt. \end{enumerate} - \end{itemize} - --The driver interrupt handler should: -+The driver interrupt handler SHOULD: - - \begin{itemize} - \item 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 driver -- should look through the used rings of each virtqueue for the -+ SHOULD look through the used rings of all virtqueues for the - device, to see if any progress has been made by the device - which requires servicing. - - \item If MSI-X capability is enabled: look through the used rings of -- each virtqueue mapped to the specific MSI-X vector for the -+ all virtqueues mapped to the specific MSI-X vector for the - device, to see if any progress has been made by the device - which requires servicing. - \end{itemize} -@@ -1354,8 +1359,7 @@ The driver interrupt handler should: - \subsubsection{Notification of Device Configuration Changes}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / 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: -+state, as reflected in the device-specific region of the device. In this case: - - \begin{itemize} - \item If MSI-X capability is disabled: an interrupt is delivered and -@@ -1364,12 +1368,13 @@ space. In this case: - 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. -+ MUST be scanned. +@@ -1377,8 +1374,8 @@ state, as reflected in the device-specific region of the device. In this case: + MUST be scanned. \item 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. + requested. \field{config_msix_vector} sets the MSI-X Table + entry number to use. If \field{config_msix_vector} is -+ NO_VECTOR, no interrupt message is requested for this event and -+ the device MUST NOT deliver an interrupt. + NO_VECTOR, no interrupt message is requested for this event and + the device MUST NOT deliver an interrupt. \end{itemize} - - \section{Virtio Over MMIO}\label{sec:Virtio Transport Options / Virtio Over MMIO} -@@ -1414,7 +1419,7 @@ All register values are organized as Little Endian. +@@ -1425,7 +1422,7 @@ All register values are organized as Little Endian. \newcommand{\mmioreg}[5]{% Name Function Offset Direction Description @@ -1076,7 +743,7 @@ index 37850c8..b75d77d 100644 } \newcommand{\mmiodreg}[7]{% NameHigh NameLow Function OffsetHigh OffsetLow Direction Description -@@ -1463,42 +1468,42 @@ All register values are organized as Little Endian. +@@ -1474,42 +1471,42 @@ All register values are organized as Little Endian. \hline \mmioreg{DeviceFeatures}{Flags representing features the device supports}{0x010}{R}{% Reading from this register returns 32 consecutive flag bits, @@ -1138,7 +805,7 @@ index 37850c8..b75d77d 100644 number of the first queue is zero (0x0). } \hline -@@ -1506,8 +1511,8 @@ All register values are organized as Little Endian. +@@ -1517,8 +1514,8 @@ All register values are organized as Little Endian. Reading from the register returns the maximum size (number of elements) of the queue the device is ready to process or zero (0x0) if the queue is not available. This applies to the @@ -1149,7 +816,7 @@ index 37850c8..b75d77d 100644 is not zero). } \hline -@@ -1516,15 +1521,15 @@ All register values are organized as Little Endian. +@@ -1527,15 +1524,15 @@ All register values are organized as Little Endian. of the Descriptor Table and both Available and Used rings. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by @@ -1168,7 +835,7 @@ index 37850c8..b75d77d 100644 When the driver wants to stop using the queue it MUST write zero (0x0) to this register and MUST read the value back to ensure synchronisation. -@@ -1560,7 +1565,7 @@ All register values are organized as Little Endian. +@@ -1571,7 +1568,7 @@ All register values are organized as Little Endian. has been handled. When the driver finishes handling an interrupt, it MUST write a value to this register with bits corresponding to the handled @@ -1177,7 +844,7 @@ index 37850c8..b75d77d 100644 equal one (1), and all other bits cleared, ie. equal zero (0). } \hline -@@ -1570,35 +1575,35 @@ All register values are organized as Little Endian. +@@ -1581,35 +1578,35 @@ All register values are organized as Little Endian. Writing non-zero values to this register sets the status flags, indicating the driver progress. Writing zero (0x0) to this register triggers a device reset, including clearing all @@ -1224,7 +891,7 @@ index 37850c8..b75d77d 100644 is not zero). } \hline -@@ -1622,8 +1627,8 @@ All register values are organized as Little Endian. +@@ -1633,8 +1630,8 @@ All register values are organized as Little Endian. \subsubsection{Device Initialization}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization} The driver MUST start the device initialization by reading and @@ -1235,7 +902,7 @@ index 37850c8..b75d77d 100644 and if its value is zero (0x0) MUST abort initialization and MUST NOT access any other register. -@@ -1635,14 +1640,14 @@ Further initialization MUST follow the procedure described in +@@ -1646,14 +1643,14 @@ Further initialization MUST follow the procedure described in The driver MUST initialize the virtual queue in the following way: \begin{enumerate} @@ -1256,7 +923,7 @@ index 37850c8..b75d77d 100644 queue is not available. \item Allocate and zero the queue pages, making sure the memory -@@ -1652,32 +1657,33 @@ The driver MUST initialize the virtual queue in the following way: +@@ -1663,32 +1660,33 @@ The driver MUST initialize the virtual queue in the following way: the maximum size returned by the device. \item Notify the device about the queue size by writing the size to @@ -1300,7 +967,7 @@ index 37850c8..b75d77d 100644 (see the register description). After the interrupt is handled, the driver MUST acknowledge it by writing a bit mask corresponding to the handled events to the InterruptACK register. -@@ -1734,8 +1740,8 @@ nor behaviour: +@@ -1745,8 +1743,8 @@ nor behaviour: \hline \mmioreg{QueueSel}{Virtual queue index}{0x030}{W}{% Writing to this register selects the virtual queue that the @@ -1311,7 +978,7 @@ index 37850c8..b75d77d 100644 number of the first queue is zero (0x0). . } -@@ -1743,8 +1749,8 @@ nor behaviour: +@@ -1754,8 +1752,8 @@ nor behaviour: \mmioreg{QueueNumMax}{Maximum virtual queue size}{0x034}{R}{% Reading from the register returns the maximum size of the queue the device is ready to process or zero (0x0) if the queue is not @@ -1322,7 +989,7 @@ index 37850c8..b75d77d 100644 (0x0), so when the queue is not actively used. } \hline -@@ -1753,14 +1759,13 @@ nor behaviour: +@@ -1764,14 +1762,13 @@ nor behaviour: of the descriptor table and both available and used rings. Writing to this register notifies the device what size of the queue the driver will use. This applies to the queue selected by @@ -1339,7 +1006,7 @@ index 37850c8..b75d77d 100644 } \hline \mmioreg{QueuePFN}{Guest physical page number of the virtual queue}{0x040}{RW}{% -@@ -1774,7 +1779,7 @@ nor behaviour: +@@ -1785,7 +1782,7 @@ nor behaviour: 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 @@ -1348,7 +1015,7 @@ index 37850c8..b75d77d 100644 } \hline \mmioreg{QueueNotify}{Queue notifier}{0x050}{W}{} -@@ -1789,7 +1794,7 @@ nor behaviour: +@@ -1800,7 +1797,7 @@ nor behaviour: Writing non-zero values to this register sets the status flags, indicating the OS/driver progress. Writing zero (0x0) to this register triggers a device reset. This should include @@ -1357,7 +1024,7 @@ index 37850c8..b75d77d 100644 Also see \ref{sec:General Initialization And Device Operation / Device Initialization}~\nameref{sec:General Initialization And Device Operation / Device Initialization}. } \hline -@@ -1797,24 +1802,24 @@ nor behaviour: +@@ -1808,24 +1805,24 @@ nor behaviour: \hline \end{longtable} @@ -1391,7 +1058,7 @@ index 37850c8..b75d77d 100644 queue is not available. \item Allocate and zero the queue pages in contiguous virtual -@@ -1823,13 +1828,13 @@ The virtual queue is configured as follows: +@@ -1834,13 +1831,13 @@ The virtual queue is configured as follows: equal to the maximum size returned by the device. \item Notify the device about the queue size by writing the size to @@ -1408,7 +1075,7 @@ index 37850c8..b75d77d 100644 \end{enumerate} Notification mechanisms did not change. -@@ -1944,14 +1949,14 @@ struct virtio_rev_info { +@@ -1955,14 +1952,14 @@ struct virtio_rev_info { }; \end{lstlisting} @@ -1426,7 +1093,7 @@ index 37850c8..b75d77d 100644 \hline \hline 0 & 0 & <empty> & legacy interface; transitional devices only \\ \hline -@@ -1964,9 +1969,9 @@ revision & length & data & remarks \\ +@@ -1975,9 +1972,9 @@ revision & length & data & remarks \\ Note that a change in the virtio standard does not necessarily correspond to a change in the virtio-ccw revision. @@ -1439,7 +1106,7 @@ index 37850c8..b75d77d 100644 non-transitional device MUST reject revision id 0. A driver SHOULD start with trying to set the highest revision it -@@ -2015,8 +2020,8 @@ struct vq_config_block { +@@ -2026,8 +2023,8 @@ struct vq_config_block { } __attribute__ ((packed)); \end{lstlisting} @@ -1450,7 +1117,7 @@ index 37850c8..b75d77d 100644 Afterwards, CCW_CMD_SET_VQ is issued by the driver to inform the device about the location used for its queue. The transmitted -@@ -2033,10 +2038,10 @@ struct vq_info_block { +@@ -2044,10 +2041,10 @@ struct vq_info_block { } __attribute__ ((packed)); \end{lstlisting} @@ -1465,7 +1132,7 @@ index 37850c8..b75d77d 100644 \paragraph{Legacy Interface: A Note on Configuring a Virtqueue}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue / Legacy Interface: A Note on Configuring a Virtqueue} -@@ -2052,8 +2057,8 @@ struct vq_info_block_legacy { +@@ -2063,8 +2060,8 @@ struct vq_info_block_legacy { } __attribute__ ((packed)); \end{lstlisting} @@ -1476,7 +1143,7 @@ index 37850c8..b75d77d 100644 \subsubsection{Virtqueue Layout}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Virtqueue Layout} -@@ -2100,16 +2105,16 @@ struct virtio_feature_desc { +@@ -2111,16 +2108,16 @@ struct virtio_feature_desc { } __attribute__ ((packed)); \end{lstlisting} @@ -1498,7 +1165,7 @@ index 37850c8..b75d77d 100644 combination. \subsubsection{Device Configuration}\label{sec:Virtio Transport Options / Virtio over channel I/O / Device Initialization / Device Configuration} -@@ -2190,13 +2195,13 @@ struct virtio_thinint_area { +@@ -2201,13 +2198,13 @@ struct virtio_thinint_area { } __attribute__ ((packed)); \end{lstlisting} @@ -1516,7 +1183,7 @@ index 37850c8..b75d77d 100644 I/O interrupt. It may be different from the isc used by the proxy virtio-ccw device's subchannel. -@@ -2370,7 +2375,7 @@ features. +@@ -2388,7 +2385,7 @@ features. \end{description} N=0 if VIRTIO_NET_F_MQ is not negotiated, otherwise N is derived @@ -1525,7 +1192,7 @@ index 37850c8..b75d77d 100644 controlq only exists if VIRTIO_NET_F_CTRL_VQ set. -@@ -2434,9 +2439,9 @@ were required. +@@ -2452,9 +2449,9 @@ were required. \subsection{Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout} @@ -1534,15 +1201,15 @@ index 37850c8..b75d77d 100644 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 +\field{status} only exists if VIRTIO_NET_F_STATUS is set. Two - read-only bits are currently defined for the status field: + read-only bits (for the driver) are currently defined for the status field: VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE. -@@ -2445,11 +2450,11 @@ VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE. +@@ -2463,11 +2460,11 @@ VIRTIO_NET_S_LINK_UP and VIRTIO_NET_S_ANNOUNCE. #define VIRTIO_NET_S_ANNOUNCE 2 \end{lstlisting} --The following read-only field, max_virtqueue_pairs only exists if -+The following read-only field, \field{max_virtqueue_pairs} only exists if +-The following driver-read-only field, max_virtqueue_pairs only exists if ++The following driver-read-only field, \field{max_virtqueue_pairs} only exists if VIRTIO_NET_F_MQ is set. This field specifies the maximum number of each of transmit and receive virtqueues (receiveq0..receiveqN and transmitq0..transmitqN respectively; @@ -1551,7 +1218,7 @@ index 37850c8..b75d77d 100644 is negotiated. Legal values for this field are 1 to 0x8000. \begin{lstlisting} -@@ -2462,7 +2467,7 @@ struct virtio_net_config { +@@ -2480,7 +2477,7 @@ struct virtio_net_config { \end{lstlisting} \subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / Network Device / Device configuration layout / Legacy Interface: Device configuration layout} @@ -1560,7 +1227,7 @@ index 37850c8..b75d77d 100644 native endian of the guest rather than (necessarily) little-endian. -@@ -2472,10 +2477,10 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -2490,10 +2487,10 @@ native endian of the guest rather than (necessarily) little-endian. \item The initialization routine should identify the receive and transmission virtqueues, up to N+1 of each kind. If VIRTIO_NET_F_MQ feature bit is negotiated, @@ -1573,7 +1240,7 @@ index 37850c8..b75d77d 100644 network card, otherwise a private MAC address should be assigned. All drivers are expected to negotiate this feature if it is set. -@@ -2484,14 +2489,14 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -2502,14 +2499,14 @@ native endian of the guest rather than (necessarily) little-endian. identify the control virtqueue. \item If the VIRTIO_NET_F_STATUS feature bit is negotiated, the link @@ -1592,7 +1259,7 @@ index 37850c8..b75d77d 100644 number of the transmit and receive queues that is going to be used and wait until the device consumes the controlq buffer and acks this command. -@@ -2505,7 +2510,7 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -2523,7 +2520,7 @@ native endian of the guest rather than (necessarily) little-endian. “checksum offload” is a common feature on modern network cards. \item If that feature is negotiated\footnote{ie. VIRTIO_NET_F_HOST_TSO* and VIRTIO_NET_F_HOST_UFO are @@ -1601,7 +1268,7 @@ index 37850c8..b75d77d 100644 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 -@@ -2577,20 +2582,20 @@ the different features the driver negotiated. +@@ -2595,20 +2592,20 @@ the different features the driver negotiated. are set as follows. Otherwise, the packet must be fully checksummed, and flags is zero. \begin{itemize} @@ -1627,7 +1294,7 @@ index 37850c8..b75d77d 100644 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 -@@ -2598,32 +2603,32 @@ correct result. +@@ -2616,32 +2613,32 @@ correct result. \item If the driver negotiated VIRTIO_NET_F_HOST_TSO4, TSO6 or UFO, and the packet requires @@ -1666,7 +1333,7 @@ index 37850c8..b75d77d 100644 \item The header and packet are added as one output buffer to the transmitq, and the device is notified of the new entry -@@ -2676,28 +2681,28 @@ Processing packet involves: +@@ -2694,28 +2691,28 @@ Processing packet involves: \begin{enumerate} \item If the driver negotiated the VIRTIO_NET_F_MRG_RXBUF feature, @@ -1703,7 +1370,7 @@ index 37850c8..b75d77d 100644 desired MSS (see Packet Transmission point 2). \end{enumerate} -@@ -2723,9 +2728,9 @@ struct virtio_net_ctrl { +@@ -2741,9 +2738,9 @@ struct virtio_net_ctrl { #define VIRTIO_NET_ERR 1 \end{lstlisting} @@ -1716,7 +1383,7 @@ index 37850c8..b75d77d 100644 VIRTIO_NET_OK. \paragraph{Packet Receive Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Packet Receive Filtering} -@@ -2774,39 +2779,39 @@ command-specific-data is two variable length tables of 6-byte MAC +@@ -2792,39 +2789,39 @@ 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. @@ -1726,7 +1393,7 @@ index 37850c8..b75d77d 100644 address which rx filtering accepts. -When VIRTIO_NET_F_MAC_ADDR is negotiated, the mac field in +When VIRTIO_NET_F_MAC_ADDR is negotiated, \field{mac} in the - config space becomes read-only. + config space becomes read-only for the driver. The VIRTIO_NET_CTRL_MAC_ADDR_SET command is used to set the default MAC address which rx filtering -accepts @@ -1766,7 +1433,7 @@ index 37850c8..b75d77d 100644 \paragraph{VLAN Filtering}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / VLAN Filtering} -@@ -2885,7 +2890,7 @@ the number of the transmit and receive queues to be used; subsequently, +@@ -2903,7 +2900,7 @@ the number of the transmit and receive queues to be used; subsequently, transmitq0..transmitqn and receiveq0..receiveqn where n=virtqueue_pairs-1 MAY be used. All these virtqueues MUST have been pre-configured in advance. The range of legal values for the @@ -1775,7 +1442,7 @@ index 37850c8..b75d77d 100644 When multiqueue is enabled, the device MUST use automatic receive steering based on packet flow. Programming of the receive steering -@@ -2895,7 +2900,7 @@ be steered to receiveqX. For uni-directional protocols, or where +@@ -2913,7 +2910,7 @@ be steered to receiveqX. For uni-directional protocols, or where no packets have been transmitted yet, the device MAY steer a packet to a random queue out of the specified receiveq0..receiveqn. @@ -1784,7 +1451,7 @@ index 37850c8..b75d77d 100644 the default). After the command has been consumed by the device, the device MUST NOT steer new packets to virtqueues receveq1..receiveqN (i.e. other than receiveq0) and MUST NOT read from -@@ -2904,7 +2909,7 @@ the driver MUST NOT transmit new packets on virtqueues other than +@@ -2922,7 +2919,7 @@ the driver MUST NOT transmit new packets on virtqueues other than transmitq0. \subparagraph{Legacy Interface: Automatic receive steering in multiqueue mode}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Automatic receive steering in multiqueue mode / Legacy Interface: Automatic receive steering in multiqueue mode} @@ -1793,7 +1460,7 @@ index 37850c8..b75d77d 100644 native endian of the guest rather than (necessarily) little-endian. \paragraph{Offloads State Configuration}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Offloads State Configuration} -@@ -2942,7 +2947,7 @@ change of specific offload state. +@@ -2960,7 +2957,7 @@ change of specific offload state. \subparagraph{Legacy Interface: Setting Offloads State}\label{sec:Device Types / Network Device / Device Operation / Control Virtqueue / Offloads State Configuration / Setting Offloads State / Legacy Interface: Setting Offloads State} @@ -1802,7 +1469,7 @@ index 37850c8..b75d77d 100644 native endian of the guest rather than (necessarily) little-endian. -@@ -2965,17 +2970,17 @@ device except where noted. +@@ -2983,17 +2980,17 @@ device except where noted. \begin{description} \item[VIRTIO_BLK_F_SIZE_MAX (1)] Maximum size of any single segment is @@ -1825,7 +1492,7 @@ index 37850c8..b75d77d 100644 \item[VIRTIO_BLK_F_TOPOLOGY (10)] Device exports information on optimal I/O alignment. -@@ -3000,7 +3005,7 @@ VIRTIO_BLK_T_FLUSH commands. +@@ -3018,7 +3015,7 @@ VIRTIO_BLK_T_FLUSH commands. \subsubsection{Device configuration layout}\label{sec:Device Types / Block Device / Feature bits / Device configuration layout} @@ -1834,7 +1501,7 @@ index 37850c8..b75d77d 100644 present. The availability of the others all depend on various feature bits as indicated above. -@@ -3039,12 +3044,12 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -3057,12 +3054,12 @@ native endian of the guest rather than (necessarily) little-endian. \subsection{Device Initialization}\label{sec:Device Types / Block Device / Device Initialization} \begin{enumerate} @@ -1851,7 +1518,7 @@ index 37850c8..b75d77d 100644 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. -@@ -3053,16 +3058,16 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -3071,16 +3068,16 @@ native endian of the guest rather than (necessarily) little-endian. requests will fail. \item If the VIRTIO_BLK_F_TOPOLOGY feature is negotiated, the fields in the @@ -1871,7 +1538,7 @@ index 37850c8..b75d77d 100644 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 -@@ -3100,11 +3105,11 @@ distinguish between them +@@ -3118,11 +3115,11 @@ distinguish between them #define VIRTIO_BLK_T_FLUSH_OUT 5 \end{lstlisting} @@ -1885,7 +1552,7 @@ index 37850c8..b75d77d 100644 VIRTIO_BLK_S_OK for success, VIRTIO_BLK_S_IOERR for device or driver error or VIRTIO_BLK_S_UNSUPP for a request unsupported by device: -@@ -3121,7 +3126,7 @@ be committed to non-volatile storage by the device. +@@ -3139,7 +3136,7 @@ be committed to non-volatile storage by the device. For legacy devices, the fields in struct virtio_blk_req are the native endian of the guest rather than (necessarily) little-endian. @@ -1894,20 +1561,20 @@ index 37850c8..b75d77d 100644 is a hint about the relative priorities of requests to the device: higher numbers indicate more important requests. -@@ -3168,38 +3173,38 @@ does not distinguish between them: +@@ -3186,38 +3183,38 @@ does not distinguish between them: #define VIRTIO_BLK_T_SCSI_CMD_OUT 3 \end{lstlisting} -The cmd field is only present for scsi packet command requests, +The \field{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 + single, separate device-readable 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 -+fields are always read-only: \field{data} is either read-only - or write-only, depending on the request. The size of the read or +-fields are always device-readable: the data field is either device-readable ++fields are always device-readable: \field{data} is either device-readable + or device-writable, 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, @@ -1931,23 +1598,23 @@ index 37850c8..b75d77d 100644 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 +-sector reside in a single, separate device-readable 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 write-only buffer of size 1 +-separate device-writable buffer; the sense field in a separate +-device-writable buffer of size 96 bytes, by itself; the fields errors, +-data_len, sense_len and residual in a single device-writable buffer; +-and the status field is a separate device-writable buffer of size 1 +Historically, devices assumed that \field{type}, \field{ioprio} and -+\field{sector} reside in a single, separate read-only buffer; ++\field{sector} reside in a single, separate device-readable buffer; +\field{errors}, \field{data_len}, \field{sense_len} and residual reside in a single, -+separate write-only buffer; \field{sense} in a separate -+write-only buffer of size 96 bytes, by itself; \field{errors}, -+\field{data_len}, \field{sense_len} and \field{residual} in a single write-only buffer; -+and \field{status} is a separate write-only buffer of size 1 ++separate device-writable buffer; \field{sense} in a separate ++device-writable buffer of size 96 bytes, by itself; \field{errors}, ++\field{data_len}, \field{sense_len} and \field{residual} in a single device-writable buffer; ++and \field{status} is a separate device-writable buffer of size 1 byte, by itself. -@@ -3239,11 +3244,11 @@ data and outgoing characters are placed in the transmit queue. +@@ -3258,11 +3255,11 @@ only exist if VIRTIO_CONSOLE_F_MULTIPORT is set. \subsection{Feature bits}\label{sec:Device Types / Console Device / Feature bits} \begin{description} @@ -1961,7 +1628,7 @@ index 37850c8..b75d77d 100644 valid and control virtqueues will be used. \item[VIRTIO_CONSOLE_F_EMERG_WRITE (2)] Device has support for emergency write. -@@ -3279,19 +3284,19 @@ native endian of the guest rather than (necessarily) little-endian. +@@ -3298,19 +3295,19 @@ native endian of the guest rather than (necessarily) little-endian. \subsection{Device Initialization}\label{sec:Device Types / Console Device / Device Initialization} \begin{enumerate} @@ -1986,7 +1653,7 @@ index 37850c8..b75d77d 100644 of virtqueues are created. A control message indicating the driver is ready is sent to the device. The device can then send control messages for adding new ports to the device. After -@@ -3464,10 +3469,10 @@ The device is driven by the receipt of a +@@ -3509,10 +3506,10 @@ The device is driven by the receipt of a configuration change interrupt. \begin{enumerate} @@ -2001,7 +1668,7 @@ index 37850c8..b75d77d 100644 use. \item To supply memory to the balloon (aka. inflate): -@@ -3495,7 +3500,7 @@ configuration change interrupt. +@@ -3540,7 +3537,7 @@ configuration change interrupt. \end{enumerate} \item In either case, once the device has completed the inflation or @@ -2010,7 +1677,7 @@ index 37850c8..b75d77d 100644 updated to reflect the new number of pages in the balloon.\footnote{As updates to configuration space are not atomic, this field isn't particularly reliable, but can be used to diagnose buggy guests. } -@@ -3619,8 +3624,8 @@ targets that receive and process the requests. +@@ -3664,8 +3661,8 @@ targets that receive and process the requests. \subsection{Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout} @@ -2021,7 +1688,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} /* Note: LEGACY version was not little endian! */ -@@ -3639,41 +3644,41 @@ struct virtio_scsi_config { +@@ -3684,41 +3681,41 @@ struct virtio_scsi_config { \end{lstlisting} \begin{description} @@ -2075,7 +1742,7 @@ index 37850c8..b75d77d 100644 \end{description} \subsubsection{Legacy Interface: Device configuration layout}\label{sec:Device Types / SCSI Host Device / Device configuration layout / Legacy Interface: Device configuration layout} -@@ -3748,48 +3753,48 @@ struct virtio_scsi_req_cmd { +@@ -3793,48 +3790,48 @@ struct virtio_scsi_req_cmd { #define VIRTIO_SCSI_S_ACA 3 \end{lstlisting} @@ -2102,14 +1769,14 @@ index 37850c8..b75d77d 100644 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 -+read-only, as are \field{cdb} and \field{dataout}. \field{cdb_size} is +-device-readable, as are the cdb and dataout field. The cdb_size is ++device-readable, as are \field{cdb} and \field{dataout}. \field{cdb_size} is taken from the configuration space. --sense and subsequent fields are always write-only. The sense_len +-sense and subsequent fields are always device-writable. The sense_len -field indicates the number of bytes actually written to the sense -buffer. The residual field indicates the residual size, -+\field{sense} and subsequent fields are always write-only. \field{sense_len} ++\field{sense} and subsequent fields are always device-writable. \field{sense_len} +indicates the number of bytes actually written to the sense +buffer. \field{residual} indicates the residual size, calculated as “data_length - number_of_transferred_bytes”, for @@ -2140,7 +1807,7 @@ index 37850c8..b75d77d 100644 byte is filled with a SCSI status code (not necessarily "GOOD"). -@@ -3800,7 +3805,7 @@ following: +@@ -3845,7 +3842,7 @@ following: ABORT TASK or ABORT TASK SET task management function. \item[VIRTIO_SCSI_S_BAD_TARGET] if the request was never processed @@ -2149,7 +1816,7 @@ index 37850c8..b75d77d 100644 \item[VIRTIO_SCSI_S_RESET] if the request was cancelled due to a bus or device reset (including a task management function). -@@ -3819,7 +3824,7 @@ following: +@@ -3864,7 +3861,7 @@ following: same path should work. \item[VIRTIO_SCSI_S_FAILURE] for other host or driver error. In @@ -2158,7 +1825,7 @@ index 37850c8..b75d77d 100644 VIRTIO_SCSI_F_INOUT feature has not been negotiated, the request will be immediately returned with a response equal to VIRTIO_SCSI_S_FAILURE. -@@ -3852,11 +3857,12 @@ struct virtio_scsi_ctrl { +@@ -3897,11 +3894,12 @@ struct virtio_scsi_ctrl { #define VIRTIO_SCSI_S_INCORRECT_LUN 12 \end{lstlisting} @@ -2173,7 +1840,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_TMF 0 -@@ -3887,24 +3893,23 @@ struct virtio_scsi_ctrl_tmf +@@ -3932,24 +3930,23 @@ struct virtio_scsi_ctrl_tmf #define VIRTIO_SCSI_S_FUNCTION_REJECTED 11 \end{lstlisting} @@ -2206,7 +1873,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_AN_QUERY 1 -@@ -3929,17 +3934,17 @@ struct virtio_scsi_ctrl_an { +@@ -3974,17 +3971,17 @@ struct virtio_scsi_ctrl_an { 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 @@ -2230,7 +1897,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_AN_SUBSCRIBE 2 -@@ -3957,17 +3962,18 @@ struct virtio_scsi_ctrl_an { +@@ -4002,17 +3999,18 @@ struct virtio_scsi_ctrl_an { 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 @@ -2254,7 +1921,7 @@ index 37850c8..b75d77d 100644 \paragraph{Legacy Interface: Device Operation: controlq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: controlq / Legacy Interface: Device Operation: controlq} -@@ -4010,16 +4016,17 @@ struct virtio_scsi_event { +@@ -4055,16 +4053,17 @@ struct virtio_scsi_event { } \end{lstlisting} @@ -2276,7 +1943,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_NO_EVENT 0 \end{lstlisting} -@@ -4040,7 +4047,7 @@ contents of the event field. The following events are defined: +@@ -4085,7 +4084,7 @@ contents of the event field. The following events are defined: flag. \end{itemize} @@ -2285,7 +1952,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_TRANSPORT_RESET 1 -@@ -4052,24 +4059,24 @@ contents of the event field. The following events are defined: +@@ -4097,24 +4096,24 @@ contents of the event field. The following events are defined: 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 @@ -2318,7 +1985,7 @@ index 37850c8..b75d77d 100644 The “removed” and “rescan” events, when sent for LUN 0, may apply to the entire target. After receiving them the driver -@@ -4104,7 +4111,7 @@ contents of the event field. The following events are defined: +@@ -4149,7 +4148,7 @@ contents of the event field. The following events are defined: codes, and it will process them as if it the driver had received the equivalent event. @@ -2327,7 +1994,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_ASYNC_NOTIFY 2 \end{lstlisting} -@@ -4121,7 +4128,7 @@ contents of the event field. The following events are defined: +@@ -4166,7 +4165,7 @@ contents of the event field. The following events are defined: When dropped events are reported, the driver should poll for asynchronous events manually using SCSI commands. @@ -2336,7 +2003,7 @@ index 37850c8..b75d77d 100644 \begin{lstlisting} #define VIRTIO_SCSI_T_PARAM_CHANGE 3 \end{lstlisting} -@@ -4141,6 +4148,7 @@ contents of the event field. The following events are defined: +@@ -4186,6 +4185,7 @@ contents of the event field. The following events are defined: 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. @@ -2344,7 +2011,7 @@ index 37850c8..b75d77d 100644 \paragraph{Legacy Interface: Device Operation: eventq}\label{sec:Device Types / SCSI Host Device / Device Operation / Device Operation: eventq / Legacy Interface: Device Operation: eventq} For legacy devices, the fields in struct virtio_scsi_event are the -@@ -4155,16 +4163,16 @@ Currently there are four device-independent feature bits defined: +@@ -4200,16 +4200,16 @@ Currently there are four device-independent feature bits defined: that the driver can use descriptors with the VRING_DESC_F_INDIRECT flag set, as described in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}. @@ -2365,11 +2032,11 @@ index 37850c8..b75d77d 100644 - driver should ignore the used_event field; the device should - ignore the avail_event field; the flags field is used + driver should ignore \field{used_event}; the device should -+ ignore \field{avail_event} and the \field{flags} fields should be used. ++ ignore \field{avail_event} and the \field{flags} fields should be used, \item[VIRTIO_F_VERSION_1(32)] This feature must be offered by any device compliant with this specification, and acknowledged by all device -@@ -4184,7 +4192,7 @@ Legacy or transitional devices may offer the following: +@@ -4229,7 +4229,7 @@ Legacy or transitional devices may offer the following: 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 |