[PATCH V4] virtio-transport: Clarify requirements

[PATCH V4] virtio-transport: Clarify requirements

[Viresh Kumar]

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}
-- 
2.31.1.272.g89b43f80a514

Re: [PATCH V4] virtio-transport: Clarify requirements

[Cornelia Huck]

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}

Re: [PATCH V4] virtio-transport: Clarify requirements

[Viresh Kumar]

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.

-- 
viresh

RE: [PATCH V4] virtio-transport: Clarify requirements

[Parav Pandit]

Hi Cornelia,

> From: Cornelia Huck <cohuck@redhat.com>
> Sent: Wednesday, June 5, 2024 5:52 PM
> 
> On Tue, Jun 04 2024, Viresh Kumar <viresh.kumar@linaro.org> wrote:
> 

[..]

> > +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/

Can you please explain why this requirement shouldn’t follow the RFC 2119?
This explanation will help to write future requirements with/without such key words.