OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

virtio message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: [PATCH] initialization: add extra device status handshake


In the past we sometimes wanted an ability to make driver
gracefully fail early in initialization if it does not
recognize/support a feature.  One such example we are introducing
right now is the new VERSION_1 feature.

Another example where the driver configuration
is inconsistent with what the device can support.

This modifies the initialization to allow
graceful failure in such cases:
1. require a driver to first ack all features it recognizes
(linux does this already)
2. require driver to set status after configuration
and re-check status afterwards

This resolves issue VIRTIO-30.

Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
---
 virtio-v1.0-wd01-part1-specification.txt | 82 ++++++++++++++++++++++++++------
 1 file changed, 67 insertions(+), 15 deletions(-)

diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index 9b855a2..f51cb8c 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -486,29 +486,82 @@ how to communicate with the specific device.
 2.2.1. Device Initialization
 ---------------------------
 
-1. Reset the device. This is not required on initial start up.
+1. Device discovery. This is only required for some transports.
 
-2. The ACKNOWLEDGE status bit is set: we have noticed the device.
+2. Reset the device. This is not required on initial start up.
 
-3. The DRIVER status bit is set: we know how to drive the device.
+3. The ACKNOWLEDGE status bit is set: we have noticed the device.
 
-4. Device-specific setup, including reading the device feature
-  bits, discovery of virtqueues for the device, optional per-bus
-  setup, and reading and possibly writing the device's virtio
-  configuration space.
+4. Host Features bit flags representing the supported
+   device features are read.
 
-5. The subset of device feature bits understood by the driver is
-   written to the device.
+5. Guest Features bit flags representing the subset of device features
+   understood by the driver are written to the device.
 
-6. The DRIVER_OK status bit is set.
+6. The DRIVER status bit is set: we know how to drive the device.
 
-7. The device can now be used (ie. buffers added to the
-   virtqueues)[4]
+7. At this stage device can verify that driver understands
+   sufficient features to operate the device.
+   On failure, device clears the DRIVER status bit[4].
+
+8. The Device Status is read back: driver verifies
+   that the device did not clear the DRIVER status bit.
+
+9. Device-specific setup, including discovery of virtqueues for
+   the device, optional per-bus setup, and reading and possibly
+   writing the device's virtio configuration space.
+
+10. A subset of device feature bit flags representing the subset
+    of device features activated by the driver is
+    written to the device. This is only required if driver does
+    not wish to activate some of the features that it understands.
+
+11. The DRIVER_OK status bit is set.
+
+12. At this stage the device can verify that features and
+    the Device-specific setup configured are consistent
+    and can be supported by the device.
+    On failure, device clears the DRIVER_OK status bit[4].
+
+13. The Device Status is read back: the driver verifies
+    that the device did not clear the DRIVER_OK status bit.
+
+14. The device can now be used (ie. buffers added to the
+    virtqueues)
 
 If any of these steps go irrecoverably wrong, the guest should
 set the FAILED status bit to indicate that it has given up on the
 device (it can reset the device later to restart if desired).
 
+2.2.1.1 Legacy Interface: A Note on Device Initialization
+--------------------------------------
+Historically, legacy drivers have used the device before
+writing the DRIVER or DRIVER_OK status bits.
+
+When using a legacy interface, transitional devices
+should allow this use, assuming that the legacy driver does not
+use any features which would alter this early use of the device.
+
+Legacy drivers do not write supported features
+to the device before setting the DRIVER status bit,
+so there is no way for a device to detect whether
+the legacy driver supports all features required to operate the
+device.
+
+When using a legacy interface, transitional devices
+should allow this use, assuming that the legacy driver
+supports all features required to operate the device.
+
+Legacy drivers do not read back Device Status register
+so there is no way for a device to indicate
+that the legacy driver failed to activate sufficient features to
+operate the device.
+
+When using a legacy interface, and when configured with a legacy
+driver not activating a feature that is required to operate
+the device, transitional devices should support this
+configuration on a best effort basis.
+
 2.2.2. Device Operation
 ----------------------
 
@@ -3211,9 +3264,8 @@ the non-PCI implementations (currently lguest and S/390).
 
 [3] The actual value within this range is ignored
 
-[4] Historically, drivers have used the device before steps 5 and 6.
-This is only allowed if the driver does not use any features
-which would alter this early use of the device.
+[4] For example, a non-transitional device would detect such a
+failure if the bit VIRTIO_F_VERSION_1 is not set by the driver.
 
 [5] When MSI-X capability is enabled, device specific configuration starts at
 byte offset 24 in virtio header structure. When MSI-X capability is not
-- 
MST


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]