[PATCH v2] virtqueue: flexible layout, size, alignment

["Michael S. Tsirkin" <mst@redhat.com>]

Transports can now lay out available/used/descriptor
regions in a flexible way.
This is useful for embedded systems to save memory,
and for large systems to reduce the need for
physically-contigious memory.

However, this does not add a way to actually program this
in any of the transports, so it's not useful by
itself, separate follow-up patches will add a way to
program this for transports.

This is needed to address
https://tools.oasis-open.org/issues/browse/VIRTIO-23

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---

Changes from v1:
- address comments by Stefan Hajnoczi: clarify Queue Size wording
- address comment by Rusty: split out PCI-specific changes,
  they should be part of the new layout section

 virtio-v1.0-wd01-part1-specification.txt | 54 ++++++++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 3 deletions(-)

diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index d9a6de7..c936d3c 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -223,6 +223,55 @@ transmit and one for receive.  Each queue has a 16-bit queue size
 parameter, which sets the number of entries and implies the total size
 of the queue.
 
+Each virtqueue consists of three parts:
+
+	Descriptor Table
+	Available Ring
+	Used Ring
+
+where each part is physically-contiguous in guest memory,
+and has different alignment requirements.
+
+The memory aligment and size requirements, in bytes, of each part of the
+virtqueue are summarized in the following table:
+
++------------+-----------------------------------------+
+| Virtqueue Part    | Alignment | Size                 |
++------------+-----------------------------------------+
++------------+-----------------------------------------+
+| Descriptor Table  | 16        | 16 * (Queue Size)    |
++------------+-----------------------------------------+
+| Available Ring    | 2         | 6 + 2 * (Queue Size) |
++------------+-----------------------------------------+
+| Used Ring         | 4         | 6 + 4 * (Queue Size) |
++------------+-----------------------------------------+
+
+The Alignment column gives the miminum alignment: for each part
+of the virtqueue, the physical address of the first byte of it
+must be a multiple of the specified alignment value.
+
+The Size column gives the total number of bytes required for each
+part of the virtqueue.
+
+Queue Size corresponds to the maximum number of buffers in the
+virtqueue.  For example, if Queue Size is 4 then at most 4 buffers
+can be queued at any given time.  Queue Size value is always a
+power of 2.  The maximum Queue Size value is 32768.  This value
+is specified in a bus-specific way.
+
+When the driver wants to send a buffer to the device, it fills in
+a slot in the descriptor table (or chains several together), and
+writes the descriptor index into the available ring.  It then
+notifies the device. When the device has finished a buffer, it
+writes the descriptor into the used ring, and sends an interrupt.
+
+
+100.100.4.1. Legacy Interfaces: A Note on Virtqueue Layout
+--------------------------------------
+
+For Legacy Interfaces, several additional
+restrictions are placed on the virtqueue layout:
+
 Each virtqueue occupies two or more physically-contiguous pages
 (usually defined as 4096 bytes, but depending on the transport)
 and consists of three parts:
@@ -241,9 +290,8 @@ required for the virtqueue according to the following formula:
 	          + ALIGN(sizeof(u16)*3 + sizeof(struct vring_used_elem)*qsz);
 	}
 
-This currently wastes some space with padding, but also allows future
-extensions such as the VIRTIO_RING_F_EVENT_IDX extension.  The
-virtqueue layout structure looks like this:
+This wastes some space with padding.
+The legacy virtqueue layout structure therefore looks like this:
 
 	struct vring {
 		// The actual descriptors (16 bytes each)
-- 
MST