Re: [virtio] [OASIS Issue Tracker] Created: (VIRTIO-26) Use feature number 32 to indicate compliance with 1.0 standard

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

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

> Use feature number 32 to indicate compliance with 1.0 standard
> --------------------------------------------------------------
>
>                  Key: VIRTIO-26
>                  URL: http://tools.oasis-open.org/issues/browse/VIRTIO-26
>              Project: OASIS Virtual I/O Device (VIRTIO) TC
>           Issue Type: Bug
>             Reporter: Rusty Russell
>             Assignee: Rusty Russell
>
>
> Virtio PCI will probably have a different layout to indicate v1.0 compliance, but other transports might not.  Stealing an idea from MST, let's separate it into its own suggestion.

This is what I ended up with.  A bit of wording tweak, and I gave it a
name:

commit 0362577143d2037e7a943a28701bad6e6896e03a
Author: Rusty Russell <rusty@au1.ibm.com>
Date:   Mon Sep 9 16:40:53 2013 +0930

    VIRTIO_F_VERSION_1: indentifying legacy devices.
    
    Most of this text is taken directly from Michael Tsirkin's proposal,
    separated from the PCI-specific parts, and given an explicit feature name.
    
    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 0531125..9b0bbca 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -135,9 +135,11 @@ Feature bits are allocated as follows:
 
   0 to 23: Feature bits for the specific device type
 
-  24 to 31: Feature bits reserved for extensions to the queue and
+  24 to 32: Feature bits reserved for extensions to the queue and
   feature negotiation mechanisms
 
+  33 and above: Feature bits resered for future extensions.
+
 For example, feature bit 0 for a network device (i.e. Subsystem
 Device ID 1) indicates that the device supports checksumming of
 packets.
@@ -146,6 +148,54 @@ In particular, new fields in the device configuration space are
 indicated by offering a feature bit, so the guest can check
 before accessing that part of the configuration space.
 
+2.1.2.1 Legacy Interface: A Note on transitions from earlier drafts
+--------------------------------------
+
+Earlier drafts of this specification (up to 0.9.X) defined a similar, but
+different interface between the hypervisor and the guest.
+Since these are widely deployed, this specification
+accomodates optional features to simplify transition
+from these earlier draft interfaces. Specifically:
+
+Legacy Interface
+	is an interface specified by an earlier draft of this specification
+        (up to 0.9.X)
+Legacy Device
+	is a device implemented before this specification was released,
+        and implementing a legacy interface on the host side
+Legacy Driver
+	is a driver implemented before this specification was released,
+        and implementing a legacy interface on the guest side
+
+Legacy devices and legacy drivers are not compliant with this
+specification.
+
+To simplify transition from these earlier draft interfaces,
+it is possible to implement:
+
+Transitional Device
+	a device supporting both drivers conforming to this
+        specification, and allowing legacy drivers.
+
+Transitional Driver
+	a driver supporting both devices conforming to this
+	specification, and legacy devices.
+
+Transitional devices and transitional drivers can be compliant with
+this specification (ie. when not operating in legacy mode).
+
+Devices or drivers with no legacy compatibility are referred to as
+non-transitional devices and drivers, respectively.
+
+Transitional Drivers can detect Legacy Devices by detecting that
+the feature bit VIRTIO_F_VERSION_1 is not offered.
+Transitional devices can detect Legacy drivers by detecting that
+VIRTIO_F_VERSION_1 has not been acknowledged by the driver.
+
+To make them easier to locate, specification sections documenting
+these transitional features are explicitly marked with 'Legacy
+Interface' in the section title.
+
 2.1.3. Configuration Space
 -------------------------
 
@@ -2518,7 +2568,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:
+Currently there are five 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
@@ -2549,6 +2599,9 @@ Currently there are four device-independent feature bits defined:
   driver should ignore the used_event field; the device should
   ignore the avail_event field; the flags field is used
 
+  VIRTIO_F_VERSION_1(32) This feature must be offered by any device
+  compliant with this specification, and acknowledged by all device
+  drivers.
 
 In addition, bit 30 is used by qemu's implementation to check for experimental
 early versions of virtio which did not perform correct feature negotiation,