[virtio] [OASIS Issue Tracker] (VIRTIO-103) PCI Common configuration layout

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

> ------------------------------------
>
>              Summary: PCI Common configuration layout
>                  Key: VIRTIO-103
>                  URL: https://tools.oasis-open.org/issues/browse/VIRTIO-103
>              Project: OASIS Virtual I/O Device (VIRTIO) TC
>           Issue Type: Sub-task
>     Affects Versions: virtio 1.0 csprd01
>             Reporter: Rusty Russell
>             Assignee: Rusty Russell
>
>
> 4.1.2.1 Common Configuration structure layout
>
> device_status
>
> ​The spec states "​
> Writing 0 resets the device
> ​".  H
> ow does the driver know when its complete.  Proposal
> ​:​
> the resetting driver will poll this register for a non-zero value
> until the reset is complete after which DMA and interrupts will not
> occur.

The current assumption is that the write traps, and is synchronous.
However, I think your suggestion is sound anyway:

diff --git a/content.tex b/content.tex
index b5a3ce0..454df83 100644
--- a/content.tex
+++ b/content.tex
@@ -1258,7 +1258,8 @@ and if that flag is set when the driver reads from the device-specific
 configuration, increment \field{config_generation} and clear the flag.
 \end{note}
 
-The device MUST reset when 0 is written to \field{device_status}.
+The device MUST reset when 0 is written to \field{device_status}, and
+present a 0 in \field{device_status} once that is done.
 
 The device MUST present a 0 in \field{queue_enable} on reset.
 
@@ -1274,6 +1275,9 @@ The driver MUST NOT write a value which is not a power of 2 to \field{queue_size
 The driver MUST configure the other virtqueue fields before enabling the virtqueue
 with \field{queue_enable}.
 
+After writing 0 to \field{device_status}, the driver MUST wait for a read of
+\field{device_status} to return 0 before reinitializing the device.
+
 \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 
 The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG

> queue_size
>
> Is there a way to find the maximum queue size without resetting the whole device?

No, but I don't think it's critical the queue size can't be changed
without a reset anyway.

> queue_enable
>
> What happens to the state of the queue when queue_enable transitions from non-zero to zero?

That's currently undefined.  There was a suggestion that we should be
able to deactivate queues on a live device, but is currently unnecessary.

We should note this explicitly:

diff --git a/content.tex b/content.tex
index 454df83..01ecd1e 100644
--- a/content.tex
+++ b/content.tex
@@ -1278,6 +1278,8 @@ with \field{queue_enable}.
 After writing 0 to \field{device_status}, the driver MUST wait for a read of
 \field{device_status} to return 0 before reinitializing the device.
 
+The driver MUST NOT write a 0 to \field{queue_enable}.
+
 \subsubsection{Notification structure layout}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI Device Layout / Notification capability}
 
 The notification location is found using the VIRTIO_PCI_CAP_NOTIFY_CFG

> queue_desc/queue_avail/queue_used​
>
> Does a zero address indicate a disabled queue?  This is how current devices work but spec clarification would be useful.

No, the queue_enable == 0 indicates a disabled queue.  However, the
driver could write 0 when the queue is not enabled and expect the value
to stick (which is what the Linux drivers do, for example).

queue_enable was added because with 64 bit addresses there's no way
to atomically enter them (legacy used a 32-bit PFN), and also we have
three addresses now, not a single one.

(And in theory, a driver could put the queue at address 0).

Cheers,
Rusty.