The virtio documentation currently doesn't define any generic requirements that are applicable to all transports. They can be useful while adding support for a new transport.
This commit tries to define the same.
Reviewed-by: Alex Bennée alex.bennee@linaro.org Signed-off-by: Viresh Kumar viresh.kumar@linaro.org --- V3->V4: - Remove the normative sections and use direct speech. - Change wording at few places.
V2->V3: - Minor fixes. - Added Reviewed by from Alex.
V1->V2: - Lot of changes after discussions with Alex and Cornelia. - Almost a rewrite of the first commit. - Add Transport normative sections.
content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 2 deletions(-)
diff --git a/content.tex b/content.tex index 0a62dce5f65f..23eea890d9b7 100644 --- a/content.tex +++ b/content.tex @@ -631,8 +631,84 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation /
\chapter{Virtio Transport Options}\label{sec:Virtio Transport Options}
-Virtio can use various different buses, thus the standard is split -into virtio general and bus-specific sections. +Devices and drivers can use different transport methods to enable +interaction, for example PCI, MMIO, or Channel I/O. The transport +methods define various aspects of the communication between the device +and the driver, like device discovery, exchanging capabilities, +interrupt handling, data transfer, etc. For example, in a host/guest +architecture, the host might expose a device to the guest on a PCI bus, +and the guest will use a PCI-specific driver to interact with it. + +The standard contains sections describing the transport-agnostic parts +of virtio, and sections describing how individual transports implement +virtio. + +\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements} + +\subsection{Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Transport Requirements} + +The transport provides a mechanism for the driver to discover the +device. + +The transport provides a mechanism for the driver to identify the device +type. + +The transport provides a mechanism for communicating virtqueue +configurations between the device and the driver. + +The transport allows multiple virtqueues per device. The number of +virtqueues for a pair of device-driver are governed by the individual +device protocol. + +The transport provides a mechanism that the device and the driver use to +access memory for implementing virtqueues. + +The transport provides a mechanism for the device to notify the driver +and a mechanism for the driver to notify the device, for example +regarding availability of a buffer on the virtqueue. + +The transport provides a mechanism for the driver to initiate a reset +of the virtqueues and device. + +The transport provides a mechanism for the driver to read the device +status. The transport MUST provide a mechanism for the driver to change +the device status. + +The transport provides a mechanism to implement configuration space +between the device and the driver. + +\subsection{Device Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Device Requirements} + +The device keeps any data associated with a device-initiated transaction +accessible to the driver until the driver acknowledges the transaction +to be complete. + +The device doesn't access the contents of a virtqueue before the driver +notifies, in a transport defined way, the device that the virtqueue is +ready to be accessed. + +The device doesn't access or modify buffers on a virtqueue after it has +notified the driver about their availability. + +The device resets itself and the virtqueues if requested by the driver, in a +transport defined way, if the transport provides such a method. + +\subsection{Driver Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Driver Requirements} + +The driver acknowledges device notifications, as mandated by the +transport. + +The driver doesn't access virtqueue contents before the device notifies +about the readiness of the same. + +The driver accesses queued buffers after the device has processed them +and notified the driver of their availability. This mechanism is +transport defined. + +The driver asks the device to reset itself and the virtqueues if, for +example, the driver times out waiting for a notification from the device +for a previously queued request. +
\input{transport-pci.tex} \input{transport-mmio.tex}
On Tue, Jun 04 2024, Viresh Kumar viresh.kumar@linaro.org wrote:
The virtio documentation currently doesn't define any generic requirements that are applicable to all transports. They can be useful while adding support for a new transport.
This commit tries to define the same.
Reviewed-by: Alex Bennée alex.bennee@linaro.org Signed-off-by: Viresh Kumar viresh.kumar@linaro.org
V3->V4:
- Remove the normative sections and use direct speech.
- Change wording at few places.
V2->V3:
- Minor fixes.
- Added Reviewed by from Alex.
V1->V2:
- Lot of changes after discussions with Alex and Cornelia.
- Almost a rewrite of the first commit.
- Add Transport normative sections.
content.tex | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 2 deletions(-)
diff --git a/content.tex b/content.tex index 0a62dce5f65f..23eea890d9b7 100644 --- a/content.tex +++ b/content.tex @@ -631,8 +631,84 @@ \section{Device Cleanup}\label{sec:General Initialization And Device Operation / \chapter{Virtio Transport Options}\label{sec:Virtio Transport Options} -Virtio can use various different buses, thus the standard is split -into virtio general and bus-specific sections. +Devices and drivers can use different transport methods to enable +interaction, for example PCI, MMIO, or Channel I/O. The transport +methods define various aspects of the communication between the device +and the driver, like device discovery, exchanging capabilities, +interrupt handling, data transfer, etc. For example, in a host/guest +architecture, the host might expose a device to the guest on a PCI bus, +and the guest will use a PCI-specific driver to interact with it.
+The standard contains sections describing the transport-agnostic parts +of virtio, and sections describing how individual transports implement +virtio.
+\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements}
It might be useful to put some kind of lead-in here, maybe something like
"There are some mechanisms that any transport is required to implement, and some requirements that devices and drivers are required to follow."
+\subsection{Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Transport Requirements}
+The transport provides a mechanism for the driver to discover the +device.
Maybe "A transport", or "Any transport"? I think "The transport" is a bit awkward if we're not talking about a specific transport, but something any transport is supposed to do.
+The transport provides a mechanism for the driver to identify the device +type.
+The transport provides a mechanism for communicating virtqueue +configurations between the device and the driver.
+The transport allows multiple virtqueues per device. The number of +virtqueues for a pair of device-driver are governed by the individual +device protocol.
+The transport provides a mechanism that the device and the driver use to +access memory for implementing virtqueues.
+The transport provides a mechanism for the device to notify the driver +and a mechanism for the driver to notify the device, for example +regarding availability of a buffer on the virtqueue.
+The transport provides a mechanism for the driver to initiate a reset +of the virtqueues and device.
+The transport provides a mechanism for the driver to read the device +status. The transport MUST provide a mechanism for the driver to change
s/MUST provide/provides/
+the device status.
+The transport provides a mechanism to implement configuration space +between the device and the driver.
+\subsection{Device Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Device Requirements}
+The device keeps any data associated with a device-initiated transaction +accessible to the driver until the driver acknowledges the transaction +to be complete.
+The device doesn't access the contents of a virtqueue before the driver +notifies, in a transport defined way, the device that the virtqueue is +ready to be accessed.
+The device doesn't access or modify buffers on a virtqueue after it has +notified the driver about their availability.
+The device resets itself and the virtqueues if requested by the driver, in a +transport defined way, if the transport provides such a method.
+\subsection{Driver Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Driver Requirements}
+The driver acknowledges device notifications, as mandated by the +transport.
+The driver doesn't access virtqueue contents before the device notifies +about the readiness of the same.
+The driver accesses queued buffers after the device has processed them +and notified the driver of their availability. This mechanism is +transport defined.
+The driver asks the device to reset itself and the virtqueues if, for +example, the driver times out waiting for a notification from the device +for a previously queued request.
\input{transport-pci.tex} \input{transport-mmio.tex}
On 05-06-24, 14:21, Cornelia Huck wrote:
On Tue, Jun 04 2024, Viresh Kumar viresh.kumar@linaro.org wrote:
+\section{Virtio Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements}
It might be useful to put some kind of lead-in here, maybe something like
"There are some mechanisms that any transport is required to implement, and some requirements that devices and drivers are required to follow."
+\subsection{Transport Requirements}\label{sec:Virtio Transport Options / Virtio Transport Requirements / Transport Requirements}
+The transport provides a mechanism for the driver to discover the +device.
Maybe "A transport", or "Any transport"? I think "The transport" is a bit awkward if we're not talking about a specific transport, but something any transport is supposed to do.
+The transport provides a mechanism for the driver to read the device +status. The transport MUST provide a mechanism for the driver to change
s/MUST provide/provides/
Sure, thanks.
stratos-dev@op-lists.linaro.org
-
Cornelia Huck -
Viresh Kumar