2.1.4.2 Message Framing: Document header framing requirement.

Ported from draft, commits 7e74459bb966ccbaad9e4bf361d1178b7f400b79,
8e47520c64c87473f910b55817ba95b0e4113c13 and part of
835628846cc04efe660e505552d06eb945277d3b.

Signed-off-by: Rusty Russell <rusty@au1.ibm.com>

git-svn-id: https://tools.oasis-open.org/version-control/svn/virtio@12 0c8fb4dd-22a2-4bb5-bc14-6c75a5f43652

1 files changed, 31 insertions, 15 deletions

diff --git a/virtio-spec.txt b/virtio-spec.txt
index bd51afc..f7c80ec 100644
--- a/virtio-spec.txt
+++ b/virtio-spec.txt
@@ -217,17 +217,25 @@ is not a significant issue.
 
 2.1.4.2 Message Framing
 -----------------------
-
-The descriptors used for a buffer should not effect the semantics 
-of the message, except for the total length of the buffer. For 
-example, a network buffer consists of a 10 byte header followed 
-by the network packet. Whether this is presented in the ring 
-descriptor chain as (say) a 10 byte buffer and a 1514 byte 
-buffer, or a single 1524 byte buffer, or even three buffers, 
-should have no effect.
-
-In particular, no implementation should use the descriptor 
-boundaries to determine the size of any header in a request.[10]
+The original intent of the specification was that message framing (the
+particular layout of descriptors) be 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).
+
+Regrettably, initial driver implementations used simple layouts, and
+devices came to rely on it, despite this specification wording[10]. It
+is thus recommended that drivers be conservative in their assumptions,
+unless the VIRTIO_F_ANY_LAYOUT feature is accepted. In addition, some
+implementations may 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!
 
 2.1.4.3 The Virtqueue Descriptor Table
 --------------------------------------
@@ -2462,7 +2470,7 @@ contents of the event field. The following events are defined:
 2.6 Reserved Feature Bits
 =========================
 
-Currently there are three device-independent feature bits defined:
+Currently there are four device-independent feature bits defined:
 
   VIRTIO_F_NOTIFY_ON_EMPTY (24) Negotiating this feature 
   indicates that the driver wants an interrupt if the device runs 
@@ -2475,6 +2483,9 @@ Currently there are three device-independent feature bits defined:
   using a timer if the device interrupts it when all the packets 
   are transmitted.
 
+  VIRTIO_F_ANY_LAYOUT (27) This feature indicates that the device accepts arbitrary
+  descriptor layouts, as described in Section FIXME.
+
   VIRTIO_F_RING_INDIRECT_DESC (28) Negotiating this feature indicates
   that the driver can use descriptors with the VRING_DESC_F_INDIRECT
   flag set, as described in 2.3.3 Indirect Descriptors.
@@ -2552,6 +2563,9 @@ Currently there are three device-independent feature bits defined:
 /* Support for avail_idx and used_idx fields */
 #define VIRTIO_RING_F_EVENT_IDX        29
 
+/* Arbitrary descriptor layouts. */
+#define VIRTIO_F_ANY_LAYOUT            27
+
 /* Virtio ring descriptors: 16 bytes.
  * These can chain together via "next". */
 struct vring_desc {
@@ -2762,9 +2776,11 @@ of this expected condition is necessary.
 
 [9] https://lists.linux-foundation.org/mailman/listinfo/virtualization
 
-[10] The current qemu device implementations mistakenly insist that 
-the first descriptor cover the header in these cases exactly, so 
-a cautious driver should arrange it so.
+[10] It was previously asserted that framing should be independent of message
+contents, yet invariably drivers layed out messages in reliable ways and
+devices assumed it.
+In addition, the specifications for virtio_blk and virtio_scsi require
+intuiting field lengths from frame boundaries.
 
 [11] Even if it does mean documenting design or implementation 
 mistakes!