Public review comment for virtio-v1.0-csprd02: 2.1 Device Status Field

[Fam Zheng <famz@redhat.com>]

> 2.1 Device Status Field
> 
> During device initialization by a driver, the driver follows the sequence of
> steps specified in 3.1.
> 
> The device status field provides a simple low-level indication of the
> completed steps of this sequence. It’s most useful to imagine it hooked up to
> traffic lights on the console indicating the status of each device. The
> following bits are defined:
> 
> ACKNOWLEDGE (1)
> Indicates that the guest OS has found the device and recognized it as a valid
> virtio device.
> DRIVER (2)
> Indicates that the guest OS knows how to drive the device. Note: There could
> be a significant (or infinite) delay before setting this bit. For example,
> under Linux, drivers can be loadable modules.
> FEATURES_OK (8)
> Indicates that the driver has acknowledged all the features it understands,
> and feature negotiation is complete.
> DRIVER_OK (4)
> Indicates that the driver is set up and ready to drive the device.
> 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 even a fatal error during device operation.

There is no bit to indicate the status of device. When device detects errors
such as: host resource error, device implementation error, invalid input from
user, invalid command or request from driver, and the error is not recoverable
for the device, we should be able to communicate this. Suggest add:

DEVICE_NEEDS_RESET (16)
Indicate that the device is in an unrecoverable failed state, and need reset.

> 2.1.1 Driver Requirements: Device Status Field
> 
> The driver MUST update device status, setting bits to indicate the completed
> steps of the driver initialization sequence specified in 3.1. The driver MUST
> NOT clear a device status bit. If the driver sets the FAILED bit, the driver
> MUST later reset the device before attempting to re-initialize.

The driver MUST reset the device upon seeing a set DEVICE_NEEDS_RESET before
doing other operations on this device.

> 
> 2.1.2 Device Requirements: Device Status Field
> 
> The device MUST initialize device status to 0 upon reset.
> 
> The device MUST NOT consume buffers or notify the driver before DRIVER_OK.

The device SHOULD set DEVICE_NEEDS_RESET when it enters an error state that a
reset is needed, and MAY send a notification of device configuration changes to
driver.

-- 
Thanks,
Fam