* [virtio] [PATCH v10 01/13] introduction: document bitfield notation
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 02/13] content: move 1.0 queue format out to a separate section Michael S. Tsirkin
` (11 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
Bitfields are a useful and familiar way to specify sub-byte structure
layout. The only issue is that bitfield order isn't portable across
architectures. Document that we list bitfields from least to
most significant one, and warn about portability issues.
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
introduction.tex | 41 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 41 insertions(+)
diff --git a/introduction.tex b/introduction.tex
index 979881e..a4ac01d 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -157,5 +157,46 @@ in little-endian byte order.
in big-endian byte order.
\end{description}
+Some of the fields to be defined in this specification don't
+start or don't end on a byte boundary. Such fields are called bit-fields.
+A set of bit-fields is always a sub-division of an integer typed field.
+
+Bit-fields within integer fields are always listed in order,
+from the least significant to the most significant bit. The
+bit-fields are considered unsigned integers of the specified
+width with the next in significance relationship of the bits
+preserved.
+
+For example:
+\begin{lstlisting}
+struct S {
+ be16 {
+ A : 15;
+ B : 1;
+ } x;
+ be16 y;
+};
+\end{lstlisting}
+documents the value A stored in the low 15 bit of \field{x} and
+the value B stored in the high bit of \field{x}, the 16-bit
+integer \field{x} in turn stored using the big-endian byte order
+at the beginning of the structure S,
+and being followed immediately by an unsigned integer \field{y}
+stored in big-endian byte order at an offset of 2 bytes (16 bits)
+from the beginning of the structure.
+
+Note that this notation somewhat resembles the C bitfield syntax but
+should not be naively converted to a bitfield notation for portable
+code: it matches the way bitfields are packed by C compilers on
+little-endian architectures but not the way bitfields are packed by C
+compilers on big-endian architectures.
+
+Assuming that CPU_TO_BE16 converts a 16-bit integer from a native
+CPU to the big-endian byte order, the following is the equivalent
+portable C code to generate a value to be stored into \field{x}:
+\begin{lstlisting}
+CPU_TO_BE16(B << 15 | A)
+\end{lstlisting}
+
\newpage
--
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 02/13] content: move 1.0 queue format out to a separate section
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 01/13] introduction: document bitfield notation Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 03/13] content: move ring text out to a separate file Michael S. Tsirkin
` (10 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 03/13] content: move ring text out to a separate file
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 01/13] introduction: document bitfield notation Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 02/13] content: move 1.0 queue format out to a separate section Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 04/13] content: move virtqueue operation description Michael S. Tsirkin
` (9 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 04/13] content: move virtqueue operation description
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (2 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 03/13] content: move ring text out to a separate file Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 05/13] content: len -> used length, used ring -> vq Michael S. Tsirkin
` (8 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 05/13] content: len -> used length, used ring -> vq
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (3 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 04/13] content: move virtqueue operation description Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 07/13] content: generalize rest of text Michael S. Tsirkin
` (7 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
Document buffer used len and use that terminology everywhere in the
generic section.
Further, drop the 'used ring' terminology and just say virtqueue.
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 07/13] content: generalize rest of text
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (4 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 05/13] content: len -> used length, used ring -> vq Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 06/13] content: generalize transport ring part naming Michael S. Tsirkin
` (6 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
Reviewed-by: Cornelia Huck <cohuck@redhat.com>
---
content.tex | 14 ++++++--------
1 file changed, 6 insertions(+), 8 deletions(-)
diff --git a/content.tex b/content.tex
index 9fc9673..5634c7d 100644
--- a/content.tex
+++ b/content.tex
@@ -1467,8 +1467,7 @@ All register values are organized as Little Endian.
}
\hline
\mmioreg{QueueNum}{Virtual queue size}{0x038}{W}{%
- Queue size is the number of elements in the queue, therefore in each
- of the Descriptor Table, the Available Ring and the Used Ring.
+ 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}.
@@ -1491,9 +1490,9 @@ All register values are organized as Little Endian.
caused the device interrupt to be asserted.
The following events are possible:
\begin{description}
- \item[Used Ring Update] - bit 0 - the interrupt was asserted
- because the device has updated the Used
- Ring in at least one of the active virtual queues.
+ \item[Used Buffer Update] - bit 0 - the interrupt was asserted
+ because the device has used a buffer
+ in at least one of the active virtual queues.
\item [Configuration Change] - bit 1 - the interrupt was
asserted because the configuration of the device has changed.
\end{description}
@@ -1642,9 +1641,8 @@ The driver will typically initialize the virtual queue in the following way:
\field{QueueNumMax}. If the returned value is zero (0x0) the
queue is not available.
-\item Allocate and zero the queue pages, making sure the memory
- is physically contiguous. It is recommended to align the
- Used Ring to an optimal boundary (usually the page size).
+\item Allocate and zero the queue memory, making sure the memory
+ is physically contiguous.
\item Notify the device about the queue size by writing the size to
\field{QueueNum}.
--
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 06/13] content: generalize transport ring part naming
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (5 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 07/13] content: generalize rest of text Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 08/13] split-ring: generalize text Michael S. Tsirkin
` (5 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 08/13] split-ring: generalize text
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (6 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 06/13] content: generalize transport ring part naming Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 10/13] packed virtqueues: more efficient virtqueue layout Michael S. Tsirkin
` (4 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
Update generic text to talk about available/used buffers, not rings.
Move some split-ring specific text to the correct section.
Update conformance section with link to the new conformance clause.
Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
conformance.tex | 1 +
content.tex | 10 ++++------
split-ring.tex | 4 ++++
3 files changed, 9 insertions(+), 6 deletions(-)
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}
diff --git a/content.tex b/content.tex
index 5634c7d..e1e30a0 100644
--- a/content.tex
+++ b/content.tex
@@ -381,12 +381,10 @@ of a device are live once the device has been reset.
\drivernormative{\subsection}{Device Cleanup}{General Initialization And Device Operation / Device Cleanup}
-A driver MUST NOT alter descriptor table entries which have been
-exposed in the available ring (and not marked consumed by the device
-in the used ring) of a live virtqueue.
-
-A driver MUST NOT decrement the available \field{idx} on a live virtqueue (ie.
-there is no way to ``unexpose'' buffers).
+A driver MUST NOT alter virtqueue entries for exposed buffers -
+i.e. buffers which have been
+made available to the device (and not been used by the device)
+of a live virtqueue.
Thus a driver MUST ensure a virtqueue isn't live (by device reset) before removing exposed buffers.
diff --git a/split-ring.tex b/split-ring.tex
index 9601a53..a594d41 100644
--- a/split-ring.tex
+++ b/split-ring.tex
@@ -296,6 +296,10 @@ 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}
+\drivernormative{\subsubsection}{The Virtqueue Available Ring}{Basic Facilities of a Virtio Device / Virtqueues / The Virtqueue Available Ring}
+A driver MUST NOT decrement the available \field{idx} on a virtqueue (ie.
+there is no way to ``unexpose'' buffers).
+
\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,
--
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 10/13] packed virtqueues: more efficient virtqueue layout
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (7 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 08/13] split-ring: generalize text Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 09/13] split-ring: typo: aligment Michael S. Tsirkin
` (3 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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>
Acked-by: Cornelia Huck <cohuck@redhat.com>
---
content.tex | 28 ++-
packed-ring.tex | 690 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 715 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..ebdba09
--- /dev/null
+++ b/packed-ring.tex
@@ -0,0 +1,690 @@
+\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.
+
+Note that this observation is mostly useful for sanity-checking
+as these are necessary but not sufficient conditions - for
+example, all descriptors are zero-initialized. To detect used and
+available descriptors it is possible for drivers and devices to
+keep track of the last observed value of
+VIRTQ_DESC_F_USED/VIRTQ_DESC_F_AVAIL. Other techniques to detect
+VIRTQ_DESC_F_AVAIL/VIRTQ_DESC_F_USED bit changes might also be
+possible.
+
+\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 features support this: descriptor chaining and indirect descriptors.
+
+If neither feature is in use by the driver, 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 pvirtq_indirect_descriptor_table {
+ /* The actual descriptor structures (struct pvirtq_desc each) */
+ struct pvirtq_desc desc[len / sizeof(struct pvirtq_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-buffer requests}
+Some devices combine multiple buffers as part of processing of a
+single request. These devices always mark the descriptor
+corresponding to the first buffer in the request used after the
+rest of the descriptors (corresponding to rest of the buffers) in
+the request - which follow the first descriptor in ring order -
+has been marked used and 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{lstlisting}
+/* Enable events */
+#define RING_EVENT_FLAGS_ENABLE 0x0
+/* Disable events */
+#define RING_EVENT_FLAGS_DISABLE 0x1
+/*
+ * 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.
+ */
+#define RING_EVENT_FLAGS_DESC 0x2
+/* The value 0x3 is reserved */
+\end{lstlisting}
+\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 alignment 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 pvirtq_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}
+struct pvirtq_event_suppress {
+ le16 {
+ desc_event_off : 15; /* Descriptor Ring Change Event Offset */
+ desc_event_wrap : 1; /* Descriptor Ring Change Event Wrap Counter */
+ } desc; /* If desc_event_flags set to RING_EVENT_FLAGS_DESC */
+ le16 {
+ desc_event_flags : 2, /* Descriptor Ring Change Event Flags */
+ reserved : 14; /* Reserved, set to 0 */
+ } 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
+(e.g. as compared to the initial zero value).
+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_AVAIL 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 all subsequent descriptors comprising the list 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}
+/* Note: vq->avail_wrap_count is initialized to 1 */
+/* Note: vq->sgs is an array same size as the ring */
+
+id = alloc_id(vq);
+
+first = vq->next_avail;
+sgs = 0;
+for (each buffer element b) {
+ sgs++;
+
+ vq->ids[vq->next_avail] = -1;
+ vq->desc[vq->next_avail].address = get_addr(b);
+ vq->desc[vq->next_avail].len = get_len(b);
+
+ avail = vq->avail_wrap_count ? VIRTQ_DESC_F_AVAIL : 0;
+ used = !vq->avail_wrap_count ? VIRTQ_DESC_F_USED : 0;
+ f = get_flags(b) | avail | used;
+ if (b is not the last buffer element) {
+ f |= VIRTQ_DESC_F_NEXT;
+ }
+
+ /* 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;
+ }
+
+ last = vq->next_avail;
+
+ vq->next_avail++;
+
+ if (vq->next_avail >= vq->size) {
+ vq->next_avail = 0;
+ vq->avail_wrap_count \^= 1;
+ }
+}
+vq->sgs[id] = sgs;
+/* ID included in the last descriptor in the list */
+vq->desc[last].id = id;
+write_memory_barrier();
+vq->desc[first].flags = flags;
+
+memory_barrier();
+
+if (vq->device_event.flags != RING_EVENT_FLAGS_DISABLE) {
+ 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}
+/* Note: vq->used_wrap_count is initialized to 1 */
+
+vq->driver_event.flags = RING_EVENT_FLAGS_DISABLE;
+
+for (;;) {
+ struct pvirtq_desc *d = vq->desc[vq->next_used];
+
+ flags = d->flags;
+ bool used = flags & VIRTQ_DESC_F_USED;
+
+ if (used != vq->used_wrap_count) {
+ vq->driver_event.flags = RING_EVENT_FLAGS_ENABLE;
+ memory_barrier();
+
+ flags = d->flags;
+ bool used = flags & VIRTQ_DESC_F_USED;
+ if (used != vq->used_wrap_count) {
+ break;
+ }
+
+ vq->driver_event.flags = RING_EVENT_FLAGS_DISABLE;
+ }
+
+ read_memory_barrier();
+
+ /* skip descriptors until the next buffer */
+ id = d->id;
+ assert(id < vq->size);
+ sgs = vq->sgs[id];
+ vq->next_used += sgs;
+ if (vq->next_used >= vq->size) {
+ vq->next_used -= vq->size;
+ vq->used_wrap_count \^= 1;
+ }
+
+ free_id(vq, id);
+
+ process_buffer(d);
+}
+\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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 09/13] split-ring: typo: aligment
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (8 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 10/13] packed virtqueues: more efficient virtqueue layout Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 11/13] content: in-order buffer use Michael S. Tsirkin
` (2 subsequent siblings)
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
---
split-ring.tex | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/split-ring.tex b/split-ring.tex
index a594d41..87ecee2 100644
--- a/split-ring.tex
+++ b/split-ring.tex
@@ -23,7 +23,7 @@ Each virtqueue consists of three parts:
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
+The memory alignment and size requirements, in bytes, of each part of the
virtqueue are summarized in the following table:
\begin{tabular}{|l|l|l|}
--
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 11/13] content: in-order buffer use
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (9 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 09/13] split-ring: typo: aligment Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 12/13] packed-ring: add in order support Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 13/13] split-ring: in order feature Michael S. Tsirkin
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 12/13] packed-ring: add in order support
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (10 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 11/13] content: in-order buffer use Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-09 21:23 ` [virtio] [PATCH v10 13/13] split-ring: in order feature Michael S. Tsirkin
12 siblings, 0 replies; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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 ebdba09..4b3d9d9 100644
--- a/packed-ring.tex
+++ b/packed-ring.tex
@@ -272,6 +272,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-buffer requests}
Some devices combine multiple buffers as part of processing of a
--
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* [virtio] [PATCH v10 13/13] split-ring: in order feature
2018-03-09 21:23 [virtio] [PATCH v10 00/13] packed ring layout spec Michael S. Tsirkin
` (11 preceding siblings ...)
2018-03-09 21:23 ` [virtio] [PATCH v10 12/13] packed-ring: add in order support Michael S. Tsirkin
@ 2018-03-09 21:23 ` Michael S. Tsirkin
2018-03-28 8:23 ` [virtio-dev] " Lars Ganrot
12 siblings, 1 reply; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-09 21:23 UTC (permalink / raw)
To: virtio, virtio-dev
Cc: Cornelia Huck, Halil Pasic, Tiwei Bie, Stefan Hajnoczi, Dhanoa, Kully
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 87ecee2..df278fe 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
---------------------------------------------------------------------
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
^ permalink raw reply related [flat|nested] 25+ messages in thread* RE: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-09 21:23 ` [virtio] [PATCH v10 13/13] split-ring: in order feature Michael S. Tsirkin
@ 2018-03-28 8:23 ` Lars Ganrot
2018-03-28 14:38 ` [virtio] " Michael S. Tsirkin
0 siblings, 1 reply; 25+ messages in thread
From: Lars Ganrot @ 2018-03-28 8:23 UTC (permalink / raw)
To: Michael S. Tsirkin, virtio, virtio-dev
Hi Michael et al
> Behalf Of Michael S. Tsirkin
> Sent: 9. marts 2018 22:24
>
> 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>
> ---
[snip]
>
> +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.
>
The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some accesses to the virtq_avail.ring and virtq_used.ring. However I'm wondering if the proposed descriptor ordering for multi-element buffers couldn't be tweaked to be more HW friendly. Currently even with the VIRTIO_F_IN_ORDER negotiated, there is no way of knowing if, or how many chained descriptors follow the descriptor pointed to by the virtq_avail.idx. A chain has to be inspected one descriptor at a time until virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward for HW offload, where you want to DMA all available descriptors in one shot, instead of iterating based on the contents of received DMA data. As currently defined, HW would have to find a compromise between likely chain length, and cost of additional DMA transfers. This leads to a performance penalty for all chained descriptors, and in case the length assumption is wrong the impact can be significant.
Now, what if the VIRTIO_F_IN_ORDER instead required chained buffers to place the last element at the lowest index, and the head-element (to which virtq_avail.idx points) at the highest index? Then all the chained element descriptors would be included in a DMA of the descriptor table from the previous virtq_avail.idx+1 to the current virtq_avail.idx. The "backward" order of the chained descriptors shouldn't pose an issue as such (at least not in HW).
Best Regards,
-Lars
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 25+ messages in thread* [virtio] Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-28 8:23 ` [virtio-dev] " Lars Ganrot
@ 2018-03-28 14:38 ` Michael S. Tsirkin
2018-03-28 16:12 ` Lars Ganrot
0 siblings, 1 reply; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-28 14:38 UTC (permalink / raw)
To: Lars Ganrot; +Cc: virtio, virtio-dev
On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> Hi Michael et al
>
> > Behalf Of Michael S. Tsirkin
> > Sent: 9. marts 2018 22:24
> >
> > 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>
> > ---
> [snip]
> >
> > +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.
> >
>
> The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some accesses to the virtq_avail.ring and virtq_used.ring. However I'm wondering if the proposed descriptor ordering for multi-element buffers couldn't be tweaked to be more HW friendly. Currently even with the VIRTIO_F_IN_ORDER negotiated, there is no way of knowing if, or how many chained descriptors follow the descriptor pointed to by the virtq_avail.idx. A chain has to be inspected one descriptor at a time until virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward for HW offload, where you want to DMA all available descriptors in one shot, instead of iterating based on the contents of received DMA data. As currently defined, HW would have to find a compromise between likely chain length, and cost of additional DMA transfers. This leads to a performance penalty for all chained descriptors, and in case the length assumption is wrong the impact can be significant.
>
> Now, what if the VIRTIO_F_IN_ORDER instead required chained buffers to place the last element at the lowest index, and the head-element (to which virtq_avail.idx points) at the highest index? Then all the chained element descriptors would be included in a DMA of the descriptor table from the previous virtq_avail.idx+1 to the current virtq_avail.idx. The "backward" order of the chained descriptors shouldn't pose an issue as such (at least not in HW).
>
> Best Regards,
>
> -Lars
virtq_avail.idx is still an index into the available ring.
I don't really see how you can use virtq_avail.idx to guess the
placement of a descriptor.
I suspect the best way to optimize this is to include the
relevant data with the VIRTIO_F_NOTIFICATION_DATA feature.
> ---------------------------------------------------------------------
> 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
^ permalink raw reply [flat|nested] 25+ messages in thread* RE: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-28 14:38 ` [virtio] " Michael S. Tsirkin
@ 2018-03-28 16:12 ` Lars Ganrot
2018-03-29 14:42 ` [virtio] " Michael S. Tsirkin
0 siblings, 1 reply; 25+ messages in thread
From: Lars Ganrot @ 2018-03-28 16:12 UTC (permalink / raw)
To: Michael S. Tsirkin; +Cc: virtio, virtio-dev
Missed replying to the lists. Sorry.
> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: 28. marts 2018 16:39
>
> On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > Hi Michael et al
> >
> > > Behalf Of Michael S. Tsirkin
> > > Sent: 9. marts 2018 22:24
> > >
> > > 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>
> > > ---
> > [snip]
> > >
> > > +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.
> > >
> >
> > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some accesses
> to the virtq_avail.ring and virtq_used.ring. However I'm wondering if the
> proposed descriptor ordering for multi-element buffers couldn't be tweaked
> to be more HW friendly. Currently even with the VIRTIO_F_IN_ORDER
> negotiated, there is no way of knowing if, or how many chained descriptors
> follow the descriptor pointed to by the virtq_avail.idx. A chain has to be
> inspected one descriptor at a time until
> virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward for HW offload,
> where you want to DMA all available descriptors in one shot, instead of
> iterating based on the contents of received DMA data. As currently defined,
> HW would have to find a compromise between likely chain length, and cost
> of additional DMA transfers. This leads to a performance penalty for all
> chained descriptors, and in case the length assumption is wrong the impact
> can be significant.
> >
> > Now, what if the VIRTIO_F_IN_ORDER instead required chained buffers to
> place the last element at the lowest index, and the head-element (to which
> virtq_avail.idx points) at the highest index? Then all the chained element
> descriptors would be included in a DMA of the descriptor table from the
> previous virtq_avail.idx+1 to the current virtq_avail.idx. The "backward"
> order of the chained descriptors shouldn't pose an issue as such (at least not
> in HW).
> >
> > Best Regards,
> >
> > -Lars
>
> virtq_avail.idx is still an index into the available ring.
>
> I don't really see how you can use virtq_avail.idx to guess the placement of a
> descriptor.
>
> I suspect the best way to optimize this is to include the relevant data with the
> VIRTIO_F_NOTIFICATION_DATA feature.
>
Argh, naturally.
For HW offload I'd want to avoid notifications for buffer transfer from host to device, and hoped to just poll virtq_avail.idx directly.
A split virtqueue with VITRIO_F_IN_ORDER will maintain virtq_avail.idx==virtq_avail.ring[idx] as long as there is no chaining. It would be nice to allow negotiating away chaining, i.e add a VIRTIO_F_NO_CHAIN. If negotiated, the driver agrees not to use chaining, and as a result (of IN_ORDER and NO_CHAIN) both device and driver can ignore the virtq_avail.ring[].
>
> > ---------------------------------------------------------------------
> > 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
^ permalink raw reply [flat|nested] 25+ messages in thread* [virtio] Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-28 16:12 ` Lars Ganrot
@ 2018-03-29 14:42 ` Michael S. Tsirkin
2018-03-29 18:23 ` Lars Ganrot
0 siblings, 1 reply; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-29 14:42 UTC (permalink / raw)
To: Lars Ganrot; +Cc: virtio, virtio-dev
On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> Missed replying to the lists. Sorry.
>
> > From: Michael S. Tsirkin <mst@redhat.com>
> > Sent: 28. marts 2018 16:39
> >
> > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > Hi Michael et al
> > >
> > > > Behalf Of Michael S. Tsirkin
> > > > Sent: 9. marts 2018 22:24
> > > >
> > > > 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>
> > > > ---
> > > [snip]
> > > >
> > > > +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.
> > > >
> > >
> > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some accesses
> > to the virtq_avail.ring and virtq_used.ring. However I'm wondering if the
> > proposed descriptor ordering for multi-element buffers couldn't be tweaked
> > to be more HW friendly. Currently even with the VIRTIO_F_IN_ORDER
> > negotiated, there is no way of knowing if, or how many chained descriptors
> > follow the descriptor pointed to by the virtq_avail.idx. A chain has to be
> > inspected one descriptor at a time until
> > virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward for HW offload,
> > where you want to DMA all available descriptors in one shot, instead of
> > iterating based on the contents of received DMA data. As currently defined,
> > HW would have to find a compromise between likely chain length, and cost
> > of additional DMA transfers. This leads to a performance penalty for all
> > chained descriptors, and in case the length assumption is wrong the impact
> > can be significant.
> > >
> > > Now, what if the VIRTIO_F_IN_ORDER instead required chained buffers to
> > place the last element at the lowest index, and the head-element (to which
> > virtq_avail.idx points) at the highest index? Then all the chained element
> > descriptors would be included in a DMA of the descriptor table from the
> > previous virtq_avail.idx+1 to the current virtq_avail.idx. The "backward"
> > order of the chained descriptors shouldn't pose an issue as such (at least not
> > in HW).
> > >
> > > Best Regards,
> > >
> > > -Lars
> >
> > virtq_avail.idx is still an index into the available ring.
> >
> > I don't really see how you can use virtq_avail.idx to guess the placement of a
> > descriptor.
> >
> > I suspect the best way to optimize this is to include the relevant data with the
> > VIRTIO_F_NOTIFICATION_DATA feature.
> >
>
> Argh, naturally.
BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the index right now.
Do you have an opinion on whether we should change that for in-order?
> For HW offload I'd want to avoid notifications for buffer transfer from host to device, and hoped to just poll virtq_avail.idx directly.
>
> A split virtqueue with VITRIO_F_IN_ORDER will maintain virtq_avail.idx==virtq_avail.ring[idx] as long as there is no chaining. It would be nice to allow negotiating away chaining, i.e add a VIRTIO_F_NO_CHAIN. If negotiated, the driver agrees not to use chaining, and as a result (of IN_ORDER and NO_CHAIN) both device and driver can ignore the virtq_avail.ring[].
My point was that device can just assume no chains, and then fall back
on doing extra reads upon encountering a chain.
> >
> > > ---------------------------------------------------------------------
> > > 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
---------------------------------------------------------------------
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
^ permalink raw reply [flat|nested] 25+ messages in thread* RE: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-29 14:42 ` [virtio] " Michael S. Tsirkin
@ 2018-03-29 18:23 ` Lars Ganrot
2018-03-29 19:12 ` [virtio] " Michael S. Tsirkin
0 siblings, 1 reply; 25+ messages in thread
From: Lars Ganrot @ 2018-03-29 18:23 UTC (permalink / raw)
To: Michael S. Tsirkin; +Cc: virtio, virtio-dev
> -----Original Message-----
> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: 29. marts 2018 16:42
> To: Lars Ganrot <lga@napatech.com>
> Cc: virtio@lists.oasis-open.org; virtio-dev@lists.oasis-open.org
> Subject: Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
>
> On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > Missed replying to the lists. Sorry.
> >
> > > From: Michael S. Tsirkin <mst@redhat.com>
> > > Sent: 28. marts 2018 16:39
> > >
> > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > > Hi Michael et al
> > > >
> > > > > Behalf Of Michael S. Tsirkin
> > > > > Sent: 9. marts 2018 22:24
> > > > >
> > > > > 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>
> > > > > ---
> > > > [snip]
> > > > >
> > > > > +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.
> > > > >
> > > >
> > > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some
> > > > accesses
> > > to the virtq_avail.ring and virtq_used.ring. However I'm wondering
> > > if the proposed descriptor ordering for multi-element buffers
> > > couldn't be tweaked to be more HW friendly. Currently even with the
> > > VIRTIO_F_IN_ORDER negotiated, there is no way of knowing if, or how
> > > many chained descriptors follow the descriptor pointed to by the
> > > virtq_avail.idx. A chain has to be inspected one descriptor at a
> > > time until virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward
> > > for HW offload, where you want to DMA all available descriptors in
> > > one shot, instead of iterating based on the contents of received DMA
> > > data. As currently defined, HW would have to find a compromise
> > > between likely chain length, and cost of additional DMA transfers.
> > > This leads to a performance penalty for all chained descriptors, and
> > > in case the length assumption is wrong the impact can be significant.
> > > >
> > > > Now, what if the VIRTIO_F_IN_ORDER instead required chained
> > > > buffers to
> > > place the last element at the lowest index, and the head-element (to
> > > which virtq_avail.idx points) at the highest index? Then all the
> > > chained element descriptors would be included in a DMA of the
> > > descriptor table from the previous virtq_avail.idx+1 to the current
> virtq_avail.idx. The "backward"
> > > order of the chained descriptors shouldn't pose an issue as such (at
> > > least not in HW).
> > > >
> > > > Best Regards,
> > > >
> > > > -Lars
> > >
> > > virtq_avail.idx is still an index into the available ring.
> > >
> > > I don't really see how you can use virtq_avail.idx to guess the
> > > placement of a descriptor.
> > >
> > > I suspect the best way to optimize this is to include the relevant
> > > data with the VIRTIO_F_NOTIFICATION_DATA feature.
> > >
> >
> > Argh, naturally.
>
> BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the index
> right now.
>
> Do you have an opinion on whether we should change that for in-order?
>
Maybe I should think more about this, however adding the last element descriptor index, would be useful to accelerate interfaces that frequently use chaining (from a HW DMA perspective at least).
> > For HW offload I'd want to avoid notifications for buffer transfer from host
> to device, and hoped to just poll virtq_avail.idx directly.
> >
> > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> virtq_avail.idx==virtq_avail.ring[idx] as long as there is no chaining. It would
> be nice to allow negotiating away chaining, i.e add a VIRTIO_F_NO_CHAIN. If
> negotiated, the driver agrees not to use chaining, and as a result (of
> IN_ORDER and NO_CHAIN) both device and driver can ignore the
> virtq_avail.ring[].
>
> My point was that device can just assume no chains, and then fall back on
> doing extra reads upon encountering a chain.
>
Yes, you are correct that the HW can speculatively use virtq_avail.idx as the direct index to the descriptor table, and if it encounters a chain, revert to using the virtq_avail.ring[] in the traditional way, and this would work without the feature-bit.
However the driver would not be able to optimize away the writing of the virtq_avail.ring[] (=cache miss) unless a NO_CHAIN feature has been negotiated. The IN_ORDER by itself has already eliminated the need to maintain the TX virtq_used.ring[], since the buffer order is always known by the driver. With a NO_CHAIN feature-bit both RX and TX virtq_avail.ring[] related cache-misses could be eliminated. I.e. looping a packet over a split virtqueue would just experience 7 driver cache misses, down from 10 in Virtio v1.0. Multi-element buffers would still be possible provided INDIRECT is negotiated.
>
>
> > >
> > > > ------------------------------------------------------------------
> > > > --- 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
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 25+ messages in thread* [virtio] Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-29 18:23 ` Lars Ganrot
@ 2018-03-29 19:12 ` Michael S. Tsirkin
2018-04-03 7:19 ` Lars Ganrot
0 siblings, 1 reply; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-03-29 19:12 UTC (permalink / raw)
To: Lars Ganrot; +Cc: virtio, virtio-dev
On Thu, Mar 29, 2018 at 06:23:28PM +0000, Lars Ganrot wrote:
>
>
> > -----Original Message-----
> > From: Michael S. Tsirkin <mst@redhat.com>
> > Sent: 29. marts 2018 16:42
> > To: Lars Ganrot <lga@napatech.com>
> > Cc: virtio@lists.oasis-open.org; virtio-dev@lists.oasis-open.org
> > Subject: Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
> >
> > On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > > Missed replying to the lists. Sorry.
> > >
> > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > Sent: 28. marts 2018 16:39
> > > >
> > > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > > > Hi Michael et al
> > > > >
> > > > > > Behalf Of Michael S. Tsirkin
> > > > > > Sent: 9. marts 2018 22:24
> > > > > >
> > > > > > 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>
> > > > > > ---
> > > > > [snip]
> > > > > >
> > > > > > +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.
> > > > > >
> > > > >
> > > > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some
> > > > > accesses
> > > > to the virtq_avail.ring and virtq_used.ring. However I'm wondering
> > > > if the proposed descriptor ordering for multi-element buffers
> > > > couldn't be tweaked to be more HW friendly. Currently even with the
> > > > VIRTIO_F_IN_ORDER negotiated, there is no way of knowing if, or how
> > > > many chained descriptors follow the descriptor pointed to by the
> > > > virtq_avail.idx. A chain has to be inspected one descriptor at a
> > > > time until virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward
> > > > for HW offload, where you want to DMA all available descriptors in
> > > > one shot, instead of iterating based on the contents of received DMA
> > > > data. As currently defined, HW would have to find a compromise
> > > > between likely chain length, and cost of additional DMA transfers.
> > > > This leads to a performance penalty for all chained descriptors, and
> > > > in case the length assumption is wrong the impact can be significant.
> > > > >
> > > > > Now, what if the VIRTIO_F_IN_ORDER instead required chained
> > > > > buffers to
> > > > place the last element at the lowest index, and the head-element (to
> > > > which virtq_avail.idx points) at the highest index? Then all the
> > > > chained element descriptors would be included in a DMA of the
> > > > descriptor table from the previous virtq_avail.idx+1 to the current
> > virtq_avail.idx. The "backward"
> > > > order of the chained descriptors shouldn't pose an issue as such (at
> > > > least not in HW).
> > > > >
> > > > > Best Regards,
> > > > >
> > > > > -Lars
> > > >
> > > > virtq_avail.idx is still an index into the available ring.
> > > >
> > > > I don't really see how you can use virtq_avail.idx to guess the
> > > > placement of a descriptor.
> > > >
> > > > I suspect the best way to optimize this is to include the relevant
> > > > data with the VIRTIO_F_NOTIFICATION_DATA feature.
> > > >
> > >
> > > Argh, naturally.
> >
> > BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the index
> > right now.
> >
> > Do you have an opinion on whether we should change that for in-order?
> >
>
> Maybe I should think more about this, however adding the last element descriptor index, would be useful to accelerate interfaces that frequently use chaining (from a HW DMA perspective at least).
>
> > > For HW offload I'd want to avoid notifications for buffer transfer from host
> > to device, and hoped to just poll virtq_avail.idx directly.
> > >
> > > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> > virtq_avail.idx==virtq_avail.ring[idx] as long as there is no chaining. It would
> > be nice to allow negotiating away chaining, i.e add a VIRTIO_F_NO_CHAIN. If
> > negotiated, the driver agrees not to use chaining, and as a result (of
> > IN_ORDER and NO_CHAIN) both device and driver can ignore the
> > virtq_avail.ring[].
> >
> > My point was that device can just assume no chains, and then fall back on
> > doing extra reads upon encountering a chain.
> >
>
> Yes, you are correct that the HW can speculatively use virtq_avail.idx as the direct index to the descriptor table, and if it encounters a chain, revert to using the virtq_avail.ring[] in the traditional way, and this would work without the feature-bit.
Sorry that was not my idea.
Device should not need to read the ring at all.
It reads the descriptor table and counts the descriptors
without the next bit. Once the count reaches the available
index, it stops.
> However the driver would not be able to optimize away the writing of
> the virtq_avail.ring[] (=cache miss)
BTW writing is a separate question (there is no provision in
the spec to skip writes) but device does not have to read the ring.
Without device accesses ring will not be invaliated in cache
so no misses hopefully.
> unless a NO_CHAIN feature has
> been negotiated.
> The IN_ORDER by itself has already eliminated the
> need to maintain the TX virtq_used.ring[], since the buffer order is
> always known by the driver.
> With a NO_CHAIN feature-bit both RX and TX
> virtq_avail.ring[] related cache-misses could be eliminated. I.e.
> looping a packet over a split virtqueue would just experience 7 driver
> cache misses, down from 10 in Virtio v1.0. Multi-element buffers would
> still be possible provided INDIRECT is negotiated.
NO_CHAIN might be a valid optimization, it is just unfortunately
somewhat narrow in that devices that need to mix write and read descriptors in
the same ring (e.g. storage) can not use this feature.
> >
> >
> > > >
> > > > > ------------------------------------------------------------------
> > > > > --- 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
> Disclaimer: This email and any files transmitted with it may contain confidential information intended for the addressee(s) only. The information is not to be surrendered or copied to unauthorized persons. If you have received this communication in error, please notify the sender immediately and delete this e-mail from your system.
---------------------------------------------------------------------
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
^ permalink raw reply [flat|nested] 25+ messages in thread* RE: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-03-29 19:12 ` [virtio] " Michael S. Tsirkin
@ 2018-04-03 7:19 ` Lars Ganrot
2018-04-03 11:47 ` [virtio] " Michael S. Tsirkin
0 siblings, 1 reply; 25+ messages in thread
From: Lars Ganrot @ 2018-04-03 7:19 UTC (permalink / raw)
To: Michael S. Tsirkin; +Cc: virtio, virtio-dev
> From: virtio-dev@lists.oasis-open.org <virtio-dev@lists.oasis-open.org> On
> Behalf Of Michael S. Tsirkin
> Sent: 29. marts 2018 21:13
>
> On Thu, Mar 29, 2018 at 06:23:28PM +0000, Lars Ganrot wrote:
> >
> >
> > > From: Michael S. Tsirkin <mst@redhat.com>
> > > Sent: 29. marts 2018 16:42
> > >
> > > On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > > > Missed replying to the lists. Sorry.
> > > >
> > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > Sent: 28. marts 2018 16:39
> > > > >
> > > > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > > > > Hi Michael et al
> > > > > >
> > > > > > > Behalf Of Michael S. Tsirkin
> > > > > > > Sent: 9. marts 2018 22:24
> > > > > > >
> > > > > > > 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>
> > > > > > > ---
> > > > > > [snip]
> > > > > > >
> > > > > > > +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.
> > > > > > >
> > > > > >
> > > > > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some
> > > > > > accesses
> > > > > to the virtq_avail.ring and virtq_used.ring. However I'm
> > > > > wondering if the proposed descriptor ordering for multi-element
> > > > > buffers couldn't be tweaked to be more HW friendly. Currently
> > > > > even with the VIRTIO_F_IN_ORDER negotiated, there is no way of
> > > > > knowing if, or how many chained descriptors follow the
> > > > > descriptor pointed to by the virtq_avail.idx. A chain has to be
> > > > > inspected one descriptor at a time until
> > > > > virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward for HW
> > > > > offload, where you want to DMA all available descriptors in one
> > > > > shot, instead of iterating based on the contents of received DMA
> > > > > data. As currently defined, HW would have to find a compromise
> between likely chain length, and cost of additional DMA transfers.
> > > > > This leads to a performance penalty for all chained descriptors,
> > > > > and in case the length assumption is wrong the impact can be
> significant.
> > > > > >
> > > > > > Now, what if the VIRTIO_F_IN_ORDER instead required chained
> > > > > > buffers to
> > > > > place the last element at the lowest index, and the head-element
> > > > > (to which virtq_avail.idx points) at the highest index? Then all
> > > > > the chained element descriptors would be included in a DMA of
> > > > > the descriptor table from the previous virtq_avail.idx+1 to the
> > > > > current
> > > virtq_avail.idx. The "backward"
> > > > > order of the chained descriptors shouldn't pose an issue as such
> > > > > (at least not in HW).
> > > > > >
> > > > > > Best Regards,
> > > > > >
> > > > > > -Lars
> > > > >
> > > > > virtq_avail.idx is still an index into the available ring.
> > > > >
> > > > > I don't really see how you can use virtq_avail.idx to guess the
> > > > > placement of a descriptor.
> > > > >
> > > > > I suspect the best way to optimize this is to include the
> > > > > relevant data with the VIRTIO_F_NOTIFICATION_DATA feature.
> > > > >
> > > >
> > > > Argh, naturally.
> > >
> > > BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the
> > > index right now.
> > >
> > > Do you have an opinion on whether we should change that for in-order?
> > >
> >
> > Maybe I should think more about this, however adding the last element
> descriptor index, would be useful to accelerate interfaces that frequently
> use chaining (from a HW DMA perspective at least).
> >
> > > > For HW offload I'd want to avoid notifications for buffer transfer
> > > > from host
> > > to device, and hoped to just poll virtq_avail.idx directly.
> > > >
> > > > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> > > virtq_avail.idx==virtq_avail.ring[idx] as long as there is no
> > > chaining. It would be nice to allow negotiating away chaining, i.e
> > > add a VIRTIO_F_NO_CHAIN. If negotiated, the driver agrees not to use
> > > chaining, and as a result (of IN_ORDER and NO_CHAIN) both device and
> > > driver can ignore the virtq_avail.ring[].
> > >
> > > My point was that device can just assume no chains, and then fall
> > > back on doing extra reads upon encountering a chain.
> > >
> >
> > Yes, you are correct that the HW can speculatively use virtq_avail.idx as the
> >direct index to the descriptor table, and if it encounters a chain, revert to
> >using the virtq_avail.ring[] in the traditional way, and this would work
> >without the feature-bit.
>
> Sorry that was not my idea.
>
> Device should not need to read the ring at all.
> It reads the descriptor table and counts the descriptors without the next bit.
> Once the count reaches the available index, it stops.
>
Agreed, that would work as well, with the benefit of keeping the ring out of
the loop.
>
> > However the driver would not be able to optimize away the writing of
> > the virtq_avail.ring[] (=cache miss)
>
>
> BTW writing is a separate question (there is no provision in the spec to skip
> writes) but device does not have to read the ring.
>
Yes, I understand the spec currently does not allow writes to be skipped, but
I'm wondering if that ought to be reconsidered for optimization features such
as IN_ORDER and NO_CHAIN? By opting for such features, both driver and
device acknowledge their willingness to accept reduced flexibility for
improved performance. Why not then make sure they get the biggest bang for
their buck? I would expect up to 20% improvement over PCIe (virtio-net,
single 64B packet), if the device does not have to write to virtq_used.ring[] on
transmit, and bandwidth over PCI is a very precious resource in e.g. virtual
switch offload with east-west acceleration (for a discussion see Intel's white-
paper 335625-001).
> Without device accesses ring will not be invaliated in cache so no misses
> hopefully.
>
> > unless a NO_CHAIN feature has
> > been negotiated.
> > The IN_ORDER by itself has already eliminated the need to maintain the
> > TX virtq_used.ring[], since the buffer order is always known by the
> > driver.
> > With a NO_CHAIN feature-bit both RX and TX virtq_avail.ring[] related
> > cache-misses could be eliminated. I.e.
> > looping a packet over a split virtqueue would just experience 7 driver
> > cache misses, down from 10 in Virtio v1.0. Multi-element buffers would
> > still be possible provided INDIRECT is negotiated.
>
>
> NO_CHAIN might be a valid optimization, it is just unfortunately somewhat
> narrow in that devices that need to mix write and read descriptors in the
> same ring (e.g. storage) can not use this feature.
>
Yes, if there was a way of making indirect buffers support it, that would be
ideal. However I don't see how that can be done without inline headers in
elements to hold their written length.
At the same time storage would not be hurt by it even if they are unable to
benefit from this particular optimization, and as long as there is a substantial
use case/space that benefit from an optimization, it ought to be considered.
I believe virtual switching offload with virtio-net devices over PCIe is such a
key use-case.
>
> > >
> > >
> > > > >
> > > > > > --------------------------------------------------------------
> > > > > > ----
> > > > > > --- 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
> > Disclaimer: This email and any files transmitted with it may contain
> confidential information intended for the addressee(s) only. The information
> is not to be surrendered or copied to unauthorized persons. If you have
> received this communication in error, please notify the sender immediately
> and delete this e-mail from your system.
>
> ---------------------------------------------------------------------
> 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
^ permalink raw reply [flat|nested] 25+ messages in thread* [virtio] Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-04-03 7:19 ` Lars Ganrot
@ 2018-04-03 11:47 ` Michael S. Tsirkin
2018-04-04 15:03 ` Lars Ganrot
0 siblings, 1 reply; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-04-03 11:47 UTC (permalink / raw)
To: Lars Ganrot; +Cc: virtio, virtio-dev
On Tue, Apr 03, 2018 at 07:19:47AM +0000, Lars Ganrot wrote:
> > From: virtio-dev@lists.oasis-open.org <virtio-dev@lists.oasis-open.org> On
> > Behalf Of Michael S. Tsirkin
> > Sent: 29. marts 2018 21:13
> >
> > On Thu, Mar 29, 2018 at 06:23:28PM +0000, Lars Ganrot wrote:
> > >
> > >
> > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > Sent: 29. marts 2018 16:42
> > > >
> > > > On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > > > > Missed replying to the lists. Sorry.
> > > > >
> > > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > > Sent: 28. marts 2018 16:39
> > > > > >
> > > > > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > > > > > Hi Michael et al
> > > > > > >
> > > > > > > > Behalf Of Michael S. Tsirkin
> > > > > > > > Sent: 9. marts 2018 22:24
> > > > > > > >
> > > > > > > > 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>
> > > > > > > > ---
> > > > > > > [snip]
> > > > > > > >
> > > > > > > > +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.
> > > > > > > >
> > > > > > >
> > > > > > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate some
> > > > > > > accesses
> > > > > > to the virtq_avail.ring and virtq_used.ring. However I'm
> > > > > > wondering if the proposed descriptor ordering for multi-element
> > > > > > buffers couldn't be tweaked to be more HW friendly. Currently
> > > > > > even with the VIRTIO_F_IN_ORDER negotiated, there is no way of
> > > > > > knowing if, or how many chained descriptors follow the
> > > > > > descriptor pointed to by the virtq_avail.idx. A chain has to be
> > > > > > inspected one descriptor at a time until
> > > > > > virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward for HW
> > > > > > offload, where you want to DMA all available descriptors in one
> > > > > > shot, instead of iterating based on the contents of received DMA
> > > > > > data. As currently defined, HW would have to find a compromise
> > between likely chain length, and cost of additional DMA transfers.
> > > > > > This leads to a performance penalty for all chained descriptors,
> > > > > > and in case the length assumption is wrong the impact can be
> > significant.
> > > > > > >
> > > > > > > Now, what if the VIRTIO_F_IN_ORDER instead required chained
> > > > > > > buffers to
> > > > > > place the last element at the lowest index, and the head-element
> > > > > > (to which virtq_avail.idx points) at the highest index? Then all
> > > > > > the chained element descriptors would be included in a DMA of
> > > > > > the descriptor table from the previous virtq_avail.idx+1 to the
> > > > > > current
> > > > virtq_avail.idx. The "backward"
> > > > > > order of the chained descriptors shouldn't pose an issue as such
> > > > > > (at least not in HW).
> > > > > > >
> > > > > > > Best Regards,
> > > > > > >
> > > > > > > -Lars
> > > > > >
> > > > > > virtq_avail.idx is still an index into the available ring.
> > > > > >
> > > > > > I don't really see how you can use virtq_avail.idx to guess the
> > > > > > placement of a descriptor.
> > > > > >
> > > > > > I suspect the best way to optimize this is to include the
> > > > > > relevant data with the VIRTIO_F_NOTIFICATION_DATA feature.
> > > > > >
> > > > >
> > > > > Argh, naturally.
> > > >
> > > > BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the
> > > > index right now.
> > > >
> > > > Do you have an opinion on whether we should change that for in-order?
> > > >
> > >
> > > Maybe I should think more about this, however adding the last element
> > descriptor index, would be useful to accelerate interfaces that frequently
> > use chaining (from a HW DMA perspective at least).
> > >
> > > > > For HW offload I'd want to avoid notifications for buffer transfer
> > > > > from host
> > > > to device, and hoped to just poll virtq_avail.idx directly.
> > > > >
> > > > > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> > > > virtq_avail.idx==virtq_avail.ring[idx] as long as there is no
> > > > chaining. It would be nice to allow negotiating away chaining, i.e
> > > > add a VIRTIO_F_NO_CHAIN. If negotiated, the driver agrees not to use
> > > > chaining, and as a result (of IN_ORDER and NO_CHAIN) both device and
> > > > driver can ignore the virtq_avail.ring[].
> > > >
> > > > My point was that device can just assume no chains, and then fall
> > > > back on doing extra reads upon encountering a chain.
> > > >
> > >
> > > Yes, you are correct that the HW can speculatively use virtq_avail.idx as the
> > >direct index to the descriptor table, and if it encounters a chain, revert to
> > >using the virtq_avail.ring[] in the traditional way, and this would work
> > >without the feature-bit.
> >
> > Sorry that was not my idea.
> >
> > Device should not need to read the ring at all.
> > It reads the descriptor table and counts the descriptors without the next bit.
> > Once the count reaches the available index, it stops.
> >
>
> Agreed, that would work as well, with the benefit of keeping the ring out of
> the loop.
>
> >
> > > However the driver would not be able to optimize away the writing of
> > > the virtq_avail.ring[] (=cache miss)
> >
> >
> > BTW writing is a separate question (there is no provision in the spec to skip
> > writes) but device does not have to read the ring.
> >
>
> Yes, I understand the spec currently does not allow writes to be skipped, but
> I'm wondering if that ought to be reconsidered for optimization features such
> as IN_ORDER and NO_CHAIN?
Why not just use the packed ring then?
> By opting for such features, both driver and
> device acknowledge their willingness to accept reduced flexibility for
> improved performance. Why not then make sure they get the biggest bang for
> their buck? I would expect up to 20% improvement over PCIe (virtio-net,
> single 64B packet), if the device does not have to write to virtq_used.ring[] on
> transmit, and bandwidth over PCI is a very precious resource in e.g. virtual
> switch offload with east-west acceleration (for a discussion see Intel's white-
> paper 335625-001).
Haven't looked at it yet but we also need to consider the complexity,
see below.
> > Without device accesses ring will not be invaliated in cache so no misses
> > hopefully.
> >
> > > unless a NO_CHAIN feature has
> > > been negotiated.
> > > The IN_ORDER by itself has already eliminated the need to maintain the
> > > TX virtq_used.ring[], since the buffer order is always known by the
> > > driver.
> > > With a NO_CHAIN feature-bit both RX and TX virtq_avail.ring[] related
> > > cache-misses could be eliminated. I.e.
> > > looping a packet over a split virtqueue would just experience 7 driver
> > > cache misses, down from 10 in Virtio v1.0. Multi-element buffers would
> > > still be possible provided INDIRECT is negotiated.
> >
> >
> > NO_CHAIN might be a valid optimization, it is just unfortunately somewhat
> > narrow in that devices that need to mix write and read descriptors in the
> > same ring (e.g. storage) can not use this feature.
> >
>
> Yes, if there was a way of making indirect buffers support it, that would be
> ideal. However I don't see how that can be done without inline headers in
> elements to hold their written length.
Kind of like it's done with with packed ring?
> At the same time storage would not be hurt by it even if they are unable to
> benefit from this particular optimization,
It will be hurt if it uses shared code paths which potentially
take up more cache, or if bugs are introduced.
> and as long as there is a substantial
> use case/space that benefit from an optimization, it ought to be considered.
> I believe virtual switching offload with virtio-net devices over PCIe is such a
> key use-case.
It looks like the packed ring addresses the need nicely,
while being device-independent.
> >
> > > >
> > > >
> > > > > >
> > > > > > > --------------------------------------------------------------
> > > > > > > ----
> > > > > > > --- 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
> > > Disclaimer: This email and any files transmitted with it may contain
> > confidential information intended for the addressee(s) only. The information
> > is not to be surrendered or copied to unauthorized persons. If you have
> > received this communication in error, please notify the sender immediately
> > and delete this e-mail from your system.
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
> > For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
>
> Disclaimer: This email and any files transmitted with it may contain confidential information intended for the addressee(s) only. The information is not to be surrendered or copied to unauthorized persons. If you have received this communication in error, please notify the sender immediately and delete this e-mail from your system.
---------------------------------------------------------------------
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
^ permalink raw reply [flat|nested] 25+ messages in thread* RE: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-04-03 11:47 ` [virtio] " Michael S. Tsirkin
@ 2018-04-04 15:03 ` Lars Ganrot
2018-04-04 16:07 ` [virtio] " Michael S. Tsirkin
0 siblings, 1 reply; 25+ messages in thread
From: Lars Ganrot @ 2018-04-04 15:03 UTC (permalink / raw)
To: Michael S. Tsirkin; +Cc: virtio, virtio-dev
> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: 3. april 2018 13:48
> To: Lars Ganrot <lga@napatech.com>
> Cc: virtio@lists.oasis-open.org; virtio-dev@lists.oasis-open.org
> Subject: Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
>
> On Tue, Apr 03, 2018 at 07:19:47AM +0000, Lars Ganrot wrote:
> > > From: virtio-dev@lists.oasis-open.org
> > > <virtio-dev@lists.oasis-open.org> On Behalf Of Michael S. Tsirkin
> > > Sent: 29. marts 2018 21:13
> > >
> > > On Thu, Mar 29, 2018 at 06:23:28PM +0000, Lars Ganrot wrote:
> > > >
> > > >
> > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > Sent: 29. marts 2018 16:42
> > > > >
> > > > > On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > > > > > Missed replying to the lists. Sorry.
> > > > > >
> > > > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > > > Sent: 28. marts 2018 16:39
> > > > > > >
> > > > > > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > > > > > > Hi Michael et al
> > > > > > > >
> > > > > > > > > Behalf Of Michael S. Tsirkin
> > > > > > > > > Sent: 9. marts 2018 22:24
> > > > > > > > >
> > > > > > > > > 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>
> > > > > > > > > ---
> > > > > > > > [snip]
> > > > > > > > >
> > > > > > > > > +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.
> > > > > > > > >
> > > > > > > >
> > > > > > > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate
> > > > > > > > some accesses
> > > > > > > to the virtq_avail.ring and virtq_used.ring. However I'm
> > > > > > > wondering if the proposed descriptor ordering for
> > > > > > > multi-element buffers couldn't be tweaked to be more HW
> > > > > > > friendly. Currently even with the VIRTIO_F_IN_ORDER
> > > > > > > negotiated, there is no way of knowing if, or how many
> > > > > > > chained descriptors follow the descriptor pointed to by the
> > > > > > > virtq_avail.idx. A chain has to be inspected one descriptor
> > > > > > > at a time until virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This
> > > > > > > is awkward for HW offload, where you want to DMA all
> > > > > > > available descriptors in one shot, instead of iterating
> > > > > > > based on the contents of received DMA data. As currently
> > > > > > > defined, HW would have to find a compromise
> > > between likely chain length, and cost of additional DMA transfers.
> > > > > > > This leads to a performance penalty for all chained
> > > > > > > descriptors, and in case the length assumption is wrong the
> > > > > > > impact can be
> > > significant.
> > > > > > > >
> > > > > > > > Now, what if the VIRTIO_F_IN_ORDER instead required
> > > > > > > > chained buffers to
> > > > > > > place the last element at the lowest index, and the
> > > > > > > head-element (to which virtq_avail.idx points) at the
> > > > > > > highest index? Then all the chained element descriptors
> > > > > > > would be included in a DMA of the descriptor table from the
> > > > > > > previous virtq_avail.idx+1 to the current
> > > > > virtq_avail.idx. The "backward"
> > > > > > > order of the chained descriptors shouldn't pose an issue as
> > > > > > > such (at least not in HW).
> > > > > > > >
> > > > > > > > Best Regards,
> > > > > > > >
> > > > > > > > -Lars
> > > > > > >
> > > > > > > virtq_avail.idx is still an index into the available ring.
> > > > > > >
> > > > > > > I don't really see how you can use virtq_avail.idx to guess
> > > > > > > the placement of a descriptor.
> > > > > > >
> > > > > > > I suspect the best way to optimize this is to include the
> > > > > > > relevant data with the VIRTIO_F_NOTIFICATION_DATA feature.
> > > > > > >
> > > > > >
> > > > > > Argh, naturally.
> > > > >
> > > > > BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the
> > > > > index right now.
> > > > >
> > > > > Do you have an opinion on whether we should change that for in-
> order?
> > > > >
> > > >
> > > > Maybe I should think more about this, however adding the last
> > > > element
> > > descriptor index, would be useful to accelerate interfaces that
> > > frequently use chaining (from a HW DMA perspective at least).
> > > >
> > > > > > For HW offload I'd want to avoid notifications for buffer
> > > > > > transfer from host
> > > > > to device, and hoped to just poll virtq_avail.idx directly.
> > > > > >
> > > > > > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> > > > > virtq_avail.idx==virtq_avail.ring[idx] as long as there is no
> > > > > chaining. It would be nice to allow negotiating away chaining,
> > > > > i.e add a VIRTIO_F_NO_CHAIN. If negotiated, the driver agrees
> > > > > not to use chaining, and as a result (of IN_ORDER and NO_CHAIN)
> > > > > both device and driver can ignore the virtq_avail.ring[].
> > > > >
> > > > > My point was that device can just assume no chains, and then
> > > > > fall back on doing extra reads upon encountering a chain.
> > > > >
> > > >
> > > > Yes, you are correct that the HW can speculatively use
> > > >virtq_avail.idx as the direct index to the descriptor table, and if
> > > >it encounters a chain, revert to using the virtq_avail.ring[] in
> > > >the traditional way, and this would work without the feature-bit.
> > >
> > > Sorry that was not my idea.
> > >
> > > Device should not need to read the ring at all.
> > > It reads the descriptor table and counts the descriptors without the next
> bit.
> > > Once the count reaches the available index, it stops.
> > >
> >
> > Agreed, that would work as well, with the benefit of keeping the ring
> > out of the loop.
> >
> > >
> > > > However the driver would not be able to optimize away the writing
> > > > of the virtq_avail.ring[] (=cache miss)
> > >
> > >
> > > BTW writing is a separate question (there is no provision in the
> > > spec to skip
> > > writes) but device does not have to read the ring.
> > >
> >
> > Yes, I understand the spec currently does not allow writes to be
> > skipped, but I'm wondering if that ought to be reconsidered for
> > optimization features such as IN_ORDER and NO_CHAIN?
>
> Why not just use the packed ring then?
>
Device notification. While the packed ring solves some of the issues in
the split ring, it also comes at a cost. In my view the two complement
each other, however the required use of driver to device notifications
in the packed ring for all driver to device transfers over PCIe (to handle
the update granularity issue with Qwords as pointed out by Ilya on 14:th
Jan) will limit performance (latency and throughput) in our experience.
We want to use device polling.
Btw, won't the notification add one extra cache miss for all TX over PCIe
transport?
> > By opting for such features, both driver and device acknowledge their
> > willingness to accept reduced flexibility for improved performance.
> > Why not then make sure they get the biggest bang for their buck? I
> > would expect up to 20% improvement over PCIe (virtio-net, single 64B
> > packet), if the device does not have to write to virtq_used.ring[] on
> > transmit, and bandwidth over PCI is a very precious resource in e.g.
> > virtual switch offload with east-west acceleration (for a discussion
> > see Intel's white- paper 335625-001).
>
> Haven't looked at it yet but we also need to consider the complexity, see
> below.
>
> > > Without device accesses ring will not be invaliated in cache so no
> > > misses hopefully.
> > >
> > > > unless a NO_CHAIN feature has
> > > > been negotiated.
> > > > The IN_ORDER by itself has already eliminated the need to maintain
> > > > the TX virtq_used.ring[], since the buffer order is always known
> > > > by the driver.
> > > > With a NO_CHAIN feature-bit both RX and TX virtq_avail.ring[]
> > > > related cache-misses could be eliminated. I.e.
> > > > looping a packet over a split virtqueue would just experience 7
> > > > driver cache misses, down from 10 in Virtio v1.0. Multi-element
> > > > buffers would still be possible provided INDIRECT is negotiated.
> > >
> > >
> > > NO_CHAIN might be a valid optimization, it is just unfortunately
> > > somewhat narrow in that devices that need to mix write and read
> > > descriptors in the same ring (e.g. storage) can not use this feature.
> > >
> >
> > Yes, if there was a way of making indirect buffers support it, that
> > would be ideal. However I don't see how that can be done without
> > inline headers in elements to hold their written length.
>
> Kind of like it's done with with packed ring?
>
> > At the same time storage would not be hurt by it even if they are
> > unable to benefit from this particular optimization,
>
> It will be hurt if it uses shared code paths which potentially take up more
> cache, or if bugs are introduced.
>
> > and as long as there is a substantial
> > use case/space that benefit from an optimization, it ought to be
> considered.
> > I believe virtual switching offload with virtio-net devices over PCIe
> > is such a key use-case.
>
> It looks like the packed ring addresses the need nicely, while being device-
> independent.
>
>
> > >
> > > > >
> > > > >
> > > > > > >
> > > > > > > > ----------------------------------------------------------
> > > > > > > > ----
> > > > > > > > ----
> > > > > > > > --- 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
> > > > Disclaimer: This email and any files transmitted with it may
> > > > contain
> > > confidential information intended for the addressee(s) only. The
> > > information is not to be surrendered or copied to unauthorized
> > > persons. If you have received this communication in error, please
> > > notify the sender immediately and delete this e-mail from your system.
> > >
> > > --------------------------------------------------------------------
> > > - To unsubscribe, e-mail:
> > > virtio-dev-unsubscribe@lists.oasis-open.org
> > > For additional commands, e-mail:
> > > virtio-dev-help@lists.oasis-open.org
> >
> > Disclaimer: This email and any files transmitted with it may contain
> confidential information intended for the addressee(s) only. The information
> is not to be surrendered or copied to unauthorized persons. If you have
> received this communication in error, please notify the sender immediately
> and delete this e-mail from your system.
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 25+ messages in thread* [virtio] Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-04-04 15:03 ` Lars Ganrot
@ 2018-04-04 16:07 ` Michael S. Tsirkin
2018-04-05 7:18 ` Lars Ganrot
0 siblings, 1 reply; 25+ messages in thread
From: Michael S. Tsirkin @ 2018-04-04 16:07 UTC (permalink / raw)
To: Lars Ganrot; +Cc: virtio, virtio-dev
On Wed, Apr 04, 2018 at 03:03:16PM +0000, Lars Ganrot wrote:
> > From: Michael S. Tsirkin <mst@redhat.com>
> > Sent: 3. april 2018 13:48
> > To: Lars Ganrot <lga@napatech.com>
> > Cc: virtio@lists.oasis-open.org; virtio-dev@lists.oasis-open.org
> > Subject: Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
> >
> > On Tue, Apr 03, 2018 at 07:19:47AM +0000, Lars Ganrot wrote:
> > > > From: virtio-dev@lists.oasis-open.org
> > > > <virtio-dev@lists.oasis-open.org> On Behalf Of Michael S. Tsirkin
> > > > Sent: 29. marts 2018 21:13
> > > >
> > > > On Thu, Mar 29, 2018 at 06:23:28PM +0000, Lars Ganrot wrote:
> > > > >
> > > > >
> > > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > > Sent: 29. marts 2018 16:42
> > > > > >
> > > > > > On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > > > > > > Missed replying to the lists. Sorry.
> > > > > > >
> > > > > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > > > > Sent: 28. marts 2018 16:39
> > > > > > > >
> > > > > > > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot wrote:
> > > > > > > > > Hi Michael et al
> > > > > > > > >
> > > > > > > > > > Behalf Of Michael S. Tsirkin
> > > > > > > > > > Sent: 9. marts 2018 22:24
> > > > > > > > > >
> > > > > > > > > > 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>
> > > > > > > > > > ---
> > > > > > > > > [snip]
> > > > > > > > > >
> > > > > > > > > > +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.
> > > > > > > > > >
> > > > > > > > >
> > > > > > > > > The use of VIRTIO_F_IN_ORDER for split-ring can eliminate
> > > > > > > > > some accesses
> > > > > > > > to the virtq_avail.ring and virtq_used.ring. However I'm
> > > > > > > > wondering if the proposed descriptor ordering for
> > > > > > > > multi-element buffers couldn't be tweaked to be more HW
> > > > > > > > friendly. Currently even with the VIRTIO_F_IN_ORDER
> > > > > > > > negotiated, there is no way of knowing if, or how many
> > > > > > > > chained descriptors follow the descriptor pointed to by the
> > > > > > > > virtq_avail.idx. A chain has to be inspected one descriptor
> > > > > > > > at a time until virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This
> > > > > > > > is awkward for HW offload, where you want to DMA all
> > > > > > > > available descriptors in one shot, instead of iterating
> > > > > > > > based on the contents of received DMA data. As currently
> > > > > > > > defined, HW would have to find a compromise
> > > > between likely chain length, and cost of additional DMA transfers.
> > > > > > > > This leads to a performance penalty for all chained
> > > > > > > > descriptors, and in case the length assumption is wrong the
> > > > > > > > impact can be
> > > > significant.
> > > > > > > > >
> > > > > > > > > Now, what if the VIRTIO_F_IN_ORDER instead required
> > > > > > > > > chained buffers to
> > > > > > > > place the last element at the lowest index, and the
> > > > > > > > head-element (to which virtq_avail.idx points) at the
> > > > > > > > highest index? Then all the chained element descriptors
> > > > > > > > would be included in a DMA of the descriptor table from the
> > > > > > > > previous virtq_avail.idx+1 to the current
> > > > > > virtq_avail.idx. The "backward"
> > > > > > > > order of the chained descriptors shouldn't pose an issue as
> > > > > > > > such (at least not in HW).
> > > > > > > > >
> > > > > > > > > Best Regards,
> > > > > > > > >
> > > > > > > > > -Lars
> > > > > > > >
> > > > > > > > virtq_avail.idx is still an index into the available ring.
> > > > > > > >
> > > > > > > > I don't really see how you can use virtq_avail.idx to guess
> > > > > > > > the placement of a descriptor.
> > > > > > > >
> > > > > > > > I suspect the best way to optimize this is to include the
> > > > > > > > relevant data with the VIRTIO_F_NOTIFICATION_DATA feature.
> > > > > > > >
> > > > > > >
> > > > > > > Argh, naturally.
> > > > > >
> > > > > > BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies the
> > > > > > index right now.
> > > > > >
> > > > > > Do you have an opinion on whether we should change that for in-
> > order?
> > > > > >
> > > > >
> > > > > Maybe I should think more about this, however adding the last
> > > > > element
> > > > descriptor index, would be useful to accelerate interfaces that
> > > > frequently use chaining (from a HW DMA perspective at least).
> > > > >
> > > > > > > For HW offload I'd want to avoid notifications for buffer
> > > > > > > transfer from host
> > > > > > to device, and hoped to just poll virtq_avail.idx directly.
> > > > > > >
> > > > > > > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> > > > > > virtq_avail.idx==virtq_avail.ring[idx] as long as there is no
> > > > > > chaining. It would be nice to allow negotiating away chaining,
> > > > > > i.e add a VIRTIO_F_NO_CHAIN. If negotiated, the driver agrees
> > > > > > not to use chaining, and as a result (of IN_ORDER and NO_CHAIN)
> > > > > > both device and driver can ignore the virtq_avail.ring[].
> > > > > >
> > > > > > My point was that device can just assume no chains, and then
> > > > > > fall back on doing extra reads upon encountering a chain.
> > > > > >
> > > > >
> > > > > Yes, you are correct that the HW can speculatively use
> > > > >virtq_avail.idx as the direct index to the descriptor table, and if
> > > > >it encounters a chain, revert to using the virtq_avail.ring[] in
> > > > >the traditional way, and this would work without the feature-bit.
> > > >
> > > > Sorry that was not my idea.
> > > >
> > > > Device should not need to read the ring at all.
> > > > It reads the descriptor table and counts the descriptors without the next
> > bit.
> > > > Once the count reaches the available index, it stops.
> > > >
> > >
> > > Agreed, that would work as well, with the benefit of keeping the ring
> > > out of the loop.
> > >
> > > >
> > > > > However the driver would not be able to optimize away the writing
> > > > > of the virtq_avail.ring[] (=cache miss)
> > > >
> > > >
> > > > BTW writing is a separate question (there is no provision in the
> > > > spec to skip
> > > > writes) but device does not have to read the ring.
> > > >
> > >
> > > Yes, I understand the spec currently does not allow writes to be
> > > skipped, but I'm wondering if that ought to be reconsidered for
> > > optimization features such as IN_ORDER and NO_CHAIN?
> >
> > Why not just use the packed ring then?
> >
>
> Device notification. While the packed ring solves some of the issues in
> the split ring, it also comes at a cost. In my view the two complement
> each other, however the required use of driver to device notifications
> in the packed ring for all driver to device transfers over PCIe (to handle
> the update granularity issue with Qwords as pointed out by Ilya on 14:th
> Jan) will limit performance (latency and throughput) in our experience.
> We want to use device polling.
You can poll the descriptor for sure.
I think you refer to this:
As an example of update ordering, assume that the block of data is in host memory, and a host CPU
writes first to location A and then to a different location B. A Requester reading that data block
with a single read transaction is not guaranteed to observe those updates in order. In other words,
the Requester may observe an updated value in location B and an old value in location A, regardless
of the placement of locations A and B within the data block. Unless a Completer makes its own
guarantees (outside this specification) with respect to update ordering, a Requester that relies on
update ordering must observe the update to location B via one read transaction before initiating a
subsequent read to location A to return its updated value.
One question would be whether placing a memory barrier (such as sfence on x86)
after writing out A will guarantee update ordering.
Do you know anything about it?
> Btw, won't the notification add one extra cache miss for all TX over PCIe
> transport?
It's a posted write, these are typically not cached.
> > > By opting for such features, both driver and device acknowledge their
> > > willingness to accept reduced flexibility for improved performance.
> > > Why not then make sure they get the biggest bang for their buck? I
> > > would expect up to 20% improvement over PCIe (virtio-net, single 64B
> > > packet), if the device does not have to write to virtq_used.ring[] on
> > > transmit, and bandwidth over PCI is a very precious resource in e.g.
> > > virtual switch offload with east-west acceleration (for a discussion
> > > see Intel's white- paper 335625-001).
> >
> > Haven't looked at it yet but we also need to consider the complexity, see
> > below.
> >
> > > > Without device accesses ring will not be invaliated in cache so no
> > > > misses hopefully.
> > > >
> > > > > unless a NO_CHAIN feature has
> > > > > been negotiated.
> > > > > The IN_ORDER by itself has already eliminated the need to maintain
> > > > > the TX virtq_used.ring[], since the buffer order is always known
> > > > > by the driver.
> > > > > With a NO_CHAIN feature-bit both RX and TX virtq_avail.ring[]
> > > > > related cache-misses could be eliminated. I.e.
> > > > > looping a packet over a split virtqueue would just experience 7
> > > > > driver cache misses, down from 10 in Virtio v1.0. Multi-element
> > > > > buffers would still be possible provided INDIRECT is negotiated.
> > > >
> > > >
> > > > NO_CHAIN might be a valid optimization, it is just unfortunately
> > > > somewhat narrow in that devices that need to mix write and read
> > > > descriptors in the same ring (e.g. storage) can not use this feature.
> > > >
> > >
> > > Yes, if there was a way of making indirect buffers support it, that
> > > would be ideal. However I don't see how that can be done without
> > > inline headers in elements to hold their written length.
> >
> > Kind of like it's done with with packed ring?
> >
> > > At the same time storage would not be hurt by it even if they are
> > > unable to benefit from this particular optimization,
> >
> > It will be hurt if it uses shared code paths which potentially take up more
> > cache, or if bugs are introduced.
> >
> > > and as long as there is a substantial
> > > use case/space that benefit from an optimization, it ought to be
> > considered.
> > > I believe virtual switching offload with virtio-net devices over PCIe
> > > is such a key use-case.
> >
> > It looks like the packed ring addresses the need nicely, while being device-
> > independent.
> >
> >
> > > >
> > > > > >
> > > > > >
> > > > > > > >
> > > > > > > > > ----------------------------------------------------------
> > > > > > > > > ----
> > > > > > > > > ----
> > > > > > > > > --- 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
> > > > > Disclaimer: This email and any files transmitted with it may
> > > > > contain
> > > > confidential information intended for the addressee(s) only. The
> > > > information is not to be surrendered or copied to unauthorized
> > > > persons. If you have received this communication in error, please
> > > > notify the sender immediately and delete this e-mail from your system.
> > > >
> > > > --------------------------------------------------------------------
> > > > - To unsubscribe, e-mail:
> > > > virtio-dev-unsubscribe@lists.oasis-open.org
> > > > For additional commands, e-mail:
> > > > virtio-dev-help@lists.oasis-open.org
> > >
> > > Disclaimer: This email and any files transmitted with it may contain
> > confidential information intended for the addressee(s) only. The information
> > is not to be surrendered or copied to unauthorized persons. If you have
> > received this communication in error, please notify the sender immediately
> > and delete this e-mail from your system.
> Disclaimer: This email and any files transmitted with it may contain confidential information intended for the addressee(s) only. The information is not to be surrendered or copied to unauthorized persons. If you have received this communication in error, please notify the sender immediately and delete this e-mail from your system.
---------------------------------------------------------------------
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
^ permalink raw reply [flat|nested] 25+ messages in thread* RE: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
2018-04-04 16:07 ` [virtio] " Michael S. Tsirkin
@ 2018-04-05 7:18 ` Lars Ganrot
0 siblings, 0 replies; 25+ messages in thread
From: Lars Ganrot @ 2018-04-05 7:18 UTC (permalink / raw)
To: Michael S. Tsirkin; +Cc: virtio, virtio-dev
> From: Michael S. Tsirkin <mst@redhat.com>
> Sent: 4. april 2018 18:08
> To: Lars Ganrot <lga@napatech.com>
> Cc: virtio@lists.oasis-open.org; virtio-dev@lists.oasis-open.org
> Subject: Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order feature
>
> On Wed, Apr 04, 2018 at 03:03:16PM +0000, Lars Ganrot wrote:
> > > From: Michael S. Tsirkin <mst@redhat.com>
> > > Sent: 3. april 2018 13:48
> > > To: Lars Ganrot <lga@napatech.com>
> > > Cc: virtio@lists.oasis-open.org; virtio-dev@lists.oasis-open.org
> > > Subject: Re: [virtio-dev] [PATCH v10 13/13] split-ring: in order
> > > feature
> > >
> > > On Tue, Apr 03, 2018 at 07:19:47AM +0000, Lars Ganrot wrote:
> > > > > From: virtio-dev@lists.oasis-open.org
> > > > > <virtio-dev@lists.oasis-open.org> On Behalf Of Michael S.
> > > > > Tsirkin
> > > > > Sent: 29. marts 2018 21:13
> > > > >
> > > > > On Thu, Mar 29, 2018 at 06:23:28PM +0000, Lars Ganrot wrote:
> > > > > >
> > > > > >
> > > > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > > > Sent: 29. marts 2018 16:42
> > > > > > >
> > > > > > > On Wed, Mar 28, 2018 at 04:12:10PM +0000, Lars Ganrot wrote:
> > > > > > > > Missed replying to the lists. Sorry.
> > > > > > > >
> > > > > > > > > From: Michael S. Tsirkin <mst@redhat.com>
> > > > > > > > > Sent: 28. marts 2018 16:39
> > > > > > > > >
> > > > > > > > > On Wed, Mar 28, 2018 at 08:23:38AM +0000, Lars Ganrot
> wrote:
> > > > > > > > > > Hi Michael et al
> > > > > > > > > >
> > > > > > > > > > > Behalf Of Michael S. Tsirkin
> > > > > > > > > > > Sent: 9. marts 2018 22:24
> > > > > > > > > > >
> > > > > > > > > > > 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>
> > > > > > > > > > > ---
> > > > > > > > > > [snip]
> > > > > > > > > > >
> > > > > > > > > > > +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.
> > > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > The use of VIRTIO_F_IN_ORDER for split-ring can
> > > > > > > > > > eliminate some accesses
> > > > > > > > > to the virtq_avail.ring and virtq_used.ring. However I'm
> > > > > > > > > wondering if the proposed descriptor ordering for
> > > > > > > > > multi-element buffers couldn't be tweaked to be more HW
> > > > > > > > > friendly. Currently even with the VIRTIO_F_IN_ORDER
> > > > > > > > > negotiated, there is no way of knowing if, or how many
> > > > > > > > > chained descriptors follow the descriptor pointed to by
> > > > > > > > > the virtq_avail.idx. A chain has to be inspected one
> > > > > > > > > descriptor at a time until
> > > > > > > > > virtq_desc.flags[VIRTQ_DESC_F_NEXT]=0. This is awkward
> > > > > > > > > for HW offload, where you want to DMA all available
> > > > > > > > > descriptors in one shot, instead of iterating based on
> > > > > > > > > the contents of received DMA data. As currently defined,
> > > > > > > > > HW would have to find a compromise
> > > > > between likely chain length, and cost of additional DMA transfers.
> > > > > > > > > This leads to a performance penalty for all chained
> > > > > > > > > descriptors, and in case the length assumption is wrong
> > > > > > > > > the impact can be
> > > > > significant.
> > > > > > > > > >
> > > > > > > > > > Now, what if the VIRTIO_F_IN_ORDER instead required
> > > > > > > > > > chained buffers to
> > > > > > > > > place the last element at the lowest index, and the
> > > > > > > > > head-element (to which virtq_avail.idx points) at the
> > > > > > > > > highest index? Then all the chained element descriptors
> > > > > > > > > would be included in a DMA of the descriptor table from
> > > > > > > > > the previous virtq_avail.idx+1 to the current
> > > > > > > virtq_avail.idx. The "backward"
> > > > > > > > > order of the chained descriptors shouldn't pose an issue
> > > > > > > > > as such (at least not in HW).
> > > > > > > > > >
> > > > > > > > > > Best Regards,
> > > > > > > > > >
> > > > > > > > > > -Lars
> > > > > > > > >
> > > > > > > > > virtq_avail.idx is still an index into the available ring.
> > > > > > > > >
> > > > > > > > > I don't really see how you can use virtq_avail.idx to
> > > > > > > > > guess the placement of a descriptor.
> > > > > > > > >
> > > > > > > > > I suspect the best way to optimize this is to include
> > > > > > > > > the relevant data with the VIRTIO_F_NOTIFICATION_DATA
> feature.
> > > > > > > > >
> > > > > > > >
> > > > > > > > Argh, naturally.
> > > > > > >
> > > > > > > BTW, for split rings VIRTIO_F_NOTIFICATION_DATA just copies
> > > > > > > the index right now.
> > > > > > >
> > > > > > > Do you have an opinion on whether we should change that for
> > > > > > > in-
> > > order?
> > > > > > >
> > > > > >
> > > > > > Maybe I should think more about this, however adding the last
> > > > > > element
> > > > > descriptor index, would be useful to accelerate interfaces that
> > > > > frequently use chaining (from a HW DMA perspective at least).
> > > > > >
> > > > > > > > For HW offload I'd want to avoid notifications for buffer
> > > > > > > > transfer from host
> > > > > > > to device, and hoped to just poll virtq_avail.idx directly.
> > > > > > > >
> > > > > > > > A split virtqueue with VITRIO_F_IN_ORDER will maintain
> > > > > > > virtq_avail.idx==virtq_avail.ring[idx] as long as there is
> > > > > > > no chaining. It would be nice to allow negotiating away
> > > > > > > chaining, i.e add a VIRTIO_F_NO_CHAIN. If negotiated, the
> > > > > > > driver agrees not to use chaining, and as a result (of
> > > > > > > IN_ORDER and NO_CHAIN) both device and driver can ignore the
> virtq_avail.ring[].
> > > > > > >
> > > > > > > My point was that device can just assume no chains, and then
> > > > > > > fall back on doing extra reads upon encountering a chain.
> > > > > > >
> > > > > >
> > > > > > Yes, you are correct that the HW can speculatively use
> > > > > >virtq_avail.idx as the direct index to the descriptor table,
> > > > > >and if it encounters a chain, revert to using the
> > > > > >virtq_avail.ring[] in the traditional way, and this would work without
> the feature-bit.
> > > > >
> > > > > Sorry that was not my idea.
> > > > >
> > > > > Device should not need to read the ring at all.
> > > > > It reads the descriptor table and counts the descriptors without
> > > > > the next
> > > bit.
> > > > > Once the count reaches the available index, it stops.
> > > > >
> > > >
> > > > Agreed, that would work as well, with the benefit of keeping the
> > > > ring out of the loop.
> > > >
> > > > >
> > > > > > However the driver would not be able to optimize away the
> > > > > > writing of the virtq_avail.ring[] (=cache miss)
> > > > >
> > > > >
> > > > > BTW writing is a separate question (there is no provision in the
> > > > > spec to skip
> > > > > writes) but device does not have to read the ring.
> > > > >
> > > >
> > > > Yes, I understand the spec currently does not allow writes to be
> > > > skipped, but I'm wondering if that ought to be reconsidered for
> > > > optimization features such as IN_ORDER and NO_CHAIN?
> > >
> > > Why not just use the packed ring then?
> > >
> >
> > Device notification. While the packed ring solves some of the issues
> > in the split ring, it also comes at a cost. In my view the two
> > complement each other, however the required use of driver to device
> > notifications in the packed ring for all driver to device transfers
> > over PCIe (to handle the update granularity issue with Qwords as
> > pointed out by Ilya on 14:th
> > Jan) will limit performance (latency and throughput) in our experience.
> > We want to use device polling.
>
> You can poll the descriptor for sure.
>
> I think you refer to this:
>
Not quite, on Jan 14 2018 Ilya Lesokhin in his mail: " [virtio-dev] PCIe ordering
and new VIRTIO packed ring format", highlighted the subsequent section
regarding observed read granularity in the PCIe rev 2.0 (paragraph 2.4.2):
## As an example of update granularity, if a host CPU writes a QWORD to host
## memory, a Requester reading that QWORD from host memory may observe
## a portion of the QWORD updated and another portion of it containing
## the old value"
To which you on Jan 16 2018 responded:
## This is a very good point. This consideration is one of the reasons I included
## last valid descriptor in the driver notification. My guess would be that such
## hardware should never use driver event suppression. As a result, driver will
## always send notifications after each batch of descriptors. Device can use
## that to figure out which descriptors to fetch. Luckily, with pass-through
## device memory can be mapped directly into the VM, so no the notification
## will not trigger a VM exit. It would be interesting to find out whether specific
## host systems give a stronger guarantee than what is required by the PCIE
## spec. If so we could add e.g. a feature bit to let the device know it's safe to
## read beyond the index supplied in the kick notification. Drivers would detect
## this and use it to reduce the overhead."
As I understand it, the notification is required for safe operation, unless the
host can be determined (how?) to uphold a stronger guarantee for update
granularity than the PCIe specification requires.
> As an example of update ordering, assume that the block of data is in host
> memory, and a host CPU writes first to location A and then to a different
> location B. A Requester reading that data block with a single read transaction
> is not guaranteed to observe those updates in order. In other words, the
> Requester may observe an updated value in location B and an old value in
> location A, regardless of the placement of locations A and B within the data
> block. Unless a Completer makes its own guarantees (outside this
> specification) with respect to update ordering, a Requester that relies on
> update ordering must observe the update to location B via one read
> transaction before initiating a subsequent read to location A to return its
> updated value.
>
> One question would be whether placing a memory barrier (such as sfence on
> x86) after writing out A will guarantee update ordering.
>
> Do you know anything about it?
>
My knowledge of PCIe is not deep enough, but the PCIe update granularity
should not be affected by barriers, since it relates to a single write.
>
>
> > Btw, won't the notification add one extra cache miss for all TX over
> > PCIe transport?
>
> It's a posted write, these are typically not cached.
>
> > > > By opting for such features, both driver and device acknowledge
> > > > their willingness to accept reduced flexibility for improved
> performance.
> > > > Why not then make sure they get the biggest bang for their buck? I
> > > > would expect up to 20% improvement over PCIe (virtio-net, single
> > > > 64B packet), if the device does not have to write to
> > > > virtq_used.ring[] on transmit, and bandwidth over PCI is a very precious
> resource in e.g.
> > > > virtual switch offload with east-west acceleration (for a
> > > > discussion see Intel's white- paper 335625-001).
> > >
> > > Haven't looked at it yet but we also need to consider the
> > > complexity, see below.
> > >
> > > > > Without device accesses ring will not be invaliated in cache so
> > > > > no misses hopefully.
> > > > >
> > > > > > unless a NO_CHAIN feature has
> > > > > > been negotiated.
> > > > > > The IN_ORDER by itself has already eliminated the need to
> > > > > > maintain the TX virtq_used.ring[], since the buffer order is
> > > > > > always known by the driver.
> > > > > > With a NO_CHAIN feature-bit both RX and TX virtq_avail.ring[]
> > > > > > related cache-misses could be eliminated. I.e.
> > > > > > looping a packet over a split virtqueue would just experience
> > > > > > 7 driver cache misses, down from 10 in Virtio v1.0.
> > > > > > Multi-element buffers would still be possible provided INDIRECT is
> negotiated.
> > > > >
> > > > >
> > > > > NO_CHAIN might be a valid optimization, it is just unfortunately
> > > > > somewhat narrow in that devices that need to mix write and read
> > > > > descriptors in the same ring (e.g. storage) can not use this feature.
> > > > >
> > > >
> > > > Yes, if there was a way of making indirect buffers support it,
> > > > that would be ideal. However I don't see how that can be done
> > > > without inline headers in elements to hold their written length.
> > >
> > > Kind of like it's done with with packed ring?
> > >
> > > > At the same time storage would not be hurt by it even if they are
> > > > unable to benefit from this particular optimization,
> > >
> > > It will be hurt if it uses shared code paths which potentially take
> > > up more cache, or if bugs are introduced.
> > >
> > > > and as long as there is a substantial use case/space that benefit
> > > > from an optimization, it ought to be
> > > considered.
> > > > I believe virtual switching offload with virtio-net devices over
> > > > PCIe is such a key use-case.
> > >
> > > It looks like the packed ring addresses the need nicely, while being
> > > device- independent.
> > >
> > >
> > > > >
> > > > > > >
> > > > > > >
> > > > > > > > >
> > > > > > > > > > ------------------------------------------------------
> > > > > > > > > > ----
> > > > > > > > > > ----
> > > > > > > > > > ----
> > > > > > > > > > --- 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
> > > > > > Disclaimer: This email and any files transmitted with it may
> > > > > > contain
> > > > > confidential information intended for the addressee(s) only. The
> > > > > information is not to be surrendered or copied to unauthorized
> > > > > persons. If you have received this communication in error,
> > > > > please notify the sender immediately and delete this e-mail from
> your system.
> > > > >
> > > > > ----------------------------------------------------------------
> > > > > ----
> > > > > - To unsubscribe, e-mail:
> > > > > virtio-dev-unsubscribe@lists.oasis-open.org
> > > > > For additional commands, e-mail:
> > > > > virtio-dev-help@lists.oasis-open.org
> > > >
> > > > Disclaimer: This email and any files transmitted with it may
> > > > contain
> > > confidential information intended for the addressee(s) only. The
> > > information is not to be surrendered or copied to unauthorized
> > > persons. If you have received this communication in error, please
> > > notify the sender immediately and delete this e-mail from your system.
> > Disclaimer: This email and any files transmitted with it may contain
> confidential information intended for the addressee(s) only. The information
> is not to be surrendered or copied to unauthorized persons. If you have
> received this communication in error, please notify the sender immediately
> and delete this e-mail from your system.
---------------------------------------------------------------------
To unsubscribe, e-mail: virtio-dev-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: virtio-dev-help@lists.oasis-open.org
^ permalink raw reply [flat|nested] 25+ messages in thread