Patchwork virtio-spec: document indirect descriptors

login
register
mail settings
Submitter Michael S. Tsirkin
Date Feb. 10, 2010, 1 p.m.
Message ID <20100210130026.GA19271@redhat.com>
Download mbox | patch
Permalink /patch/45031/
State New
Headers show

Comments

Michael S. Tsirkin - Feb. 10, 2010, 1 p.m.
Add documentation for indirect descriptors

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 virtio-spec.lyx |  118 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 114 insertions(+), 4 deletions(-)
Rusty Russell - Feb. 10, 2010, 11:24 p.m.
On Wed, 10 Feb 2010 11:30:39 pm Michael S. Tsirkin wrote:
> Add documentation for indirect descriptors

Thanks, that's awesome!

I added an entry to the Reserved Feature table in appendix B, and applied
it.  We're now at 0.8.5.

Cheers,
Rusty.

Patch

diff --git a/virtio-spec.lyx b/virtio-spec.lyx
index 8062e11..b5a8fbd 100644
--- a/virtio-spec.lyx
+++ b/virtio-spec.lyx
@@ -1,4 +1,4 @@ 
-#LyX 1.6.4 created this file. For more info see http://www.lyx.org/
+#LyX 1.6.5 created this file. For more info see http://www.lyx.org/
 \lyxformat 345
 \begin_document
 \begin_header
@@ -36,8 +36,7 @@ 
 \paperpagestyle default
 \tracking_changes true
 \output_changes true
-\author "" 
-\author "" 
+\author "Michael S. Tsirkin" 
 \author "" 
 \end_header
 
@@ -1441,7 +1440,28 @@  struct vring_desc {
 
 \begin_layout Plain Layout
 
-#define VRING_DESC_F_WRITE     2 
+#define VRING_DESC_F_WRITE     2
+\change_deleted 0 1265802057
+ 
+\change_inserted 0 1265802048
+
+\end_layout
+
+\begin_layout Plain Layout
+
+\change_inserted 0 1265802054
+
+/* This means the buffer contains a list of buffer descriptors.
+ */
+\end_layout
+
+\begin_layout Plain Layout
+
+\change_inserted 0 1265802049
+
+#define VRING_DESC_F_INDIRECT   4 
+\change_unchanged
+
 \end_layout
 
 \begin_layout Plain Layout
@@ -1478,6 +1498,96 @@  struct vring_desc {
 \begin_layout Standard
 The number of descriptors in the table is specified by the Queue Size field
  for this virtqueue.
+\change_deleted 0 1265801065
+
+\end_layout
+
+\begin_layout Subsubsection
+
+\change_inserted 0 1265801341
+Indirect Descriptors
+\end_layout
+
+\begin_layout Standard
+
+\change_inserted 0 1265805736
+Some devices benefit by concurrently dispatching a large number of large
+ requests.
+ To increase ring capacity it is possible to store a table of 
+\emph on
+indirect descriptors
+\emph default
+ anywhere in memory, and insert a descriptor in main virtqueue (with flags&INDIRECT on) that refers to memory buffer containing this 
+\emph on
+indirect descriptor table
+\emph default
+; fields 
+\emph on
+addr
+\emph default
+ and 
+\emph on
+len
+\emph default
+ refer to the indirect table address and length in bytes, respectively.
+ The indirect table layout structure looks like this (len is the length
+ of the descriptor that refers to this table, which is a variable, so this
+ code won't compile):
+\end_layout
+
+\begin_layout Standard
+
+\change_inserted 0 1265804397
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+\change_inserted 0 1265804526
+
+struct indirect_descriptor_table {
+\end_layout
+
+\begin_layout Plain Layout
+
+\change_inserted 0 1265804397
+
+    /* The actual descriptors (16 bytes each) */
+\end_layout
+
+\begin_layout Plain Layout
+
+\change_inserted 0 1265804473
+
+    struct vring_desc desc[len / 16];
+\end_layout
+
+\begin_layout Plain Layout
+
+\change_inserted 0 1265804397
+
+};
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+
+\change_inserted 0 1265805219
+The first indirect descriptor is located at start of the indirect descriptor
+ table (index 0), additional indirect descriptors are chained by next field.
+ An indirect descriptor without next field (with flags&NEXT off) signals
+ the end of the indirect descriptor table, and transfers control back to
+ the main virtqueue.
+ An indirect descriptor can not refer to another indirect descriptor table
+ (flags&INDIRECT must be off).
+ A single indirect descriptor table can include both read-only and write-only
+ descriptors; write-only flag (flags&WRITE) in the descriptor that refers
+ to it is ignored.
 \end_layout
 
 \begin_layout Subsection