[PATCH v8 01/16] content: move 1.0 queue format out to a separate section

[PATCH v8 01/16] content: move 1.0 queue format out to a separate section

[Michael S. Tsirkin]

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
 content.tex | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/content.tex b/content.tex
index c7ef7fd..4483a4b 100644
--- a/content.tex
+++ b/content.tex
@@ -230,7 +230,30 @@ result.
 The mechanism for bulk data transport on virtio devices is
 pretentiously called a virtqueue. Each device can have zero or more
 virtqueues\footnote{For example, the simplest network device has one virtqueue for
-transmit and one for receive.}.  Each queue has a 16-bit queue size
+transmit and one for receive.}.
+
+Driver makes requests available to device by adding
+an available buffer to the queue - i.e. adding a buffer
+describing the request to a virtqueue, and optionally triggering
+a driver event - i.e. sending a notification to the device.
+
+Device executes the requests and - when complete - adds
+a used buffer to the queue - i.e. lets the driver
+know by marking the buffer as used. Device can then trigger
+a device event - i.e. send an interrupt to the driver.
+
+For queue operation detail, see \ref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}.
+
+\section{Split Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Split Virtqueues}
+The split virtqueue format is the original format used by legacy
+virtio devices.  The split virtqueue format separates the
+virtqueue into several parts, where each part is write-able by
+either the driver or the device, but not both. Multiple
+locations need to be updated when making a buffer available
+and when marking it as used.
+
+
+Each queue has a 16-bit queue size
 parameter, which sets the number of entries and implies the total size
 of the queue.
 
-- 
MST

[PATCH v8 02/16] content: move ring text out to a separate file

[Michael S. Tsirkin]

Will be easier to manage this way.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
 content.tex    | 499 +--------------------------------------------------------
 split-ring.tex | 498 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 499 insertions(+), 498 deletions(-)
 create mode 100644 split-ring.tex

diff --git a/content.tex b/content.tex
index 4483a4b..5b4c4e9 100644
--- a/content.tex
+++ b/content.tex
@@ -244,504 +244,7 @@ a device event - i.e. send an interrupt to the driver.
 
 For queue operation detail, see \ref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}.
 
-\section{Split Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Split Virtqueues}
-The split virtqueue format is the original format used by legacy
-virtio devices.  The split virtqueue format separates the
-virtqueue into several parts, where each part is write-able by
-either the driver or the device, but not both. Multiple
-locations need to be updated when making a buffer available
-and when marking it as used.
-
-
-Each queue has a 16-bit queue size
-parameter, which sets the number of entries and implies the total size
-of the queue.
-
-Each virtqueue consists of three parts:
-
-\begin{itemize}
-\item Descriptor Table
-\item Available Ring
-\item Used Ring
-\end{itemize}
-
-where each part is physically-contiguous in guest memory,
-and has different alignment requirements.
-
-The memory aligment and size requirements, in bytes, of each part of the
-virtqueue are summarized in the following table:
-
-\begin{tabular}{|l|l|l|}
-\hline
-Virtqueue Part    & Alignment & Size \\
-\hline \hline
-Descriptor Table  & 16        & $16 * $(Queue Size) \\
-\hline
-Available Ring    & 2         & $6 + 2 * $(Queue Size) \\
- \hline
-Used Ring         & 4         & $6 + 8 * $(Queue Size) \\
- \hline
-\end{tabular}
-
-The Alignment column gives the minimum alignment for each part
-of the virtqueue.
-
-The Size column gives the total number of bytes for each
-part of the virtqueue.
-
-Queue Size corresponds to the maximum number of buffers in the
-virtqueue\footnote{For example, if Queue Size is 4 then at most 4 buffers
-can be queued at any given time.}.  Queue Size value is always a
-power of 2.  The maximum Queue Size value is 32768.  This value
-is specified in a bus-specific way.
-
-When the driver wants to send a buffer to the device, it fills in
-a slot in the descriptor table (or chains several together), and
-writes the descriptor index into the available ring.  It then
-notifies the device. When the device has finished a buffer, it
-writes the descriptor index into the used ring, and sends an interrupt.
-
-\drivernormative{\subsection}{Virtqueues}{Basic Facilities of a Virtio Device / Virtqueues}
-The driver MUST ensure that the physical address of the first byte
-of each virtqueue part is a multiple of the specified alignment value
-in the above table.
-
-\subsection{Legacy Interfaces: A Note on Virtqueue Layout}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}
-
-For Legacy Interfaces, several additional
-restrictions are placed on the virtqueue layout:
-
-Each virtqueue occupies two or more physically-contiguous pages
-(usually defined as 4096 bytes, but depending on the transport;
-henceforth referred to as Queue Align)
-and consists of three parts:
-
-\begin{tabular}{|l|l|l|}
-\hline
-Descriptor Table & Available Ring (\ldots padding\ldots) & Used Ring \\
-\hline
-\end{tabular}
-
-The bus-specific Queue Size field controls the total number of bytes
-for the virtqueue.
-When using the legacy interface, the transitional
-driver MUST retrieve the Queue Size field from the device
-and MUST allocate the total number of bytes for the virtqueue
-according to the following formula (Queue Align given in qalign and
-Queue Size given in qsz):
-
-\begin{lstlisting}
-#define ALIGN(x) (((x) + qalign) & ~qalign)
-static inline unsigned virtq_size(unsigned int qsz)
-{
-     return ALIGN(sizeof(struct virtq_desc)*qsz + sizeof(u16)*(3 + qsz))
-          + ALIGN(sizeof(u16)*3 + sizeof(struct virtq_used_elem)*qsz);
-}
-\end{lstlisting}
-
-This wastes some space with padding.
-When using the legacy interface, both transitional
-devices and drivers MUST use the following virtqueue layout
-structure to locate elements of the virtqueue:
-
-\begin{lstlisting}
-struct virtq {
-        // The actual descriptors (16 bytes each)
-        struct virtq_desc desc[ Queue Size ];
-
-        // A ring of available descriptor heads with free-running index.
-        struct virtq_avail avail;
-
-        // Padding to the next Queue Align boundary.
-        u8 pad[ Padding ];
-
-        // A ring of used descriptor heads with free-running index.
-        struct virtq_used used;
-};
-\end{lstlisting}
-
-\subsection{Legacy Interfaces: A Note on Virtqueue Endianness}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Endianness}
-
-Note that when using the legacy interface, transitional
-devices and drivers MUST use the native
-endian of the guest as the endian of fields and in the virtqueue.
-This is opposed to little-endian for non-legacy interface as
-specified by this standard.
-It is assumed that the host is already aware of the guest endian.
-
-\subsection{Message Framing}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing}
-The framing of messages with descriptors is
-independent of the contents of the buffers. For example, a network
-transmit buffer consists of a 12 byte header followed by the network
-packet. This could be most simply placed in the descriptor table as a
-12 byte output descriptor followed by a 1514 byte output descriptor,
-but it could also consist of a single 1526 byte output descriptor in
-the case where the header and packet are adjacent, or even three or
-more descriptors (possibly with loss of efficiency in that case).
-
-Note that, some device implementations have large-but-reasonable
-restrictions on total descriptor size (such as based on IOV_MAX in the
-host OS). This has not been a problem in practice: little sympathy
-will be given to drivers which create unreasonably-sized descriptors
-such as by dividing a network packet into 1500 single-byte
-descriptors!
-
-\devicenormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing}
-The device MUST NOT make assumptions about the particular arrangement
-of descriptors.  The device MAY have a reasonable limit of descriptors
-it will allow in a chain.
-
-\drivernormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing}
-The driver MUST place any device-writable descriptor elements after
-any device-readable descriptor elements.
-
-The driver SHOULD NOT use an excessive number of descriptors to
-describe a buffer.
-
-\subsubsection{Legacy Interface: Message Framing}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing / Legacy Interface: Message Framing}
-
-Regrettably, initial driver implementations used simple layouts, and
-devices came to rely on it, despite this specification wording.  In
-addition, the specification for virtio_blk SCSI commands required
-intuiting field lengths from frame boundaries (see
- \ref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}~\nameref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation})
-
-Thus when using the legacy interface, the VIRTIO_F_ANY_LAYOUT
-feature indicates to both the device and the driver that no
-assumptions were made about framing.  Requirements for
-transitional drivers when this is not negotiated are included in
-each device section.
-
-\subsection{The Virtqueue Descriptor Table}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
-
-The descriptor table refers to the buffers the driver is using for
-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 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.
-
-The actual contents of the memory offered to the device depends on the
-device type.  Most common is to begin the data with a header
-(containing little-endian fields) for the device to read, and postfix
-it with a status tailer for the device to write.
-
-\begin{lstlisting}
-struct virtq_desc {
-        /* Address (guest-physical). */
-        le64 addr;
-        /* Length. */
-        le32 len;
-
-/* This marks a buffer as continuing via the next field. */
-#define VIRTQ_DESC_F_NEXT   1
-/* This marks a buffer as device write-only (otherwise device read-only). */
-#define VIRTQ_DESC_F_WRITE     2
-/* This means the buffer contains a list of buffer descriptors. */
-#define VIRTQ_DESC_F_INDIRECT   4
-        /* The flags as indicated above. */
-        le16 flags;
-        /* Next field if flags & NEXT */
-        le16 next;
-};
-\end{lstlisting}
-
-The number of descriptors in the table is defined by the queue size
-for this virtqueue: this is the maximum possible descriptor chain length.
-
-\begin{note}
-The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
-referred to this structure as vring_desc, and the constants as
-VRING_DESC_F_NEXT, etc, but the layout and values were identical.
-\end{note}
-
-\devicenormative{\subsubsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
-A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
-read a device-writable buffer (it MAY do so for debugging or diagnostic
-purposes).
-
-\drivernormative{\subsubsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
-Drivers MUST NOT add a descriptor chain over than $2^{32}$ bytes long in total;
-this implies that loops in the descriptor chain are forbidden!
-
-\subsubsection{Indirect Descriptors}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
-
-Some devices benefit by concurrently dispatching a large number
-of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this (see \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}). To increase
-ring capacity the driver can store a table of indirect
-descriptors anywhere in memory, and insert a descriptor in main
-virtqueue (with \field{flags}\&VIRTQ_DESC_F_INDIRECT on) that refers to memory buffer
-containing this indirect descriptor table; \field{addr} and \field{len}
-refer to the indirect table address and length in bytes,
-respectively.
-
-The indirect table layout structure looks like this
-(\field{len} is the length of the descriptor that refers to this table,
-which is a variable, so this code won't compile):
-
-\begin{lstlisting}
-struct indirect_descriptor_table {
-        /* The actual descriptors (16 bytes each) */
-        struct virtq_desc desc[len / 16];
-};
-\end{lstlisting}
-
-The first indirect descriptor is located at start of the indirect
-descriptor table (index 0), additional indirect descriptors are
-chained by \field{next}. An indirect descriptor without a valid \field{next}
-(with \field{flags}\&VIRTQ_DESC_F_NEXT off) signals the end of the descriptor.
-A single indirect descriptor
-table can include both device-readable and device-writable descriptors.
-
-\drivernormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
-The driver MUST NOT set the VIRTQ_DESC_F_INDIRECT flag unless the
-VIRTIO_F_INDIRECT_DESC feature was negotiated.   The driver MUST NOT
-set the VIRTQ_DESC_F_INDIRECT flag within an indirect descriptor (ie. only
-one table per descriptor).
-
-A driver MUST NOT create a descriptor chain longer than the Queue Size of
-the device.
-
-A driver MUST NOT set both VIRTQ_DESC_F_INDIRECT and VIRTQ_DESC_F_NEXT
-in \field{flags}.
-
-\devicenormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
-The device MUST ignore the write-only flag (\field{flags}\&VIRTQ_DESC_F_WRITE) in the descriptor that refers to an indirect table.
-
-The device MUST handle the case of zero or more normal chained
-descriptors followed by a single descriptor with \field{flags}\&VIRTQ_DESC_F_INDIRECT.
-
-\begin{note}
-While unusual (most implementations either create a chain solely using
-non-indirect descriptors, or use a single indirect element), such a
-layout is valid.
-\end{note}
-
-\subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
-
-\begin{lstlisting}
-struct virtq_avail {
-#define VIRTQ_AVAIL_F_NO_INTERRUPT      1
-        le16 flags;
-        le16 idx;
-        le16 ring[ /* Queue Size */ ];
-        le16 used_event; /* Only if VIRTIO_F_EVENT_IDX */
-};
-\end{lstlisting}
-
-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.
-
-\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.
-
-\begin{note}
-The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
-referred to this structure as vring_avail, and the constant as
-VRING_AVAIL_F_NO_INTERRUPT, but the layout and value were identical.
-\end{note}
-
-\subsection{Virtqueue Interrupt Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
-
-If the VIRTIO_F_EVENT_IDX feature bit is not negotiated,
-the \field{flags} field in the available ring offers a crude mechanism for the driver to inform
-the device that it doesn't want interrupts when buffers are used.  Otherwise
-\field{used_event} is a more performant alternative where the driver
-specifies how far the device can progress before interrupting.
-
-Neither of these interrupt suppression methods are reliable, as they
-are not synchronized with the device, but they serve as
-useful optimizations.
-
-\drivernormative{\subsubsection}{Virtqueue Interrupt Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
-If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
-\begin{itemize}
-\item The driver MUST set \field{flags} to 0 or 1.
-\item The driver MAY set \field{flags} to 1 to advise
-the device that interrupts are not needed.
-\end{itemize}
-
-Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
-\begin{itemize}
-\item The driver MUST set \field{flags} to 0.
-\item The driver MAY use \field{used_event} to advise the device that interrupts are unnecessary until the device writes entry with an index specified by \field{used_event} into the used ring (equivalently, until \field{idx} in the
-used ring will reach the value \field{used_event} + 1).
-\end{itemize}
-
-The driver MUST handle spurious interrupts from the device.
-
-\devicenormative{\subsubsection}{Virtqueue Interrupt Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
-
-If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
-\begin{itemize}
-\item The device MUST ignore the \field{used_event} value.
-\item After the device writes a descriptor index into the used ring:
-  \begin{itemize}
-  \item If \field{flags} is 1, the device SHOULD NOT send an interrupt.
-  \item If \field{flags} is 0, the device MUST send an interrupt.
-  \end{itemize}
-\end{itemize}
-
-Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
-\begin{itemize}
-\item The device MUST ignore the lower bit of \field{flags}.
-\item After the device writes a descriptor index into the used ring:
-  \begin{itemize}
-  \item If the \field{idx} field in the used ring (which determined
-    where that descriptor index was placed) was equal to
-    \field{used_event}, the device MUST send an interrupt.
-  \item Otherwise the device SHOULD NOT send an interrupt.
-  \end{itemize}
-\end{itemize}
-
-\begin{note}
-For example, if \field{used_event} is 0, then a device using
-  VIRTIO_F_EVENT_IDX would interrupt after the first buffer is
-  used (and again after the 65536th buffer, etc).
-\end{note}
-
-\subsection{The Virtqueue Used Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
-
-\begin{lstlisting}
-struct virtq_used {
-#define VIRTQ_USED_F_NO_NOTIFY  1
-        le16 flags;
-        le16 idx;
-        struct virtq_used_elem ring[ /* Queue Size */];
-        le16 avail_event; /* Only if VIRTIO_F_EVENT_IDX */
-};
-
-/* le32 is used here for ids for padding reasons. */
-struct virtq_used_elem {
-        /* Index of start of used descriptor chain. */
-        le32 id;
-        /* Total length of the descriptor chain which was used (written to) */
-        le32 len;
-};
-\end{lstlisting}
-
-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.
-
-Each entry in the ring is a pair: \field{id} indicates the head entry of the
-descriptor chain describing the buffer (this matches an entry
-placed in the available ring by the guest earlier), and \field{len} the total
-of bytes written into the buffer.
-
-\begin{note}
-\field{len} is particularly useful
-for drivers using untrusted buffers: if a driver does not know exactly
-how much has been written by the device, the driver would have to zero
-the buffer in advance to ensure no data leakage occurs.
-
-For example, a network driver may hand a received buffer directly to
-an unprivileged userspace application.  If the network device has not
-overwritten the bytes which were in that buffer, this could leak the
-contents of freed memory from other processes to the application.
-\end{note}
-
-\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.
-
-\begin{note}
-The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
-referred to these structures as vring_used and vring_used_elem, and
-the constant as VRING_USED_F_NO_NOTIFY, but the layout and value were
-identical.
-\end{note}
-
-\subsubsection{Legacy Interface: The Virtqueue Used
-Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues
-/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used
-Ring}
-
-Historically, many drivers ignored the \field{len} value, as a
-result, many devices set \field{len} incorrectly.  Thus, when
-using the legacy interface, it is generally a good idea to ignore
-the \field{len} value in used ring entries if possible.  Specific
-known issues are listed per device type.
-
-\devicenormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
-
-The device MUST set \field{len} prior to updating the used \field{idx}.
-
-The device MUST write at least \field{len} bytes to descriptor,
-beginning at the first device-writable buffer,
-prior to updating the used \field{idx}.
-
-The device MAY write more than \field{len} bytes to descriptor.
-
-\begin{note}
-There are potential error cases where a device might not know what
-parts of the buffers have been written.  This is why \field{len} is
-permitted to be an underestimate: that's preferable to the driver believing
-that uninitialized memory has been overwritten when it has not.
-\end{note}
-
-\drivernormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
-
-The driver MUST NOT make assumptions about data in device-writable buffers
-beyond the first \field{len} bytes, and SHOULD ignore this data.
-
-\subsection{Virtqueue Notification Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
-
-The device can suppress notifications in a manner analogous to the way
-drivers can suppress interrupts as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}.
-The device manipulates \field{flags} or \field{avail_event} in the used ring the
-same way the driver manipulates \field{flags} or \field{used_event} in the available ring.
-
-\drivernormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
-
-The driver MUST initialize \field{flags} in the used ring to 0 when
-allocating the used ring.
-
-If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
-\begin{itemize}
-\item The driver MUST ignore the \field{avail_event} value.
-\item After the driver writes a descriptor index into the available ring:
-  \begin{itemize}
-        \item If \field{flags} is 1, the driver SHOULD NOT send a notification.
-        \item If \field{flags} is 0, the driver MUST send a notification.
-  \end{itemize}
-\end{itemize}
-
-Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
-\begin{itemize}
-\item The driver MUST ignore the lower bit of \field{flags}.
-\item After the driver writes a descriptor index into the available ring:
-  \begin{itemize}
-        \item If the \field{idx} field in the available ring (which determined
-          where that descriptor index was placed) was equal to
-          \field{avail_event}, the driver MUST send a notification.
-        \item Otherwise the driver SHOULD NOT send a notification.
-  \end{itemize}
-\end{itemize}
-
-\devicenormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
-If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
-\begin{itemize}
-\item The device MUST set \field{flags} to 0 or 1.
-\item The device MAY set \field{flags} to 1 to advise
-the driver that notifications are not needed.
-\end{itemize}
-
-Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
-\begin{itemize}
-\item The device MUST set \field{flags} to 0.
-\item The device MAY use \field{avail_event} to advise the driver that notifications are unnecessary until the driver writes entry with an index specified by \field{avail_event} into the available ring (equivalently, until \field{idx} in the
-available ring will reach the value \field{avail_event} + 1).
-\end{itemize}
-
-The device MUST handle spurious notifications from the driver.
-
-\subsection{Helpers for Operating Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Helpers for Operating Virtqueues}
-
-The Linux Kernel Source code contains the definitions above and
-helper routines in a more usable form, in
-include/uapi/linux/virtio_ring.h. This was explicitly licensed by IBM
-and Red Hat under the (3-clause) BSD license so that it can be
-freely used by all other projects, and is reproduced (with slight
-variation) in \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}.
+\input{split-ring.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
 
diff --git a/split-ring.tex b/split-ring.tex
new file mode 100644
index 0000000..418f63d
--- /dev/null
+++ b/split-ring.tex
@@ -0,0 +1,498 @@
+\section{Split Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Split Virtqueues}
+The split virtqueue format is the original format used by legacy
+virtio devices.  The split virtqueue format separates the
+virtqueue into several parts, where each part is write-able by
+either the driver or the device, but not both. Multiple
+locations need to be updated when making a buffer available
+and when marking it as used.
+
+
+Each queue has a 16-bit queue size
+parameter, which sets the number of entries and implies the total size
+of the queue.
+
+Each virtqueue consists of three parts:
+
+\begin{itemize}
+\item Descriptor Table
+\item Available Ring
+\item Used Ring
+\end{itemize}
+
+where each part is physically-contiguous in guest memory,
+and has different alignment requirements.
+
+The memory aligment and size requirements, in bytes, of each part of the
+virtqueue are summarized in the following table:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Virtqueue Part    & Alignment & Size \\
+\hline \hline
+Descriptor Table  & 16        & $16 * $(Queue Size) \\
+\hline
+Available Ring    & 2         & $6 + 2 * $(Queue Size) \\
+ \hline
+Used Ring         & 4         & $6 + 8 * $(Queue Size) \\
+ \hline
+\end{tabular}
+
+The Alignment column gives the minimum alignment for each part
+of the virtqueue.
+
+The Size column gives the total number of bytes for each
+part of the virtqueue.
+
+Queue Size corresponds to the maximum number of buffers in the
+virtqueue\footnote{For example, if Queue Size is 4 then at most 4 buffers
+can be queued at any given time.}.  Queue Size value is always a
+power of 2.  The maximum Queue Size value is 32768.  This value
+is specified in a bus-specific way.
+
+When the driver wants to send a buffer to the device, it fills in
+a slot in the descriptor table (or chains several together), and
+writes the descriptor index into the available ring.  It then
+notifies the device. When the device has finished a buffer, it
+writes the descriptor index into the used ring, and sends an interrupt.
+
+\drivernormative{\subsection}{Virtqueues}{Basic Facilities of a Virtio Device / Virtqueues}
+The driver MUST ensure that the physical address of the first byte
+of each virtqueue part is a multiple of the specified alignment value
+in the above table.
+
+\subsection{Legacy Interfaces: A Note on Virtqueue Layout}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Layout}
+
+For Legacy Interfaces, several additional
+restrictions are placed on the virtqueue layout:
+
+Each virtqueue occupies two or more physically-contiguous pages
+(usually defined as 4096 bytes, but depending on the transport;
+henceforth referred to as Queue Align)
+and consists of three parts:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Descriptor Table & Available Ring (\ldots padding\ldots) & Used Ring \\
+\hline
+\end{tabular}
+
+The bus-specific Queue Size field controls the total number of bytes
+for the virtqueue.
+When using the legacy interface, the transitional
+driver MUST retrieve the Queue Size field from the device
+and MUST allocate the total number of bytes for the virtqueue
+according to the following formula (Queue Align given in qalign and
+Queue Size given in qsz):
+
+\begin{lstlisting}
+#define ALIGN(x) (((x) + qalign) & ~qalign)
+static inline unsigned virtq_size(unsigned int qsz)
+{
+     return ALIGN(sizeof(struct virtq_desc)*qsz + sizeof(u16)*(3 + qsz))
+          + ALIGN(sizeof(u16)*3 + sizeof(struct virtq_used_elem)*qsz);
+}
+\end{lstlisting}
+
+This wastes some space with padding.
+When using the legacy interface, both transitional
+devices and drivers MUST use the following virtqueue layout
+structure to locate elements of the virtqueue:
+
+\begin{lstlisting}
+struct virtq {
+        // The actual descriptors (16 bytes each)
+        struct virtq_desc desc[ Queue Size ];
+
+        // A ring of available descriptor heads with free-running index.
+        struct virtq_avail avail;
+
+        // Padding to the next Queue Align boundary.
+        u8 pad[ Padding ];
+
+        // A ring of used descriptor heads with free-running index.
+        struct virtq_used used;
+};
+\end{lstlisting}
+
+\subsection{Legacy Interfaces: A Note on Virtqueue Endianness}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Legacy Interfaces: A Note on Virtqueue Endianness}
+
+Note that when using the legacy interface, transitional
+devices and drivers MUST use the native
+endian of the guest as the endian of fields and in the virtqueue.
+This is opposed to little-endian for non-legacy interface as
+specified by this standard.
+It is assumed that the host is already aware of the guest endian.
+
+\subsection{Message Framing}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing}
+The framing of messages with descriptors is
+independent of the contents of the buffers. For example, a network
+transmit buffer consists of a 12 byte header followed by the network
+packet. This could be most simply placed in the descriptor table as a
+12 byte output descriptor followed by a 1514 byte output descriptor,
+but it could also consist of a single 1526 byte output descriptor in
+the case where the header and packet are adjacent, or even three or
+more descriptors (possibly with loss of efficiency in that case).
+
+Note that, some device implementations have large-but-reasonable
+restrictions on total descriptor size (such as based on IOV_MAX in the
+host OS). This has not been a problem in practice: little sympathy
+will be given to drivers which create unreasonably-sized descriptors
+such as by dividing a network packet into 1500 single-byte
+descriptors!
+
+\devicenormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing}
+The device MUST NOT make assumptions about the particular arrangement
+of descriptors.  The device MAY have a reasonable limit of descriptors
+it will allow in a chain.
+
+\drivernormative{\subsubsection}{Message Framing}{Basic Facilities of a Virtio Device / Message Framing}
+The driver MUST place any device-writable descriptor elements after
+any device-readable descriptor elements.
+
+The driver SHOULD NOT use an excessive number of descriptors to
+describe a buffer.
+
+\subsubsection{Legacy Interface: Message Framing}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing / Legacy Interface: Message Framing}
+
+Regrettably, initial driver implementations used simple layouts, and
+devices came to rely on it, despite this specification wording.  In
+addition, the specification for virtio_blk SCSI commands required
+intuiting field lengths from frame boundaries (see
+ \ref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}~\nameref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation})
+
+Thus when using the legacy interface, the VIRTIO_F_ANY_LAYOUT
+feature indicates to both the device and the driver that no
+assumptions were made about framing.  Requirements for
+transitional drivers when this is not negotiated are included in
+each device section.
+
+\subsection{The Virtqueue Descriptor Table}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
+
+The descriptor table refers to the buffers the driver is using for
+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 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.
+
+The actual contents of the memory offered to the device depends on the
+device type.  Most common is to begin the data with a header
+(containing little-endian fields) for the device to read, and postfix
+it with a status tailer for the device to write.
+
+\begin{lstlisting}
+struct virtq_desc {
+        /* Address (guest-physical). */
+        le64 addr;
+        /* Length. */
+        le32 len;
+
+/* This marks a buffer as continuing via the next field. */
+#define VIRTQ_DESC_F_NEXT   1
+/* This marks a buffer as device write-only (otherwise device read-only). */
+#define VIRTQ_DESC_F_WRITE     2
+/* This means the buffer contains a list of buffer descriptors. */
+#define VIRTQ_DESC_F_INDIRECT   4
+        /* The flags as indicated above. */
+        le16 flags;
+        /* Next field if flags & NEXT */
+        le16 next;
+};
+\end{lstlisting}
+
+The number of descriptors in the table is defined by the queue size
+for this virtqueue: this is the maximum possible descriptor chain length.
+
+\begin{note}
+The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
+referred to this structure as vring_desc, and the constants as
+VRING_DESC_F_NEXT, etc, but the layout and values were identical.
+\end{note}
+
+\devicenormative{\subsubsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
+A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
+read a device-writable buffer (it MAY do so for debugging or diagnostic
+purposes).
+
+\drivernormative{\subsubsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
+Drivers MUST NOT add a descriptor chain over than $2^{32}$ bytes long in total;
+this implies that loops in the descriptor chain are forbidden!
+
+\subsubsection{Indirect Descriptors}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
+
+Some devices benefit by concurrently dispatching a large number
+of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this (see \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}). To increase
+ring capacity the driver can store a table of indirect
+descriptors anywhere in memory, and insert a descriptor in main
+virtqueue (with \field{flags}\&VIRTQ_DESC_F_INDIRECT on) that refers to memory buffer
+containing this indirect descriptor table; \field{addr} and \field{len}
+refer to the indirect table address and length in bytes,
+respectively.
+
+The indirect table layout structure looks like this
+(\field{len} is the length of the descriptor that refers to this table,
+which is a variable, so this code won't compile):
+
+\begin{lstlisting}
+struct indirect_descriptor_table {
+        /* The actual descriptors (16 bytes each) */
+        struct virtq_desc desc[len / 16];
+};
+\end{lstlisting}
+
+The first indirect descriptor is located at start of the indirect
+descriptor table (index 0), additional indirect descriptors are
+chained by \field{next}. An indirect descriptor without a valid \field{next}
+(with \field{flags}\&VIRTQ_DESC_F_NEXT off) signals the end of the descriptor.
+A single indirect descriptor
+table can include both device-readable and device-writable descriptors.
+
+\drivernormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
+The driver MUST NOT set the VIRTQ_DESC_F_INDIRECT flag unless the
+VIRTIO_F_INDIRECT_DESC feature was negotiated.   The driver MUST NOT
+set the VIRTQ_DESC_F_INDIRECT flag within an indirect descriptor (ie. only
+one table per descriptor).
+
+A driver MUST NOT create a descriptor chain longer than the Queue Size of
+the device.
+
+A driver MUST NOT set both VIRTQ_DESC_F_INDIRECT and VIRTQ_DESC_F_NEXT
+in \field{flags}.
+
+\devicenormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
+The device MUST ignore the write-only flag (\field{flags}\&VIRTQ_DESC_F_WRITE) in the descriptor that refers to an indirect table.
+
+The device MUST handle the case of zero or more normal chained
+descriptors followed by a single descriptor with \field{flags}\&VIRTQ_DESC_F_INDIRECT.
+
+\begin{note}
+While unusual (most implementations either create a chain solely using
+non-indirect descriptors, or use a single indirect element), such a
+layout is valid.
+\end{note}
+
+\subsection{The Virtqueue Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
+
+\begin{lstlisting}
+struct virtq_avail {
+#define VIRTQ_AVAIL_F_NO_INTERRUPT      1
+        le16 flags;
+        le16 idx;
+        le16 ring[ /* Queue Size */ ];
+        le16 used_event; /* Only if VIRTIO_F_EVENT_IDX */
+};
+\end{lstlisting}
+
+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.
+
+\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.
+
+\begin{note}
+The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
+referred to this structure as vring_avail, and the constant as
+VRING_AVAIL_F_NO_INTERRUPT, but the layout and value were identical.
+\end{note}
+
+\subsection{Virtqueue Interrupt Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
+
+If the VIRTIO_F_EVENT_IDX feature bit is not negotiated,
+the \field{flags} field in the available ring offers a crude mechanism for the driver to inform
+the device that it doesn't want interrupts when buffers are used.  Otherwise
+\field{used_event} is a more performant alternative where the driver
+specifies how far the device can progress before interrupting.
+
+Neither of these interrupt suppression methods are reliable, as they
+are not synchronized with the device, but they serve as
+useful optimizations.
+
+\drivernormative{\subsubsection}{Virtqueue Interrupt Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
+If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
+\begin{itemize}
+\item The driver MUST set \field{flags} to 0 or 1.
+\item The driver MAY set \field{flags} to 1 to advise
+the device that interrupts are not needed.
+\end{itemize}
+
+Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
+\begin{itemize}
+\item The driver MUST set \field{flags} to 0.
+\item The driver MAY use \field{used_event} to advise the device that interrupts are unnecessary until the device writes entry with an index specified by \field{used_event} into the used ring (equivalently, until \field{idx} in the
+used ring will reach the value \field{used_event} + 1).
+\end{itemize}
+
+The driver MUST handle spurious interrupts from the device.
+
+\devicenormative{\subsubsection}{Virtqueue Interrupt Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
+
+If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
+\begin{itemize}
+\item The device MUST ignore the \field{used_event} value.
+\item After the device writes a descriptor index into the used ring:
+  \begin{itemize}
+  \item If \field{flags} is 1, the device SHOULD NOT send an interrupt.
+  \item If \field{flags} is 0, the device MUST send an interrupt.
+  \end{itemize}
+\end{itemize}
+
+Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
+\begin{itemize}
+\item The device MUST ignore the lower bit of \field{flags}.
+\item After the device writes a descriptor index into the used ring:
+  \begin{itemize}
+  \item If the \field{idx} field in the used ring (which determined
+    where that descriptor index was placed) was equal to
+    \field{used_event}, the device MUST send an interrupt.
+  \item Otherwise the device SHOULD NOT send an interrupt.
+  \end{itemize}
+\end{itemize}
+
+\begin{note}
+For example, if \field{used_event} is 0, then a device using
+  VIRTIO_F_EVENT_IDX would interrupt after the first buffer is
+  used (and again after the 65536th buffer, etc).
+\end{note}
+
+\subsection{The Virtqueue Used Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
+
+\begin{lstlisting}
+struct virtq_used {
+#define VIRTQ_USED_F_NO_NOTIFY  1
+        le16 flags;
+        le16 idx;
+        struct virtq_used_elem ring[ /* Queue Size */];
+        le16 avail_event; /* Only if VIRTIO_F_EVENT_IDX */
+};
+
+/* le32 is used here for ids for padding reasons. */
+struct virtq_used_elem {
+        /* Index of start of used descriptor chain. */
+        le32 id;
+        /* Total length of the descriptor chain which was used (written to) */
+        le32 len;
+};
+\end{lstlisting}
+
+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.
+
+Each entry in the ring is a pair: \field{id} indicates the head entry of the
+descriptor chain describing the buffer (this matches an entry
+placed in the available ring by the guest earlier), and \field{len} the total
+of bytes written into the buffer.
+
+\begin{note}
+\field{len} is particularly useful
+for drivers using untrusted buffers: if a driver does not know exactly
+how much has been written by the device, the driver would have to zero
+the buffer in advance to ensure no data leakage occurs.
+
+For example, a network driver may hand a received buffer directly to
+an unprivileged userspace application.  If the network device has not
+overwritten the bytes which were in that buffer, this could leak the
+contents of freed memory from other processes to the application.
+\end{note}
+
+\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.
+
+\begin{note}
+The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
+referred to these structures as vring_used and vring_used_elem, and
+the constant as VRING_USED_F_NO_NOTIFY, but the layout and value were
+identical.
+\end{note}
+
+\subsubsection{Legacy Interface: The Virtqueue Used
+Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues
+/ The Virtqueue Used Ring/ Legacy Interface: The Virtqueue Used
+Ring}
+
+Historically, many drivers ignored the \field{len} value, as a
+result, many devices set \field{len} incorrectly.  Thus, when
+using the legacy interface, it is generally a good idea to ignore
+the \field{len} value in used ring entries if possible.  Specific
+known issues are listed per device type.
+
+\devicenormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
+
+The device MUST set \field{len} prior to updating the used \field{idx}.
+
+The device MUST write at least \field{len} bytes to descriptor,
+beginning at the first device-writable buffer,
+prior to updating the used \field{idx}.
+
+The device MAY write more than \field{len} bytes to descriptor.
+
+\begin{note}
+There are potential error cases where a device might not know what
+parts of the buffers have been written.  This is why \field{len} is
+permitted to be an underestimate: that's preferable to the driver believing
+that uninitialized memory has been overwritten when it has not.
+\end{note}
+
+\drivernormative{\subsubsection}{The Virtqueue Used Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
+
+The driver MUST NOT make assumptions about data in device-writable buffers
+beyond the first \field{len} bytes, and SHOULD ignore this data.
+
+\subsection{Virtqueue Notification Suppression}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
+
+The device can suppress notifications in a manner analogous to the way
+drivers can suppress interrupts as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}.
+The device manipulates \field{flags} or \field{avail_event} in the used ring the
+same way the driver manipulates \field{flags} or \field{used_event} in the available ring.
+
+\drivernormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
+
+The driver MUST initialize \field{flags} in the used ring to 0 when
+allocating the used ring.
+
+If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
+\begin{itemize}
+\item The driver MUST ignore the \field{avail_event} value.
+\item After the driver writes a descriptor index into the available ring:
+  \begin{itemize}
+        \item If \field{flags} is 1, the driver SHOULD NOT send a notification.
+        \item If \field{flags} is 0, the driver MUST send a notification.
+  \end{itemize}
+\end{itemize}
+
+Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
+\begin{itemize}
+\item The driver MUST ignore the lower bit of \field{flags}.
+\item After the driver writes a descriptor index into the available ring:
+  \begin{itemize}
+        \item If the \field{idx} field in the available ring (which determined
+          where that descriptor index was placed) was equal to
+          \field{avail_event}, the driver MUST send a notification.
+        \item Otherwise the driver SHOULD NOT send a notification.
+  \end{itemize}
+\end{itemize}
+
+\devicenormative{\subsubsection}{Virtqueue Notification Suppression}{Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
+If the VIRTIO_F_EVENT_IDX feature bit is not negotiated:
+\begin{itemize}
+\item The device MUST set \field{flags} to 0 or 1.
+\item The device MAY set \field{flags} to 1 to advise
+the driver that notifications are not needed.
+\end{itemize}
+
+Otherwise, if the VIRTIO_F_EVENT_IDX feature bit is negotiated:
+\begin{itemize}
+\item The device MUST set \field{flags} to 0.
+\item The device MAY use \field{avail_event} to advise the driver that notifications are unnecessary until the driver writes entry with an index specified by \field{avail_event} into the available ring (equivalently, until \field{idx} in the
+available ring will reach the value \field{avail_event} + 1).
+\end{itemize}
+
+The device MUST handle spurious notifications from the driver.
+
+\subsection{Helpers for Operating Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Helpers for Operating Virtqueues}
+
+The Linux Kernel Source code contains the definitions above and
+helper routines in a more usable form, in
+include/uapi/linux/virtio_ring.h. This was explicitly licensed by IBM
+and Red Hat under the (3-clause) BSD license so that it can be
+freely used by all other projects, and is reproduced (with slight
+variation) in \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}.
-- 
MST

[PATCH v8 03/16] content: move virtqueue operation description

[Michael S. Tsirkin]

virtqueue operation description is specific to the virtqueue
format. Move it out to split-ring.tex and update all
references.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
 conformance.tex |   4 +-
 content.tex     | 171 +++-------------------------------------------------
 split-ring.tex  | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 185 insertions(+), 171 deletions(-)

diff --git a/conformance.tex b/conformance.tex
index f59e360..55d17b4 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -40,9 +40,9 @@ A driver MUST conform to the following normative statements:
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
+\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Updating idx}
+\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Notifying The Device}
 \item \ref{drivernormative:General Initialization And Device Operation / Device Initialization}
-\item \ref{drivernormative:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx}
-\item \ref{drivernormative:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Notifying The Device}
 \item \ref{drivernormative:General Initialization And Device Operation / Device Cleanup}
 \item \ref{drivernormative:Reserved Feature Bits}
 \end{itemize}
diff --git a/content.tex b/content.tex
index 5b4c4e9..3b4579e 100644
--- a/content.tex
+++ b/content.tex
@@ -337,167 +337,14 @@ And Device Operation / Device Initialization / Set DRIVER-OK}.
 
 \section{Device Operation}\label{sec:General Initialization And Device Operation / Device Operation}
 
-There are two parts to device operation: supplying new buffers to
-the device, and processing used buffers from the device.
-
-\begin{note} As an
-example, the simplest virtio network device has two virtqueues: the
-transmit virtqueue and the receive virtqueue. The driver adds
-outgoing (device-readable) packets to the transmit virtqueue, and then
-frees them after they are used. Similarly, incoming (device-writable)
-buffers are added to the receive virtqueue, and processed after
-they are used.
-\end{note}
-
-\subsection{Supplying Buffers to The Device}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device}
-
-The driver offers buffers to one of the device's virtqueues as follows:
-
-\begin{enumerate}
-\item\label{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Buffers} The driver places the buffer into free descriptor(s) in the
-   descriptor table, chaining as necessary (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}).
-
-\item\label{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Index} The driver places the index of the head of the descriptor chain
-   into the next ring entry of the available ring.
-
-\item Steps \ref{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Buffers} and \ref{itm:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Place Index} MAY be performed repeatedly if batching
-  is possible.
-
-\item The driver performs suitable a memory barrier to ensure the device sees
-  the updated descriptor table and available ring before the next
-  step.
-
-\item The available \field{idx} is increased by the number of
-  descriptor chain heads added to the available ring.
-
-\item The driver performs a suitable memory barrier to ensure that it updates
-  the \field{idx} field before checking for notification suppression.
-
-\item If notifications are not suppressed, the driver notifies the device
-    of the new available buffers.
-\end{enumerate}
-
-Note that the above code does not take precautions against the
-available ring buffer wrapping around: this is not possible since
-the ring buffer is the same size as the descriptor table, so step
-(1) will prevent such a condition.
-
-In addition, the maximum queue size is 32768 (the highest power
-of 2 which fits in 16 bits), so the 16-bit \field{idx} value can always
-distinguish between a full and empty buffer.
+When operating the device, each field in the device configuration
+space can be changed by either the driver or the device.
 
-What follows is the requirements 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}
-
-A buffer consists of zero or more device-readable physically-contiguous
-elements followed by zero or more physically-contiguous
-device-writable elements (each has at least one element). This
-algorithm maps it into the descriptor table to form a descriptor
-chain:
-
-for each buffer element, b:
-
-\begin{enumerate}
-\item Get the next free descriptor table entry, d
-\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 device-writable, set \field{d.flags} to VIRTQ_DESC_F_WRITE,
-    otherwise 0.
-\item If there is a buffer element after this:
-    \begin{enumerate}
-    \item Set \field{d.next} to the index of the next free descriptor
-      element.
-    \item Set the VIRTQ_DESC_F_NEXT bit in \field{d.flags}.
-    \end{enumerate}
-\end{enumerate}
-
-In practice, \field{d.next} is usually used to chain free
-descriptors, and a separate count kept to check there are enough
-free descriptors before beginning the mappings.
-
-\subsubsection{Updating The Available Ring}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating The Available Ring}
-
-The descriptor chain head is the first d in the algorithm
-above, ie. the index of the descriptor table entry referring to the first
-part of the buffer.  A naive driver implementation MAY do the following (with the
-appropriate conversion to-and-from little-endian assumed):
-
-\begin{lstlisting}
-avail->ring[avail->idx % qsz] = head;
-\end{lstlisting}
+Whenever such a configuration change is triggered by the device,
+driver is notified. This makes it possible for drivers to
+cache device configuration, avoiding expensive configuration
+reads unless notified.
 
-However, in general the driver MAY add many descriptor chains before it updates
-\field{idx} (at which point they become visible to the
-device), so it is common to keep a counter of how many the driver has added:
-
-\begin{lstlisting}
-avail->ring[(avail->idx + added++) % qsz] = head;
-\end{lstlisting}
-
-\subsubsection{Updating \field{idx}}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx}
-
-\field{idx} always increments, and wraps naturally at
-65536:
-
-\begin{lstlisting}
-avail->idx += added;
-\end{lstlisting}
-
-Once available \field{idx} is updated by the driver, this exposes the
-descriptor and its contents.  The device MAY
-access the descriptor chains the driver created and the
-memory they refer to immediately.
-
-\drivernormative{\paragraph}{Updating idx}{General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Updating idx}
-The driver MUST perform a suitable memory barrier before the \field{idx} update, to ensure the
-device sees the most up-to-date copy.
-
-\subsubsection{Notifying The Device}\label{sec:General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Notifying The Device}
-
-The actual method of device notification is bus-specific, but generally
-it can be expensive.  So the device MAY suppress such notifications if it
-doesn't need them, as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}.
-
-The driver has to be careful to expose the new \field{idx}
-value before checking if notifications are suppressed.
-
-\drivernormative{\paragraph}{Notifying The Device}{General Initialization And Device Operation / Device Operation / Supplying Buffers to The Device / Notifying The Device}
-The driver MUST perform a suitable memory barrier before reading \field{flags} or
-\field{avail_event}, to avoid missing a notification.
-
-\subsection{Receiving Used Buffers From The Device}\label{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}
-
-Once the device has used buffers referred to by a descriptor (read from or written to them, or
-parts of both, depending on the nature of the virtqueue and the
-device), it interrupts the driver as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}.
-
-\begin{note}
-For optimal performance, a driver MAY disable interrupts while processing
-the used ring, but beware the problem of missing interrupts between
-emptying the ring and reenabling interrupts.  This is usually handled by
-re-checking for more used buffers after interrups are re-enabled:
-
-\begin{lstlisting}
-virtq_disable_interrupts(vq);
-
-for (;;) {
-        if (vq->last_seen_used != le16_to_cpu(virtq->used.idx)) {
-                virtq_enable_interrupts(vq);
-                mb();
-
-                if (vq->last_seen_used != le16_to_cpu(virtq->used.idx))
-                        break;
-
-                virtq_disable_interrupts(vq);
-        }
-
-        struct virtq_used_elem *e = virtq.used->ring[vq->last_seen_used%vsz];
-        process_buffer(e);
-        vq->last_seen_used++;
-}
-\end{lstlisting}
-\end{note}
 
 \subsection{Notification of Device Configuration Changes}\label{sec:General Initialization And Device Operation / Device Operation / Notification of Device Configuration Changes}
 
@@ -3017,9 +2864,7 @@ If VIRTIO_NET_HDR_F_NEEDS_CSUM is not set, the device MUST NOT
 rely on the packet checksum being correct.
 \paragraph{Packet Transmission Interrupt}\label{sec:Device Types / Network Device / Device Operation / Packet Transmission / Packet Transmission Interrupt}
 
-Often a driver will suppress transmission interrupts using the
-VIRTQ_AVAIL_F_NO_INTERRUPT flag
- (see \ref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}~\nameref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device})
+Often a driver will suppress transmission virtqueue interrupts
 and check for used packets in the transmit path of following
 packets.
 
@@ -3079,7 +2924,7 @@ if VIRTIO_NET_F_MRG_RXBUF is not negotiated.}
 
 When a packet is copied into a buffer in the receiveq, the
 optimal path is to disable further interrupts for the receiveq
-(see \ref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}~\nameref{sec:General Initialization And Device Operation / Device Operation / Receiving Used Buffers From The Device}) and process
+and process
 packets until no more are found, then re-enable them.
 
 Processing incoming packets involves:
diff --git a/split-ring.tex b/split-ring.tex
index 418f63d..404660b 100644
--- a/split-ring.tex
+++ b/split-ring.tex
@@ -1,11 +1,12 @@
 \section{Split Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Split Virtqueues}
-The split virtqueue format is the original format used by legacy
-virtio devices.  The split virtqueue format separates the
-virtqueue into several parts, where each part is write-able by
-either the driver or the device, but not both. Multiple
-locations need to be updated when making a buffer available
-and when marking it as used.
+The split virtqueue format was the only format supported
+by the version 1.0 (and earlier) of this standard.
 
+The split virtqueue format separates the virtqueue into several
+parts, where each part is write-able by either the driver or the
+device, but not both. Multiple parts and/or locations within
+a part need to be updated when making a buffer
+available and when marking it as used.
 
 Each queue has a 16-bit queue size
 parameter, which sets the number of entries and implies the total size
@@ -496,3 +497,171 @@ include/uapi/linux/virtio_ring.h. This was explicitly licensed by IBM
 and Red Hat under the (3-clause) BSD license so that it can be
 freely used by all other projects, and is reproduced (with slight
 variation) in \ref{sec:virtio-queue.h}~\nameref{sec:virtio-queue.h}.
+
+\subsection{Virtqueue Operation}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Operation}
+
+There are two parts to virtqueue operation: supplying new
+available buffers to the device, and processing used buffers from
+the device.
+
+\begin{note} As an
+example, the simplest virtio network device has two virtqueues: the
+transmit virtqueue and the receive virtqueue. The driver adds
+outgoing (device-readable) packets to the transmit virtqueue, and then
+frees them after they are used. Similarly, incoming (device-writable)
+buffers are added to the receive virtqueue, and processed after
+they are used.
+\end{note}
+
+What follows is the requirements of each of these two parts
+when using the split virtqueue format in more detail.
+
+\subsection{Supplying Buffers to The Device}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device}
+
+The driver offers buffers to one of the device's virtqueues as follows:
+
+\begin{enumerate}
+\item\label{itm:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Place Buffers} The driver places the buffer into free descriptor(s) in the
+   descriptor table, chaining as necessary (see \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}~\nameref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}).
+
+\item\label{itm:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Place Index} The driver places the index of the head of the descriptor chain
+   into the next ring entry of the available ring.
+
+\item Steps \ref{itm:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Place Buffers} and \ref{itm:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Place Index} MAY be performed repeatedly if batching
+  is possible.
+
+\item The driver performs suitable a memory barrier to ensure the device sees
+  the updated descriptor table and available ring before the next
+  step.
+
+\item The available \field{idx} is increased by the number of
+  descriptor chain heads added to the available ring.
+
+\item The driver performs a suitable memory barrier to ensure that it updates
+  the \field{idx} field before checking for notification suppression.
+
+\item If notifications are not suppressed, the driver notifies the device
+    of the new available buffers.
+\end{enumerate}
+
+Note that the above code does not take precautions against the
+available ring buffer wrapping around: this is not possible since
+the ring buffer is the same size as the descriptor table, so step
+(1) will prevent such a condition.
+
+In addition, the maximum queue size is 32768 (the highest power
+of 2 which fits in 16 bits), so the 16-bit \field{idx} value can always
+distinguish between a full and empty buffer.
+
+What follows is the requirements of each stage in more detail.
+
+\subsubsection{Placing Buffers Into The Descriptor Table}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Placing Buffers Into The Descriptor Table}
+
+A buffer consists of zero or more device-readable physically-contiguous
+elements followed by zero or more physically-contiguous
+device-writable elements (each has at least one element). This
+algorithm maps it into the descriptor table to form a descriptor
+chain:
+
+for each buffer element, b:
+
+\begin{enumerate}
+\item Get the next free descriptor table entry, d
+\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 device-writable, set \field{d.flags} to VIRTQ_DESC_F_WRITE,
+    otherwise 0.
+\item If there is a buffer element after this:
+    \begin{enumerate}
+    \item Set \field{d.next} to the index of the next free descriptor
+      element.
+    \item Set the VIRTQ_DESC_F_NEXT bit in \field{d.flags}.
+    \end{enumerate}
+\end{enumerate}
+
+In practice, \field{d.next} is usually used to chain free
+descriptors, and a separate count kept to check there are enough
+free descriptors before beginning the mappings.
+
+\subsubsection{Updating The Available Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Updating The Available Ring}
+
+The descriptor chain head is the first d in the algorithm
+above, ie. the index of the descriptor table entry referring to the first
+part of the buffer.  A naive driver implementation MAY do the following (with the
+appropriate conversion to-and-from little-endian assumed):
+
+\begin{lstlisting}
+avail->ring[avail->idx % qsz] = head;
+\end{lstlisting}
+
+However, in general the driver MAY add many descriptor chains before it updates
+\field{idx} (at which point they become visible to the
+device), so it is common to keep a counter of how many the driver has added:
+
+\begin{lstlisting}
+avail->ring[(avail->idx + added++) % qsz] = head;
+\end{lstlisting}
+
+\subsubsection{Updating \field{idx}}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Updating idx}
+
+\field{idx} always increments, and wraps naturally at
+65536:
+
+\begin{lstlisting}
+avail->idx += added;
+\end{lstlisting}
+
+Once available \field{idx} is updated by the driver, this exposes the
+descriptor and its contents.  The device MAY
+access the descriptor chains the driver created and the
+memory they refer to immediately.
+
+\drivernormative{\paragraph}{Updating idx}{Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Updating idx}
+The driver MUST perform a suitable memory barrier before the \field{idx} update, to ensure the
+device sees the most up-to-date copy.
+
+\subsubsection{Notifying The Device}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Notifying The Device}
+
+The actual method of device notification is bus-specific, but generally
+it can be expensive.  So the device MAY suppress such notifications if it
+doesn't need them, as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}.
+
+The driver has to be careful to expose the new \field{idx}
+value before checking if notifications are suppressed.
+
+\drivernormative{\paragraph}{Notifying The Device}{Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Notifying The Device}
+The driver MUST perform a suitable memory barrier before reading \field{flags} or
+\field{avail_event}, to avoid missing a notification.
+
+\subsection{Receiving Used Buffers From The Device}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Receiving Used Buffers From The Device}
+
+Once the device has used buffers referred to by a descriptor (read from or written to them, or
+parts of both, depending on the nature of the virtqueue and the
+device), it interrupts the driver as detailed in section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}.
+
+\begin{note}
+For optimal performance, a driver MAY disable interrupts while processing
+the used ring, but beware the problem of missing interrupts between
+emptying the ring and reenabling interrupts.  This is usually handled by
+re-checking for more used buffers after interrups are re-enabled:
+
+\begin{lstlisting}
+virtq_disable_interrupts(vq);
+
+for (;;) {
+        if (vq->last_seen_used != le16_to_cpu(virtq->used.idx)) {
+                virtq_enable_interrupts(vq);
+                mb();
+
+                if (vq->last_seen_used != le16_to_cpu(virtq->used.idx))
+                        break;
+
+                virtq_disable_interrupts(vq);
+        }
+
+        struct virtq_used_elem *e = virtq.used->ring[vq->last_seen_used%vsz];
+        process_buffer(e);
+        vq->last_seen_used++;
+}
+\end{lstlisting}
+\end{note}
-- 
MST

[PATCH v8 04/16] content: replace mentions of len with used length

[Michael S. Tsirkin]

Document buffer used len and use that terminology everywhere in the
generic section.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 content.tex | 39 ++++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/content.tex b/content.tex
index 3b4579e..4350ecf 100644
--- a/content.tex
+++ b/content.tex
@@ -242,7 +242,8 @@ a used buffer to the queue - i.e. lets the driver
 know by marking the buffer as used. Device can then trigger
 a device event - i.e. send an interrupt to the driver.
 
-For queue operation detail, see \ref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}.
+Device reports the number of bytes it has written to memory for
+each buffer it uses. This is referred to as ``used length''.
 
 \input{split-ring.tex}
 
@@ -1304,7 +1305,7 @@ The driver interrupt handler would typically:
     \begin{itemize}
       \item Read the ISR Status field, which will reset it to zero.
       \item If the lower bit is set:
-        look through the used rings of all virtqueues for the
+        look through all virtqueues for the
         device, to see if any progress has been made by the device
         which requires servicing.
       \item If the second lower bit is set:
@@ -1313,8 +1314,7 @@ The driver interrupt handler would typically:
   \item If MSI-X capability is enabled:
     \begin{itemize}
       \item
-        Look through the used rings of
-        all virtqueues mapped to that MSI-X vector for the
+        Look through all virtqueues mapped to that MSI-X vector for the
         device, to see if any progress has been made by the device
         which requires servicing.
       \item
@@ -1728,8 +1728,7 @@ nor behaviour:
   }
   \hline
   \mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{%
-    Queue size is the number of elements in the queue, therefore size
-    of the descriptor table and both available and used rings.
+    Queue size is the number of elements in the queue.
     Writing to this register notifies the device what size of the
     queue the driver will use. This applies to the queue selected by
     writing to \field{QueueSel}.
@@ -2709,7 +2708,7 @@ when VIRTIO_NET_F_MRG_RXBUF was negotiated; without that feature the
 structure was 2 bytes shorter.
 
 When using the legacy interface, the driver SHOULD ignore the
-\field{len} value in used ring entries for the transmit queues
+used length for the transmit queues
 and the controlq queue.
 \begin{note}
 Historically, some devices put
@@ -2868,8 +2867,8 @@ Often a driver will suppress transmission virtqueue interrupts
 and check for used packets in the transmit path of following
 packets.
 
-The normal behavior in this interrupt handler is to retrieve and
-new descriptors from the used ring and free the corresponding
+The normal behavior in this interrupt handler is to retrieve
+used buffers from the virtqueue and free the corresponding
 headers and packets.
 
 \subsubsection{Setting Up Receive Buffers}\label{sec:Device Types / Network Device / Device Operation / Setting Up Receive Buffers}
@@ -2936,7 +2935,7 @@ Processing incoming packets involves:
   This allows receipt of large packets without having to allocate large
   buffers: a packet that does not fit in a single buffer can flow
   over to the next buffer, and so on. In this case, there will be
-  at least \field{num_buffers} in the used ring, and the device
+  at least \field{num_buffers} used buffers in the virtqueue, and the device
   chains them together to form a single packet in a way similar to
   how it would store it in a single buffer spread over multiple
   descriptors.
@@ -2990,8 +2989,8 @@ MUST use all buffers but the last (i.e. the first $num_buffers -
 supplied by the driver.
 
 The device MUST use all buffers used by a single receive
-packet together, by atomically incrementing \field{idx} in the
-used ring by the \field{num_buffers} value.
+packet together, such that at least \field{num_buffers} are
+observed by driver as used.
 
 If VIRTIO_NET_F_GUEST_CSUM is not negotiated, the device MUST set
 \field{flags} to zero and SHOULD supply a fully checksummed
@@ -3378,7 +3377,8 @@ The device MUST queue packets only on any receiveq1 before the
 VIRTIO_NET_CTRL_MQ_VQ_PAIRS_SET command.
 
 The device MUST NOT queue packets on receive queues greater than
-\field{virtqueue_pairs} once it has placed the VIRTIO_NET_CTRL_MQ_VQ_PAIRS_SET command in the used ring.
+\field{virtqueue_pairs} once it has placed the
+VIRTIO_NET_CTRL_MQ_VQ_PAIRS_SET command in a used buffer.
 
 \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}
 When using the legacy interface, transitional devices and drivers
@@ -3744,7 +3744,7 @@ according to the native endian of the guest rather than
 (necessarily when not using the legacy interface) little-endian.
 
 When using the legacy interface, transitional drivers
-SHOULD ignore the \field{len} value in used ring entries.
+SHOULD ignore the used length values.
 \begin{note}
 Historically, some devices put the total descriptor length,
 or the total length of device-writable buffers there,
@@ -4081,7 +4081,7 @@ according to the native endian of the guest rather than
 (necessarily when not using the legacy interface) little-endian.
 
 When using the legacy interface, the driver SHOULD ignore the
-\field{len} value in used ring entries for the transmit queues
+used length values for the transmit queues
 and the control transmitq.
 \begin{note}
 Historically, some devices put the total descriptor length there,
@@ -4337,7 +4337,8 @@ and acknowledging the deflate request.
 \paragraph{Legacy Interface: Device Operation}\label{sec:Device
 Types / Memory Balloon Device / Device Operation / Legacy
 Interface: Device Operation}
-When using the legacy interface, the driver SHOULD ignore the \field{len} value in used ring entries.
+When using the legacy interface, the driver SHOULD ignore the
+used length values.
 \begin{note}
 Historically, some devices put the total descriptor length there,
 even though no data was actually written.
@@ -4370,8 +4371,7 @@ and notifies the device. A request for memory statistics proceeds
 as follows:
 
 \begin{enumerate}
-\item The device pushes the buffer onto the used ring and sends an
-  interrupt.
+\item The device uses the buffer and sends an interrupt.
 
 \item The driver pops the used buffer and discards it.
 
@@ -4632,7 +4632,8 @@ queue and the event queue.
 \paragraph{Legacy Interface: Device Operation}\label{sec:Device
 Types / SCSI Host Device / Device Operation / Legacy
 Interface: Device Operation}
-When using the legacy interface, the driver SHOULD ignore the \field{len} value in used ring entries.
+When using the legacy interface, the driver SHOULD ignore the
+used length values.
 \begin{note}
 Historically, devices put the total descriptor length,
 or the total length of device-writable buffers there,
-- 
MST

[virtio] Re: [PATCH v8 04/16] content: replace mentions of len with used length

[Cornelia Huck]

On Fri, 16 Feb 2018 09:22:08 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Document buffer used len and use that terminology everywhere in the
> generic section.

It also replaces the 'used ring' terminology (which makes sense, but
was not mentioned.)

> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  content.tex | 39 ++++++++++++++++++++-------------------
>  1 file changed, 20 insertions(+), 19 deletions(-)

Reviewed-by: Cornelia Huck <cohuck@redhat.com>

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[PATCH v8 05/16] content: generalize transport ring part naming

[Michael S. Tsirkin]

Replace descriptor table/available ring/used ring
with descriptor area/driver area/device area
in all transports.

Document what's in which area.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
 content.tex    | 61 ++++++++++++++++++++++++++++++++++++++--------------------
 split-ring.tex |  6 +++---
 2 files changed, 43 insertions(+), 24 deletions(-)

diff --git a/content.tex b/content.tex
index 4350ecf..9fc9673 100644
--- a/content.tex
+++ b/content.tex
@@ -245,6 +245,24 @@ a device event - i.e. send an interrupt to the driver.
 Device reports the number of bytes it has written to memory for
 each buffer it uses. This is referred to as ``used length''.
 
+Each virtqueue can consist of up to 3 parts:
+\begin{itemize}
+\item Descriptor Area - used for describing buffers
+\item Driver Area - extra data supplied by driver to the device
+\item Device Area - extra data supplied by device to driver
+\end{itemize}
+
+\begin{note}
+Note that previous versions of this spec used different names for
+these parts (following \ref{sec:Basic Facilities of a Virtio Device / Split Virtqueues}):
+\begin{itemize}
+\item Descriptor Table - for the Descriptor Area
+\item Available Ring - for the Driver Area
+\item Used Ring - for the Device Area
+\end{itemize}
+
+\end{note}
+
 \input{split-ring.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
@@ -667,8 +685,8 @@ struct virtio_pci_common_cfg {
         le16 queue_enable;              /* read-write */
         le16 queue_notify_off;          /* read-only for driver */
         le64 queue_desc;                /* read-write */
-        le64 queue_avail;               /* read-write */
-        le64 queue_used;                /* read-write */
+        le64 queue_driver;              /* read-write */
+        le64 queue_device;              /* read-write */
 };
 \end{lstlisting}
 
@@ -728,13 +746,13 @@ struct virtio_pci_common_cfg {
         \end{note}
 
 \item[\field{queue_desc}]
-        The driver writes the physical address of Descriptor Table here.  See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
+        The driver writes the physical address of Descriptor Area here.  See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
 
-\item[\field{queue_avail}]
-        The driver writes the physical address of Available Ring here.  See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
+\item[\field{queue_driver}]
+        The driver writes the physical address of Driver Area here.  See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
 
-\item[\field{queue_used}]
-        The driver writes the physical address of Used Ring here.  See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
+\item[\field{queue_device}]
+        The driver writes the physical address of Device Area here.  See section \ref{sec:Basic Facilities of a Virtio Device / Virtqueues}.
 \end{description}
 
 \devicenormative{\paragraph}{Common configuration structure layout}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Common configuration structure layout}
@@ -1496,24 +1514,24 @@ All register values are organized as Little Endian.
     See also p. \ref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}~\nameref{sec:Virtio Transport Options / Virtio Over MMIO / MMIO-specific Initialization And Device Operation / Device Initialization}.
   }
   \hline 
-  \mmiodreg{QueueDescLow}{QueueDescHigh}{Virtual queue's Descriptor Table 64 bit long physical address}{0x080}{0x084}{W}{%
+  \mmiodreg{QueueDescLow}{QueueDescHigh}{Virtual queue's Descriptor Area 64 bit long physical address}{0x080}{0x084}{W}{%
     Writing to these two registers (lower 32 bits of the address
     to \field{QueueDescLow}, higher 32 bits to \field{QueueDescHigh}) notifies
-    the device about location of the Descriptor Table of the queue
+    the device about location of the Descriptor Area of the queue
     selected by writing to \field{QueueSel} register.
   }
   \hline 
-  \mmiodreg{QueueAvailLow}{QueueAvailHigh}{Virtual queue's Available Ring 64 bit long physical address}{0x090}{0x094}{W}{%
+  \mmiodreg{QueueDriverLow}{QueueDriverHigh}{Virtual queue's Driver Area 64 bit long physical address}{0x090}{0x094}{W}{%
     Writing to these two registers (lower 32 bits of the address
     to \field{QueueAvailLow}, higher 32 bits to \field{QueueAvailHigh}) notifies
-    the device about location of the Available Ring of the queue
+    the device about location of the Driver Area of the queue
     selected by writing to \field{QueueSel}.
   }
   \hline 
-  \mmiodreg{QueueUsedLow}{QueueUsedHigh}{Virtual queue's Used Ring 64 bit long physical address}{0x0a0}{0x0a4}{W}{%
+  \mmiodreg{QueueDeviceLow}{QueueDeviceHigh}{Virtual queue's Device Area 64 bit long physical address}{0x0a0}{0x0a4}{W}{%
     Writing to these two registers (lower 32 bits of the address
     to \field{QueueUsedLow}, higher 32 bits to \field{QueueUsedHigh}) notifies
-    the device about location of the Used Ring of the queue
+    the device about location of the Device Area of the queue
     selected by writing to \field{QueueSel}.
   }
   \hline 
@@ -1631,11 +1649,11 @@ The driver will typically initialize the virtual queue in the following way:
 \item Notify the device about the queue size by writing the size to
    \field{QueueNum}.
 
-\item Write physical addresses of the queue's Descriptor Table,
-   Available Ring and Used Ring to (respectively) the
+\item Write physical addresses of the queue's Descriptor Area,
+   Driver Area and Device Area to (respectively) the
    \field{QueueDescLow}/\field{QueueDescHigh},
-   \field{QueueAvailLow}/\field{QueueAvailHigh} and
-   \field{QueueUsedLow}/\field{QueueUsedHigh} register pairs.
+   \field{QueueDriverLow}/\field{QueueDriverHigh} and
+   \field{QueueDeviceLow}/\field{QueueDeviceHigh} register pairs.
 
 \item Write 0x1 to \field{QueueReady}.
 \end{enumerate}
@@ -2025,13 +2043,14 @@ struct vq_info_block {
         be32 res0;
         be16 index;
         be16 num;
-        be64 avail;
-        be64 used;
+        be64 driver;
+        be64 device;
 };
 \end{lstlisting}
 
-\field{desc}, \field{avail} and \field{used} contain the guest addresses for the descriptor table,
-available ring and used ring for queue \field{index}, respectively. The actual
+\field{desc}, \field{driver} and \field{device} contain the guest
+addresses for the descriptor area,
+available area and used area for queue \field{index}, respectively. The actual
 virtqueue size (number of allocated buffers) is transmitted in \field{num}.
 
 \devicenormative{\paragraph}{Configuring a Virtqueue}{Virtio Transport Options / Virtio over channel I/O / Device Initialization / Configuring a Virtqueue}
diff --git a/split-ring.tex b/split-ring.tex
index 404660b..9601a53 100644
--- a/split-ring.tex
+++ b/split-ring.tex
@@ -15,9 +15,9 @@ of the queue.
 Each virtqueue consists of three parts:
 
 \begin{itemize}
-\item Descriptor Table
-\item Available Ring
-\item Used Ring
+\item Descriptor Table - occupies the Descriptor Area
+\item Available Ring - occupies the Driver Area
+\item Used Ring - occupies the Device Area
 \end{itemize}
 
 where each part is physically-contiguous in guest memory,
-- 
MST

[PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

Performance analysis of this is in my kvm forum 2016 presentation.  The
idea is to have a r/w descriptor in a ring structure, replacing the used
and available ring, index and descriptor buffer.

This is also easier for devices to implement than the 1.0 layout.
Several more enhancements will be necessary to actually make this
efficient for devices to use.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 content.tex     |  28 ++-
 packed-ring.tex | 646 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 671 insertions(+), 3 deletions(-)
 create mode 100644 packed-ring.tex

diff --git a/content.tex b/content.tex
index e1e30a0..73f40b7 100644
--- a/content.tex
+++ b/content.tex
@@ -263,8 +263,20 @@ these parts (following \ref{sec:Basic Facilities of a Virtio Device / Split Virt
 
 \end{note}
 
+Two formats are supported: Split Virtqueues (see \ref{sec:Basic
+Facilities of a Virtio Device / Split
+Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device /
+Split Virtqueues}) and Packed Virtqueues (see \ref{sec:Basic
+Facilities of a Virtio Device / Packed
+Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device /
+Packed Virtqueues}).
+
+Every driver and device supports either the Packed or the Split
+Virtqueue format, or both.
+
 \input{split-ring.tex}
 
+\input{packed-ring.tex}
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
 
 We start with an overview of device initialization, then expand on the
@@ -5215,10 +5227,15 @@ Currently these device-independent feature bits defined:
 \begin{description}
   \item[VIRTIO_F_RING_INDIRECT_DESC (28)] Negotiating this feature indicates
   that the driver can use descriptors with the VIRTQ_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}.
-
+  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} and \ref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}~\nameref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}.
   \item[VIRTIO_F_RING_EVENT_IDX(29)] This feature enables the \field{used_event}
-  and the \field{avail_event} fields as described in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} and \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}.
+  and the \field{avail_event} fields as described in
+\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}, \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and \ref{sec:Packed Virtqueues / Driver and Device Event Suppression}.
+
 
   \item[VIRTIO_F_VERSION_1(32)] This indicates compliance with this
     specification, giving a simple way to detect legacy devices or drivers.
@@ -5228,6 +5245,9 @@ Currently these device-independent feature bits defined:
   addresses in memory.  If this feature bit is set to 0, then the device emits
   physical addresses which are not translated further, even though an IOMMU
   may be present.
+  \item[VIRTIO_F_RING_PACKED(34)] This feature indicates
+  support for the packed virtqueue layout as described in
+  \ref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}.
 \end{description}
 
 \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
@@ -5241,6 +5261,8 @@ passed to the device into physical addresses in memory.  If
 VIRTIO_F_IOMMU_PLATFORM is not offered, then a driver MUST pass only physical
 addresses to the device.
 
+A driver SHOULD accept VIRTIO_F_RING_PACKED if it is offered.
+
 \devicenormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
 
 A device MUST offer VIRTIO_F_VERSION_1.  A device MAY fail to operate further
diff --git a/packed-ring.tex b/packed-ring.tex
new file mode 100644
index 0000000..213295b
--- /dev/null
+++ b/packed-ring.tex
@@ -0,0 +1,646 @@
+\section{Packed Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}
+
+Packed virtqueues is an alternative compact virtqueue layout using
+read-write memory, that is memory that is both read and written
+by both host and guest.
+
+Use of packed virtqueues is negotiated by the VIRTIO_F_RING_PACKED
+feature bit.
+
+Packed virtqueues support up to $2^{15}$ entries each.
+
+With current transports, virtqueues are located in guest memory
+allocated by driver.
+Each packed virtqueue consists of three parts:
+
+\begin{itemize}
+\item Descriptor Ring - occupies the Descriptor Area
+\item Driver Event Suppression - occupies the Driver Area
+\item Device Event Suppression - occupies the Device Area
+\end{itemize}
+
+Where Descriptor Ring in turn consists of descriptors,
+and where each descriptor can contain the following parts:
+
+\begin{itemize}
+\item Buffer ID
+\item Element Address
+\item Element Length
+\item Flags
+\end{itemize}
+
+A buffer consists of zero or more device-readable physically-contiguous
+elements followed by zero or more physically-contiguous
+device-writable elements (each buffer has at least one element).
+
+When the driver wants to send such a buffer to the device, it
+writes at least one available descriptor describing elements of
+the buffer into the Descriptor Ring.  The descriptor(s) are
+associated with a buffer by means of a Buffer ID stored within
+the descriptor.
+
+Driver then notifies the device. When the device has finished
+processing the buffer, it writes a used device descriptor
+including the Buffer ID into the Descriptor Ring (overwriting a
+driver descriptor previously made available), and sends an
+interrupt.
+
+Descriptor Ring is used in a circular manner: driver writes
+descriptors into the ring in order. After reaching end of ring,
+the next descriptor is placed at head of the ring.  Once ring is
+full of driver descriptors, driver stops sending new requests and
+waits for device to start processing descriptors and to write out
+some used descriptors before making new driver descriptors
+available.
+
+Similarly, device reads descriptors from the ring in order and
+detects that a driver descriptor has been made available.  As
+processing of descriptors is completed used descriptors are
+written by the device back into the ring.
+
+Note: after reading driver descriptors and starting their
+processing in order, device might complete their processing out
+of order.  Used device descriptors are written in the order
+in which their processing is complete.
+
+Device Event Suppression data structure is write-only by the
+device. It includes information for reducing the number of
+device events - i.e. driver notifications to device.
+
+Driver Event Suppression data structure is read-only by the
+device. It includes information for reducing the number of
+driver events - i.e. device interrupts to driver.
+
+\subsection{Driver and Device Ring Wrap Counters}
+\label{sec:Packed Virtqueues / Driver and Device Ring Wrap Counters}
+Each of the driver and the device are expected to maintain,
+internally, a single-bit ring wrap counter initialized to 1.
+
+The counter maintained by the driver is called the Driver
+Ring Wrap Counter. Driver changes the value of this counter
+each time it makes available the
+last descriptor in the ring (after making the last descriptor
+available).
+
+The counter maintained by the device is called the Device Ring Wrap
+Counter.  Device changes the value of this counter
+each time it uses the last descriptor in
+the ring (after marking the last descriptor used).
+
+It is easy to see that the Driver Ring Wrap Counter in the driver matches
+the Device Ring Wrap Counter in the device when both are processing the same
+descriptor, or when all available descriptors have been used.
+
+To mark a descriptor as available and used, both driver and
+device use the following two flags:
+\begin{lstlisting}
+#define VIRTQ_DESC_F_AVAIL     (1 << 7)
+#define VIRTQ_DESC_F_USED      (1 << 15)
+\end{lstlisting}
+
+To mark a descriptor as available, driver sets the
+VIRTQ_DESC_F_AVAIL bit in Flags to match the internal Driver
+Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_USED bit to match the
+\emph{inverse} value (i.e. to not match the internal Driver Ring
+Wrap Counter).
+
+To mark a descriptor as used, device sets the
+VIRTQ_DESC_F_USED bit in Flags to match the internal Device
+Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_AVAIL bit to match the
+\emph{same} value.
+
+Thus VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED bits are different
+for an available descriptor and equal for a used descriptor.
+
+\subsection{Polling of available and used descriptors}
+\label{sec:Packed Virtqueues / Polling of available and used descriptors}
+
+Writes of device and driver descriptors can generally be
+reordered, but each side (driver and device) are only required to
+poll (or test) a single location in memory: next device descriptor after
+the one they processed previously, in circular order.
+
+Sometimes device needs to only write out a single used descriptor
+after processing a batch of multiple available descriptors.  As
+described in more detail below, this can happen when using
+descriptor chaining or with in-order
+use of descriptors.  In this case, device writes out a used
+descriptor with buffer id of the last descriptor in the group.
+After processing the used descriptor, both device and driver then
+skip forward in the ring the number of the remaining descriptors
+in the group until processing (reading for the driver and writing
+for the device) the next used descriptor.
+
+\subsection{Write Flag}
+\label{sec:Packed Virtqueues / Write Flag}
+
+In an available descriptor, VIRTQ_DESC_F_WRITE bit within Flags
+is used to mark a descriptor as corresponding to a write-only or
+read-only element of a buffer.
+
+\begin{lstlisting}
+/* This marks a descriptor as device write-only (otherwise device read-only). */
+#define VIRTQ_DESC_F_WRITE     2
+\end{lstlisting}
+
+In a used descriptor, this bit is used to specify whether any
+data has been written by the device into any parts of the buffer.
+
+
+\subsection{Element Address and Length}
+\label{sec:Packed Virtqueues / Element Address and Length}
+
+In an available descriptor, Element Address corresponds to the
+physical address of the buffer element. The length of the element assumed
+to be physically contigious is stored in Element Length.
+
+In a used descriptor, Element Address is unused. Element Length
+specifies the length of the buffer that has been initialized
+(written to) by the device.
+
+Element length is reserved for used descriptors without the
+VIRTQ_DESC_F_WRITE flag, and is ignored by drivers.
+
+\subsection{Scatter-Gather Support}
+\label{sec:Packed Virtqueues / Scatter-Gather Support}
+
+Some drivers need an ability to supply a list of multiple buffer
+elements (also known as a scatter/gather list) with a request.
+Two optional features support this: descriptor
+chaining and indirect descriptors.
+
+If neither feature has been negotiated, each buffer is
+physically-contigious, either read-only or write-only and is
+described completely by a single descriptor.
+
+While unusual (most implementations either create all lists
+solely using non-indirect descriptors, or always use a single
+indirect element), if both features have been negotiated, mixing
+direct and direct descriptors in a ring is valid, as long as each
+list only contains descriptors of a given type.
+
+Scatter/gather lists only apply to available descriptors. A
+single used descriptor corresponds to the whole list.
+
+The device limits the number of descriptors in a list through a
+transport-specific and/or device-specific value. If not limited,
+the maximum number of descriptors in a list is the virt queue
+size.
+
+\subsection{Next Flag: Descriptor Chaining}
+\label{sec:Packed Virtqueues / Next Flag: Descriptor Chaining}
+
+The packed ring format allows driver to supply
+a scatter/gather list to the device
+by using multiple descriptors, and setting the VIRTQ_DESC_F_NEXT in
+Flags for all but the last available descriptor.
+
+\begin{lstlisting}
+/* This marks a buffer as continuing. */
+#define VIRTQ_DESC_F_NEXT   1
+\end{lstlisting}
+
+Buffer ID is included in the last descriptor in the list.
+
+The driver always makes the first descriptor in the list
+available after the rest of the list has been written out into
+the ring. This guarantees that the device will never observe a
+partial scatter/gather list in the ring.
+
+Note: all flags, including VIRTQ_DESC_F_AVAIL, VIRTQ_DESC_F_USED,
+VIRTQ_DESC_F_WRITE must be set/cleared correctly in all
+descriptors in the list, not just the first one.
+
+Device only writes out a single used descriptor for the whole
+list. It then skips forward according to the number of
+descriptors in the list. Driver needs to keep track of the size
+of the list corresponding to each buffer ID, to be able to skip
+to where the next used descriptor is written by the device.
+
+For example, if descriptors are used in the same order in which
+they are made available, this will result in the used descriptor
+overwriting the first available descriptor in the list, the used
+descriptor for the next list overwriting the first available
+descriptor in the next list, etc.
+
+VIRTQ_DESC_F_NEXT is reserved in used descriptors, and
+should be ignored by drivers.
+
+\subsection{Indirect Flag: Scatter-Gather Support}
+\label{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}
+
+Some devices benefit by concurrently dispatching a large number
+of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this. To increase
+ring capacity the driver can store a (read-only by the device) table of indirect
+descriptors anywhere in memory, and insert a descriptor in main
+virtqueue (with \field{Flags} bit VIRTQ_DESC_F_INDIRECT on) that refers to
+a buffer element
+containing this indirect descriptor table; \field{addr} and \field{len}
+refer to the indirect table address and length in bytes,
+respectively.
+\begin{lstlisting}
+/* This means the element contains a table of descriptors. */
+#define VIRTQ_DESC_F_INDIRECT   4
+\end{lstlisting}
+
+The indirect table layout structure looks like this
+(\field{len} is the Buffer Length of the descriptor that refers to this table,
+which is a variable):
+
+\begin{lstlisting}
+struct indirect_descriptor_table {
+        /* The actual descriptor structures (struct virtq_desc each) */
+        struct virtq_desc desc[len / sizeof(struct virtq_desc)];
+};
+\end{lstlisting}
+
+The first descriptor is located at start of the indirect
+descriptor table, additional indirect descriptors come
+immediately afterwards. \field{Flags} bit VIRTQ_DESC_F_WRITE is the
+only valid flag for descriptors in the indirect table. Others
+are reserved and are ignored by the device.
+Buffer ID is also reserved and is ignored by the device.
+
+In Descriptors with VIRTQ_DESC_F_INDIRECT set VIRTQ_DESC_F_WRITE
+is reserved and is ignored by the device.
+
+\subsection{Multi-buffer requests}
+\label{sec:Packed Virtqueues / Multi-descriptor batches}
+Some devices combine multiple buffers as part of processing of a
+single request.  These devices always mark the first descriptor
+in the request used after the rest of the descriptors in the
+request has been written out into the ring. This guarantees that
+the driver will never observe a partial request in the ring.
+
+
+\subsection{Driver and Device Event Suppression}
+\label{sec:Packed Virtqueues / Driver and Device Event Suppression}
+In many systems driver and device notifications involve
+significant overhead. To mitigate this overhead,
+each virtqueue includes two identical structures used for
+controlling notifications between device and driver.
+
+Driver Event Suppression structure is read-only by the
+device and controls the events sent by the device
+to the driver (e.g. interrupts).
+
+Device Event Suppression structure is read-only by
+the driver and controls the events sent by the driver
+to the device (e.g. IO).
+
+Each of these Event Suppression structures controls
+both Descriptor Ring events and structure events, and
+each includes the following fields:
+
+\begin{description}
+\item [Descriptor Ring Change Event Flags] Takes values:
+\begin{itemize}
+\item 00b enable events
+\item 01b disable events
+\item 10b enable events for a specific descriptor
+(as specified by Descriptor Ring Change Event Offset/Wrap Counter).
+Only valid if VIRTIO_F_RING_EVENT_IDX has been negotiated.
+\item 11b reserved
+\end{itemize}
+\item [Descriptor Ring Change Event Offset] If Event Flags set to descriptor
+specific event: offset within the ring (in units of descriptor
+size). Event will only trigger when this descriptor is
+made available/used respectively.
+\item [Descriptor Ring Change Event Wrap Counter] If Event Flags set to descriptor
+specific event: offset within the ring (in units of descriptor
+size). Event will only trigger when Ring Wrap Counter
+matches this value and a descriptor is
+made available/used respectively.
+\end{description}
+
+After writing out some descriptors, both device and driver
+are expected to consult the relevant structure to find out
+whether interrupt/notification should be sent.
+
+\subsubsection{Structure Size and Alignment}
+\label{sec:Packed Virtqueues / Structure Size and Alignment}
+
+Each part of the virtqueue is physically-contiguous in guest memory,
+and has different alignment requirements.
+
+The memory aligment and size requirements, in bytes, of each part of the
+virtqueue are summarized in the following table:
+
+\begin{tabular}{|l|l|l|}
+\hline
+Virtqueue Part    & Alignment & Size \\
+\hline \hline
+Descriptor Ring  & 16        & $16 * $(Queue Size) \\
+\hline
+Device Event Suppression    & 4         & 4 \\
+ \hline
+Driver Event Suppression         & 4         & 4 \\
+ \hline
+\end{tabular}
+
+The Alignment column gives the minimum alignment for each part
+of the virtqueue.
+
+The Size column gives the total number of bytes for each
+part of the virtqueue.
+
+Queue Size corresponds to the maximum number of descriptors in the
+virtqueue\footnote{For example, if Queue Size is 4 then at most 4 buffers
+can be queued at any given time.}.  Queue Size value does not
+have to be a power of 2 unless enforced by the transport.
+
+\drivernormative{\subsection}{Virtqueues}{Basic Facilities of a
+Virtio Device / Packed Virtqueues}
+The driver MUST ensure that the physical address of the first byte
+of each virtqueue part is a multiple of the specified alignment value
+in the above table.
+
+\devicenormative{\subsection}{Virtqueues}{Basic Facilities of a
+Virtio Device / Packed Virtqueues}
+The device MUST start processing driver descriptors in the order
+in which they appear in the ring.
+The device MUST start writing device descriptors into the ring in
+the order in which they complete.
+Device MAY reorder descriptor writes once they are started.
+
+\subsection{The Virtqueue Descriptor Format}\label{sec:Basic
+Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue
+Descriptor Format}
+
+The available descriptor refers to the buffers the driver is sending
+to the device. \field{addr} is a physical address, and the
+descriptor is identified with a buffer using the \field{id} field.
+
+\begin{lstlisting}
+struct virtq_desc {
+        /* Buffer Address. */
+        le64 addr;
+        /* Buffer Length. */
+        le32 len;
+        /* Buffer ID. */
+        le16 id;
+        /* The flags depending on descriptor type. */
+        le16 flags;
+};
+\end{lstlisting}
+
+The descriptor ring is zero-initialized.
+
+\subsection{Event Suppression Structure Format}\label{sec:Basic
+Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
+Format}
+
+The following structure is used to reduce the number of
+notifications sent between driver and device.
+
+\begin{lstlisting}
+__le16 desc_event_off : 15; /* Descriptor Event Offset */
+int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
+__le16 desc_event_flags : 2; /* Descriptor Event Flags */
+\end{lstlisting}
+
+\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
+A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
+read a device-writable buffer.
+A device MUST NOT use a descriptor unless it observes
+VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
+A device MUST NOT change a descriptor after changing it's
+VIRTQ_DESC_F_USED bit in its \field{flags}.
+
+\drivernormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / PAcked Virtqueues / The Virtqueue Descriptor Table}
+A driver MUST NOT change a descriptor unless it observes
+VIRTQ_DESC_F_USED bit in its \field{flags} being changed.
+A driver MUST NOT change a descriptor after changing
+VIRTQ_DESC_F_USED bit in its \field{flags}.
+When notifying the device, driver MUST set
+\field{next_off} and
+\field{next_wrap} to match the next descriptor
+not yet made available to the device.
+A driver MAY send multiple notifications without making
+any new descriptors available to the device.
+
+\drivernormative{\subsection}{Scatter-Gather Support}{Basic Facilities of a
+Virtio Device / Packed Virtqueues / Scatter-Gather Support}
+A driver MUST NOT create a descriptor list longer than allowed
+by the device.
+
+A driver MUST NOT create a descriptor list longer than the Queue
+Size.
+
+This implies that loops in the descriptor list are forbidden!
+
+The driver MUST place any device-writable descriptor elements after
+any device-readable descriptor elements.
+
+A driver MUST NOT depend on the device to use more descriptors
+to be able to write out all descriptors in a list. A driver
+MUST make sure there's enough space in the ring
+for the whole list before making the first descriptor in the list
+available to the device.
+
+A driver MUST NOT make the first descriptor in the list
+available before initializing the rest of the descriptors.
+
+\devicenormative{\subsection}{Scatter-Gather Support}{Basic Facilities of a
+Virtio Device / Packed Virtqueues / Scatter-Gather Support}
+The device MUST use descriptors in a list chained by the
+VIRTQ_DESC_F_NEXT flag in the same order that they
+were made available by the driver.
+
+The device MAY limit the number of buffers it will allow in a
+list.
+
+\drivernormative{\subsection}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
+The driver MUST NOT set the DESC_F_INDIRECT flag unless the
+VIRTIO_F_INDIRECT_DESC feature was negotiated.   The driver MUST NOT
+set any flags except DESC_F_WRITE within an indirect descriptor.
+
+A driver MUST NOT create a descriptor chain longer than allowed
+by the device.
+
+A driver MUST NOT write direct descriptors with
+DESC_F_INDIRECT set in a scatter-gather list linked by
+VIRTQ_DESC_F_NEXT.
+\field{flags}.
+
+\subsection{Virtqueue Operation}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Virtqueue Operation}
+
+There are two parts to virtqueue operation: supplying new
+available buffers to the device, and processing used buffers from
+the device.
+
+What follows is the requirements of each of these two parts
+when using the packed virtqueue format in more detail.
+
+\subsection{Supplying Buffers to The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device}
+
+The driver offers buffers to one of the device's virtqueues as follows:
+
+\begin{enumerate}
+\item The driver places the buffer into free descriptor in the Descriptor Ring.
+
+\item The driver performs a suitable memory barrier to ensure that it updates
+  the descriptor(s) before checking for notification suppression.
+
+\item If notifications are not suppressed, the driver notifies the device
+    of the new available buffers.
+\end{enumerate}
+
+What follows is the requirements of each stage in more detail.
+
+\subsubsection{Placing Available Buffers Into The Descriptor Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Placing Available Buffers Into The Descriptor Ring}
+
+For each buffer element, b:
+
+\begin{enumerate}
+\item Get the next descriptor table entry, d
+\item Get the next free buffer id value
+\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 Set \field{d.id} to the buffer id
+\item Calculate the flags as follows:
+\begin{enumerate}
+\item If b is device-writable, set the VIRTQ_DESC_F_WRITE bit to 1, otherwise 0
+\item Set VIRTQ_DESC_F_AVAIL bit to the current value of the Driver Ring Wrap Counter
+\item Set VIRTQ_DESC_F_USED bit to inverse value
+\end{enumerate}
+\item Perform a memory barrier to ensure that the descriptor has
+      been initialized
+\item Set \field{d.flags} to the calculated flags value
+\item If d is the last descriptor in the ring, toggle the
+      Driver Ring Wrap Counter
+\item Otherwise, increment d to point at the next descriptor
+\end{enumerate}
+
+This makes a single descriptor buffer available. However, in
+general the driver MAY make use of a batch of descriptors as part
+of a single request. In that case, it defers updating
+the descriptor flags for the first descriptor
+(and the previous memory barrier) until after the rest of
+the descriptors have been initialized.
+
+Once the descriptor \field{flags} is updated by the driver, this exposes the
+descriptor and its contents.  The device MAY
+access the descriptor and any following descriptors the driver created and the
+memory they refer to immediately.
+
+\drivernormative{\paragraph}{Updating flags}{Basic Facilities of
+a Virtio Device / Packed Virtqueues / Supplying Buffers to The
+Device / Updating flags}
+The driver MUST perform a suitable memory barrier before the
+\field{flags} update, to ensure the
+device sees the most up-to-date copy.
+
+\subsubsection{Notifying The Device}\label{sec:Basic Facilities
+of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
+
+The actual method of device notification is bus-specific, but generally
+it can be expensive.  So the device MAY suppress such notifications if it
+doesn't need them, using the Driver Event Suppression structure
+as detailed in section \ref{sec:Basic
+Facilities of a Virtio Device / Packed Virtqueues / Event
+Suppression Structure Format}.
+
+The driver has to be careful to expose the new \field{flags}
+value before checking if notifications are suppressed.
+
+\subsubsection{Implementation Example}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Implementation Example}
+
+Below is an example driver code. It does not attempt to reduce
+the number of device interrupts, neither does it support
+the VIRTIO_F_RING_EVENT_IDX feature.
+
+\begin{lstlisting}
+
+first = vq->next_avail;
+id = alloc_id(vq);
+
+for (each buffer element b) {
+        vq->desc[vq->next_avail].address = get_addr(b);
+        vq->desc[vq->next_avail].len = get_len(b);
+        init_desc(vq->next_avail, b);
+        avail = vq->avail_wrap_count;
+        used = !vq->avail_wrap_count;
+        f = get_flags(b) | (avail << VIRTQ_DESC_F_AVAIL) | (used << VIRTQ_DESC_F_USED);
+	/* Don't mark the 1st descriptor available until all of them are ready. */
+        if (vq->next_avail == first) {
+                flags = f;
+        } else {
+                vq->desc[vq->next_avail].flags = f;
+        }
+
+	vq->next_avail++;
+
+	if (vq->next_avail >= vq->size) {
+		vq->next_avail = 0;
+		vq->avail_wrap_count \^= 1;
+	}
+
+
+}
+/* ID included in the last descriptor in the list */
+vq->desc[vq->next_avail].id = id;
+write_memory_barrier();
+vq->desc[first].flags = flags;
+
+memory_barrier();
+
+if (vq->device_event.flags != 0x2) {
+        notify_device(vq);
+}
+
+\end{lstlisting}
+
+
+\drivernormative{\paragraph}{Notifying The Device}{Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
+The driver MUST perform a suitable memory barrier before reading
+the Driver Event Suppression structure, to avoid missing a notification.
+
+\subsection{Receiving Used Buffers From The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Receiving Used Buffers From The Device}
+
+Once the device has used buffers referred to by a descriptor (read from or written to them, or
+parts of both, depending on the nature of the virtqueue and the
+device), it interrupts the driver
+as detailed in section \ref{sec:Basic
+Facilities of a Virtio Device / Packed Virtqueues / Event
+Suppression Structure Format}.
+
+\begin{note}
+For optimal performance, a driver MAY disable interrupts while processing
+the used buffers, but beware the problem of missing interrupts between
+emptying the ring and reenabling interrupts.  This is usually handled by
+re-checking for more used buffers after interrups are re-enabled:
+\end{note}
+
+\begin{lstlisting}
+vq->driver_event.flags = 0x2;
+
+for (;;) {
+        struct virtq_desc *d = vq->desc[vq->next_used];
+
+        flags = d->flags;
+        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
+        bool used = flags & (1 << VIRTQ_DESC_F_USED);
+
+        if (avail != used) {
+                vq->driver_event.flags = 0x1;
+                memory_barrier();
+
+                flags = d->flags;
+                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
+                bool used = flags & (1 << VIRTQ_DESC_F_USED);
+                if (avail != used) {
+                        break;
+                }
+
+                vq->driver_event.flags = 0x2;
+        }
+
+	read_memory_barrier();
+        process_buffer(d);
+        vq->next_used++;
+        if (vq->next_used >= vq->size) {
+                vq->next_used = 0;
+        }
+}
+\end{lstlisting}
-- 
MST

[virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Cornelia Huck]

On Fri, 16 Feb 2018 09:24:12 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Performance analysis of this is in my kvm forum 2016 presentation.  The
> idea is to have a r/w descriptor in a ring structure, replacing the used
> and available ring, index and descriptor buffer.
> 
> This is also easier for devices to implement than the 1.0 layout.
> Several more enhancements will be necessary to actually make this
> efficient for devices to use.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  content.tex     |  28 ++-
>  packed-ring.tex | 646 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 671 insertions(+), 3 deletions(-)
>  create mode 100644 packed-ring.tex

I'm at the point where my eyes glaze over when I try to look at this
yet again, so you won't get a r-b from me, but

Acked-by: Cornelia Huck <cohuck@redhat.com>

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Tiwei Bie]

On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
[...]
> +\subsection{Scatter-Gather Support}
> +\label{sec:Packed Virtqueues / Scatter-Gather Support}
> +
> +Some drivers need an ability to supply a list of multiple buffer
> +elements (also known as a scatter/gather list) with a request.
> +Two optional features support this: descriptor
> +chaining and indirect descriptors.
> +
> +If neither feature has been negotiated, each buffer is
> +physically-contigious, either read-only or write-only and is
> +described completely by a single descriptor.

Based on the updates in "Descriptor Chaining" section
and the below note in cover letter:

- dropped _F_DESC_LIST, 1.0 includes this unconditionally, we
  can do same

Descriptor chaining is always available.

> +
[...]
> +\subsection{Event Suppression Structure Format}\label{sec:Basic
> +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> +Format}
> +
> +The following structure is used to reduce the number of
> +notifications sent between driver and device.
> +
> +\begin{lstlisting}
> +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */

Is this `int` a typo?

> +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> +\end{lstlisting}
[...]
> +\subsubsection{Implementation Example}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Implementation Example}
> +
> +Below is an example driver code. It does not attempt to reduce
> +the number of device interrupts, neither does it support
> +the VIRTIO_F_RING_EVENT_IDX feature.
> +
> +\begin{lstlisting}
> +
> +first = vq->next_avail;
> +id = alloc_id(vq);
> +
> +for (each buffer element b) {
> +        vq->desc[vq->next_avail].address = get_addr(b);
> +        vq->desc[vq->next_avail].len = get_len(b);
> +        init_desc(vq->next_avail, b);
> +        avail = vq->avail_wrap_count;
> +        used = !vq->avail_wrap_count;
> +        f = get_flags(b) | (avail << VIRTQ_DESC_F_AVAIL) | (used << VIRTQ_DESC_F_USED);

In this version, above two flags are defined as:

#define VIRTQ_DESC_F_AVAIL     (1 << 7)
#define VIRTQ_DESC_F_USED      (1 << 15)

So we couldn't use them to shift the bit like this.

> +	/* Don't mark the 1st descriptor available until all of them are ready. */
> +        if (vq->next_avail == first) {
> +                flags = f;
> +        } else {
> +                vq->desc[vq->next_avail].flags = f;
> +        }
> +
> +	vq->next_avail++;
> +
> +	if (vq->next_avail >= vq->size) {
> +		vq->next_avail = 0;
> +		vq->avail_wrap_count \^= 1;
> +	}

Maybe it's better to not mix using tab and space in
this example code.

> +
> +
> +}
> +/* ID included in the last descriptor in the list */
> +vq->desc[vq->next_avail].id = id;

Maybe it should be something like this:

vq->desc[prev].id = id;

Otherwise, the other fields (e.g. flags) of this desc (the
vq->desc[vq->next_avail]) also need to be updated.

> +write_memory_barrier();
> +vq->desc[first].flags = flags;
> +
> +memory_barrier();
> +
> +if (vq->device_event.flags != 0x2) {

Maybe it should be:

if (vq->device_event.flags != 0x1) {

As the flags definitions in this version are:

00b enable events
01b disable events
10b enable events for a specific descriptor
    (as specified by Descriptor Ring Change Event Offset/Wrap Counter).
    Only valid if VIRTIO_F_RING_EVENT_IDX has been negotiated.
11b reserved

> +        notify_device(vq);
> +}
> +
> +\end{lstlisting}
> +
> +
> +\drivernormative{\paragraph}{Notifying The Device}{Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
> +The driver MUST perform a suitable memory barrier before reading
> +the Driver Event Suppression structure, to avoid missing a notification.
> +
> +\subsection{Receiving Used Buffers From The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Receiving Used Buffers From The Device}
> +
> +Once the device has used buffers referred to by a descriptor (read from or written to them, or
> +parts of both, depending on the nature of the virtqueue and the
> +device), it interrupts the driver
> +as detailed in section \ref{sec:Basic
> +Facilities of a Virtio Device / Packed Virtqueues / Event
> +Suppression Structure Format}.
> +
> +\begin{note}
> +For optimal performance, a driver MAY disable interrupts while processing
> +the used buffers, but beware the problem of missing interrupts between
> +emptying the ring and reenabling interrupts.  This is usually handled by
> +re-checking for more used buffers after interrups are re-enabled:
> +\end{note}
> +
> +\begin{lstlisting}
> +vq->driver_event.flags = 0x2;

If my understanding is correct, this is to disable interrupt.
So maybe it should be:

vq->driver_event.flags = 0x1;

> +
> +for (;;) {
> +        struct virtq_desc *d = vq->desc[vq->next_used];
> +
> +        flags = d->flags;
> +        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> +        bool used = flags & (1 << VIRTQ_DESC_F_USED);

We couldn't use them to shift the bit like this in this version.

> +
> +        if (avail != used) {
> +                vq->driver_event.flags = 0x1;

If my understanding is correct, this is to enable interrupt.
So maybe it should be:

vq->driver_event.flags = 0x0;

> +                memory_barrier();
> +
> +                flags = d->flags;
> +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> +                bool used = flags & (1 << VIRTQ_DESC_F_USED);

We couldn't use them to shift the bit like this in this version.

> +                if (avail != used) {
> +                        break;
> +                }
> +
> +                vq->driver_event.flags = 0x2;

If my understanding is correct, this is to disable interrupt.
So maybe it should be:

vq->driver_event.flags = 0x1;

> +        }
> +
> +	read_memory_barrier();
> +        process_buffer(d);
> +        vq->next_used++;
> +        if (vq->next_used >= vq->size) {
> +                vq->next_used = 0;
> +        }
> +}
> +\end{lstlisting}
> -- 
> MST
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
> [...]
> > +\subsection{Scatter-Gather Support}
> > +\label{sec:Packed Virtqueues / Scatter-Gather Support}
> > +
> > +Some drivers need an ability to supply a list of multiple buffer
> > +elements (also known as a scatter/gather list) with a request.
> > +Two optional features support this: descriptor
> > +chaining and indirect descriptors.
> > +
> > +If neither feature has been negotiated, each buffer is
> > +physically-contigious, either read-only or write-only and is
> > +described completely by a single descriptor.
> 
> Based on the updates in "Descriptor Chaining" section
> and the below note in cover letter:
> 
> - dropped _F_DESC_LIST, 1.0 includes this unconditionally, we
>   can do same
> 
> Descriptor chaining is always available.

That's right - I should fix this.

> > +
> [...]
> > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > +Format}
> > +
> > +The following structure is used to reduce the number of
> > +notifications sent between driver and device.
> > +
> > +\begin{lstlisting}
> > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> 
> Is this `int` a typo?

It's a single bit so I think it does not matter.
What type would you like me to use instead?

> > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > +\end{lstlisting}
> [...]
> > +\subsubsection{Implementation Example}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Implementation Example}
> > +
> > +Below is an example driver code. It does not attempt to reduce
> > +the number of device interrupts, neither does it support
> > +the VIRTIO_F_RING_EVENT_IDX feature.
> > +
> > +\begin{lstlisting}
> > +
> > +first = vq->next_avail;
> > +id = alloc_id(vq);
> > +
> > +for (each buffer element b) {
> > +        vq->desc[vq->next_avail].address = get_addr(b);
> > +        vq->desc[vq->next_avail].len = get_len(b);
> > +        init_desc(vq->next_avail, b);
> > +        avail = vq->avail_wrap_count;
> > +        used = !vq->avail_wrap_count;
> > +        f = get_flags(b) | (avail << VIRTQ_DESC_F_AVAIL) | (used << VIRTQ_DESC_F_USED);
> 
> In this version, above two flags are defined as:
> 
> #define VIRTQ_DESC_F_AVAIL     (1 << 7)
> #define VIRTQ_DESC_F_USED      (1 << 15)
> 
> So we couldn't use them to shift the bit like this.

You are right. I guess we should change all flags to be bit numbers.

> > +	/* Don't mark the 1st descriptor available until all of them are ready. */
> > +        if (vq->next_avail == first) {
> > +                flags = f;
> > +        } else {
> > +                vq->desc[vq->next_avail].flags = f;
> > +        }
> > +
> > +	vq->next_avail++;
> > +
> > +	if (vq->next_avail >= vq->size) {
> > +		vq->next_avail = 0;
> > +		vq->avail_wrap_count \^= 1;
> > +	}
> 
> Maybe it's better to not mix using tab and space in
> this example code.

I'm not sure it matters for latex but I agree we should be
consistent.

> > +
> > +
> > +}
> > +/* ID included in the last descriptor in the list */
> > +vq->desc[vq->next_avail].id = id;
> 
> Maybe it should be something like this:
> 
> vq->desc[prev].id = id;
> 
> Otherwise, the other fields (e.g. flags) of this desc (the
> vq->desc[vq->next_avail]) also need to be updated.
> 
> > +write_memory_barrier();
> > +vq->desc[first].flags = flags;
> > +
> > +memory_barrier();
> > +
> > +if (vq->device_event.flags != 0x2) {
> 
> Maybe it should be:
> 
> if (vq->device_event.flags != 0x1) {
> 
> As the flags definitions in this version are:
> 
> 00b enable events
> 01b disable events
> 10b enable events for a specific descriptor
>     (as specified by Descriptor Ring Change Event Offset/Wrap Counter).
>     Only valid if VIRTIO_F_RING_EVENT_IDX has been negotiated.
> 11b reserved

I'll recheck it and reply to above two separately.


> > +        notify_device(vq);
> > +}
> > +
> > +\end{lstlisting}
> > +
> > +
> > +\drivernormative{\paragraph}{Notifying The Device}{Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
> > +The driver MUST perform a suitable memory barrier before reading
> > +the Driver Event Suppression structure, to avoid missing a notification.
> > +
> > +\subsection{Receiving Used Buffers From The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Receiving Used Buffers From The Device}
> > +
> > +Once the device has used buffers referred to by a descriptor (read from or written to them, or
> > +parts of both, depending on the nature of the virtqueue and the
> > +device), it interrupts the driver
> > +as detailed in section \ref{sec:Basic
> > +Facilities of a Virtio Device / Packed Virtqueues / Event
> > +Suppression Structure Format}.
> > +
> > +\begin{note}
> > +For optimal performance, a driver MAY disable interrupts while processing
> > +the used buffers, but beware the problem of missing interrupts between
> > +emptying the ring and reenabling interrupts.  This is usually handled by
> > +re-checking for more used buffers after interrups are re-enabled:
> > +\end{note}
> > +
> > +\begin{lstlisting}
> > +vq->driver_event.flags = 0x2;
> 
> If my understanding is correct, this is to disable interrupt.
> So maybe it should be:
> 
> vq->driver_event.flags = 0x1;

I'll check.

> > +
> > +for (;;) {
> > +        struct virtq_desc *d = vq->desc[vq->next_used];
> > +
> > +        flags = d->flags;
> > +        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> > +        bool used = flags & (1 << VIRTQ_DESC_F_USED);
> 
> We couldn't use them to shift the bit like this in this version.
> 
> > +
> > +        if (avail != used) {
> > +                vq->driver_event.flags = 0x1;
> 
> If my understanding is correct, this is to enable interrupt.
> So maybe it should be:
> 
> vq->driver_event.flags = 0x0;
> 
> > +                memory_barrier();
> > +
> > +                flags = d->flags;
> > +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> > +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
> 
> We couldn't use them to shift the bit like this in this version.
> 
> > +                if (avail != used) {
> > +                        break;
> > +                }
> > +
> > +                vq->driver_event.flags = 0x2;
> 
> If my understanding is correct, this is to disable interrupt.
> So maybe it should be:
> 
> vq->driver_event.flags = 0x1;


Thanks for all the comments, will address.

> > +        }
> > +
> > +	read_memory_barrier();
> > +        process_buffer(d);
> > +        vq->next_used++;
> > +        if (vq->next_used >= vq->size) {
> > +                vq->next_used = 0;
> > +        }
> > +}
> > +\end{lstlisting}
> > -- 
> > MST
> > 

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Tiwei Bie]

On Sun, Feb 25, 2018 at 08:49:10PM +0200, Michael S. Tsirkin wrote:
> On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> > On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
[...]
> > > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > > +Format}
> > > +
> > > +The following structure is used to reduce the number of
> > > +notifications sent between driver and device.
> > > +
> > > +\begin{lstlisting}
> > > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > 
> > Is this `int` a typo?
> 
> It's a single bit so I think it does not matter.
> What type would you like me to use instead?

It looks a bit strange to use different types here, and
that's why I asked. If there is no particular reason to
use `int` here, maybe it's better to keep using __le16.

Besides, just for fun. For C language, I checked gcc and
clang. It seems that `int desc_event_wrap:1;` is a signed
type. So, e.g. `p->desc_event_wrap == 1` is always false.

Best regards,
Tiwei Bie

> 
> > > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > > +\end{lstlisting}
[...]

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Mon, Feb 26, 2018 at 06:51:11PM +0800, Tiwei Bie wrote:
> On Sun, Feb 25, 2018 at 08:49:10PM +0200, Michael S. Tsirkin wrote:
> > On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> > > On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
> [...]
> > > > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > > > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > > > +Format}
> > > > +
> > > > +The following structure is used to reduce the number of
> > > > +notifications sent between driver and device.
> > > > +
> > > > +\begin{lstlisting}
> > > > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > > > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > > 
> > > Is this `int` a typo?
> > 
> > It's a single bit so I think it does not matter.
> > What type would you like me to use instead?
> 
> It looks a bit strange to use different types here, and
> that's why I asked. If there is no particular reason to
> use `int` here, maybe it's better to keep using __le16.
> 
> Besides, just for fun. For C language, I checked gcc and
> clang. It seems that `int desc_event_wrap:1;` is a signed
> type. So, e.g. `p->desc_event_wrap == 1` is always false.
> 
> Best regards,
> Tiwei Bie

I'll switch to u8 here, IMHO le16 for a single bit
is really confusing. There's no byte order for a single byte.

> > 
> > > > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > > > +\end{lstlisting}
> [...]

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Tiwei Bie]

On Mon, Feb 26, 2018 at 10:38:13PM +0200, Michael S. Tsirkin wrote:
> On Mon, Feb 26, 2018 at 06:51:11PM +0800, Tiwei Bie wrote:
> > On Sun, Feb 25, 2018 at 08:49:10PM +0200, Michael S. Tsirkin wrote:
> > > On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> > > > On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
> > [...]
> > > > > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > > > > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > > > > +Format}
> > > > > +
> > > > > +The following structure is used to reduce the number of
> > > > > +notifications sent between driver and device.
> > > > > +
> > > > > +\begin{lstlisting}
> > > > > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > > > > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > > > 
> > > > Is this `int` a typo?
> > > 
> > > It's a single bit so I think it does not matter.
> > > What type would you like me to use instead?
> > 
> > It looks a bit strange to use different types here, and
> > that's why I asked. If there is no particular reason to
> > use `int` here, maybe it's better to keep using __le16.
> > 
> > Besides, just for fun. For C language, I checked gcc and
> > clang. It seems that `int desc_event_wrap:1;` is a signed
> > type. So, e.g. `p->desc_event_wrap == 1` is always false.
> > 
> > Best regards,
> > Tiwei Bie
> 
> I'll switch to u8 here, IMHO le16 for a single bit
> is really confusing. There's no byte order for a single byte.

Sorry, I just realized that I misunderstood your point
previously.. Just to double check, `desc_event_off` and
`desc_event_wrap` are not in the same 2 bytes?

Previously I thought both of them are in the first 2
bytes. As it said it's a structure, and the fields are
defined in a way very similar to the bit field in C.

In C,

struct {
	__le16 desc_event_off : 15;
	int    desc_event_wrap : 1;
	__le16 desc_event_flags : 2;
};

struct {
	__le16 desc_event_off : 15;
	__le16 desc_event_wrap : 1;
	__le16 desc_event_flags : 2;
};

struct {
	__le16 desc_event_off : 15,
	       desc_event_wrap : 1;
	__le16 desc_event_flags : 2;
};

All above means `desc_event_off` and `desc_event_wrap`
are in the first 2 bytes. So I thought the `int` is a
typo. And I thought they are in the first 2 bytes (which
is little-endian).

Best regards,
Tiwei Bie

> 
> > > 
> > > > > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > > > > +\end{lstlisting}
> > [...]

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Tue, Feb 27, 2018 at 09:49:28AM +0800, Tiwei Bie wrote:
> On Mon, Feb 26, 2018 at 10:38:13PM +0200, Michael S. Tsirkin wrote:
> > On Mon, Feb 26, 2018 at 06:51:11PM +0800, Tiwei Bie wrote:
> > > On Sun, Feb 25, 2018 at 08:49:10PM +0200, Michael S. Tsirkin wrote:
> > > > On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> > > > > On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
> > > [...]
> > > > > > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > > > > > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > > > > > +Format}
> > > > > > +
> > > > > > +The following structure is used to reduce the number of
> > > > > > +notifications sent between driver and device.
> > > > > > +
> > > > > > +\begin{lstlisting}
> > > > > > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > > > > > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > > > > 
> > > > > Is this `int` a typo?
> > > > 
> > > > It's a single bit so I think it does not matter.
> > > > What type would you like me to use instead?
> > > 
> > > It looks a bit strange to use different types here, and
> > > that's why I asked. If there is no particular reason to
> > > use `int` here, maybe it's better to keep using __le16.
> > > 
> > > Besides, just for fun. For C language, I checked gcc and
> > > clang. It seems that `int desc_event_wrap:1;` is a signed
> > > type. So, e.g. `p->desc_event_wrap == 1` is always false.
> > > 
> > > Best regards,
> > > Tiwei Bie
> > 
> > I'll switch to u8 here, IMHO le16 for a single bit
> > is really confusing. There's no byte order for a single byte.
> 
> Sorry, I just realized that I misunderstood your point
> previously.. Just to double check, `desc_event_off` and
> `desc_event_wrap` are not in the same 2 bytes?
> 
> Previously I thought both of them are in the first 2
> bytes. As it said it's a structure, and the fields are
> defined in a way very similar to the bit field in C.
> 
> In C,
> 
> struct {
> 	__le16 desc_event_off : 15;
> 	int    desc_event_wrap : 1;
> 	__le16 desc_event_flags : 2;
> };
> 
> struct {
> 	__le16 desc_event_off : 15;
> 	__le16 desc_event_wrap : 1;
> 	__le16 desc_event_flags : 2;
> };
> 
> struct {
> 	__le16 desc_event_off : 15,
> 	       desc_event_wrap : 1;
> 	__le16 desc_event_flags : 2;
> };
> 
> All above means `desc_event_off` and `desc_event_wrap`
> are in the first 2 bytes. So I thought the `int` is a
> typo. And I thought they are in the first 2 bytes (which
> is little-endian).
>
> Best regards,
> Tiwei Bie

Yes but desc_event_wrap itself is completely within the
second byte. So the question of byte-order does not arise.

Right, and above is also identical to:

 struct {
 	__le16 desc_event_off : 15,
 	u8     desc_event_wrap : 1;
 	__le16 desc_event_flags : 2;
 };

introduction explains:

\item[u8, u16, u32, u64] An unsigned integer of the specified length in bits.

\item[le16, le32, le64] An unsigned integer of the specified length in bits,
in little-endian byte order.



> > 
> > > > 
> > > > > > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > > > > > +\end{lstlisting}
> > > [...]

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Tiwei Bie]

On Tue, Feb 27, 2018 at 10:17:17PM +0200, Michael S. Tsirkin wrote:
> On Tue, Feb 27, 2018 at 09:49:28AM +0800, Tiwei Bie wrote:
> > On Mon, Feb 26, 2018 at 10:38:13PM +0200, Michael S. Tsirkin wrote:
> > > On Mon, Feb 26, 2018 at 06:51:11PM +0800, Tiwei Bie wrote:
> > > > On Sun, Feb 25, 2018 at 08:49:10PM +0200, Michael S. Tsirkin wrote:
> > > > > On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> > > > > > On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
> > > > [...]
> > > > > > > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > > > > > > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > > > > > > +Format}
> > > > > > > +
> > > > > > > +The following structure is used to reduce the number of
> > > > > > > +notifications sent between driver and device.
> > > > > > > +
> > > > > > > +\begin{lstlisting}
> > > > > > > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > > > > > > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > > > > > 
> > > > > > Is this `int` a typo?
> > > > > 
> > > > > It's a single bit so I think it does not matter.
> > > > > What type would you like me to use instead?
> > > > 
> > > > It looks a bit strange to use different types here, and
> > > > that's why I asked. If there is no particular reason to
> > > > use `int` here, maybe it's better to keep using __le16.
> > > > 
> > > > Besides, just for fun. For C language, I checked gcc and
> > > > clang. It seems that `int desc_event_wrap:1;` is a signed
> > > > type. So, e.g. `p->desc_event_wrap == 1` is always false.
> > > > 
> > > > Best regards,
> > > > Tiwei Bie
> > > 
> > > I'll switch to u8 here, IMHO le16 for a single bit
> > > is really confusing. There's no byte order for a single byte.
> > 
> > Sorry, I just realized that I misunderstood your point
> > previously.. Just to double check, `desc_event_off` and
> > `desc_event_wrap` are not in the same 2 bytes?
> > 
> > Previously I thought both of them are in the first 2
> > bytes. As it said it's a structure, and the fields are
> > defined in a way very similar to the bit field in C.
> > 
> > In C,
> > 
> > struct {
> > 	__le16 desc_event_off : 15;
> > 	int    desc_event_wrap : 1;
> > 	__le16 desc_event_flags : 2;
> > };
> > 
> > struct {
> > 	__le16 desc_event_off : 15;
> > 	__le16 desc_event_wrap : 1;
> > 	__le16 desc_event_flags : 2;
> > };
> > 
> > struct {
> > 	__le16 desc_event_off : 15,
> > 	       desc_event_wrap : 1;
> > 	__le16 desc_event_flags : 2;
> > };
> > 
> > All above means `desc_event_off` and `desc_event_wrap`
> > are in the first 2 bytes. So I thought the `int` is a
> > typo. And I thought they are in the first 2 bytes (which
> > is little-endian).
> >
> > Best regards,
> > Tiwei Bie
> 
> Yes but desc_event_wrap itself is completely within the
> second byte. So the question of byte-order does not arise.
> 
> Right, and above is also identical to:
> 
>  struct {
>  	__le16 desc_event_off : 15,
>  	u8     desc_event_wrap : 1;
>  	__le16 desc_event_flags : 2;
>  };
> 
> introduction explains:
> 
> \item[u8, u16, u32, u64] An unsigned integer of the specified length in bits.
> 
> \item[le16, le32, le64] An unsigned integer of the specified length in bits,
> in little-endian byte order.
> 

I've got your point now. Thanks! ;-)
BTW, maybe it's better to remove the `__` prefix for
`__le16` to keep consistency.

Best regards,
Tiwei Bie

> 
> 
> > > 
> > > > > 
> > > > > > > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > > > > > > +\end{lstlisting}
> > > > [...]

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Wed, Feb 28, 2018 at 05:19:15PM +0800, Tiwei Bie wrote:
> On Tue, Feb 27, 2018 at 10:17:17PM +0200, Michael S. Tsirkin wrote:
> > On Tue, Feb 27, 2018 at 09:49:28AM +0800, Tiwei Bie wrote:
> > > On Mon, Feb 26, 2018 at 10:38:13PM +0200, Michael S. Tsirkin wrote:
> > > > On Mon, Feb 26, 2018 at 06:51:11PM +0800, Tiwei Bie wrote:
> > > > > On Sun, Feb 25, 2018 at 08:49:10PM +0200, Michael S. Tsirkin wrote:
> > > > > > On Sat, Feb 24, 2018 at 01:17:08PM +0800, Tiwei Bie wrote:
> > > > > > > On Fri, Feb 16, 2018 at 09:24:12AM +0200, Michael S. Tsirkin wrote:
> > > > > [...]
> > > > > > > > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > > > > > > > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > > > > > > > +Format}
> > > > > > > > +
> > > > > > > > +The following structure is used to reduce the number of
> > > > > > > > +notifications sent between driver and device.
> > > > > > > > +
> > > > > > > > +\begin{lstlisting}
> > > > > > > > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > > > > > > > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > > > > > > 
> > > > > > > Is this `int` a typo?
> > > > > > 
> > > > > > It's a single bit so I think it does not matter.
> > > > > > What type would you like me to use instead?
> > > > > 
> > > > > It looks a bit strange to use different types here, and
> > > > > that's why I asked. If there is no particular reason to
> > > > > use `int` here, maybe it's better to keep using __le16.
> > > > > 
> > > > > Besides, just for fun. For C language, I checked gcc and
> > > > > clang. It seems that `int desc_event_wrap:1;` is a signed
> > > > > type. So, e.g. `p->desc_event_wrap == 1` is always false.
> > > > > 
> > > > > Best regards,
> > > > > Tiwei Bie
> > > > 
> > > > I'll switch to u8 here, IMHO le16 for a single bit
> > > > is really confusing. There's no byte order for a single byte.
> > > 
> > > Sorry, I just realized that I misunderstood your point
> > > previously.. Just to double check, `desc_event_off` and
> > > `desc_event_wrap` are not in the same 2 bytes?
> > > 
> > > Previously I thought both of them are in the first 2
> > > bytes. As it said it's a structure, and the fields are
> > > defined in a way very similar to the bit field in C.
> > > 
> > > In C,
> > > 
> > > struct {
> > > 	__le16 desc_event_off : 15;
> > > 	int    desc_event_wrap : 1;
> > > 	__le16 desc_event_flags : 2;
> > > };
> > > 
> > > struct {
> > > 	__le16 desc_event_off : 15;
> > > 	__le16 desc_event_wrap : 1;
> > > 	__le16 desc_event_flags : 2;
> > > };
> > > 
> > > struct {
> > > 	__le16 desc_event_off : 15,
> > > 	       desc_event_wrap : 1;
> > > 	__le16 desc_event_flags : 2;
> > > };
> > > 
> > > All above means `desc_event_off` and `desc_event_wrap`
> > > are in the first 2 bytes. So I thought the `int` is a
> > > typo. And I thought they are in the first 2 bytes (which
> > > is little-endian).
> > >
> > > Best regards,
> > > Tiwei Bie
> > 
> > Yes but desc_event_wrap itself is completely within the
> > second byte. So the question of byte-order does not arise.
> > 
> > Right, and above is also identical to:
> > 
> >  struct {
> >  	__le16 desc_event_off : 15,
> >  	u8     desc_event_wrap : 1;
> >  	__le16 desc_event_flags : 2;
> >  };
> > 
> > introduction explains:
> > 
> > \item[u8, u16, u32, u64] An unsigned integer of the specified length in bits.
> > 
> > \item[le16, le32, le64] An unsigned integer of the specified length in bits,
> > in little-endian byte order.
> > 
> 
> I've got your point now. Thanks! ;-)
> BTW, maybe it's better to remove the `__` prefix for
> `__le16` to keep consistency.
> 
> Best regards,
> Tiwei Bie

I agree.  I think I will stop using the bitfields - they seem to
cause too much confusion. Just

struct event {
 	__le16 event_desc; /* bits 0-14: desc_off. 15 - desc_wrap. */
	__le16 event_flags; /* bits 0-1: event_flags, 2-15 - reserved */
};

> > 
> > 
> > > > 
> > > > > > 
> > > > > > > > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > > > > > > > +\end{lstlisting}
> > > > > [...]

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Cornelia Huck]

On Wed, 28 Feb 2018 17:20:29 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> I agree.  I think I will stop using the bitfields - they seem to
> cause too much confusion. Just
> 
> struct event {
>  	__le16 event_desc; /* bits 0-14: desc_off. 15 - desc_wrap. */
> 	__le16 event_flags; /* bits 0-1: event_flags, 2-15 - reserved */
> };

Looks sensible; but while you're add it, drop the leading underscores
as well? The spec only talks about 'le16' and friends.

[Also, reserved-and-to-be-ignored or reserved-and-must-be-0?]

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Tue, Feb 27, 2018 at 09:49:28AM +0800, Tiwei Bie wrote:
> struct {
> 	__le16 desc_event_off : 15,
> 	       desc_event_wrap : 1;
> 	__le16 desc_event_flags : 2;
> };

I decided on this format in the end. Thanks for the suggestion!

-- 
MST

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Halil Pasic]

Some of my comments are taken from (unchanged or reworded)
(https://lists.oasis-open.org/archives/virtio-dev/201802/msg00026.html)

Tried to not repeat stuff pointed out by Tiwei Bie.


On 02/16/2018 08:24 AM, Michael S. Tsirkin wrote:
> Performance analysis of this is in my kvm forum 2016 presentation.  The
> idea is to have a r/w descriptor in a ring structure, replacing the used
> and available ring, index and descriptor buffer.
> 
> This is also easier for devices to implement than the 1.0 layout.
> Several more enhancements will be necessary to actually make this
> efficient for devices to use.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  content.tex     |  28 ++-
>  packed-ring.tex | 646 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 671 insertions(+), 3 deletions(-)
>  create mode 100644 packed-ring.tex
> 
> diff --git a/content.tex b/content.tex
> index e1e30a0..73f40b7 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -263,8 +263,20 @@ these parts (following \ref{sec:Basic Facilities of a Virtio Device / Split Virt
> 
>  \end{note}
> 
> +Two formats are supported: Split Virtqueues (see \ref{sec:Basic
> +Facilities of a Virtio Device / Split
> +Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device /
> +Split Virtqueues}) and Packed Virtqueues (see \ref{sec:Basic
> +Facilities of a Virtio Device / Packed
> +Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device /
> +Packed Virtqueues}).
> +
> +Every driver and device supports either the Packed or the Split
> +Virtqueue format, or both.
> +
>  \input{split-ring.tex}
> 
> +\input{packed-ring.tex}
>  \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
> 
>  We start with an overview of device initialization, then expand on the
> @@ -5215,10 +5227,15 @@ Currently these device-independent feature bits defined:
>  \begin{description}
>    \item[VIRTIO_F_RING_INDIRECT_DESC (28)] Negotiating this feature indicates
>    that the driver can use descriptors with the VIRTQ_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}.
> -
> +  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} and \ref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}~\nameref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}.
>    \item[VIRTIO_F_RING_EVENT_IDX(29)] This feature enables the \field{used_event}
> -  and the \field{avail_event} fields as described in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} and \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}.
> +  and the \field{avail_event} fields as described in
> +\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}, \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and \ref{sec:Packed Virtqueues / Driver and Device Event Suppression}.
> +
> 
>    \item[VIRTIO_F_VERSION_1(32)] This indicates compliance with this
>      specification, giving a simple way to detect legacy devices or drivers.
> @@ -5228,6 +5245,9 @@ Currently these device-independent feature bits defined:
>    addresses in memory.  If this feature bit is set to 0, then the device emits
>    physical addresses which are not translated further, even though an IOMMU
>    may be present.
> +  \item[VIRTIO_F_RING_PACKED(34)] This feature indicates
> +  support for the packed virtqueue layout as described in
> +  \ref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}.
>  \end{description}
> 
>  \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
> @@ -5241,6 +5261,8 @@ passed to the device into physical addresses in memory.  If
>  VIRTIO_F_IOMMU_PLATFORM is not offered, then a driver MUST pass only physical
>  addresses to the device.
> 
> +A driver SHOULD accept VIRTIO_F_RING_PACKED if it is offered.
> +
>  \devicenormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
> 
>  A device MUST offer VIRTIO_F_VERSION_1.  A device MAY fail to operate further
> diff --git a/packed-ring.tex b/packed-ring.tex
> new file mode 100644
> index 0000000..213295b
> --- /dev/null
> +++ b/packed-ring.tex
> @@ -0,0 +1,646 @@
> +\section{Packed Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}
> +
> +Packed virtqueues is an alternative compact virtqueue layout using
> +read-write memory, that is memory that is both read and written
> +by both host and guest.
> +
> +Use of packed virtqueues is negotiated by the VIRTIO_F_RING_PACKED
> +feature bit.
> +
> +Packed virtqueues support up to $2^{15}$ entries each.
> +
> +With current transports, virtqueues are located in guest memory
> +allocated by driver.
> +Each packed virtqueue consists of three parts:
> +
> +\begin{itemize}
> +\item Descriptor Ring - occupies the Descriptor Area
> +\item Driver Event Suppression - occupies the Driver Area
> +\item Device Event Suppression - occupies the Device Area
> +\end{itemize}
> +
> +Where Descriptor Ring in turn consists of descriptors,
> +and where each descriptor can contain the following parts:
> +
> +\begin{itemize}
> +\item Buffer ID
> +\item Element Address
> +\item Element Length
> +\item Flags
> +\end{itemize}
> +
> +A buffer consists of zero or more device-readable physically-contiguous
> +elements followed by zero or more physically-contiguous
> +device-writable elements (each buffer has at least one element).
> +
> +When the driver wants to send such a buffer to the device, it
> +writes at least one available descriptor describing elements of
> +the buffer into the Descriptor Ring.  The descriptor(s) are
> +associated with a buffer by means of a Buffer ID stored within
> +the descriptor.
> +
> +Driver then notifies the device. When the device has finished
> +processing the buffer, it writes a used device descriptor
> +including the Buffer ID into the Descriptor Ring (overwriting a
> +driver descriptor previously made available), and sends an
> +interrupt.
> +
> +Descriptor Ring is used in a circular manner: driver writes
> +descriptors into the ring in order. After reaching end of ring,
> +the next descriptor is placed at head of the ring.  Once ring is
> +full of driver descriptors, driver stops sending new requests and
> +waits for device to start processing descriptors and to write out
> +some used descriptors before making new driver descriptors
> +available.
> +
> +Similarly, device reads descriptors from the ring in order and
> +detects that a driver descriptor has been made available.  As
> +processing of descriptors is completed used descriptors are
> +written by the device back into the ring.
> +
> +Note: after reading driver descriptors and starting their
> +processing in order, device might complete their processing out
> +of order.  Used device descriptors are written in the order
> +in which their processing is complete.
> +
> +Device Event Suppression data structure is write-only by the
> +device. It includes information for reducing the number of
> +device events - i.e. driver notifications to device.
> +
> +Driver Event Suppression data structure is read-only by the
> +device. It includes information for reducing the number of
> +driver events - i.e. device interrupts to driver.
> +
> +\subsection{Driver and Device Ring Wrap Counters}
> +\label{sec:Packed Virtqueues / Driver and Device Ring Wrap Counters}
> +Each of the driver and the device are expected to maintain,
> +internally, a single-bit ring wrap counter initialized to 1.
> +
> +The counter maintained by the driver is called the Driver
> +Ring Wrap Counter. Driver changes the value of this counter
> +each time it makes available the
> +last descriptor in the ring (after making the last descriptor
> +available).
> +
> +The counter maintained by the device is called the Device Ring Wrap
> +Counter.  Device changes the value of this counter
> +each time it uses the last descriptor in
> +the ring (after marking the last descriptor used).
> +
> +It is easy to see that the Driver Ring Wrap Counter in the driver matches
> +the Device Ring Wrap Counter in the device when both are processing the same
> +descriptor, or when all available descriptors have been used.
> +
> +To mark a descriptor as available and used, both driver and
> +device use the following two flags:
> +\begin{lstlisting}
> +#define VIRTQ_DESC_F_AVAIL     (1 << 7)
> +#define VIRTQ_DESC_F_USED      (1 << 15)
> +\end{lstlisting}
> +
> +To mark a descriptor as available, driver sets the
> +VIRTQ_DESC_F_AVAIL bit in Flags to match the internal Driver
> +Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_USED bit to match the
> +\emph{inverse} value (i.e. to not match the internal Driver Ring
> +Wrap Counter).
> +
> +To mark a descriptor as used, device sets the
> +VIRTQ_DESC_F_USED bit in Flags to match the internal Device
> +Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_AVAIL bit to match the
> +\emph{same} value.
> +
> +Thus VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED bits are different
> +for an available descriptor and equal for a used descriptor.
> +

AFAIU VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED being
different is a necessary but not a sufficient pre-condition for
a descriptor being available; VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED
equal is a necessary but not a sufficient pre-condition for
a descriptor being used. Did I get that right?

If I got it right, then my suggestion is to provide a necessary and
sufficient condition here.


> +\subsection{Polling of available and used descriptors}
> +\label{sec:Packed Virtqueues / Polling of available and used descriptors}
> +
> +Writes of device and driver descriptors can generally be
> +reordered, but each side (driver and device) are only required to
> +poll (or test) a single location in memory: next device descriptor after
> +the one they processed previously, in circular order.
> +
> +Sometimes device needs to only write out a single used descriptor
> +after processing a batch of multiple available descriptors.  As
> +described in more detail below, this can happen when using
> +descriptor chaining or with in-order
> +use of descriptors.  In this case, device writes out a used
> +descriptor with buffer id of the last descriptor in the group.
> +After processing the used descriptor, both device and driver then
> +skip forward in the ring the number of the remaining descriptors
> +in the group until processing (reading for the driver and writing
> +for the device) the next used descriptor.
> +
> +\subsection{Write Flag}
> +\label{sec:Packed Virtqueues / Write Flag}
> +
> +In an available descriptor, VIRTQ_DESC_F_WRITE bit within Flags
> +is used to mark a descriptor as corresponding to a write-only or
> +read-only element of a buffer.
> +
> +\begin{lstlisting}
> +/* This marks a descriptor as device write-only (otherwise device read-only). */
> +#define VIRTQ_DESC_F_WRITE     2
> +\end{lstlisting}
> +
> +In a used descriptor, this bit is used to specify whether any
> +data has been written by the device into any parts of the buffer.
> +
> +
> +\subsection{Element Address and Length}
> +\label{sec:Packed Virtqueues / Element Address and Length}
> +
> +In an available descriptor, Element Address corresponds to the
> +physical address of the buffer element. The length of the element assumed
> +to be physically contigious is stored in Element Length.
> +
> +In a used descriptor, Element Address is unused. Element Length
> +specifies the length of the buffer that has been initialized
> +(written to) by the device.
> +
> +Element length is reserved for used descriptors without the
> +VIRTQ_DESC_F_WRITE flag, and is ignored by drivers.
> +
> +\subsection{Scatter-Gather Support}

[Consistent wording] Both types of virtqueues support scatter-gather
but the term is used only for packed. Maybe we could unify the wording.
Or is this something for later?

> +\label{sec:Packed Virtqueues / Scatter-Gather Support}
> +
> +Some drivers need an ability to supply a list of multiple buffer
> +elements (also known as a scatter/gather list) with a request.
> +Two optional features support this: descriptor
> +chaining and indirect descriptors.
> +
> +If neither feature has been negotiated, each buffer is
> +physically-contigious, either read-only or write-only and is
> +described completely by a single descriptor.
> +
> +While unusual (most implementations either create all lists
> +solely using non-indirect descriptors, or always use a single
> +indirect element), if both features have been negotiated, mixing
> +direct and direct descriptors in a ring is valid, as long as each
> +list only contains descriptors of a given type.
> +
> +Scatter/gather lists only apply to available descriptors. A
> +single used descriptor corresponds to the whole list.
> +
> +The device limits the number of descriptors in a list through a
> +transport-specific and/or device-specific value. If not limited,
> +the maximum number of descriptors in a list is the virt queue
> +size.
> +
> +\subsection{Next Flag: Descriptor Chaining}
> +\label{sec:Packed Virtqueues / Next Flag: Descriptor Chaining}
> +
> +The packed ring format allows driver to supply
> +a scatter/gather list to the device
> +by using multiple descriptors, and setting the VIRTQ_DESC_F_NEXT in
> +Flags for all but the last available descriptor.
> +
> +\begin{lstlisting}
> +/* This marks a buffer as continuing. */
> +#define VIRTQ_DESC_F_NEXT   1
> +\end{lstlisting}
> +
> +Buffer ID is included in the last descriptor in the list.
> +
> +The driver always makes the first descriptor in the list
> +available after the rest of the list has been written out into
> +the ring. This guarantees that the device will never observe a
> +partial scatter/gather list in the ring.
> +
> +Note: all flags, including VIRTQ_DESC_F_AVAIL, VIRTQ_DESC_F_USED,
> +VIRTQ_DESC_F_WRITE must be set/cleared correctly in all
> +descriptors in the list, not just the first one.
> +
> +Device only writes out a single used descriptor for the whole
> +list. It then skips forward according to the number of
> +descriptors in the list. Driver needs to keep track of the size
> +of the list corresponding to each buffer ID, to be able to skip
> +to where the next used descriptor is written by the device.
> +
> +For example, if descriptors are used in the same order in which
> +they are made available, this will result in the used descriptor
> +overwriting the first available descriptor in the list, the used
> +descriptor for the next list overwriting the first available
> +descriptor in the next list, etc.
> +
> +VIRTQ_DESC_F_NEXT is reserved in used descriptors, and
> +should be ignored by drivers.
> +
> +\subsection{Indirect Flag: Scatter-Gather Support}
> +\label{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}
> +
> +Some devices benefit by concurrently dispatching a large number
> +of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this. To increase
> +ring capacity the driver can store a (read-only by the device) table of indirect
> +descriptors anywhere in memory, and insert a descriptor in main
> +virtqueue (with \field{Flags} bit VIRTQ_DESC_F_INDIRECT on) that refers to
> +a buffer element
> +containing this indirect descriptor table; \field{addr} and \field{len}
> +refer to the indirect table address and length in bytes,
> +respectively.
> +\begin{lstlisting}
> +/* This means the element contains a table of descriptors. */
> +#define VIRTQ_DESC_F_INDIRECT   4
> +\end{lstlisting}
> +
> +The indirect table layout structure looks like this
> +(\field{len} is the Buffer Length of the descriptor that refers to this table,
> +which is a variable):
> +
> +\begin{lstlisting}
> +struct indirect_descriptor_table {
> +        /* The actual descriptor structures (struct virtq_desc each) */
> +        struct virtq_desc desc[len / sizeof(struct virtq_desc)];
> +};
> +\end{lstlisting}
> +
> +The first descriptor is located at start of the indirect
> +descriptor table, additional indirect descriptors come
> +immediately afterwards. \field{Flags} bit VIRTQ_DESC_F_WRITE is the
> +only valid flag for descriptors in the indirect table. Others
> +are reserved and are ignored by the device.
> +Buffer ID is also reserved and is ignored by the device.
> +
> +In Descriptors with VIRTQ_DESC_F_INDIRECT set VIRTQ_DESC_F_WRITE
> +is reserved and is ignored by the device.
> +
> +\subsection{Multi-buffer requests}
> +\label{sec:Packed Virtqueues / Multi-descriptor batches}
> +Some devices combine multiple buffers as part of processing of a
> +single request.  These devices always mark the first descriptor
> +in the request used after the rest of the descriptors in the
> +request has been written out into the ring. This guarantees that
> +the driver will never observe a partial request in the ring.
> +

I see you've changed s/in the request available/in the request used/.
But I still don't understand this paragraph. I will try to figure
it out later (and will come back to you if I fail).

> +
> +\subsection{Driver and Device Event Suppression}
> +\label{sec:Packed Virtqueues / Driver and Device Event Suppression}
> +In many systems driver and device notifications involve
> +significant overhead. To mitigate this overhead,
> +each virtqueue includes two identical structures used for
> +controlling notifications between device and driver.
> +
> +Driver Event Suppression structure is read-only by the
> +device and controls the events sent by the device
> +to the driver (e.g. interrupts).
> +
> +Device Event Suppression structure is read-only by
> +the driver and controls the events sent by the driver
> +to the device (e.g. IO).
> +
> +Each of these Event Suppression structures controls
> +both Descriptor Ring events and structure events, and
> +each includes the following fields:
> +
> +\begin{description}
> +\item [Descriptor Ring Change Event Flags] Takes values:
> +\begin{itemize}
> +\item 00b enable events
> +\item 01b disable events
> +\item 10b enable events for a specific descriptor
> +(as specified by Descriptor Ring Change Event Offset/Wrap Counter).
> +Only valid if VIRTIO_F_RING_EVENT_IDX has been negotiated.
> +\item 11b reserved
> +\end{itemize}
> +\item [Descriptor Ring Change Event Offset] If Event Flags set to descriptor
> +specific event: offset within the ring (in units of descriptor
> +size). Event will only trigger when this descriptor is
> +made available/used respectively.
> +\item [Descriptor Ring Change Event Wrap Counter] If Event Flags set to descriptor
> +specific event: offset within the ring (in units of descriptor
> +size). Event will only trigger when Ring Wrap Counter
> +matches this value and a descriptor is
> +made available/used respectively.
> +\end{description}
> +
> +After writing out some descriptors, both device and driver
> +are expected to consult the relevant structure to find out
> +whether interrupt/notification should be sent.
> +
> +\subsubsection{Structure Size and Alignment}
> +\label{sec:Packed Virtqueues / Structure Size and Alignment}
> +
> +Each part of the virtqueue is physically-contiguous in guest memory,
> +and has different alignment requirements.
> +
> +The memory aligment and size requirements, in bytes, of each part of the

s/aligment/alignment/

> +virtqueue are summarized in the following table:
> +
> +\begin{tabular}{|l|l|l|}
> +\hline
> +Virtqueue Part    & Alignment & Size \\
> +\hline \hline
> +Descriptor Ring  & 16        & $16 * $(Queue Size) \\
> +\hline
> +Device Event Suppression    & 4         & 4 \\
> + \hline
> +Driver Event Suppression         & 4         & 4 \\
> + \hline
> +\end{tabular}
> +
> +The Alignment column gives the minimum alignment for each part
> +of the virtqueue.
> +
> +The Size column gives the total number of bytes for each
> +part of the virtqueue.
> +
> +Queue Size corresponds to the maximum number of descriptors in the
> +virtqueue\footnote{For example, if Queue Size is 4 then at most 4 buffers
> +can be queued at any given time.}.  Queue Size value does not
> +have to be a power of 2 unless enforced by the transport.
> +
> +\drivernormative{\subsection}{Virtqueues}{Basic Facilities of a
> +Virtio Device / Packed Virtqueues}
> +The driver MUST ensure that the physical address of the first byte
> +of each virtqueue part is a multiple of the specified alignment value
> +in the above table.
> +
> +\devicenormative{\subsection}{Virtqueues}{Basic Facilities of a
> +Virtio Device / Packed Virtqueues}
> +The device MUST start processing driver descriptors in the order
> +in which they appear in the ring.
> +The device MUST start writing device descriptors into the ring in
> +the order in which they complete.
> +Device MAY reorder descriptor writes once they are started.
> +
> +\subsection{The Virtqueue Descriptor Format}\label{sec:Basic
> +Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue
> +Descriptor Format}
> +
> +The available descriptor refers to the buffers the driver is sending
> +to the device. \field{addr} is a physical address, and the
> +descriptor is identified with a buffer using the \field{id} field.
> +
> +\begin{lstlisting}
> +struct virtq_desc {
> +        /* Buffer Address. */
> +        le64 addr;
> +        /* Buffer Length. */
> +        le32 len;
> +        /* Buffer ID. */
> +        le16 id;
> +        /* The flags depending on descriptor type. */
> +        le16 flags;
> +};
> +\end{lstlisting}
> +
> +The descriptor ring is zero-initialized.
> +
> +\subsection{Event Suppression Structure Format}\label{sec:Basic
> +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> +Format}
> +
> +The following structure is used to reduce the number of
> +notifications sent between driver and device.
> +
> +\begin{lstlisting}
> +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> +\end{lstlisting}
> +
> +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
> +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
> +read a device-writable buffer.
> +A device MUST NOT use a descriptor unless it observes
> +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.

I don't really understand this. How does the device observe
the VIRTQ_DESC_F_AVAIL bit being changed?

> +A device MUST NOT change a descriptor after changing it's
> +VIRTQ_DESC_F_USED bit in its \field{flags}.
> +
> +\drivernormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / PAcked Virtqueues / The Virtqueue Descriptor Table}
> +A driver MUST NOT change a descriptor unless it observes
> +VIRTQ_DESC_F_USED bit in its \field{flags} being changed.
> +A driver MUST NOT change a descriptor after changing
> +VIRTQ_DESC_F_USED bit in its \field{flags}.

I'm a bit confused with this protocol. AFAIU the driver
always writes the value into the VIRTQ_DESC_F_USED that
is already there (so it does not change). Was that supposed
to be VIRTQ_DESC_F_AVAIL.

> +When notifying the device, driver MUST set
> +\field{next_off} and
> +\field{next_wrap} to match the next descriptor
> +not yet made available to the device.
> +A driver MAY send multiple notifications without making
> +any new descriptors available to the device.
> +
> +\drivernormative{\subsection}{Scatter-Gather Support}{Basic Facilities of a
> +Virtio Device / Packed Virtqueues / Scatter-Gather Support}
> +A driver MUST NOT create a descriptor list longer than allowed
> +by the device.
> +
> +A driver MUST NOT create a descriptor list longer than the Queue
> +Size.
> +
> +This implies that loops in the descriptor list are forbidden!
> +
> +The driver MUST place any device-writable descriptor elements after
> +any device-readable descriptor elements.
> +
> +A driver MUST NOT depend on the device to use more descriptors
> +to be able to write out all descriptors in a list. A driver
> +MUST make sure there's enough space in the ring
> +for the whole list before making the first descriptor in the list
> +available to the device.
> +
> +A driver MUST NOT make the first descriptor in the list
> +available before initializing the rest of the descriptors.

Initializing is a bit vague here. How about: unless all subsequent descriptors
comprising the list (that is the request) are made available.

> +
> +\devicenormative{\subsection}{Scatter-Gather Support}{Basic Facilities of a
> +Virtio Device / Packed Virtqueues / Scatter-Gather Support}
> +The device MUST use descriptors in a list chained by the
> +VIRTQ_DESC_F_NEXT flag in the same order that they
> +were made available by the driver.
> +
> +The device MAY limit the number of buffers it will allow in a
> +list.
> +
> +\drivernormative{\subsection}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
> +The driver MUST NOT set the DESC_F_INDIRECT flag unless the
> +VIRTIO_F_INDIRECT_DESC feature was negotiated.   The driver MUST NOT
> +set any flags except DESC_F_WRITE within an indirect descriptor.
> +
> +A driver MUST NOT create a descriptor chain longer than allowed
> +by the device.
> +
> +A driver MUST NOT write direct descriptors with
> +DESC_F_INDIRECT set in a scatter-gather list linked by
> +VIRTQ_DESC_F_NEXT.
> +\field{flags}.
> +
> +\subsection{Virtqueue Operation}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Virtqueue Operation}
> +
> +There are two parts to virtqueue operation: supplying new
> +available buffers to the device, and processing used buffers from
> +the device.
> +
> +What follows is the requirements of each of these two parts
> +when using the packed virtqueue format in more detail.
> +
> +\subsection{Supplying Buffers to The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device}
> +
> +The driver offers buffers to one of the device's virtqueues as follows:
> +
> +\begin{enumerate}
> +\item The driver places the buffer into free descriptor in the Descriptor Ring.
> +
> +\item The driver performs a suitable memory barrier to ensure that it updates
> +  the descriptor(s) before checking for notification suppression.
> +
> +\item If notifications are not suppressed, the driver notifies the device
> +    of the new available buffers.
> +\end{enumerate}
> +
> +What follows is the requirements of each stage in more detail.
> +
> +\subsubsection{Placing Available Buffers Into The Descriptor Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Placing Available Buffers Into The Descriptor Ring}
> +
> +For each buffer element, b:
> +
> +\begin{enumerate}
> +\item Get the next descriptor table entry, d
> +\item Get the next free buffer id value
> +\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 Set \field{d.id} to the buffer id
> +\item Calculate the flags as follows:
> +\begin{enumerate}
> +\item If b is device-writable, set the VIRTQ_DESC_F_WRITE bit to 1, otherwise 0
> +\item Set VIRTQ_DESC_F_AVAIL bit to the current value of the Driver Ring Wrap Counter
> +\item Set VIRTQ_DESC_F_USED bit to inverse value
> +\end{enumerate}
> +\item Perform a memory barrier to ensure that the descriptor has
> +      been initialized
> +\item Set \field{d.flags} to the calculated flags value
> +\item If d is the last descriptor in the ring, toggle the
> +      Driver Ring Wrap Counter
> +\item Otherwise, increment d to point at the next descriptor
> +\end{enumerate}
> +
> +This makes a single descriptor buffer available. However, in
> +general the driver MAY make use of a batch of descriptors as part
> +of a single request. In that case, it defers updating
> +the descriptor flags for the first descriptor
> +(and the previous memory barrier) until after the rest of
> +the descriptors have been initialized.
> +
> +Once the descriptor \field{flags} is updated by the driver, this exposes the
> +descriptor and its contents.  The device MAY
> +access the descriptor and any following descriptors the driver created and the
> +memory they refer to immediately.
> +
> +\drivernormative{\paragraph}{Updating flags}{Basic Facilities of
> +a Virtio Device / Packed Virtqueues / Supplying Buffers to The
> +Device / Updating flags}
> +The driver MUST perform a suitable memory barrier before the
> +\field{flags} update, to ensure the
> +device sees the most up-to-date copy.
> +
> +\subsubsection{Notifying The Device}\label{sec:Basic Facilities
> +of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
> +
> +The actual method of device notification is bus-specific, but generally
> +it can be expensive.  So the device MAY suppress such notifications if it
> +doesn't need them, using the Driver Event Suppression structure
> +as detailed in section \ref{sec:Basic
> +Facilities of a Virtio Device / Packed Virtqueues / Event
> +Suppression Structure Format}.
> +
> +The driver has to be careful to expose the new \field{flags}
> +value before checking if notifications are suppressed.
> +
> +\subsubsection{Implementation Example}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Implementation Example}
> +
> +Below is an example driver code. It does not attempt to reduce
> +the number of device interrupts, neither does it support
> +the VIRTIO_F_RING_EVENT_IDX feature.
> +
> +\begin{lstlisting}
> +
> +first = vq->next_avail;
> +id = alloc_id(vq);
> +
> +for (each buffer element b) {
> +        vq->desc[vq->next_avail].address = get_addr(b);
> +        vq->desc[vq->next_avail].len = get_len(b);
> +        init_desc(vq->next_avail, b);

What is init_desc? Can't find it elsewhere and I can't
guess it.

> +        avail = vq->avail_wrap_count;
> +        used = !vq->avail_wrap_count;
> +        f = get_flags(b) | (avail << VIRTQ_DESC_F_AVAIL) | (used << VIRTQ_DESC_F_USED);
> +	/* Don't mark the 1st descriptor available until all of them are ready. */
> +        if (vq->next_avail == first) {
> +                flags = f;
> +        } else {
> +                vq->desc[vq->next_avail].flags = f;
> +        }
> +
> +	vq->next_avail++;
> +
> +	if (vq->next_avail >= vq->size) {
> +		vq->next_avail = 0;
> +		vq->avail_wrap_count \^= 1;
> +	}
> +
> +
> +}
> +/* ID included in the last descriptor in the list */
> +vq->desc[vq->next_avail].id = id;
> +write_memory_barrier();
> +vq->desc[first].flags = flags;
> +
> +memory_barrier();
> +
> +if (vq->device_event.flags != 0x2) {
> +        notify_device(vq);
> +}
> +
> +\end{lstlisting}
> +
> +
> +\drivernormative{\paragraph}{Notifying The Device}{Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
> +The driver MUST perform a suitable memory barrier before reading
> +the Driver Event Suppression structure, to avoid missing a notification.
> +
> +\subsection{Receiving Used Buffers From The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Receiving Used Buffers From The Device}
> +
> +Once the device has used buffers referred to by a descriptor (read from or written to them, or
> +parts of both, depending on the nature of the virtqueue and the
> +device), it interrupts the driver
> +as detailed in section \ref{sec:Basic
> +Facilities of a Virtio Device / Packed Virtqueues / Event
> +Suppression Structure Format}.
> +
> +\begin{note}
> +For optimal performance, a driver MAY disable interrupts while processing
> +the used buffers, but beware the problem of missing interrupts between
> +emptying the ring and reenabling interrupts.  This is usually handled by
> +re-checking for more used buffers after interrups are re-enabled:
> +\end{note}
> +
> +\begin{lstlisting}
> +vq->driver_event.flags = 0x2;
> +
> +for (;;) {
> +        struct virtq_desc *d = vq->desc[vq->next_used];
> +
> +        flags = d->flags;
> +        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> +        bool used = flags & (1 << VIRTQ_DESC_F_USED);
> +
> +        if (avail != used) {

I don't understand the condition which is AFAIU supposed to
correspond to the descriptor *not* being used.

> +                vq->driver_event.flags = 0x1;
> +                memory_barrier();
> +
> +                flags = d->flags;
> +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
> +                if (avail != used) {
> +                        break;
> +                }
> +
> +                vq->driver_event.flags = 0x2;
> +        }
> +
> +	read_memory_barrier();

Now with the condition avail != used a freshly (that is zero initialized)
ring would appear all used. And we would do process_buffer(d) for the
whole ring if this code happens to get executed. Do we have to make
sure that this does not happen?

I was under the impression that this whole wrap counter exercise is
to be able to distinguish these cases.

BTW tools/virtio/ringtest/ring.c has a single flag bit to indicate
available/used and does not have these wrap counters AFAIR.

Also for split virtqueues  a descriptor has three possible states:
* available
* used
* free

I wonder if it's the same for packed, and if, how do I recognize
free descriptors (that is descriptors that are neither available
nor used.

I'm pretty much confused on how this scheme with the available
and used wrap counters (or device and driver wrap counters is
supposed to work). A working implementation in C would really help
me to understand this.

> +        process_buffer(d);
> +        vq->next_used++;
> +        if (vq->next_used >= vq->size) {
> +                vq->next_used = 0;
> +        }
> +}
> +\end{lstlisting}
> 


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
> Some of my comments are taken from (unchanged or reworded)
> (https://lists.oasis-open.org/archives/virtio-dev/201802/msg00026.html)
> 
> Tried to not repeat stuff pointed out by Tiwei Bie.
> 
> 
> On 02/16/2018 08:24 AM, Michael S. Tsirkin wrote:
> > Performance analysis of this is in my kvm forum 2016 presentation.  The
> > idea is to have a r/w descriptor in a ring structure, replacing the used
> > and available ring, index and descriptor buffer.
> > 
> > This is also easier for devices to implement than the 1.0 layout.
> > Several more enhancements will be necessary to actually make this
> > efficient for devices to use.
> > 
> > Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> > ---
> >  content.tex     |  28 ++-
> >  packed-ring.tex | 646 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 671 insertions(+), 3 deletions(-)
> >  create mode 100644 packed-ring.tex
> > 
> > diff --git a/content.tex b/content.tex
> > index e1e30a0..73f40b7 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -263,8 +263,20 @@ these parts (following \ref{sec:Basic Facilities of a Virtio Device / Split Virt
> > 
> >  \end{note}
> > 
> > +Two formats are supported: Split Virtqueues (see \ref{sec:Basic
> > +Facilities of a Virtio Device / Split
> > +Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device /
> > +Split Virtqueues}) and Packed Virtqueues (see \ref{sec:Basic
> > +Facilities of a Virtio Device / Packed
> > +Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device /
> > +Packed Virtqueues}).
> > +
> > +Every driver and device supports either the Packed or the Split
> > +Virtqueue format, or both.
> > +
> >  \input{split-ring.tex}
> > 
> > +\input{packed-ring.tex}
> >  \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
> > 
> >  We start with an overview of device initialization, then expand on the
> > @@ -5215,10 +5227,15 @@ Currently these device-independent feature bits defined:
> >  \begin{description}
> >    \item[VIRTIO_F_RING_INDIRECT_DESC (28)] Negotiating this feature indicates
> >    that the driver can use descriptors with the VIRTQ_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}.
> > -
> > +  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} and \ref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}~\nameref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}.
> >    \item[VIRTIO_F_RING_EVENT_IDX(29)] This feature enables the \field{used_event}
> > -  and the \field{avail_event} fields as described in \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression} and \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}.
> > +  and the \field{avail_event} fields as described in
> > +\ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}, \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring} and \ref{sec:Packed Virtqueues / Driver and Device Event Suppression}.
> > +
> > 
> >    \item[VIRTIO_F_VERSION_1(32)] This indicates compliance with this
> >      specification, giving a simple way to detect legacy devices or drivers.
> > @@ -5228,6 +5245,9 @@ Currently these device-independent feature bits defined:
> >    addresses in memory.  If this feature bit is set to 0, then the device emits
> >    physical addresses which are not translated further, even though an IOMMU
> >    may be present.
> > +  \item[VIRTIO_F_RING_PACKED(34)] This feature indicates
> > +  support for the packed virtqueue layout as described in
> > +  \ref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}.
> >  \end{description}
> > 
> >  \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
> > @@ -5241,6 +5261,8 @@ passed to the device into physical addresses in memory.  If
> >  VIRTIO_F_IOMMU_PLATFORM is not offered, then a driver MUST pass only physical
> >  addresses to the device.
> > 
> > +A driver SHOULD accept VIRTIO_F_RING_PACKED if it is offered.
> > +
> >  \devicenormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
> > 
> >  A device MUST offer VIRTIO_F_VERSION_1.  A device MAY fail to operate further
> > diff --git a/packed-ring.tex b/packed-ring.tex
> > new file mode 100644
> > index 0000000..213295b
> > --- /dev/null
> > +++ b/packed-ring.tex
> > @@ -0,0 +1,646 @@
> > +\section{Packed Virtqueues}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}
> > +
> > +Packed virtqueues is an alternative compact virtqueue layout using
> > +read-write memory, that is memory that is both read and written
> > +by both host and guest.
> > +
> > +Use of packed virtqueues is negotiated by the VIRTIO_F_RING_PACKED
> > +feature bit.
> > +
> > +Packed virtqueues support up to $2^{15}$ entries each.
> > +
> > +With current transports, virtqueues are located in guest memory
> > +allocated by driver.
> > +Each packed virtqueue consists of three parts:
> > +
> > +\begin{itemize}
> > +\item Descriptor Ring - occupies the Descriptor Area
> > +\item Driver Event Suppression - occupies the Driver Area
> > +\item Device Event Suppression - occupies the Device Area
> > +\end{itemize}
> > +
> > +Where Descriptor Ring in turn consists of descriptors,
> > +and where each descriptor can contain the following parts:
> > +
> > +\begin{itemize}
> > +\item Buffer ID
> > +\item Element Address
> > +\item Element Length
> > +\item Flags
> > +\end{itemize}
> > +
> > +A buffer consists of zero or more device-readable physically-contiguous
> > +elements followed by zero or more physically-contiguous
> > +device-writable elements (each buffer has at least one element).
> > +
> > +When the driver wants to send such a buffer to the device, it
> > +writes at least one available descriptor describing elements of
> > +the buffer into the Descriptor Ring.  The descriptor(s) are
> > +associated with a buffer by means of a Buffer ID stored within
> > +the descriptor.
> > +
> > +Driver then notifies the device. When the device has finished
> > +processing the buffer, it writes a used device descriptor
> > +including the Buffer ID into the Descriptor Ring (overwriting a
> > +driver descriptor previously made available), and sends an
> > +interrupt.
> > +
> > +Descriptor Ring is used in a circular manner: driver writes
> > +descriptors into the ring in order. After reaching end of ring,
> > +the next descriptor is placed at head of the ring.  Once ring is
> > +full of driver descriptors, driver stops sending new requests and
> > +waits for device to start processing descriptors and to write out
> > +some used descriptors before making new driver descriptors
> > +available.
> > +
> > +Similarly, device reads descriptors from the ring in order and
> > +detects that a driver descriptor has been made available.  As
> > +processing of descriptors is completed used descriptors are
> > +written by the device back into the ring.
> > +
> > +Note: after reading driver descriptors and starting their
> > +processing in order, device might complete their processing out
> > +of order.  Used device descriptors are written in the order
> > +in which their processing is complete.
> > +
> > +Device Event Suppression data structure is write-only by the
> > +device. It includes information for reducing the number of
> > +device events - i.e. driver notifications to device.
> > +
> > +Driver Event Suppression data structure is read-only by the
> > +device. It includes information for reducing the number of
> > +driver events - i.e. device interrupts to driver.
> > +
> > +\subsection{Driver and Device Ring Wrap Counters}
> > +\label{sec:Packed Virtqueues / Driver and Device Ring Wrap Counters}
> > +Each of the driver and the device are expected to maintain,
> > +internally, a single-bit ring wrap counter initialized to 1.
> > +
> > +The counter maintained by the driver is called the Driver
> > +Ring Wrap Counter. Driver changes the value of this counter
> > +each time it makes available the
> > +last descriptor in the ring (after making the last descriptor
> > +available).
> > +
> > +The counter maintained by the device is called the Device Ring Wrap
> > +Counter.  Device changes the value of this counter
> > +each time it uses the last descriptor in
> > +the ring (after marking the last descriptor used).
> > +
> > +It is easy to see that the Driver Ring Wrap Counter in the driver matches
> > +the Device Ring Wrap Counter in the device when both are processing the same
> > +descriptor, or when all available descriptors have been used.
> > +
> > +To mark a descriptor as available and used, both driver and
> > +device use the following two flags:
> > +\begin{lstlisting}
> > +#define VIRTQ_DESC_F_AVAIL     (1 << 7)
> > +#define VIRTQ_DESC_F_USED      (1 << 15)
> > +\end{lstlisting}
> > +
> > +To mark a descriptor as available, driver sets the
> > +VIRTQ_DESC_F_AVAIL bit in Flags to match the internal Driver
> > +Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_USED bit to match the
> > +\emph{inverse} value (i.e. to not match the internal Driver Ring
> > +Wrap Counter).
> > +
> > +To mark a descriptor as used, device sets the
> > +VIRTQ_DESC_F_USED bit in Flags to match the internal Device
> > +Ring Wrap Counter.  It also sets the VIRTQ_DESC_F_AVAIL bit to match the
> > +\emph{same} value.
> > +
> > +Thus VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED bits are different
> > +for an available descriptor and equal for a used descriptor.
> > +
> 
> AFAIU VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED being
> different is a necessary but not a sufficient pre-condition for
> a descriptor being available; VIRTQ_DESC_F_AVAIL and VIRTQ_DESC_F_USED
> equal is a necessary but not a sufficient pre-condition for
> a descriptor being used. Did I get that right?
> 
> If I got it right, then my suggestion is to provide a necessary and
> sufficient condition here.
> 
> 
> > +\subsection{Polling of available and used descriptors}
> > +\label{sec:Packed Virtqueues / Polling of available and used descriptors}
> > +
> > +Writes of device and driver descriptors can generally be
> > +reordered, but each side (driver and device) are only required to
> > +poll (or test) a single location in memory: next device descriptor after
> > +the one they processed previously, in circular order.
> > +
> > +Sometimes device needs to only write out a single used descriptor
> > +after processing a batch of multiple available descriptors.  As
> > +described in more detail below, this can happen when using
> > +descriptor chaining or with in-order
> > +use of descriptors.  In this case, device writes out a used
> > +descriptor with buffer id of the last descriptor in the group.
> > +After processing the used descriptor, both device and driver then
> > +skip forward in the ring the number of the remaining descriptors
> > +in the group until processing (reading for the driver and writing
> > +for the device) the next used descriptor.
> > +
> > +\subsection{Write Flag}
> > +\label{sec:Packed Virtqueues / Write Flag}
> > +
> > +In an available descriptor, VIRTQ_DESC_F_WRITE bit within Flags
> > +is used to mark a descriptor as corresponding to a write-only or
> > +read-only element of a buffer.
> > +
> > +\begin{lstlisting}
> > +/* This marks a descriptor as device write-only (otherwise device read-only). */
> > +#define VIRTQ_DESC_F_WRITE     2
> > +\end{lstlisting}
> > +
> > +In a used descriptor, this bit is used to specify whether any
> > +data has been written by the device into any parts of the buffer.
> > +
> > +
> > +\subsection{Element Address and Length}
> > +\label{sec:Packed Virtqueues / Element Address and Length}
> > +
> > +In an available descriptor, Element Address corresponds to the
> > +physical address of the buffer element. The length of the element assumed
> > +to be physically contigious is stored in Element Length.
> > +
> > +In a used descriptor, Element Address is unused. Element Length
> > +specifies the length of the buffer that has been initialized
> > +(written to) by the device.
> > +
> > +Element length is reserved for used descriptors without the
> > +VIRTQ_DESC_F_WRITE flag, and is ignored by drivers.
> > +
> > +\subsection{Scatter-Gather Support}
> 
> [Consistent wording] Both types of virtqueues support scatter-gather
> but the term is used only for packed. Maybe we could unify the wording.
> Or is this something for later?

I'll take a look but this can be safely done later too.


> > +\label{sec:Packed Virtqueues / Scatter-Gather Support}
> > +
> > +Some drivers need an ability to supply a list of multiple buffer
> > +elements (also known as a scatter/gather list) with a request.
> > +Two optional features support this: descriptor
> > +chaining and indirect descriptors.
> > +
> > +If neither feature has been negotiated, each buffer is
> > +physically-contigious, either read-only or write-only and is
> > +described completely by a single descriptor.
> > +
> > +While unusual (most implementations either create all lists
> > +solely using non-indirect descriptors, or always use a single
> > +indirect element), if both features have been negotiated, mixing
> > +direct and direct descriptors in a ring is valid, as long as each
> > +list only contains descriptors of a given type.
> > +
> > +Scatter/gather lists only apply to available descriptors. A
> > +single used descriptor corresponds to the whole list.
> > +
> > +The device limits the number of descriptors in a list through a
> > +transport-specific and/or device-specific value. If not limited,
> > +the maximum number of descriptors in a list is the virt queue
> > +size.
> > +
> > +\subsection{Next Flag: Descriptor Chaining}
> > +\label{sec:Packed Virtqueues / Next Flag: Descriptor Chaining}
> > +
> > +The packed ring format allows driver to supply
> > +a scatter/gather list to the device
> > +by using multiple descriptors, and setting the VIRTQ_DESC_F_NEXT in
> > +Flags for all but the last available descriptor.
> > +
> > +\begin{lstlisting}
> > +/* This marks a buffer as continuing. */
> > +#define VIRTQ_DESC_F_NEXT   1
> > +\end{lstlisting}
> > +
> > +Buffer ID is included in the last descriptor in the list.
> > +
> > +The driver always makes the first descriptor in the list
> > +available after the rest of the list has been written out into
> > +the ring. This guarantees that the device will never observe a
> > +partial scatter/gather list in the ring.
> > +
> > +Note: all flags, including VIRTQ_DESC_F_AVAIL, VIRTQ_DESC_F_USED,
> > +VIRTQ_DESC_F_WRITE must be set/cleared correctly in all
> > +descriptors in the list, not just the first one.
> > +
> > +Device only writes out a single used descriptor for the whole
> > +list. It then skips forward according to the number of
> > +descriptors in the list. Driver needs to keep track of the size
> > +of the list corresponding to each buffer ID, to be able to skip
> > +to where the next used descriptor is written by the device.
> > +
> > +For example, if descriptors are used in the same order in which
> > +they are made available, this will result in the used descriptor
> > +overwriting the first available descriptor in the list, the used
> > +descriptor for the next list overwriting the first available
> > +descriptor in the next list, etc.
> > +
> > +VIRTQ_DESC_F_NEXT is reserved in used descriptors, and
> > +should be ignored by drivers.
> > +
> > +\subsection{Indirect Flag: Scatter-Gather Support}
> > +\label{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Support}
> > +
> > +Some devices benefit by concurrently dispatching a large number
> > +of large requests. The VIRTIO_F_INDIRECT_DESC feature allows this. To increase
> > +ring capacity the driver can store a (read-only by the device) table of indirect
> > +descriptors anywhere in memory, and insert a descriptor in main
> > +virtqueue (with \field{Flags} bit VIRTQ_DESC_F_INDIRECT on) that refers to
> > +a buffer element
> > +containing this indirect descriptor table; \field{addr} and \field{len}
> > +refer to the indirect table address and length in bytes,
> > +respectively.
> > +\begin{lstlisting}
> > +/* This means the element contains a table of descriptors. */
> > +#define VIRTQ_DESC_F_INDIRECT   4
> > +\end{lstlisting}
> > +
> > +The indirect table layout structure looks like this
> > +(\field{len} is the Buffer Length of the descriptor that refers to this table,
> > +which is a variable):
> > +
> > +\begin{lstlisting}
> > +struct indirect_descriptor_table {
> > +        /* The actual descriptor structures (struct virtq_desc each) */
> > +        struct virtq_desc desc[len / sizeof(struct virtq_desc)];
> > +};
> > +\end{lstlisting}
> > +
> > +The first descriptor is located at start of the indirect
> > +descriptor table, additional indirect descriptors come
> > +immediately afterwards. \field{Flags} bit VIRTQ_DESC_F_WRITE is the
> > +only valid flag for descriptors in the indirect table. Others
> > +are reserved and are ignored by the device.
> > +Buffer ID is also reserved and is ignored by the device.
> > +
> > +In Descriptors with VIRTQ_DESC_F_INDIRECT set VIRTQ_DESC_F_WRITE
> > +is reserved and is ignored by the device.
> > +
> > +\subsection{Multi-buffer requests}
> > +\label{sec:Packed Virtqueues / Multi-descriptor batches}
> > +Some devices combine multiple buffers as part of processing of a
> > +single request.  These devices always mark the first descriptor
> > +in the request used after the rest of the descriptors in the
> > +request has been written out into the ring. This guarantees that
> > +the driver will never observe a partial request in the ring.
> > +
> 
> I see you've changed s/in the request available/in the request used/.
> But I still don't understand this paragraph. I will try to figure
> it out later (and will come back to you if I fail).

FYI this applies to mergeable buffers for the network device.


> > +
> > +\subsection{Driver and Device Event Suppression}
> > +\label{sec:Packed Virtqueues / Driver and Device Event Suppression}
> > +In many systems driver and device notifications involve
> > +significant overhead. To mitigate this overhead,
> > +each virtqueue includes two identical structures used for
> > +controlling notifications between device and driver.
> > +
> > +Driver Event Suppression structure is read-only by the
> > +device and controls the events sent by the device
> > +to the driver (e.g. interrupts).
> > +
> > +Device Event Suppression structure is read-only by
> > +the driver and controls the events sent by the driver
> > +to the device (e.g. IO).
> > +
> > +Each of these Event Suppression structures controls
> > +both Descriptor Ring events and structure events, and
> > +each includes the following fields:
> > +
> > +\begin{description}
> > +\item [Descriptor Ring Change Event Flags] Takes values:
> > +\begin{itemize}
> > +\item 00b enable events
> > +\item 01b disable events
> > +\item 10b enable events for a specific descriptor
> > +(as specified by Descriptor Ring Change Event Offset/Wrap Counter).
> > +Only valid if VIRTIO_F_RING_EVENT_IDX has been negotiated.
> > +\item 11b reserved
> > +\end{itemize}
> > +\item [Descriptor Ring Change Event Offset] If Event Flags set to descriptor
> > +specific event: offset within the ring (in units of descriptor
> > +size). Event will only trigger when this descriptor is
> > +made available/used respectively.
> > +\item [Descriptor Ring Change Event Wrap Counter] If Event Flags set to descriptor
> > +specific event: offset within the ring (in units of descriptor
> > +size). Event will only trigger when Ring Wrap Counter
> > +matches this value and a descriptor is
> > +made available/used respectively.
> > +\end{description}
> > +
> > +After writing out some descriptors, both device and driver
> > +are expected to consult the relevant structure to find out
> > +whether interrupt/notification should be sent.
> > +
> > +\subsubsection{Structure Size and Alignment}
> > +\label{sec:Packed Virtqueues / Structure Size and Alignment}
> > +
> > +Each part of the virtqueue is physically-contiguous in guest memory,
> > +and has different alignment requirements.
> > +
> > +The memory aligment and size requirements, in bytes, of each part of the
> 
> s/aligment/alignment/
> 
> > +virtqueue are summarized in the following table:
> > +
> > +\begin{tabular}{|l|l|l|}
> > +\hline
> > +Virtqueue Part    & Alignment & Size \\
> > +\hline \hline
> > +Descriptor Ring  & 16        & $16 * $(Queue Size) \\
> > +\hline
> > +Device Event Suppression    & 4         & 4 \\
> > + \hline
> > +Driver Event Suppression         & 4         & 4 \\
> > + \hline
> > +\end{tabular}
> > +
> > +The Alignment column gives the minimum alignment for each part
> > +of the virtqueue.
> > +
> > +The Size column gives the total number of bytes for each
> > +part of the virtqueue.
> > +
> > +Queue Size corresponds to the maximum number of descriptors in the
> > +virtqueue\footnote{For example, if Queue Size is 4 then at most 4 buffers
> > +can be queued at any given time.}.  Queue Size value does not
> > +have to be a power of 2 unless enforced by the transport.
> > +
> > +\drivernormative{\subsection}{Virtqueues}{Basic Facilities of a
> > +Virtio Device / Packed Virtqueues}
> > +The driver MUST ensure that the physical address of the first byte
> > +of each virtqueue part is a multiple of the specified alignment value
> > +in the above table.
> > +
> > +\devicenormative{\subsection}{Virtqueues}{Basic Facilities of a
> > +Virtio Device / Packed Virtqueues}
> > +The device MUST start processing driver descriptors in the order
> > +in which they appear in the ring.
> > +The device MUST start writing device descriptors into the ring in
> > +the order in which they complete.
> > +Device MAY reorder descriptor writes once they are started.
> > +
> > +\subsection{The Virtqueue Descriptor Format}\label{sec:Basic
> > +Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue
> > +Descriptor Format}
> > +
> > +The available descriptor refers to the buffers the driver is sending
> > +to the device. \field{addr} is a physical address, and the
> > +descriptor is identified with a buffer using the \field{id} field.
> > +
> > +\begin{lstlisting}
> > +struct virtq_desc {
> > +        /* Buffer Address. */
> > +        le64 addr;
> > +        /* Buffer Length. */
> > +        le32 len;
> > +        /* Buffer ID. */
> > +        le16 id;
> > +        /* The flags depending on descriptor type. */
> > +        le16 flags;
> > +};
> > +\end{lstlisting}
> > +
> > +The descriptor ring is zero-initialized.
> > +
> > +\subsection{Event Suppression Structure Format}\label{sec:Basic
> > +Facilities of a Virtio Device / Packed Virtqueues / Event Suppression Structure
> > +Format}
> > +
> > +The following structure is used to reduce the number of
> > +notifications sent between driver and device.
> > +
> > +\begin{lstlisting}
> > +__le16 desc_event_off : 15; /* Descriptor Event Offset */
> > +int    desc_event_wrap : 1; /* Descriptor Event Wrap Counter */
> > +__le16 desc_event_flags : 2; /* Descriptor Event Flags */
> > +\end{lstlisting}
> > +
> > +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
> > +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
> > +read a device-writable buffer.
> > +A device MUST NOT use a descriptor unless it observes
> > +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
> 
> I don't really understand this. How does the device observe
> the VIRTQ_DESC_F_AVAIL bit being changed?

By reading the descriptor.

> > +A device MUST NOT change a descriptor after changing it's
> > +VIRTQ_DESC_F_USED bit in its \field{flags}.
> > +
> > +\drivernormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / PAcked Virtqueues / The Virtqueue Descriptor Table}
> > +A driver MUST NOT change a descriptor unless it observes
> > +VIRTQ_DESC_F_USED bit in its \field{flags} being changed.
> > +A driver MUST NOT change a descriptor after changing
> > +VIRTQ_DESC_F_USED bit in its \field{flags}.
> 
> I'm a bit confused with this protocol. AFAIU the driver
> always writes the value into the VIRTQ_DESC_F_USED that
> is already there (so it does not change). Was that supposed
> to be VIRTQ_DESC_F_AVAIL.

That was supposed to be VIRTQ_DESC_F_AVAIL.

> > +When notifying the device, driver MUST set
> > +\field{next_off} and
> > +\field{next_wrap} to match the next descriptor
> > +not yet made available to the device.
> > +A driver MAY send multiple notifications without making
> > +any new descriptors available to the device.
> > +
> > +\drivernormative{\subsection}{Scatter-Gather Support}{Basic Facilities of a
> > +Virtio Device / Packed Virtqueues / Scatter-Gather Support}
> > +A driver MUST NOT create a descriptor list longer than allowed
> > +by the device.
> > +
> > +A driver MUST NOT create a descriptor list longer than the Queue
> > +Size.
> > +
> > +This implies that loops in the descriptor list are forbidden!
> > +
> > +The driver MUST place any device-writable descriptor elements after
> > +any device-readable descriptor elements.
> > +
> > +A driver MUST NOT depend on the device to use more descriptors
> > +to be able to write out all descriptors in a list. A driver
> > +MUST make sure there's enough space in the ring
> > +for the whole list before making the first descriptor in the list
> > +available to the device.
> > +
> > +A driver MUST NOT make the first descriptor in the list
> > +available before initializing the rest of the descriptors.
> 
> Initializing is a bit vague here. How about: unless all subsequent descriptors
> comprising the list (that is the request) are made available.

OK.

> > +
> > +\devicenormative{\subsection}{Scatter-Gather Support}{Basic Facilities of a
> > +Virtio Device / Packed Virtqueues / Scatter-Gather Support}
> > +The device MUST use descriptors in a list chained by the
> > +VIRTQ_DESC_F_NEXT flag in the same order that they
> > +were made available by the driver.
> > +
> > +The device MAY limit the number of buffers it will allow in a
> > +list.
> > +
> > +\drivernormative{\subsection}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
> > +The driver MUST NOT set the DESC_F_INDIRECT flag unless the
> > +VIRTIO_F_INDIRECT_DESC feature was negotiated.   The driver MUST NOT
> > +set any flags except DESC_F_WRITE within an indirect descriptor.
> > +
> > +A driver MUST NOT create a descriptor chain longer than allowed
> > +by the device.
> > +
> > +A driver MUST NOT write direct descriptors with
> > +DESC_F_INDIRECT set in a scatter-gather list linked by
> > +VIRTQ_DESC_F_NEXT.
> > +\field{flags}.
> > +
> > +\subsection{Virtqueue Operation}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Virtqueue Operation}
> > +
> > +There are two parts to virtqueue operation: supplying new
> > +available buffers to the device, and processing used buffers from
> > +the device.
> > +
> > +What follows is the requirements of each of these two parts
> > +when using the packed virtqueue format in more detail.
> > +
> > +\subsection{Supplying Buffers to The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device}
> > +
> > +The driver offers buffers to one of the device's virtqueues as follows:
> > +
> > +\begin{enumerate}
> > +\item The driver places the buffer into free descriptor in the Descriptor Ring.
> > +
> > +\item The driver performs a suitable memory barrier to ensure that it updates
> > +  the descriptor(s) before checking for notification suppression.
> > +
> > +\item If notifications are not suppressed, the driver notifies the device
> > +    of the new available buffers.
> > +\end{enumerate}
> > +
> > +What follows is the requirements of each stage in more detail.
> > +
> > +\subsubsection{Placing Available Buffers Into The Descriptor Ring}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Placing Available Buffers Into The Descriptor Ring}
> > +
> > +For each buffer element, b:
> > +
> > +\begin{enumerate}
> > +\item Get the next descriptor table entry, d
> > +\item Get the next free buffer id value
> > +\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 Set \field{d.id} to the buffer id
> > +\item Calculate the flags as follows:
> > +\begin{enumerate}
> > +\item If b is device-writable, set the VIRTQ_DESC_F_WRITE bit to 1, otherwise 0
> > +\item Set VIRTQ_DESC_F_AVAIL bit to the current value of the Driver Ring Wrap Counter
> > +\item Set VIRTQ_DESC_F_USED bit to inverse value
> > +\end{enumerate}
> > +\item Perform a memory barrier to ensure that the descriptor has
> > +      been initialized
> > +\item Set \field{d.flags} to the calculated flags value
> > +\item If d is the last descriptor in the ring, toggle the
> > +      Driver Ring Wrap Counter
> > +\item Otherwise, increment d to point at the next descriptor
> > +\end{enumerate}
> > +
> > +This makes a single descriptor buffer available. However, in
> > +general the driver MAY make use of a batch of descriptors as part
> > +of a single request. In that case, it defers updating
> > +the descriptor flags for the first descriptor
> > +(and the previous memory barrier) until after the rest of
> > +the descriptors have been initialized.
> > +
> > +Once the descriptor \field{flags} is updated by the driver, this exposes the
> > +descriptor and its contents.  The device MAY
> > +access the descriptor and any following descriptors the driver created and the
> > +memory they refer to immediately.
> > +
> > +\drivernormative{\paragraph}{Updating flags}{Basic Facilities of
> > +a Virtio Device / Packed Virtqueues / Supplying Buffers to The
> > +Device / Updating flags}
> > +The driver MUST perform a suitable memory barrier before the
> > +\field{flags} update, to ensure the
> > +device sees the most up-to-date copy.
> > +
> > +\subsubsection{Notifying The Device}\label{sec:Basic Facilities
> > +of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
> > +
> > +The actual method of device notification is bus-specific, but generally
> > +it can be expensive.  So the device MAY suppress such notifications if it
> > +doesn't need them, using the Driver Event Suppression structure
> > +as detailed in section \ref{sec:Basic
> > +Facilities of a Virtio Device / Packed Virtqueues / Event
> > +Suppression Structure Format}.
> > +
> > +The driver has to be careful to expose the new \field{flags}
> > +value before checking if notifications are suppressed.
> > +
> > +\subsubsection{Implementation Example}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Implementation Example}
> > +
> > +Below is an example driver code. It does not attempt to reduce
> > +the number of device interrupts, neither does it support
> > +the VIRTIO_F_RING_EVENT_IDX feature.
> > +
> > +\begin{lstlisting}
> > +
> > +first = vq->next_avail;
> > +id = alloc_id(vq);
> > +
> > +for (each buffer element b) {
> > +        vq->desc[vq->next_avail].address = get_addr(b);
> > +        vq->desc[vq->next_avail].len = get_len(b);
> > +        init_desc(vq->next_avail, b);
> 
> What is init_desc? Can't find it elsewhere and I can't
> guess it.

Leftover  I think  - initially the above two lines
were part of that function.

> > +        avail = vq->avail_wrap_count;
> > +        used = !vq->avail_wrap_count;
> > +        f = get_flags(b) | (avail << VIRTQ_DESC_F_AVAIL) | (used << VIRTQ_DESC_F_USED);
> > +	/* Don't mark the 1st descriptor available until all of them are ready. */
> > +        if (vq->next_avail == first) {
> > +                flags = f;
> > +        } else {
> > +                vq->desc[vq->next_avail].flags = f;
> > +        }
> > +
> > +	vq->next_avail++;
> > +
> > +	if (vq->next_avail >= vq->size) {
> > +		vq->next_avail = 0;
> > +		vq->avail_wrap_count \^= 1;
> > +	}
> > +
> > +
> > +}
> > +/* ID included in the last descriptor in the list */
> > +vq->desc[vq->next_avail].id = id;
> > +write_memory_barrier();
> > +vq->desc[first].flags = flags;
> > +
> > +memory_barrier();
> > +
> > +if (vq->device_event.flags != 0x2) {
> > +        notify_device(vq);
> > +}
> > +
> > +\end{lstlisting}
> > +
> > +
> > +\drivernormative{\paragraph}{Notifying The Device}{Basic Facilities of a Virtio Device / Packed Virtqueues / Supplying Buffers to The Device / Notifying The Device}
> > +The driver MUST perform a suitable memory barrier before reading
> > +the Driver Event Suppression structure, to avoid missing a notification.
> > +
> > +\subsection{Receiving Used Buffers From The Device}\label{sec:Basic Facilities of a Virtio Device / Packed Virtqueues / Receiving Used Buffers From The Device}
> > +
> > +Once the device has used buffers referred to by a descriptor (read from or written to them, or
> > +parts of both, depending on the nature of the virtqueue and the
> > +device), it interrupts the driver
> > +as detailed in section \ref{sec:Basic
> > +Facilities of a Virtio Device / Packed Virtqueues / Event
> > +Suppression Structure Format}.
> > +
> > +\begin{note}
> > +For optimal performance, a driver MAY disable interrupts while processing
> > +the used buffers, but beware the problem of missing interrupts between
> > +emptying the ring and reenabling interrupts.  This is usually handled by
> > +re-checking for more used buffers after interrups are re-enabled:
> > +\end{note}
> > +
> > +\begin{lstlisting}
> > +vq->driver_event.flags = 0x2;
> > +
> > +for (;;) {
> > +        struct virtq_desc *d = vq->desc[vq->next_used];
> > +
> > +        flags = d->flags;
> > +        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> > +        bool used = flags & (1 << VIRTQ_DESC_F_USED);
> > +
> > +        if (avail != used) {
> 
> I don't understand the condition which is AFAIU supposed to
> correspond to the descriptor *not* being used.

So avail == used means used. avail != used means available.

> > +                vq->driver_event.flags = 0x1;
> > +                memory_barrier();
> > +
> > +                flags = d->flags;
> > +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> > +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
> > +                if (avail != used) {
> > +                        break;
> > +                }
> > +
> > +                vq->driver_event.flags = 0x2;
> > +        }
> > +
> > +	read_memory_barrier();
> 
> Now with the condition avail != used a freshly (that is zero initialized)
> ring would appear all used. And we would do process_buffer(d) for the
> whole ring if this code happens to get executed. Do we have to make
> sure that this does not happen?

I'll have to think about this.



> I was under the impression that this whole wrap counter exercise is
> to be able to distinguish these cases.
> 
> BTW tools/virtio/ringtest/ring.c has a single flag bit to indicate
> available/used and does not have these wrap counters AFAIR.

A single flag is fine if there's not s/g support and all descriptors are
written out.  Wrap counters are needed if we are to support skipping
descriptors because of s/g or in order.


> Also for split virtqueues  a descriptor has three possible states:
> * available
> * used
> * free
> 
> I wonder if it's the same for packed, and if, how do I recognize
> free descriptors (that is descriptors that are neither available
> nor used.

I'll think about this.

> I'm pretty much confused on how this scheme with the available
> and used wrap counters (or device and driver wrap counters is
> supposed to work). A working implementation in C would really help
> me to understand this.

DPDK based implementation has been posted.

> > +        process_buffer(d);
> > +        vq->next_used++;
> > +        if (vq->next_used >= vq->size) {
> > +                vq->next_used = 0;
> > +        }
> > +}
> > +\end{lstlisting}
> > 

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Jens Freimann]

On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
>On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
>> > +                vq->driver_event.flags = 0x1;
>> > +                memory_barrier();
>> > +
>> > +                flags = d->flags;
>> > +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>> > +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
>> > +                if (avail != used) {
>> > +                        break;
>> > +                }
>> > +
>> > +                vq->driver_event.flags = 0x2;
>> > +        }
>> > +
>> > +	read_memory_barrier();
>>
>> Now with the condition avail != used a freshly (that is zero initialized)
>> ring would appear all used. And we would do process_buffer(d) for the
>> whole ring if this code happens to get executed. Do we have to make
>> sure that this does not happen?
>
>I'll have to think about this.

With the wrap counter initialized to 1 descriptors would not be seen
as used. 

>
>
>> I was under the impression that this whole wrap counter exercise is
>> to be able to distinguish these cases.
>>
>> BTW tools/virtio/ringtest/ring.c has a single flag bit to indicate
>> available/used and does not have these wrap counters AFAIR.
>
>A single flag is fine if there's not s/g support and all descriptors are
>written out.  Wrap counters are needed if we are to support skipping
>descriptors because of s/g or in order.
>
>
>> Also for split virtqueues  a descriptor has three possible states:
>> * available
>> * used
>> * free
>>
>> I wonder if it's the same for packed, and if, how do I recognize
>> free descriptors (that is descriptors that are neither available
>> nor used.
>
>I'll think about this.
>
>> I'm pretty much confused on how this scheme with the available
>> and used wrap counters (or device and driver wrap counters is
>> supposed to work). A working implementation in C would really help
>> me to understand this.
>
>DPDK based implementation has been posted.

vhost and guest drivers have also been posted.
guest: https://lkml.org/lkml/2018/2/23/242
vhost: https://lkml.org/lkml/2018/2/13/1102

regards,
Jens 

>
>> > +        process_buffer(d);
>> > +        vq->next_used++;
>> > +        if (vq->next_used >= vq->size) {
>> > +                vq->next_used = 0;
>> > +        }
>> > +}
>> > +\end{lstlisting}
>> >
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
>For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Halil Pasic]

On 02/27/2018 11:23 AM, Jens Freimann wrote:
> On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
>> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
>>> > +                vq->driver_event.flags = 0x1;
>>> > +                memory_barrier();
>>> > +
>>> > +                flags = d->flags;
>>> > +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>>> > +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
>>> > +                if (avail != used) {
>>> > +                        break;
>>> > +                }
>>> > +
>>> > +                vq->driver_event.flags = 0x2;
>>> > +        }
>>> > +
>>> > +    read_memory_barrier();
>>>
>>> Now with the condition avail != used a freshly (that is zero initialized)
>>> ring would appear all used. And we would do process_buffer(d) for the
>>> whole ring if this code happens to get executed. Do we have to make
>>> sure that this does not happen?
>>
>> I'll have to think about this.
> 
> With the wrap counter initialized to 1 descriptors would not be seen
> as used.

Looking at the code... In vhost:

+static bool desc_is_avail(struct vhost_virtqueue *vq,
+			  struct vring_desc_packed *desc)
+{
+	if (vq->used_wrap_counter)
+		if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
+			return true;
+	if (vq->used_wrap_counter == false)
+		if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
+			return true;
+
+	return false;
+}

Here the bit pattern corresponding to available depends on the
value of the wrap counter. I kind of anticipated this, but I could not
find it defined in this spec.

OTOH in guest:

+static inline bool more_used_packed(const struct vring_virtqueue *vq)
+{
+	u16 last_used, flags;
+	bool avail, used;
+
+	if (vq->vq.num_free == vq->vring.num)
+		return false;
+
+	last_used = vq->last_used_idx;
+	flags = virtio16_to_cpu(vq->vq.vdev,
+				vq->vring_packed.desc[last_used].flags);
+	avail = flags & VRING_DESC_F_AVAIL(1);
+	used = flags & VRING_DESC_F_USED(1);
+
+	return avail == used;
+}

if the next to be used descriptor is actually used does not depend on
any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
condition. This extra condition is basically 'there are outstanding
descriptors' and those are obviously either 'available' or yet to be observed
'used' descriptors. Right after initialization is covered by this extra
condition. And obviously if the descriptor in question is still available
flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
with the extra condition we are right there where we want to be.

But I could not find the extra condition in the spec.

With that said, I also want to point out that I don't understand
your statement Jens. I don't see a way to express the condition corresponding
to more_used_packed() using the driver wrap counter (avail_wrap_count).
Of course a wrap counter that wraps when last_used wraps could be used
to (but no such counter is mentioned here AFAIU).

>>
>>
>>> I was under the impression that this whole wrap counter exercise is
>>> to be able to distinguish these cases.
>>>
>>> BTW tools/virtio/ringtest/ring.c has a single flag bit to indicate
>>> available/used and does not have these wrap counters AFAIR.
>>
>> A single flag is fine if there's not s/g support and all descriptors are
>> written out.  Wrap counters are needed if we are to support skipping
>> descriptors because of s/g or in order.
>>
>>
>>> Also for split virtqueues  a descriptor has three possible states:
>>> * available
>>> * used
>>> * free
>>>
>>> I wonder if it's the same for packed, and if, how do I recognize
>>> free descriptors (that is descriptors that are neither available
>>> nor used.
>>
>> I'll think about this.
>>
>>> I'm pretty much confused on how this scheme with the available
>>> and used wrap counters (or device and driver wrap counters is
>>> supposed to work). A working implementation in C would really help
>>> me to understand this.
>>
>> DPDK based implementation has been posted.
> 
> vhost and guest drivers have also been posted.
> guest: https://lkml.org/lkml/2018/2/23/242
> vhost: https://lkml.org/lkml/2018/2/13/1102
> 

Thanks a lot. I've already found vhost myself but you saved me
some searching with the other one ;).

> regards,
> Jens
>>
>>> > +        process_buffer(d);
>>> > +        vq->next_used++;
>>> > +        if (vq->next_used >= vq->size) {
>>> > +                vq->next_used = 0;
>>> > +        }
>>> > +}
>>> > +\end{lstlisting}
>>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
>>
> 


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Jens Freimann]

On Tue, Feb 27, 2018 at 12:29:11PM +0100, Halil Pasic wrote:
>
>
>On 02/27/2018 11:23 AM, Jens Freimann wrote:
>> On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
>>> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
>>>> > +?????????????????????????????? vq->driver_event.flags = 0x1;
>>>> > +?????????????????????????????? memory_barrier();
>>>> > +
>>>> > +?????????????????????????????? flags = d->flags;
>>>> > +?????????????????????????????? bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>>>> > +?????????????????????????????? bool used = flags & (1 << VIRTQ_DESC_F_USED);
>>>> > +?????????????????????????????? if (avail != used) {
>>>> > +?????????????????????????????????????????????? break;
>>>> > +?????????????????????????????? }
>>>> > +
>>>> > +?????????????????????????????? vq->driver_event.flags = 0x2;
>>>> > +?????????????? }
>>>> > +
>>>> > +?????? read_memory_barrier();
>>>>
>>>> Now with the condition avail != used a freshly (that is zero initialized)
>>>> ring would appear all used. And we would do process_buffer(d) for the
>>>> whole ring if this code happens to get executed. Do we have to make
>>>> sure that this does not happen?
>>>
>>> I'll have to think about this.
>>
>> With the wrap counter initialized to 1 descriptors would not be seen
>> as used.
>
>Looking at the code... In vhost:
>
>+static bool desc_is_avail(struct vhost_virtqueue *vq,
>+			  struct vring_desc_packed *desc)
>+{
>+	if (vq->used_wrap_counter)
>+		if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
>+			return true;
>+	if (vq->used_wrap_counter == false)
>+		if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
>+			return true;
>+
>+	return false;
>+}
>
>Here the bit pattern corresponding to available depends on the
>value of the wrap counter. I kind of anticipated this, but I could not
>find it defined in this spec.
>
>OTOH in guest:
>
>+static inline bool more_used_packed(const struct vring_virtqueue *vq)
>+{
>+	u16 last_used, flags;
>+	bool avail, used;
>+
>+	if (vq->vq.num_free == vq->vring.num)
>+		return false;
>+
>+	last_used = vq->last_used_idx;
>+	flags = virtio16_to_cpu(vq->vq.vdev,
>+				vq->vring_packed.desc[last_used].flags);
>+	avail = flags & VRING_DESC_F_AVAIL(1);
>+	used = flags & VRING_DESC_F_USED(1);
>+
>+	return avail == used;
>+}
>
>if the next to be used descriptor is actually used does not depend on
>any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
>condition. This extra condition is basically 'there are outstanding
>descriptors' and those are obviously either 'available' or yet to be observed
>'used' descriptors. Right after initialization is covered by this extra
>condition. And obviously if the descriptor in question is still available
>flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
>with the extra condition we are right there where we want to be.
>
>But I could not find the extra condition in the spec.
>
>With that said, I also want to point out that I don't understand
>your statement Jens. I don't see a way to express the condition corresponding
>to more_used_packed() using the driver wrap counter (avail_wrap_count).
>Of course a wrap counter that wraps when last_used wraps could be used
>to (but no such counter is mentioned here AFAIU).

Not sure I get this. 

I was merely saying that when descriptor flags are initialized to 0
and the wrap counters to 1, then it is not the case that the driver
would see all descriptors as used because it takes the wrap counter
into account.


regards,
Jens 

---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Halil Pasic]

On 02/28/2018 02:42 PM, Jens Freimann wrote:
> On Tue, Feb 27, 2018 at 12:29:11PM +0100, Halil Pasic wrote:
>>
>>
>> On 02/27/2018 11:23 AM, Jens Freimann wrote:
>>> On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
>>>> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
>>>>> > +?????????????????????????????? vq->driver_event.flags = 0x1;
>>>>> > +?????????????????????????????? memory_barrier();
>>>>> > +
>>>>> > +?????????????????????????????? flags = d->flags;
>>>>> > +?????????????????????????????? bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>>>>> > +?????????????????????????????? bool used = flags & (1 << VIRTQ_DESC_F_USED);
>>>>> > +?????????????????????????????? if (avail != used) {
>>>>> > +?????????????????????????????????????????????? break;
>>>>> > +?????????????????????????????? }
>>>>> > +
>>>>> > +?????????????????????????????? vq->driver_event.flags = 0x2;
>>>>> > +?????????????? }
>>>>> > +
>>>>> > +?????? read_memory_barrier();
>>>>>
>>>>> Now with the condition avail != used a freshly (that is zero initialized)
>>>>> ring would appear all used. And we would do process_buffer(d) for the
>>>>> whole ring if this code happens to get executed. Do we have to make
>>>>> sure that this does not happen?
>>>>
>>>> I'll have to think about this.
>>>
>>> With the wrap counter initialized to 1 descriptors would not be seen
>>> as used.
>>
>> Looking at the code... In vhost:
>>
>> +static bool desc_is_avail(struct vhost_virtqueue *vq,
>> +              struct vring_desc_packed *desc)
>> +{
>> +    if (vq->used_wrap_counter)
>> +        if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
>> +            return true;
>> +    if (vq->used_wrap_counter == false)
>> +        if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
>> +            return true;
>> +
>> +    return false;
>> +}
>>
>> Here the bit pattern corresponding to available depends on the
>> value of the wrap counter. I kind of anticipated this, but I could not
>> find it defined in this spec.
>>
>> OTOH in guest:
>>
>> +static inline bool more_used_packed(const struct vring_virtqueue *vq)
>> +{
>> +    u16 last_used, flags;
>> +    bool avail, used;
>> +
>> +    if (vq->vq.num_free == vq->vring.num)
>> +        return false;
>> +
>> +    last_used = vq->last_used_idx;
>> +    flags = virtio16_to_cpu(vq->vq.vdev,
>> +                vq->vring_packed.desc[last_used].flags);
>> +    avail = flags & VRING_DESC_F_AVAIL(1);
>> +    used = flags & VRING_DESC_F_USED(1);
>> +
>> +    return avail == used;
>> +}
>>
>> if the next to be used descriptor is actually used does not depend on
>> any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
>> condition. This extra condition is basically 'there are outstanding
>> descriptors' and those are obviously either 'available' or yet to be observed
>> 'used' descriptors. Right after initialization is covered by this extra
>> condition. And obviously if the descriptor in question is still available
>> flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
>> with the extra condition we are right there where we want to be.
>>
>> But I could not find the extra condition in the spec.
>>
>> With that said, I also want to point out that I don't understand
>> your statement Jens. I don't see a way to express the condition corresponding
>> to more_used_packed() using the driver wrap counter (avail_wrap_count).
>> Of course a wrap counter that wraps when last_used wraps could be used
>> to (but no such counter is mentioned here AFAIU).
> 
> Not sure I get this.
> I was merely saying that when descriptor flags are initialized to 0
> and the wrap counters to 1, then it is not the case that the driver
> would see all descriptors as used because it takes the wrap counter
> into account.
> 

Please point me to the paragraph where it's written  how is the wrap
counter to be taken into account when trying to determine if the
desc_ring[last_used] (the descriptor we are polling) is used or not.

Nothing like that being specified (or at least I could not find it)
was actually what I got hooked on.

Regards,
Halil




---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Wed, Feb 28, 2018 at 02:59:51PM +0100, Halil Pasic wrote:
> 
> 
> On 02/28/2018 02:42 PM, Jens Freimann wrote:
> > On Tue, Feb 27, 2018 at 12:29:11PM +0100, Halil Pasic wrote:
> >>
> >>
> >> On 02/27/2018 11:23 AM, Jens Freimann wrote:
> >>> On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
> >>>> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
> >>>>> > +?????????????????????????????? vq->driver_event.flags = 0x1;
> >>>>> > +?????????????????????????????? memory_barrier();
> >>>>> > +
> >>>>> > +?????????????????????????????? flags = d->flags;
> >>>>> > +?????????????????????????????? bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> >>>>> > +?????????????????????????????? bool used = flags & (1 << VIRTQ_DESC_F_USED);
> >>>>> > +?????????????????????????????? if (avail != used) {
> >>>>> > +?????????????????????????????????????????????? break;
> >>>>> > +?????????????????????????????? }
> >>>>> > +
> >>>>> > +?????????????????????????????? vq->driver_event.flags = 0x2;
> >>>>> > +?????????????? }
> >>>>> > +
> >>>>> > +?????? read_memory_barrier();
> >>>>>
> >>>>> Now with the condition avail != used a freshly (that is zero initialized)
> >>>>> ring would appear all used. And we would do process_buffer(d) for the
> >>>>> whole ring if this code happens to get executed. Do we have to make
> >>>>> sure that this does not happen?
> >>>>
> >>>> I'll have to think about this.
> >>>
> >>> With the wrap counter initialized to 1 descriptors would not be seen
> >>> as used.
> >>
> >> Looking at the code... In vhost:
> >>
> >> +static bool desc_is_avail(struct vhost_virtqueue *vq,
> >> +              struct vring_desc_packed *desc)
> >> +{
> >> +    if (vq->used_wrap_counter)
> >> +        if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
> >> +            return true;
> >> +    if (vq->used_wrap_counter == false)
> >> +        if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
> >> +            return true;
> >> +
> >> +    return false;
> >> +}
> >>
> >> Here the bit pattern corresponding to available depends on the
> >> value of the wrap counter. I kind of anticipated this, but I could not
> >> find it defined in this spec.
> >>
> >> OTOH in guest:
> >>
> >> +static inline bool more_used_packed(const struct vring_virtqueue *vq)
> >> +{
> >> +    u16 last_used, flags;
> >> +    bool avail, used;
> >> +
> >> +    if (vq->vq.num_free == vq->vring.num)
> >> +        return false;
> >> +
> >> +    last_used = vq->last_used_idx;
> >> +    flags = virtio16_to_cpu(vq->vq.vdev,
> >> +                vq->vring_packed.desc[last_used].flags);
> >> +    avail = flags & VRING_DESC_F_AVAIL(1);
> >> +    used = flags & VRING_DESC_F_USED(1);
> >> +
> >> +    return avail == used;
> >> +}
> >>
> >> if the next to be used descriptor is actually used does not depend on
> >> any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
> >> condition. This extra condition is basically 'there are outstanding
> >> descriptors' and those are obviously either 'available' or yet to be observed
> >> 'used' descriptors. Right after initialization is covered by this extra
> >> condition. And obviously if the descriptor in question is still available
> >> flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
> >> with the extra condition we are right there where we want to be.
> >>
> >> But I could not find the extra condition in the spec.
> >>
> >> With that said, I also want to point out that I don't understand
> >> your statement Jens. I don't see a way to express the condition corresponding
> >> to more_used_packed() using the driver wrap counter (avail_wrap_count).
> >> Of course a wrap counter that wraps when last_used wraps could be used
> >> to (but no such counter is mentioned here AFAIU).
> > 
> > Not sure I get this.
> > I was merely saying that when descriptor flags are initialized to 0
> > and the wrap counters to 1, then it is not the case that the driver
> > would see all descriptors as used because it takes the wrap counter
> > into account.
> > 
> 
> Please point me to the paragraph where it's written  how is the wrap
> counter to be taken into account when trying to determine if the
> desc_ring[last_used] (the descriptor we are polling) is used or not.
> 
> Nothing like that being specified (or at least I could not find it)
> was actually what I got hooked on.
> 
> Regards,
> Halil
> 

Maintaining an internal "last used wrap counter" is one way to
detect ring entry change. Another would be to maintain
a per-entry "last used flag".

I should probably do this in pseudo-code, and maybe add an
implementation note.

-- 
MST

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Halil Pasic]

On 02/28/2018 04:40 PM, Michael S. Tsirkin wrote:
> On Wed, Feb 28, 2018 at 02:59:51PM +0100, Halil Pasic wrote:
>>
>>
>> On 02/28/2018 02:42 PM, Jens Freimann wrote:
>>> On Tue, Feb 27, 2018 at 12:29:11PM +0100, Halil Pasic wrote:
>>>>
>>>>
>>>> On 02/27/2018 11:23 AM, Jens Freimann wrote:
>>>>> On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
>>>>>> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
>>>>>>>> +?????????????????????????????? vq->driver_event.flags = 0x1;
>>>>>>>> +?????????????????????????????? memory_barrier();
>>>>>>>> +
>>>>>>>> +?????????????????????????????? flags = d->flags;
>>>>>>>> +?????????????????????????????? bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>>>>>>>> +?????????????????????????????? bool used = flags & (1 << VIRTQ_DESC_F_USED);
>>>>>>>> +?????????????????????????????? if (avail != used) {
>>>>>>>> +?????????????????????????????????????????????? break;
>>>>>>>> +?????????????????????????????? }
>>>>>>>> +
>>>>>>>> +?????????????????????????????? vq->driver_event.flags = 0x2;
>>>>>>>> +?????????????? }
>>>>>>>> +
>>>>>>>> +?????? read_memory_barrier();
>>>>>>>
>>>>>>> Now with the condition avail != used a freshly (that is zero initialized)
>>>>>>> ring would appear all used. And we would do process_buffer(d) for the
>>>>>>> whole ring if this code happens to get executed. Do we have to make
>>>>>>> sure that this does not happen?
>>>>>>
>>>>>> I'll have to think about this.
>>>>>
>>>>> With the wrap counter initialized to 1 descriptors would not be seen
>>>>> as used.
>>>>
>>>> Looking at the code... In vhost:
>>>>
>>>> +static bool desc_is_avail(struct vhost_virtqueue *vq,
>>>> +              struct vring_desc_packed *desc)
>>>> +{
>>>> +    if (vq->used_wrap_counter)
>>>> +        if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
>>>> +            return true;
>>>> +    if (vq->used_wrap_counter == false)
>>>> +        if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
>>>> +            return true;
>>>> +
>>>> +    return false;
>>>> +}
>>>>
>>>> Here the bit pattern corresponding to available depends on the
>>>> value of the wrap counter. I kind of anticipated this, but I could not
>>>> find it defined in this spec.
>>>>
>>>> OTOH in guest:
>>>>
>>>> +static inline bool more_used_packed(const struct vring_virtqueue *vq)
>>>> +{
>>>> +    u16 last_used, flags;
>>>> +    bool avail, used;
>>>> +
>>>> +    if (vq->vq.num_free == vq->vring.num)
>>>> +        return false;
>>>> +
>>>> +    last_used = vq->last_used_idx;
>>>> +    flags = virtio16_to_cpu(vq->vq.vdev,
>>>> +                vq->vring_packed.desc[last_used].flags);
>>>> +    avail = flags & VRING_DESC_F_AVAIL(1);
>>>> +    used = flags & VRING_DESC_F_USED(1);
>>>> +
>>>> +    return avail == used;
>>>> +}
>>>>
>>>> if the next to be used descriptor is actually used does not depend on
>>>> any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
>>>> condition. This extra condition is basically 'there are outstanding
>>>> descriptors' and those are obviously either 'available' or yet to be observed
>>>> 'used' descriptors. Right after initialization is covered by this extra
>>>> condition. And obviously if the descriptor in question is still available
>>>> flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
>>>> with the extra condition we are right there where we want to be.
>>>>
>>>> But I could not find the extra condition in the spec.
>>>>
>>>> With that said, I also want to point out that I don't understand
>>>> your statement Jens. I don't see a way to express the condition corresponding
>>>> to more_used_packed() using the driver wrap counter (avail_wrap_count).
>>>> Of course a wrap counter that wraps when last_used wraps could be used
>>>> to (but no such counter is mentioned here AFAIU).
>>>
>>> Not sure I get this.
>>> I was merely saying that when descriptor flags are initialized to 0
>>> and the wrap counters to 1, then it is not the case that the driver
>>> would see all descriptors as used because it takes the wrap counter
>>> into account.
>>>
>>
>> Please point me to the paragraph where it's written  how is the wrap
>> counter to be taken into account when trying to determine if the
>> desc_ring[last_used] (the descriptor we are polling) is used or not.
>>
>> Nothing like that being specified (or at least I could not find it)
>> was actually what I got hooked on.
>>
>> Regards,
>> Halil
>>
> 
> Maintaining an internal "last used wrap counter" is one way to
> detect ring entry change. Another would be to maintain
> a per-entry "last used flag".
> 
> I should probably do this in pseudo-code, and maybe add an
> implementation note.
> 

Thanks! I will revisit this once you have a proposed solution.

Regards,
Halil


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Wed, Feb 28, 2018 at 02:59:51PM +0100, Halil Pasic wrote:
> 
> 
> On 02/28/2018 02:42 PM, Jens Freimann wrote:
> > On Tue, Feb 27, 2018 at 12:29:11PM +0100, Halil Pasic wrote:
> >>
> >>
> >> On 02/27/2018 11:23 AM, Jens Freimann wrote:
> >>> On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
> >>>> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
> >>>>> > +?????????????????????????????? vq->driver_event.flags = 0x1;
> >>>>> > +?????????????????????????????? memory_barrier();
> >>>>> > +
> >>>>> > +?????????????????????????????? flags = d->flags;
> >>>>> > +?????????????????????????????? bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> >>>>> > +?????????????????????????????? bool used = flags & (1 << VIRTQ_DESC_F_USED);
> >>>>> > +?????????????????????????????? if (avail != used) {
> >>>>> > +?????????????????????????????????????????????? break;
> >>>>> > +?????????????????????????????? }
> >>>>> > +
> >>>>> > +?????????????????????????????? vq->driver_event.flags = 0x2;
> >>>>> > +?????????????? }
> >>>>> > +
> >>>>> > +?????? read_memory_barrier();
> >>>>>
> >>>>> Now with the condition avail != used a freshly (that is zero initialized)
> >>>>> ring would appear all used. And we would do process_buffer(d) for the
> >>>>> whole ring if this code happens to get executed. Do we have to make
> >>>>> sure that this does not happen?
> >>>>
> >>>> I'll have to think about this.
> >>>
> >>> With the wrap counter initialized to 1 descriptors would not be seen
> >>> as used.
> >>
> >> Looking at the code... In vhost:
> >>
> >> +static bool desc_is_avail(struct vhost_virtqueue *vq,
> >> +              struct vring_desc_packed *desc)
> >> +{
> >> +    if (vq->used_wrap_counter)
> >> +        if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
> >> +            return true;
> >> +    if (vq->used_wrap_counter == false)
> >> +        if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
> >> +            return true;
> >> +
> >> +    return false;
> >> +}
> >>
> >> Here the bit pattern corresponding to available depends on the
> >> value of the wrap counter. I kind of anticipated this, but I could not
> >> find it defined in this spec.
> >>
> >> OTOH in guest:
> >>
> >> +static inline bool more_used_packed(const struct vring_virtqueue *vq)
> >> +{
> >> +    u16 last_used, flags;
> >> +    bool avail, used;
> >> +
> >> +    if (vq->vq.num_free == vq->vring.num)
> >> +        return false;
> >> +
> >> +    last_used = vq->last_used_idx;
> >> +    flags = virtio16_to_cpu(vq->vq.vdev,
> >> +                vq->vring_packed.desc[last_used].flags);
> >> +    avail = flags & VRING_DESC_F_AVAIL(1);
> >> +    used = flags & VRING_DESC_F_USED(1);
> >> +
> >> +    return avail == used;
> >> +}
> >>
> >> if the next to be used descriptor is actually used does not depend on
> >> any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
> >> condition. This extra condition is basically 'there are outstanding
> >> descriptors' and those are obviously either 'available' or yet to be observed
> >> 'used' descriptors. Right after initialization is covered by this extra
> >> condition. And obviously if the descriptor in question is still available
> >> flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
> >> with the extra condition we are right there where we want to be.
> >>
> >> But I could not find the extra condition in the spec.
> >>
> >> With that said, I also want to point out that I don't understand
> >> your statement Jens. I don't see a way to express the condition corresponding
> >> to more_used_packed() using the driver wrap counter (avail_wrap_count).
> >> Of course a wrap counter that wraps when last_used wraps could be used
> >> to (but no such counter is mentioned here AFAIU).
> > 
> > Not sure I get this.
> > I was merely saying that when descriptor flags are initialized to 0
> > and the wrap counters to 1, then it is not the case that the driver
> > would see all descriptors as used because it takes the wrap counter
> > into account.
> > 
> 
> Please point me to the paragraph where it's written  how is the wrap
> counter to be taken into account when trying to determine if the
> desc_ring[last_used] (the descriptor we are polling) is used or not.
> 
> Nothing like that being specified (or at least I could not find it)
> was actually what I got hooked on.
> 
> Regards,
> Halil

So the spec just says this: if you see avail flag change,
descriptor is available. If you see used flag change, it
is used.

As value of the flag is also known (equals the wrap bit)
that is one way to detect change.


> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that 
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio] Re: [virtio-dev] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Tue, Feb 27, 2018 at 12:29:11PM +0100, Halil Pasic wrote:
> 
> 
> On 02/27/2018 11:23 AM, Jens Freimann wrote:
> > On Mon, Feb 26, 2018 at 11:05:14PM +0200, Michael S. Tsirkin wrote:
> >> On Mon, Feb 26, 2018 at 06:19:21PM +0100, Halil Pasic wrote:
> >>> > +                vq->driver_event.flags = 0x1;
> >>> > +                memory_barrier();
> >>> > +
> >>> > +                flags = d->flags;
> >>> > +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> >>> > +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
> >>> > +                if (avail != used) {
> >>> > +                        break;
> >>> > +                }
> >>> > +
> >>> > +                vq->driver_event.flags = 0x2;
> >>> > +        }
> >>> > +
> >>> > +    read_memory_barrier();
> >>>
> >>> Now with the condition avail != used a freshly (that is zero initialized)
> >>> ring would appear all used. And we would do process_buffer(d) for the
> >>> whole ring if this code happens to get executed. Do we have to make
> >>> sure that this does not happen?
> >>
> >> I'll have to think about this.
> > 
> > With the wrap counter initialized to 1 descriptors would not be seen
> > as used.
> 
> Looking at the code... In vhost:
> 
> +static bool desc_is_avail(struct vhost_virtqueue *vq,
> +			  struct vring_desc_packed *desc)
> +{
> +	if (vq->used_wrap_counter)
> +		if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
> +			return true;
> +	if (vq->used_wrap_counter == false)
> +		if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
> +			return true;
> +
> +	return false;
> +}
> 
> Here the bit pattern corresponding to available depends on the
> value of the wrap counter. I kind of anticipated this, but I could not
> find it defined in this spec.
> 
> OTOH in guest:
> 
> +static inline bool more_used_packed(const struct vring_virtqueue *vq)
> +{
> +	u16 last_used, flags;
> +	bool avail, used;
> +
> +	if (vq->vq.num_free == vq->vring.num)
> +		return false;
> +
> +	last_used = vq->last_used_idx;
> +	flags = virtio16_to_cpu(vq->vq.vdev,
> +				vq->vring_packed.desc[last_used].flags);
> +	avail = flags & VRING_DESC_F_AVAIL(1);
> +	used = flags & VRING_DESC_F_USED(1);
> +
> +	return avail == used;
> +}
> 
> if the next to be used descriptor is actually used does not depend on
> any wrap counter, but has vq->vq.num_free == vq->vring.num as an extra
> condition. This extra condition is basically 'there are outstanding
> descriptors' and those are obviously either 'available' or yet to be observed
> 'used' descriptors. Right after initialization is covered by this extra
> condition. And obviously if the descriptor in question is still available
> flags & VRING_DESC_F_AVAIL(1) != flags & VRING_DESC_F_USED(1) holds, so
> with the extra condition we are right there where we want to be.
> 
> But I could not find the extra condition in the spec.
> 
> With that said, I also want to point out that I don't understand
> your statement Jens. I don't see a way to express the condition corresponding
> to more_used_packed() using the driver wrap counter (avail_wrap_count).
> Of course a wrap counter that wraps when last_used wraps could be used
> to (but no such counter is mentioned here AFAIU).

I added such a counter in the pseudo-code.


> >>
> >>
> >>> I was under the impression that this whole wrap counter exercise is
> >>> to be able to distinguish these cases.
> >>>
> >>> BTW tools/virtio/ringtest/ring.c has a single flag bit to indicate
> >>> available/used and does not have these wrap counters AFAIR.
> >>
> >> A single flag is fine if there's not s/g support and all descriptors are
> >> written out.  Wrap counters are needed if we are to support skipping
> >> descriptors because of s/g or in order.
> >>
> >>
> >>> Also for split virtqueues  a descriptor has three possible states:
> >>> * available
> >>> * used
> >>> * free
> >>>
> >>> I wonder if it's the same for packed, and if, how do I recognize
> >>> free descriptors (that is descriptors that are neither available
> >>> nor used.
> >>
> >> I'll think about this.
> >>
> >>> I'm pretty much confused on how this scheme with the available
> >>> and used wrap counters (or device and driver wrap counters is
> >>> supposed to work). A working implementation in C would really help
> >>> me to understand this.
> >>
> >> DPDK based implementation has been posted.
> > 
> > vhost and guest drivers have also been posted.
> > guest: https://lkml.org/lkml/2018/2/23/242
> > vhost: https://lkml.org/lkml/2018/2/13/1102
> > 
> 
> Thanks a lot. I've already found vhost myself but you saved me
> some searching with the other one ;).
> 
> > regards,
> > Jens
> >>
> >>> > +        process_buffer(d);
> >>> > +        vq->next_used++;
> >>> > +        if (vq->next_used >= vq->size) {
> >>> > +                vq->next_used = 0;
> >>> > +        }
> >>> > +}
> >>> > +\end{lstlisting}
> >>> >
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> >> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
> >>
> > 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that 
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Halil Pasic]

[..]
>> On 02/16/2018 08:24 AM, Michael S. Tsirkin wrote:
>>> Performance analysis of this is in my kvm forum 2016 presentation.  The
>>> idea is to have a r/w descriptor in a ring structure, replacing the used
>>> and available ring, index and descriptor buffer.
>>>
>>> This is also easier for devices to implement than the 1.0 layout.
>>> Several more enhancements will be necessary to actually make this
>>> efficient for devices to use.
>>>
>>> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
>>> ---
>>>  content.tex     |  28 ++-
>>>  packed-ring.tex | 646 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>  2 files changed, 671 insertions(+), 3 deletions(-)
>>>  create mode 100644 packed-ring.tex
[..]
>>> +
>>> +\subsection{Element Address and Length}
>>> +\label{sec:Packed Virtqueues / Element Address and Length}
>>> +
>>> +In an available descriptor, Element Address corresponds to the
>>> +physical address of the buffer element. The length of the element assumed
>>> +to be physically contigious is stored in Element Length.
>>> +
>>> +In a used descriptor, Element Address is unused. Element Length
>>> +specifies the length of the buffer that has been initialized
>>> +(written to) by the device.
>>> +
>>> +Element length is reserved for used descriptors without the
>>> +VIRTQ_DESC_F_WRITE flag, and is ignored by drivers.
>>> +
>>> +\subsection{Scatter-Gather Support}
>>
>> [Consistent wording] Both types of virtqueues support scatter-gather
>> but the term is used only for packed. Maybe we could unify the wording.
>> Or is this something for later?
> 
> I'll take a look but this can be safely done later too.
> 
> 

Agreed.

[..]
>>> +
>>> +\subsection{Multi-buffer requests}
>>> +\label{sec:Packed Virtqueues / Multi-descriptor batches}
>>> +Some devices combine multiple buffers as part of processing of a
>>> +single request.  These devices always mark the first descriptor
>>> +in the request used after the rest of the descriptors in the
>>> +request has been written out into the ring. This guarantees that
>>> +the driver will never observe a partial request in the ring.
>>> +
>>
>> I see you've changed s/in the request available/in the request used/.
>> But I still don't understand this paragraph. I will try to figure
>> it out later (and will come back to you if I fail).
> 
> FYI this applies to mergeable buffers for the network device.
> 
> 

Yeah, was my understanding to, but I will have to look into the
details starting from there. Will come back to you if I can't
clear it up for myself.

[..]
>>> +
>>> +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
>>> +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
>>> +read a device-writable buffer.
>>> +A device MUST NOT use a descriptor unless it observes
>>> +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
>>
>> I don't really understand this. How does the device observe
>> the VIRTQ_DESC_F_AVAIL bit being changed?
> 
> By reading the descriptor.
> 

:) My point is: to observe a change one usually either needs at
least one reading before and at least one reading after the change,
or one needs to know that a certain reading means change. The latter
is possible if we know that at the beginning of the time frame under
consideration (t_0) only a certain set of values,let's say B like before,
is possible, and after the change only a certain other set of values
let's say A like after, is possible, and A and B are disjunctive (
$A \cap B = \emtyset$).

I guess here the latter is supposed to be the case. But then I think
we need a more detailed description here. Please see also my other email
(response to Jens).

[..]
>>> +Suppression Structure Format}.
>>> +
>>> +\begin{note}
>>> +For optimal performance, a driver MAY disable interrupts while processing
>>> +the used buffers, but beware the problem of missing interrupts between
>>> +emptying the ring and reenabling interrupts.  This is usually handled by
>>> +re-checking for more used buffers after interrups are re-enabled:
>>> +\end{note}
>>> +
>>> +\begin{lstlisting}
>>> +vq->driver_event.flags = 0x2;
>>> +
>>> +for (;;) {
>>> +        struct virtq_desc *d = vq->desc[vq->next_used];
>>> +
>>> +        flags = d->flags;
>>> +        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>>> +        bool used = flags & (1 << VIRTQ_DESC_F_USED);
>>> +
>>> +        if (avail != used) {
>>
>> I don't understand the condition which is AFAIU supposed to
>> correspond to the descriptor *not* being used.
> 
> So avail == used means used. avail != used means available.
> 

Please see the follow up with Jens.

>>> +                vq->driver_event.flags = 0x1;
>>> +                memory_barrier();
>>> +
>>> +                flags = d->flags;
>>> +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
>>> +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
>>> +                if (avail != used) {
>>> +                        break;
>>> +                }
>>> +
>>> +                vq->driver_event.flags = 0x2;
>>> +        }
>>> +
>>> +	read_memory_barrier();
[..]
>> I'm pretty much confused on how this scheme with the available
>> and used wrap counters (or device and driver wrap counters is
>> supposed to work). A working implementation in C would really help
>> me to understand this.
> 
> DPDK based implementation has been posted.
>

Thank you very much for the hint. Slipped past me unfortunately.

Regards,
Halil
 
>>> +        process_buffer(d);
>>> +        vq->next_used++;
>>> +        if (vq->next_used >= vq->size) {
>>> +                vq->next_used = 0;
>>> +        }
>>> +}
>>> +\end{lstlisting}
>>>
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that 
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
> 


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Tue, Feb 27, 2018 at 12:53:14PM +0100, Halil Pasic wrote:
> [..]
> >> On 02/16/2018 08:24 AM, Michael S. Tsirkin wrote:
> >>> Performance analysis of this is in my kvm forum 2016 presentation.  The
> >>> idea is to have a r/w descriptor in a ring structure, replacing the used
> >>> and available ring, index and descriptor buffer.
> >>>
> >>> This is also easier for devices to implement than the 1.0 layout.
> >>> Several more enhancements will be necessary to actually make this
> >>> efficient for devices to use.
> >>>
> >>> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> >>> ---
> >>>  content.tex     |  28 ++-
> >>>  packed-ring.tex | 646 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >>>  2 files changed, 671 insertions(+), 3 deletions(-)
> >>>  create mode 100644 packed-ring.tex
> [..]
> >>> +
> >>> +\subsection{Element Address and Length}
> >>> +\label{sec:Packed Virtqueues / Element Address and Length}
> >>> +
> >>> +In an available descriptor, Element Address corresponds to the
> >>> +physical address of the buffer element. The length of the element assumed
> >>> +to be physically contigious is stored in Element Length.
> >>> +
> >>> +In a used descriptor, Element Address is unused. Element Length
> >>> +specifies the length of the buffer that has been initialized
> >>> +(written to) by the device.
> >>> +
> >>> +Element length is reserved for used descriptors without the
> >>> +VIRTQ_DESC_F_WRITE flag, and is ignored by drivers.
> >>> +
> >>> +\subsection{Scatter-Gather Support}
> >>
> >> [Consistent wording] Both types of virtqueues support scatter-gather
> >> but the term is used only for packed. Maybe we could unify the wording.
> >> Or is this something for later?
> > 
> > I'll take a look but this can be safely done later too.
> > 
> > 
> 
> Agreed.
> 
> [..]
> >>> +
> >>> +\subsection{Multi-buffer requests}
> >>> +\label{sec:Packed Virtqueues / Multi-descriptor batches}
> >>> +Some devices combine multiple buffers as part of processing of a
> >>> +single request.  These devices always mark the first descriptor
> >>> +in the request used after the rest of the descriptors in the
> >>> +request has been written out into the ring. This guarantees that
> >>> +the driver will never observe a partial request in the ring.
> >>> +
> >>
> >> I see you've changed s/in the request available/in the request used/.
> >> But I still don't understand this paragraph. I will try to figure
> >> it out later (and will come back to you if I fail).
> > 
> > FYI this applies to mergeable buffers for the network device.
> > 
> > 
> 
> Yeah, was my understanding to, but I will have to look into the
> details starting from there. Will come back to you if I can't
> clear it up for myself.
> 
> [..]
> >>> +
> >>> +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
> >>> +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
> >>> +read a device-writable buffer.
> >>> +A device MUST NOT use a descriptor unless it observes
> >>> +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
> >>
> >> I don't really understand this. How does the device observe
> >> the VIRTQ_DESC_F_AVAIL bit being changed?
> > 
> > By reading the descriptor.
> > 
> 
> :) My point is: to observe a change one usually either needs at
> least one reading before and at least one reading after the change,
> or one needs to know that a certain reading means change. The latter
> is possible if we know that at the beginning of the time frame under
> consideration (t_0) only a certain set of values,let's say B like before,
> is possible, and after the change only a certain other set of values
> let's say A like after, is possible, and A and B are disjunctive (
> $A \cap B = \emtyset$).

Well each descriptor is read each time ring wraps around,
and the bit value changes each time ring wraps around.
For example device knows it's zero initialized so
if it reads bit value as 1 it knows the bit value has changed.


> I guess here the latter is supposed to be the case. But then I think
> we need a more detailed description here. Please see also my other email
> (response to Jens).
> 
> [..]
> >>> +Suppression Structure Format}.
> >>> +
> >>> +\begin{note}
> >>> +For optimal performance, a driver MAY disable interrupts while processing
> >>> +the used buffers, but beware the problem of missing interrupts between
> >>> +emptying the ring and reenabling interrupts.  This is usually handled by
> >>> +re-checking for more used buffers after interrups are re-enabled:
> >>> +\end{note}
> >>> +
> >>> +\begin{lstlisting}
> >>> +vq->driver_event.flags = 0x2;
> >>> +
> >>> +for (;;) {
> >>> +        struct virtq_desc *d = vq->desc[vq->next_used];
> >>> +
> >>> +        flags = d->flags;
> >>> +        bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> >>> +        bool used = flags & (1 << VIRTQ_DESC_F_USED);
> >>> +
> >>> +        if (avail != used) {
> >>
> >> I don't understand the condition which is AFAIU supposed to
> >> correspond to the descriptor *not* being used.
> > 
> > So avail == used means used. avail != used means available.
> > 
> 
> Please see the follow up with Jens.
> 
> >>> +                vq->driver_event.flags = 0x1;
> >>> +                memory_barrier();
> >>> +
> >>> +                flags = d->flags;
> >>> +                bool avail = flags & (1 << VIRTQ_DESC_F_AVAIL);
> >>> +                bool used = flags & (1 << VIRTQ_DESC_F_USED);
> >>> +                if (avail != used) {
> >>> +                        break;
> >>> +                }
> >>> +
> >>> +                vq->driver_event.flags = 0x2;
> >>> +        }
> >>> +
> >>> +	read_memory_barrier();
> [..]
> >> I'm pretty much confused on how this scheme with the available
> >> and used wrap counters (or device and driver wrap counters is
> >> supposed to work). A working implementation in C would really help
> >> me to understand this.
> > 
> > DPDK based implementation has been posted.
> >
> 
> Thank you very much for the hint. Slipped past me unfortunately.
> 
> Regards,
> Halil
>  
> >>> +        process_buffer(d);
> >>> +        vq->next_used++;
> >>> +        if (vq->next_used >= vq->size) {
> >>> +                vq->next_used = 0;
> >>> +        }
> >>> +}
> >>> +\end{lstlisting}
> >>>
> > 
> > ---------------------------------------------------------------------
> > To unsubscribe from this mail list, you must leave the OASIS TC that 
> > generates this mail.  Follow this link to all your TCs in OASIS at:
> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 
> > 

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Halil Pasic]

On 02/27/2018 03:11 PM, Michael S. Tsirkin wrote:
>> [..]
>>>>> +
>>>>> +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
>>>>> +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
>>>>> +read a device-writable buffer.
>>>>> +A device MUST NOT use a descriptor unless it observes
>>>>> +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
>>>> I don't really understand this. How does the device observe
>>>> the VIRTQ_DESC_F_AVAIL bit being changed?
>>> By reading the descriptor.
>>>
>> :) My point is: to observe a change one usually either needs at
>> least one reading before and at least one reading after the change,
>> or one needs to know that a certain reading means change. The latter
>> is possible if we know that at the beginning of the time frame under
>> consideration (t_0) only a certain set of values,let's say B like before,
>> is possible, and after the change only a certain other set of values
>> let's say A like after, is possible, and A and B are disjunctive (
>> $A \cap B = \emtyset$).
> Well each descriptor is read each time ring wraps around,
> and the bit value changes each time ring wraps around.
> For example device knows it's zero initialized so
> if it reads bit value as 1 it knows the bit value has changed.
> 
> 

Yeah I kind of understand but I would like having a more straightforward
formulation here (than changes).

BTW does this mean that the vhost implementation (that is:

+static bool desc_is_avail(struct vhost_virtqueue *vq,
+			  struct vring_desc_packed *desc)
+{
+	if (vq->used_wrap_counter)
+		if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
+			return true;
+	if (vq->used_wrap_counter == false)
+		if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
+			return true;
+
+	return false;
+}

) is needlessly looking at the 'used' bit? (I think that is the case.)

Bottom line is: I would like avail/used protocol described in a less
ambiguous fashion.

However if I'm the only one who finds this aspect hard to understand,
the problem probably lies with me and not with the text. I can accept
that too.


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

Re: [virtio-dev] Re: [virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Jens Freimann]

On Tue, Feb 27, 2018 at 06:03:01PM +0100, Halil Pasic wrote:
>
>
>On 02/27/2018 03:11 PM, Michael S. Tsirkin wrote:
>>> [..]
>>>>>> +
>>>>>> +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
>>>>>> +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
>>>>>> +read a device-writable buffer.
>>>>>> +A device MUST NOT use a descriptor unless it observes
>>>>>> +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
>>>>> I don't really understand this. How does the device observe
>>>>> the VIRTQ_DESC_F_AVAIL bit being changed?
>>>> By reading the descriptor.
>>>>
>>> :) My point is: to observe a change one usually either needs at
>>> least one reading before and at least one reading after the change,
>>> or one needs to know that a certain reading means change. The latter
>>> is possible if we know that at the beginning of the time frame under
>>> consideration (t_0) only a certain set of values,let's say B like before,
>>> is possible, and after the change only a certain other set of values
>>> let's say A like after, is possible, and A and B are disjunctive (
>>> $A \cap B = \emtyset$).
>> Well each descriptor is read each time ring wraps around,
>> and the bit value changes each time ring wraps around.
>> For example device knows it's zero initialized so
>> if it reads bit value as 1 it knows the bit value has changed.
>>
>>
>
>Yeah I kind of understand but I would like having a more straightforward
>formulation here (than changes).
>
>BTW does this mean that the vhost implementation (that is:
>
>+static bool desc_is_avail(struct vhost_virtqueue *vq,
>+			  struct vring_desc_packed *desc)
>+{
>+	if (vq->used_wrap_counter)
>+		if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
>+			return true;
>+	if (vq->used_wrap_counter == false)
>+		if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
>+			return true;
>+
>+	return false;
>+}
>
>) is needlessly looking at the 'used' bit? (I think that is the case.)

Why do you think so? I assume with "used bit" you refer to the device
ring wrap counter. It needs to be looked at because if device looks
only at the descriptor flags it could be that they are different (so
available != used), but actually this descriptor was just skipped
previously. This could happen when descriptors are used in-order
(VIRTIO_F_IN_ORDER) and only the first descriptor of a batch is marked
as used. 

Should we mention that in the section about the counters?

regards,
Jens 


---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

[virtio] Re: [virtio-dev] Re: [virtio] Re: [PATCH v8 08/16] packed virtqueues: more efficient virtqueue layout

[Michael S. Tsirkin]

On Tue, Feb 27, 2018 at 06:03:01PM +0100, Halil Pasic wrote:
> 
> 
> On 02/27/2018 03:11 PM, Michael S. Tsirkin wrote:
> >> [..]
> >>>>> +
> >>>>> +\devicenormative{\subsection}{The Virtqueue Descriptor Table}{Basic Facilities of a Virtio Device / Packed Virtqueues / The Virtqueue Descriptor Table}
> >>>>> +A device MUST NOT write to a device-readable buffer, and a device SHOULD NOT
> >>>>> +read a device-writable buffer.
> >>>>> +A device MUST NOT use a descriptor unless it observes
> >>>>> +VIRTQ_DESC_F_AVAIL bit in its \field{flags} being changed.
> >>>> I don't really understand this. How does the device observe
> >>>> the VIRTQ_DESC_F_AVAIL bit being changed?
> >>> By reading the descriptor.
> >>>
> >> :) My point is: to observe a change one usually either needs at
> >> least one reading before and at least one reading after the change,
> >> or one needs to know that a certain reading means change. The latter
> >> is possible if we know that at the beginning of the time frame under
> >> consideration (t_0) only a certain set of values,let's say B like before,
> >> is possible, and after the change only a certain other set of values
> >> let's say A like after, is possible, and A and B are disjunctive (
> >> $A \cap B = \emtyset$).
> > Well each descriptor is read each time ring wraps around,
> > and the bit value changes each time ring wraps around.
> > For example device knows it's zero initialized so
> > if it reads bit value as 1 it knows the bit value has changed.
> > 
> > 
> 
> Yeah I kind of understand but I would like having a more straightforward
> formulation here (than changes).
> 
> BTW does this mean that the vhost implementation (that is:
> 
> +static bool desc_is_avail(struct vhost_virtqueue *vq,
> +			  struct vring_desc_packed *desc)
> +{
> +	if (vq->used_wrap_counter)
> +		if ((desc->flags & DESC_AVAIL) && !(desc->flags & DESC_USED))
> +			return true;
> +	if (vq->used_wrap_counter == false)
> +		if (!(desc->flags & DESC_AVAIL) && (desc->flags & DESC_USED))
> +			return true;
> +
> +	return false;
> +}
> 
> ) is needlessly looking at the 'used' bit? (I think that is the case.)
> 
> Bottom line is: I would like avail/used protocol described in a less
> ambiguous fashion.
> 
> However if I'm the only one who finds this aspect hard to understand,
> the problem probably lies with me and not with the text. I can accept
> that too.

I don't want to over-specify it. There are many options.
For example, if driver sets ID to a value != 0 then
when it sees ID != 0 it knows it has been used.

I added pseudo-code for the driver, hopefully that is sufficient.

> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[PATCH v8 09/16] content: in-order buffer use

[Michael S. Tsirkin]

Using descriptors in-order is sometimes beneficial.  Add an option for
that - per-format detail allowing more optimizations will be added by
follow-up patches.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 content.tex | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/content.tex b/content.tex
index 73f40b7..c57a918 100644
--- a/content.tex
+++ b/content.tex
@@ -245,6 +245,15 @@ a device event - i.e. send an interrupt to the driver.
 Device reports the number of bytes it has written to memory for
 each buffer it uses. This is referred to as ``used length''.
 
+Device is not generally required to use buffers in
+the same order in which they have been made available
+by the driver.
+
+Some devices always use descriptors in the same order in which
+they have been made available. These devices can offer the
+VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge
+might allow optimizations or simplify driver and/or device code.
+
 Each virtqueue can consist of up to 3 parts:
 \begin{itemize}
 \item Descriptor Area - used for describing buffers
@@ -5248,6 +5257,9 @@ Descriptors} and \ref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Supp
   \item[VIRTIO_F_RING_PACKED(34)] This feature indicates
   support for the packed virtqueue layout as described in
   \ref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}~\nameref{sec:Basic Facilities of a Virtio Device / Packed Virtqueues}.
+  \item[VIRTIO_F_IN_ORDER(35)] This feature indicates
+  that all buffers are used by the device in the same
+  order in which they have been made available.
 \end{description}
 
 \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
@@ -5273,6 +5285,9 @@ translates bus addresses from the device into physical addresses in memory.
 A device MAY fail to operate further if VIRTIO_F_IOMMU_PLATFORM is not
 accepted.
 
+If VIRTIO_F_IN_ORDER has been negotiated, a device MUST use
+buffers in the same order in which they have been available.
+
 \section{Legacy Interface: Reserved Feature Bits}\label{sec:Reserved Feature Bits / Legacy Interface: Reserved Feature Bits}
 
 Transitional devices MAY offer the following:
-- 
MST

[PATCH v8 10/16] packed-ring: add in order support

[Michael S. Tsirkin]

Support in-order requests for packed rings.
This allows selective write-out of used descriptors.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 packed-ring.tex | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/packed-ring.tex b/packed-ring.tex
index 213295b..14e137d 100644
--- a/packed-ring.tex
+++ b/packed-ring.tex
@@ -264,6 +264,30 @@ Buffer ID is also reserved and is ignored by the device.
 In Descriptors with VIRTQ_DESC_F_INDIRECT set VIRTQ_DESC_F_WRITE
 is reserved and is ignored by the device.
 
+\subsection{In-order use of descriptors}
+\label{sec:Packed Virtqueues / In-order use of descriptors}
+
+Some devices always use descriptors in the same order in which
+they have been made available. These devices can offer the
+VIRTIO_F_IN_ORDER feature. If negotiated, this knowledge allows
+devices to notify the use of a batch of buffers to the driver by
+only writing out a single used descriptor with the Buffer ID
+corresponding to the last descriptor in the batch.
+
+Device then skips forward in the ring according to the size of
+the batch. Driver needs to look up the used Buffer ID and
+calculate the batch size to be able to advance to where the next
+used descriptor will be written by the device.
+
+This will result in the used descriptor overwriting the first
+available descriptor in the batch, the used descriptor for the
+next batch overwriting the first available descriptor in the next
+batch, etc.
+
+The skipped buffers (for which no used descriptor was written)
+are assumed to have been used (read or written) by the
+device completely.
+
 \subsection{Multi-buffer requests}
 \label{sec:Packed Virtqueues / Multi-descriptor batches}
 Some devices combine multiple buffers as part of processing of a
-- 
MST

[PATCH v8 11/16] split-ring: in order feature

[Michael S. Tsirkin]

For a split ring, require that drivers use descriptors in order too.
This allows devices to skip reading the available ring.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 split-ring.tex | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/split-ring.tex b/split-ring.tex
index a594d41..5572958 100644
--- a/split-ring.tex
+++ b/split-ring.tex
@@ -203,6 +203,10 @@ struct virtq_desc {
 The number of descriptors in the table is defined by the queue size
 for this virtqueue: this is the maximum possible descriptor chain length.
 
+If VIRTIO_F_IN_ORDER has been negotiated, driver uses
+descriptors in ring order: starting from offset 0 in the table,
+and wrapping around at the end of the table.
+
 \begin{note}
 The legacy \hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}
 referred to this structure as vring_desc, and the constants as
@@ -218,6 +222,12 @@ purposes).
 Drivers MUST NOT add a descriptor chain over than $2^{32}$ bytes long in total;
 this implies that loops in the descriptor chain are forbidden!
 
+If VIRTIO_F_IN_ORDER has been negotiated, and when making a
+descriptor with VRING_DESC_F_NEXT set in \field{flags} at offset
+$x$ in the table available to the device, driver MUST set
+\field{next} to $0$ for the last descriptor in the table
+(where $x = queue\_size - 1$) and to $x + 1$ for the rest of the descriptors.
+
 \subsubsection{Indirect Descriptors}\label{sec:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
 
 Some devices benefit by concurrently dispatching a large number
@@ -247,6 +257,10 @@ chained by \field{next}. An indirect descriptor without a valid \field{next}
 A single indirect descriptor
 table can include both device-readable and device-writable descriptors.
 
+If VIRTIO_F_IN_ORDER has been negotiated, indirect descriptors
+use sequential indices, in-order: index 0 followed by index 1
+followed by index 2, etc.
+
 \drivernormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
 The driver MUST NOT set the VIRTQ_DESC_F_INDIRECT flag unless the
 VIRTIO_F_INDIRECT_DESC feature was negotiated.   The driver MUST NOT
@@ -259,6 +273,10 @@ the device.
 A driver MUST NOT set both VIRTQ_DESC_F_INDIRECT and VIRTQ_DESC_F_NEXT
 in \field{flags}.
 
+If VIRTIO_F_IN_ORDER has been negotiated, indirect descriptors
+MUST appear sequentially, with \field{next} taking the value
+of 1 for the 1st descriptor, 2 for the 2nd one, etc.
+
 \devicenormative{\paragraph}{Indirect Descriptors}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
 The device MUST ignore the write-only flag (\field{flags}\&VIRTQ_DESC_F_WRITE) in the descriptor that refers to an indirect table.
 
-- 
MST

[PATCH v8 12/16] makediff: update to show diff from master

[Michael S. Tsirkin]

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 makediff.sh | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/makediff.sh b/makediff.sh
index 1dd75d4..2ef92fc 100755
--- a/makediff.sh
+++ b/makediff.sh
@@ -9,7 +9,7 @@ export DATESTR=${DATESTR:-`cat REVISION-DATE`}
 MAIN=$1
 PATH=.:${PATH}
 cur="$PWD"
-oldrev=`git rev-list -1 origin/tags/v1.0-cs03`
+oldrev=`git rev-list -1 origin/master`
 newrev=`git rev-list -1 HEAD`
 rm -fr old new
 git clone $PWD old
@@ -19,7 +19,6 @@ while read -r rev; do
 	echo "Applying $rev"
 	git cherry-pick `git rev-list -1 -F --grep "$rev" $newrev` || exit 1
 done << 'EOF'
-headerfile: rename virtio_ring to virtio queue
 EOF
 
 #mv specvars.tex specvars-orig.tex
-- 
MST

[virtio] Re: [PATCH v8 12/16] makediff: update to show diff from master

[Cornelia Huck]

On Fri, 16 Feb 2018 09:25:40 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  makediff.sh | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
> 
> diff --git a/makediff.sh b/makediff.sh
> index 1dd75d4..2ef92fc 100755
> --- a/makediff.sh
> +++ b/makediff.sh
> @@ -9,7 +9,7 @@ export DATESTR=${DATESTR:-`cat REVISION-DATE`}
>  MAIN=$1
>  PATH=.:${PATH}
>  cur="$PWD"
> -oldrev=`git rev-list -1 origin/tags/v1.0-cs03`
> +oldrev=`git rev-list -1 origin/master`
>  newrev=`git rev-list -1 HEAD`
>  rm -fr old new
>  git clone $PWD old
> @@ -19,7 +19,6 @@ while read -r rev; do
>  	echo "Applying $rev"
>  	git cherry-pick `git rev-list -1 -F --grep "$rev" $newrev` || exit 1
>  done << 'EOF'
> -headerfile: rename virtio_ring to virtio queue
>  EOF
>  
>  #mv specvars.tex specvars-orig.tex

So, this script is now always supposed to be run on a branch to get the
diff to master?

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[PATCH v8 13/16] REVISION: set to 1.1 wd07

[Michael S. Tsirkin]

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 REVISION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/REVISION b/REVISION
index 6a9f46a..cff9c21 100644
--- a/REVISION
+++ b/REVISION
@@ -1 +1 @@
-virtio-v1.0-cs04
+virtio-v1.1-wd07
-- 
MST

[PATCH v8 14/16] VIRTIO_F_NOTIFICATION_DATA: extra data to devices

[Michael S. Tsirkin]

Motivation for the new feature is included in the text.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 content.tex | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 130 insertions(+), 6 deletions(-)

diff --git a/content.tex b/content.tex
index c57a918..ca6d2d9 100644
--- a/content.tex
+++ b/content.tex
@@ -283,9 +283,76 @@ Packed Virtqueues}).
 Every driver and device supports either the Packed or the Split
 Virtqueue format, or both.
 
+\subsection{Driver notifications} \label{sec:Virtqueues / Driver notifications}
+Driver is sometimes required to notify the device after
+making changes to the virtqueue.
+
+When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
+this notification involves sending the
+virtqueue number to the device (depending on the transport).
+
+However, some devices benefit from ability to find out the number of
+available descriptors in the ring, and whether to send
+interrupts to drivers without accessing virtqueue in memory:
+for efficiency or as a debugging aid.
+
+To help with these optimizations, when VIRTIO_F_NOTIFICATION_DATA
+has been negotiated, driver notifications to the device include
+the following information:
+
+\begin{itemize}
+\item VQ number
+\item Offset
+      Within the ring where the next available ring entry
+      will be written.
+      Without VIRTIO_F_RING_PACKED this refers to the
+      15 least significant bits of the available index.
+      With VIRTIO_F_RING_PACKED this refers to the offset
+      (in units of descritor entries)
+      within the descriptor ring where the next available
+      descriptor will be written.
+\item Wrap Counter
+      With VIRTIO_F_RING_PACKED this is the wrap counter
+      referring to the next available descriptor.
+      Without VIRTIO_F_RING_PACKED this is the most significant bit
+      of the available index.
+\end{itemize}
+
+Note that driver can trigger multiple notifications even without
+making any more changes to the ring. These would then have
+identical \field{Offset} and \field{Wrap Counter} values.
+
 \input{split-ring.tex}
 
 \input{packed-ring.tex}
+
+\subsubsection{Driver notifications}
+
+\label{sec:Packed Virtqueues / Driver notifications}
+Whenever not suppressed by Device Event Suppression,
+driver is required to notify the device after
+making changes to the virtqueue.
+
+Some devices benefit from ability to find out the number of
+available descriptors in the ring, and whether to send
+interrupts to drivers without accessing virtqueue in memory:
+for efficiency or as a debugging aid.
+
+To help with these optimizations, driver notifications
+to the device include the following information:
+
+\begin{itemize}
+\item VQ number
+\item Offset (in units of descriptor size) within the ring
+      where the next available descriptor will be written
+\item Wrap Counter referring to the next available
+      descriptor
+\end{itemize}
+
+Note that driver can trigger multiple notifications even without
+making any more changes to the ring. These would then have
+identical \field{Offset} and \field{Wrap Counter} values.
+
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
 
 We start with an overview of device initialization, then expand on the
@@ -862,7 +929,9 @@ the same Queue Notify address for all queues.
 \devicenormative{\paragraph}{Notification capability}{Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 The device MUST present at least one notification capability.
 
-The \field{cap.offset} MUST be 2-byte aligned.  
+For devices not offering VIRTIO_F_NOTIFICATION_DATA:
+
+The \field{cap.offset} MUST be 2-byte aligned.
 
 The device MUST either present \field{notify_off_multiplier} as an even power of 2,
 or present \field{notify_off_multiplier} as 0.
@@ -876,6 +945,23 @@ For all queues, the value \field{cap.length} presented by the device MUST satisf
 cap.length >= queue_notify_off * notify_off_multiplier + 2
 \end{lstlisting}
 
+For devices offering VIRTIO_F_NOTIFICATION_DATA:
+
+The device MUST either present \field{notify_off_multiplier} as a
+number that is a power of 2 that is also a multiple 4,
+or present \field{notify_off_multiplier} as 0.
+
+The \field{cap.offset} MUST be 4-byte aligned.
+
+The value \field{cap.length} presented by the device MUST be at least 4
+and MUST be large enough to support queue notification offsets
+for all supported queues in all possible configurations.
+
+For all queues, the value \field{cap.length} presented by the device MUST satisfy:
+\begin{lstlisting}
+cap.length >= queue_notify_off * notify_off_multiplier + 4
+\end{lstlisting}
+
 \subsubsection{ISR status capability}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / ISR status capability}
 
 The VIRTIO_PCI_CAP_ISR_CFG capability
@@ -1268,8 +1354,22 @@ separate cache lines.
 
 \subsubsection{Notifying The Device}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Notifying The Device}
 
-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.
+When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
+the driver notifies the device by writing the 16-bit virtqueue index
+of this virtqueue (in little-endian byte order format)
+to the Queue Notify address.
+
+When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
+the driver notifies the device by writing the following
+32-bit value to the Queue Notify address:
+\begin{lstlisting}
+__le16 vqn;
+__le16 next_off : 15;
+u8    next_wrap : 1;
+\end{lstlisting}
+
+See \ref{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability} for how to calculate the
+Queue Notify address.
 
 \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}
 
@@ -1500,8 +1600,17 @@ All register values are organized as Little Endian.
   }
   \hline 
   \mmioreg{QueueNotify}{Queue notifier}{0x050}{W}{%
-    Writing a queue index to this register notifies the device that
-    there are new buffers to process in the queue.
+    Writing a value this register notifies the device that
+    there are new buffers to process in a queue.
+
+    When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
+    the value written is the queue index.
+
+    When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
+    the value is calculated as follows:
+    $
+    u32 notification\_data = vqn | (next\_off << 16) | (next\_wrap << 31);
+    $
   }
   \hline 
   \mmioreg{InterruptStatus}{Interrupt status}{0x60}{R}{%
@@ -2340,12 +2449,23 @@ GPR  &   Input Value     & Output Value \\
 \hline
   2   &  Subchannel ID    & Host Cookie  \\
 \hline
-  3   & Virtqueue number  &              \\
+  3   & Notification data &              \\
 \hline
   4   &   Host Cookie     &              \\
 \hline
 \end{tabular}
 
+When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
+the \field{Notification data} includes the Virtqueue number.
+
+When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
+the \field{Notification data} is calculated as follows:
+
+\begin{lstlisting}
+u32 notification_data = vqn | (next_off << 16) | (next_wrap << 31);
+\end{lstlisting}
+
+
 \devicenormative{\paragraph}{Guest->Host Notification}{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
 The device MUST ignore bits 0-31 (counting from the left) of GPR2.
 This aligns passing the subchannel ID with the way it is passed
@@ -5260,6 +5380,10 @@ Descriptors} and \ref{sec:Packed Virtqueues / Indirect Flag: Scatter-Gather Supp
   \item[VIRTIO_F_IN_ORDER(35)] This feature indicates
   that all buffers are used by the device in the same
   order in which they have been made available.
+  \item[VIRTIO_F_NOTIFICATION_DATA(36)] This feature indicates
+  that drivers pass extra data (besides identifying the Virtqueue)
+  in their device notifications.
+  See \ref{sec:Virtqueues / Driver notifications}~\nameref{sec:Virtqueues / Driver notifications}.
 \end{description}
 
 \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
-- 
MST

[virtio] Re: [PATCH v8 14/16] VIRTIO_F_NOTIFICATION_DATA: extra data to devices

[Cornelia Huck]

On Fri, 16 Feb 2018 09:26:22 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Motivation for the new feature is included in the text.
> 
> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  content.tex | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 130 insertions(+), 6 deletions(-)
> 
> diff --git a/content.tex b/content.tex
> index c57a918..ca6d2d9 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -283,9 +283,76 @@ Packed Virtqueues}).
>  Every driver and device supports either the Packed or the Split
>  Virtqueue format, or both.
>  
> +\subsection{Driver notifications} \label{sec:Virtqueues / Driver notifications}
> +Driver is sometimes required to notify the device after
> +making changes to the virtqueue.
> +
> +When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
> +this notification involves sending the
> +virtqueue number to the device (depending on the transport).
> +
> +However, some devices benefit from ability to find out the number of
> +available descriptors in the ring, and whether to send
> +interrupts to drivers without accessing virtqueue in memory:
> +for efficiency or as a debugging aid.
> +
> +To help with these optimizations, when VIRTIO_F_NOTIFICATION_DATA
> +has been negotiated, driver notifications to the device include
> +the following information:
> +
> +\begin{itemize}
> +\item VQ number
> +\item Offset
> +      Within the ring where the next available ring entry
> +      will be written.
> +      Without VIRTIO_F_RING_PACKED this refers to the
> +      15 least significant bits of the available index.
> +      With VIRTIO_F_RING_PACKED this refers to the offset
> +      (in units of descritor entries)
> +      within the descriptor ring where the next available
> +      descriptor will be written.
> +\item Wrap Counter
> +      With VIRTIO_F_RING_PACKED this is the wrap counter
> +      referring to the next available descriptor.
> +      Without VIRTIO_F_RING_PACKED this is the most significant bit
> +      of the available index.
> +\end{itemize}

This looks a bit odd in the resulting pdf...

> +
> +Note that driver can trigger multiple notifications even without
> +making any more changes to the ring. These would then have
> +identical \field{Offset} and \field{Wrap Counter} values.
> +
>  \input{split-ring.tex}
>  
>  \input{packed-ring.tex}
> +
> +\subsubsection{Driver notifications}
> +
> +\label{sec:Packed Virtqueues / Driver notifications}
> +Whenever not suppressed by Device Event Suppression,
> +driver is required to notify the device after
> +making changes to the virtqueue.
> +
> +Some devices benefit from ability to find out the number of
> +available descriptors in the ring, and whether to send
> +interrupts to drivers without accessing virtqueue in memory:
> +for efficiency or as a debugging aid.
> +
> +To help with these optimizations, driver notifications
> +to the device include the following information:
> +
> +\begin{itemize}
> +\item VQ number
> +\item Offset (in units of descriptor size) within the ring
> +      where the next available descriptor will be written
> +\item Wrap Counter referring to the next available
> +      descriptor
> +\end{itemize}
> +
> +Note that driver can trigger multiple notifications even without
> +making any more changes to the ring. These would then have
> +identical \field{Offset} and \field{Wrap Counter} values.

So, this in effect makes NOTIFICATION_DATA mandatory for the packed
ring... or is this just a leftover hunk?

(...)

> @@ -2340,12 +2449,23 @@ GPR  &   Input Value     & Output Value \\
>  \hline
>    2   &  Subchannel ID    & Host Cookie  \\
>  \hline
> -  3   & Virtqueue number  &              \\
> +  3   & Notification data &              \\
>  \hline
>    4   &   Host Cookie     &              \\
>  \hline
>  \end{tabular}
>  
> +When VIRTIO_F_NOTIFICATION_DATA has not been negotiated,
> +the \field{Notification data} includes the Virtqueue number.
> +
> +When VIRTIO_F_NOTIFICATION_DATA has been negotiated,
> +the \field{Notification data} is calculated as follows:
> +
> +\begin{lstlisting}
> +u32 notification_data = vqn | (next_off << 16) | (next_wrap << 31);
> +\end{lstlisting}

It would be good to add a reference to the part where the components of
the notification data are defined.

Otherwise, I think this looks fine (did not really look at the details
for pci or mmio).

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[PATCH v8 15/16] conformance: link the new conformance clause

[Michael S. Tsirkin]

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 conformance.tex | 1 +
 1 file changed, 1 insertion(+)

diff --git a/conformance.tex b/conformance.tex
index 55d17b4..e4efe33 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -38,6 +38,7 @@ A driver MUST conform to the following normative statements:
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
+\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
 \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Updating idx}
-- 
MST

[virtio] Re: [PATCH v8 15/16] conformance: link the new conformance clause

[Cornelia Huck]

On Fri, 16 Feb 2018 09:26:43 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  conformance.tex | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/conformance.tex b/conformance.tex
> index 55d17b4..e4efe33 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -38,6 +38,7 @@ A driver MUST conform to the following normative statements:
>  \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table}
>  \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Descriptor Table / Indirect Descriptors}
>  \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Interrupt Suppression}
> +\item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
>  \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Used Ring}
>  \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Virtqueue Notification Suppression}
>  \item \ref{drivernormative:Basic Facilities of a Virtio Device / Virtqueues / Supplying Buffers to The Device / Updating idx}

This updates another patch where that was missing?

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 

[PATCH v8 16/16] REVISION: set for packed-wd07.pdf

[Michael S. Tsirkin]

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 REVISION | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/REVISION b/REVISION
index cff9c21..c1f9103 100644
--- a/REVISION
+++ b/REVISION
@@ -1 +1 @@
-virtio-v1.1-wd07
+virtio-v1.1-wd08
-- 
MST

[virtio] Re: [PATCH v8 16/16] REVISION: set for packed-wd07.pdf

[Cornelia Huck]

On Fri, 16 Feb 2018 09:27:04 +0200
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
> ---
>  REVISION | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/REVISION b/REVISION
> index cff9c21..c1f9103 100644
> --- a/REVISION
> +++ b/REVISION
> @@ -1 +1 @@
> -virtio-v1.1-wd07
> +virtio-v1.1-wd08

The two REVISION updates are, frankly, a bit of a headscratcher for
me...

---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that 
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php