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

 


Help: OASIS Mailing Lists Help | MarkMail Help

virtio-dev message

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


Subject: [PATCH v2] 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

A related issue is that while spec requires that
device is not used before DRIVER_OK, drivers
need to add buffers to device before DRIVER_OK in practice.
So add a new DEVICE_OK bit, and split the meaning
of the old one up:
	- driver ready to add buffers -> set driver ok
	- dev ready to consume buffers -> set device ok

Lastly, it wasn't made clear when can driver change feature bits.
Document this clearly.

This resolves issue VIRTIO-30.

Changes from v1:
	- add new DEVICE_OK state
	- document device requirements before handshake complete
	  (don't consume buffers or send interrupts)
	- note that all legacy drivers use devices before
	  driver_ok
	- legacy drivers actually do set driver and
	  driver_ok eventually, just in a wrong order. note this.
	- document that driver_ok/device_ok is feature lock point

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

diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index b4298bb..427f21e 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -109,6 +109,9 @@ This field is 0 upon reset, otherwise at least one bit should be set:
   DRIVER_OK (4) Indicates that the driver is set up and ready to
   drive the device.
 
+  DEVICE_OK (8) Indicates that the device is set up and ready to
+  consume buffers.
+
   FAILED (128) Indicates that something went wrong in the guest,
   and it has given up on the device. This could be an internal
   error, or the driver didn't like the device for some reason, or
@@ -438,6 +441,67 @@ how to communicate with the specific device.
 2.2.1. Device Initialization
 ---------------------------
 
+1. Device discovery. This is only required for some transports.
+
+2. Reset the device. This is not required on initial start up.
+
+3. The ACKNOWLEDGE status bit is set: we have noticed the device.
+
+4. Host Features bit flags representing the supported
+   device features are read.
+
+5. Guest Features bit flags representing the subset of device features
+   understood by the driver are written to the device.
+
+6. The DRIVER status bit is set: we know how to drive the device.
+
+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. 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.
+
+10. 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.
+
+11. The DRIVER_OK status bit is set. Driver must not set or
+    clear feature bit flags after this point.
+
+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). Device should not consume buffers,
+    and should not send notifications (interrupts).
+    If device is notified of new buffers, it should
+    defer this notification until DEVICE_OK is set later.
+
+15. The DEVICE_OK status bit is set.
+
+16. The device can now consume buffers, and send notifications
+    (interrupts) to the driver.
+
+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
+--------------------------------------
+When used through the legacy interface, transitional
+devices are initialized as follows:
+
 1. Reset the device. This is not required on initial start up.
 
 2. The ACKNOWLEDGE status bit is set: we have noticed the device.
@@ -445,21 +509,54 @@ how to communicate with the specific device.
 3. The DRIVER status bit is set: we know how to drive 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.
+   bits, discovery of virtqueues for the device, optional per-bus
+   setup, and reading and possibly writing the device's virtio
+   configuration space.
 
 5. The subset of device feature bits understood by the driver is
    written to the device.
 
-6. The DRIVER_OK status bit is set.
+6. The device can now be used (ie. buffers added to the
+   virtqueues). Device should not consume buffers,
+   and should not send notifications (interrupts).
+   If device is notified of new buffers, it should
+   defer this notification until DRIVER_OK is set later.
 
-7. The device can now be used (ie. buffers added to the
-   virtqueues)[4]
+7. The DRIVER_OK status bit is set.  Driver must not set or
+   clear feature bit flags after this point.
 
-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).
+8. The device can now consume buffers, and send notifications
+   (interrupts) to the driver.
+
+Historically, legacy drivers never set the DEVICE_OK status bit,
+instead, they used the DRIVER_OK bit to indicate
+the device was thus used before writing the DRIVER_OK status bit.
+
+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.
+Devices should not consume buffers, and should not send
+notifications (interrupts) until DRIVER_OK status bit is set.
+
+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
 ----------------------
@@ -2863,9 +2960,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] ie. once you enable MSI-X on the device, the other fields move.
 If you turn it off again, they move back!
-- 
MST


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