Re: [virtio] [OASIS Issue Tracker] Created: (VIRTIO-10) Allow arbitrary descriptor layouts / message framing.

[Rusty Russell <rusty@au1.ibm.com>]

OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org> writes:

> Allow arbitrary descriptor layouts / message framing.
> -----------------------------------------------------
>
>                  Key: VIRTIO-10
>                  URL: http://tools.oasis-open.org/issues/browse/VIRTIO-10
>              Project: OASIS Virtual I/O Device (VIRTIO) TC
>           Issue Type: Improvement
>             Reporter: Rusty Russell
>
>
> This will require a change in virtio_blk's SCSI commands, which requires framing cues.

This it it on top of virtio-18 (which removes the virtio_blk SCSI
commands):

commit 2ff25da0aa8adf6235cc8267c4fe331b541edaaa
Author: Rusty Russell <rusty@au1.ibm.com>
Date:   Mon Sep 9 17:40:32 2013 +0930

    Any layout is allowed (deprecate VIRTIO_F_ANY_LAYOUT)
    
    As per issue virtio-10.
    
    Signed-off-by: Rusty Russell <rusty@au1.ibm.com>

diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index f1988c9..6f7d4d5 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -268,25 +268,33 @@ is not a significant issue.
 
 2.1.4.2. Message Framing
 -----------------------
-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).
+The message framing (the particular layout of 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 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.2.1. Legacy Interface: Message Framing
+-----------------------
 
 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!
+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 "2.4.2.5.1 Legacy
+Interface: Device Operation")
+
+It is thus recommended that drivers be conservative in their
+assumptions, unless the VIRTIO_F_ANY_LAYOUT feature is accepted.
 
 2.1.4.3. The Virtqueue Descriptor Table
 --------------------------------------
@@ -2576,10 +2584,7 @@ contents of the event field. The following events are defined:
 2.5. Reserved Feature Bits
 =========================
 
-Currently there are four device-independent feature bits defined:
-
-  VIRTIO_F_ANY_LAYOUT (27) This feature indicates that the device accepts arbitrary
-  descriptor layouts, as described in Section "2.1.4.2. Message Framing".
+Currently there are three device-independent feature bits defined:
 
   VIRTIO_F_RING_INDIRECT_DESC (28) Negotiating this feature indicates
   that the driver can use descriptors with the VRING_DESC_F_INDIRECT
@@ -2620,6 +2625,10 @@ VIRTIO_F_NOTIFY_ON_EMPTY (24) Negotiating this feature
   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
+  "2.1.4.2.1. Legacy Interface: Message Framing".
+
 2.6. virtio_ring.h
 =================
 
@@ -2894,12 +2903,6 @@ of this expected condition is necessary.
 
 [9] https://lists.linux-foundation.org/mailman/listinfo/virtualization
 
-[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!