[PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Viresh Kumar]

The current Virtio documentation lacks a set of generic requirements
applicable to all transports. Defining these generic requirements could
be beneficial when integrating support for a new transport.

This section outlines the essential requirements that any transport
method must adhere to.

Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
---
V7->V8:
- Remove separate sections for device/driver requirements.
- Remove optional requirements.
- Other generic improvements.

V6->V7:
- Remove parts that talk about accessing content of the virtqueue.

V5->V6:
- Move the changes to a new appendix section.
- Clarify the requirements a bit more based on review comments.

V4->V5:
- s/The transport/A transport/
- s/MUST provide/provides/
- Added some text for transport requirements.

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.

 main.tex         |  2 ++
 newtransport.tex | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 newtransport.tex

diff --git a/main.tex b/main.tex
index b1913d65e964..6d337217a3d1 100644
--- a/main.tex
+++ b/main.tex
@@ -42,6 +42,8 @@
 
 \input{newdevice.tex}
 
+\input{newtransport.tex}
+
 % acknowledgements
 \input{acknowledgements.tex} 
 
diff --git a/newtransport.tex b/newtransport.tex
new file mode 100644
index 000000000000..1c424ef907e3
--- /dev/null
+++ b/newtransport.tex
@@ -0,0 +1,40 @@
+\chapter{Creating New Transports}\label{sec:Creating New Transports}
+
+Devices and drivers utilize various transport methods to facilitate
+communication, such as PCI, MMIO, or Channel I/O. These transport
+methods determine multiple aspects of the interaction between the device
+and the driver, including device discovery, capability exchange,
+interrupt handling, and data transfer. For instance, in a host/guest
+architecture, the host might expose a device to the guest via a PCI bus,
+and the guest would employ a PCI device driver to interface with the
+device.
+
+This section outlines the mandatory requirements that a transport method
+must implement.
+
+A transport provides a mechanism to implement configuration space for
+the device.
+
+A transport provides a mechanism for the driver to communicate virtqueue
+configuration and memory location to the device.
+
+A transport provides a mechanism for the driver to identify the device
+type.
+
+A transport allows one or more virtqueues to be implemented by the
+device. The number of virtqueues is device specific and not specified by
+the transport.
+
+A transport provides a mechanism for the device to send device
+notifications to the driver, such as used buffer notification.
+
+A transport provides a mechanism for the driver to send driver
+notifications to the device, such as available buffer notification.
+
+A transport provides a mechanism for the driver to initiate a device reset.
+
+A transport provides a mechanism for the driver to read the device's
+status bit.
+
+A transport provides a mechanism for the driver to modify the device's
+status.
-- 
2.31.1.272.g89b43f80a514

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Michael S. Tsirkin]

On Tue, Jul 30, 2024 at 12:59:26PM +0530, Viresh Kumar wrote:
> The current Virtio documentation lacks a set of generic requirements
> applicable to all transports. Defining these generic requirements could
> be beneficial when integrating support for a new transport.
> 
> This section outlines the essential requirements that any transport
> method must adhere to.
> 
> Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
> ---
> V7->V8:
> - Remove separate sections for device/driver requirements.
> - Remove optional requirements.
> - Other generic improvements.
> 
> V6->V7:
> - Remove parts that talk about accessing content of the virtqueue.
> 
> V5->V6:
> - Move the changes to a new appendix section.
> - Clarify the requirements a bit more based on review comments.
> 
> V4->V5:
> - s/The transport/A transport/
> - s/MUST provide/provides/
> - Added some text for transport requirements.
> 
> 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.
> 
>  main.tex         |  2 ++
>  newtransport.tex | 40 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 42 insertions(+)
>  create mode 100644 newtransport.tex
> 
> diff --git a/main.tex b/main.tex
> index b1913d65e964..6d337217a3d1 100644
> --- a/main.tex
> +++ b/main.tex
> @@ -42,6 +42,8 @@
>  
>  \input{newdevice.tex}
>  
> +\input{newtransport.tex}
> +
>  % acknowledgements
>  \input{acknowledgements.tex} 
>  
> diff --git a/newtransport.tex b/newtransport.tex
> new file mode 100644
> index 000000000000..1c424ef907e3
> --- /dev/null
> +++ b/newtransport.tex
> @@ -0,0 +1,40 @@
> +\chapter{Creating New Transports}\label{sec:Creating New Transports}
> +
> +Devices and drivers utilize various transport methods to facilitate
> +communication, such as PCI, MMIO, or Channel I/O. These transport
> +methods determine multiple aspects of the interaction between the device
> +and the driver, including device discovery, capability exchange,
> +interrupt handling, and data transfer. For instance, in a host/guest
> +architecture, the host might expose a device to the guest via a PCI bus,

a virtual PCI bus

> +and the guest would employ a PCI device driver to interface with the
> +device.
> +
> +This section outlines the mandatory requirements that a transport method
> +must implement.

implements.

> +
> +A transport provides a mechanism to implement configuration space for
> +the device.
> +
> +A transport provides a mechanism for the driver to communicate virtqueue
> +configuration and memory location to the device.
> +
> +A transport provides a mechanism for the driver to identify the device
> +type.
> +
> +A transport allows one or more virtqueues to be implemented by the
> +device. The number of virtqueues is device specific and not specified by
> +the transport.
> +
> +A transport provides a mechanism for the device to send device
> +notifications to the driver, such as used buffer notification.
> +
> +A transport provides a mechanism for the driver to send driver
> +notifications to the device, such as available buffer notification.

available buffer notifications (plural)

> +
> +A transport provides a mechanism for the driver to initiate a device reset.
> +
> +A transport provides a mechanism for the driver to read the device's
> +status bit.
> +
> +A transport provides a mechanism for the driver to modify the device's
> +status.

what about feature bits? that is fundamental

Let's order it sensibly though, in the order in which stuff is used

1st identify the device
2 access status

number of vqs

configure vqs

notification

reset

> -- 
> 2.31.1.272.g89b43f80a514

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Viresh Kumar]

On 30-07-24, 09:14, Michael S. Tsirkin wrote:
> Let's order it sensibly though, in the order in which stuff is used

Right.

diff --git a/newtransport.tex b/newtransport.tex
new file mode 100644
index 000000000000..3b760250a4c0
--- /dev/null
+++ b/newtransport.tex
@@ -0,0 +1,44 @@
+\chapter{Creating New Transports}\label{sec:Creating New Transports}
+
+Devices and drivers utilize various transport methods to facilitate
+communication, such as PCI, MMIO, or Channel I/O. These transport
+methods determine multiple aspects of the interaction between the device
+and the driver, including device discovery, capability exchange,
+interrupt handling, and data transfer. For instance, in a host/guest
+architecture, the host might expose a device to the guest via a virtual
+PCI bus, and the guest would employ a PCI device driver to interface
+with the device.
+
+This section outlines the mandatory requirements that a transport method
+implements.
+
+A transport provides a mechanism to implement configuration space for
+the device.
+
+A transport provides a mechanism for the driver to identify the device
+type.
+
+A transport provides a mechanism for the driver to read the device's
+status bit.
+
+A transport provides a mechanism for the driver to modify the device's
+status.
+
+A transport provides a mechanism for the driver to read and modify the
+device's feature bits.
+
+A transport allows one or more virtqueues to be implemented by the
+device. The number of virtqueues is device specific and not specified by
+the transport.
+
+A transport provides a mechanism for the driver to communicate virtqueue
+configuration and memory location to the device.
+
+A transport provides a mechanism for the device to send device
+notifications to the driver, such as used buffer notifications.
+
+A transport provides a mechanism for the driver to send driver
+notifications to the device, such as available buffer notifications.
+
+A transport provides a mechanism for the driver to initiate a device
+reset.

-- 
viresh

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Cornelia Huck]

On Wed, Jul 31 2024, Viresh Kumar <viresh.kumar@linaro.org> wrote:

> On 30-07-24, 09:14, Michael S. Tsirkin wrote:
>> Let's order it sensibly though, in the order in which stuff is used
>
> Right.
>
> diff --git a/newtransport.tex b/newtransport.tex
> new file mode 100644
> index 000000000000..3b760250a4c0
> --- /dev/null
> +++ b/newtransport.tex
> @@ -0,0 +1,44 @@
> +\chapter{Creating New Transports}\label{sec:Creating New Transports}
> +
> +Devices and drivers utilize various transport methods to facilitate
> +communication, such as PCI, MMIO, or Channel I/O. These transport
> +methods determine multiple aspects of the interaction between the device
> +and the driver, including device discovery, capability exchange,
> +interrupt handling, and data transfer. For instance, in a host/guest
> +architecture, the host might expose a device to the guest via a virtual
> +PCI bus, and the guest would employ a PCI device driver to interface
> +with the device.
> +
> +This section outlines the mandatory requirements that a transport method
> +implements.
> +
> +A transport provides a mechanism to implement configuration space for
> +the device.
> +
> +A transport provides a mechanism for the driver to identify the device
> +type.
> +
> +A transport provides a mechanism for the driver to read the device's
> +status bit.

Either "status bits", or "status" (as below.)

> +
> +A transport provides a mechanism for the driver to modify the device's
> +status.
> +
> +A transport provides a mechanism for the driver to read and modify the
> +device's feature bits.
> +
> +A transport allows one or more virtqueues to be implemented by the
> +device. The number of virtqueues is device specific and not specified by
> +the transport.

Do we also need to say that the transport provides a mechanism for the
driver to discover the number of virtqueues?

> +
> +A transport provides a mechanism for the driver to communicate virtqueue
> +configuration and memory location to the device.
> +
> +A transport provides a mechanism for the device to send device
> +notifications to the driver, such as used buffer notifications.
> +
> +A transport provides a mechanism for the driver to send driver
> +notifications to the device, such as available buffer notifications.
> +
> +A transport provides a mechanism for the driver to initiate a device
> +reset.

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Michael S. Tsirkin]

On Wed, Jul 31, 2024 at 11:43:13AM +0200, Cornelia Huck wrote:
> On Wed, Jul 31 2024, Viresh Kumar <viresh.kumar@linaro.org> wrote:
> 
> > On 30-07-24, 09:14, Michael S. Tsirkin wrote:
> >> Let's order it sensibly though, in the order in which stuff is used
> >
> > Right.
> >
> > diff --git a/newtransport.tex b/newtransport.tex
> > new file mode 100644
> > index 000000000000..3b760250a4c0
> > --- /dev/null
> > +++ b/newtransport.tex
> > @@ -0,0 +1,44 @@
> > +\chapter{Creating New Transports}\label{sec:Creating New Transports}
> > +
> > +Devices and drivers utilize various transport methods to facilitate
> > +communication, such as PCI, MMIO, or Channel I/O. These transport
> > +methods determine multiple aspects of the interaction between the device
> > +and the driver, including device discovery, capability exchange,
> > +interrupt handling, and data transfer. For instance, in a host/guest
> > +architecture, the host might expose a device to the guest via a virtual
> > +PCI bus, and the guest would employ a PCI device driver to interface
> > +with the device.
> > +
> > +This section outlines the mandatory requirements that a transport method
> > +implements.
> > +
> > +A transport provides a mechanism to implement configuration space for
> > +the device.
> > +
> > +A transport provides a mechanism for the driver to identify the device
> > +type.
> > +
> > +A transport provides a mechanism for the driver to read the device's
> > +status bit.
> 
> Either "status bits", or "status" (as below.)

It is actually "FEATURES_OK status bit" I think.

> > +
> > +A transport provides a mechanism for the driver to modify the device's
> > +status.
> > +
> > +A transport provides a mechanism for the driver to read and modify the
> > +device's feature bits.
> > +
> > +A transport allows one or more virtqueues to be implemented by the
> > +device. The number of virtqueues is device specific and not specified by
> > +the transport.
> 
> Do we also need to say that the transport provides a mechanism for the
> driver to discover the number of virtqueues?

Some do, but it does not have to. Legacy pci did not do it,
modern does but it is mostly used for sanity checking.

> > +
> > +A transport provides a mechanism for the driver to communicate virtqueue
> > +configuration and memory location to the device.
> > +
> > +A transport provides a mechanism for the device to send device
> > +notifications to the driver, such as used buffer notifications.
> > +
> > +A transport provides a mechanism for the driver to send driver
> > +notifications to the device, such as available buffer notifications.
> > +
> > +A transport provides a mechanism for the driver to initiate a device
> > +reset.

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Cornelia Huck]

On Wed, Jul 31 2024, "Michael S. Tsirkin" <mst@redhat.com> wrote:

> On Wed, Jul 31, 2024 at 11:43:13AM +0200, Cornelia Huck wrote:
>> On Wed, Jul 31 2024, Viresh Kumar <viresh.kumar@linaro.org> wrote:
>> 
>> > On 30-07-24, 09:14, Michael S. Tsirkin wrote:
>> >> Let's order it sensibly though, in the order in which stuff is used
>> >
>> > Right.
>> >
>> > diff --git a/newtransport.tex b/newtransport.tex
>> > new file mode 100644
>> > index 000000000000..3b760250a4c0
>> > --- /dev/null
>> > +++ b/newtransport.tex
>> > @@ -0,0 +1,44 @@
>> > +\chapter{Creating New Transports}\label{sec:Creating New Transports}
>> > +
>> > +Devices and drivers utilize various transport methods to facilitate
>> > +communication, such as PCI, MMIO, or Channel I/O. These transport
>> > +methods determine multiple aspects of the interaction between the device
>> > +and the driver, including device discovery, capability exchange,
>> > +interrupt handling, and data transfer. For instance, in a host/guest
>> > +architecture, the host might expose a device to the guest via a virtual
>> > +PCI bus, and the guest would employ a PCI device driver to interface
>> > +with the device.
>> > +
>> > +This section outlines the mandatory requirements that a transport method
>> > +implements.
>> > +
>> > +A transport provides a mechanism to implement configuration space for
>> > +the device.
>> > +
>> > +A transport provides a mechanism for the driver to identify the device
>> > +type.
>> > +
>> > +A transport provides a mechanism for the driver to read the device's
>> > +status bit.
>> 
>> Either "status bits", or "status" (as below.)
>
> It is actually "FEATURES_OK status bit" I think.

Also DEVICE_NEEDS_RESET? I don't think it makes sense to say that the
driver needs a way to read individual bits, it should be able to read
the whole status.

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Michael S. Tsirkin]

On Wed, Jul 31, 2024 at 12:15:30PM +0200, Cornelia Huck wrote:
> On Wed, Jul 31 2024, "Michael S. Tsirkin" <mst@redhat.com> wrote:
> 
> > On Wed, Jul 31, 2024 at 11:43:13AM +0200, Cornelia Huck wrote:
> >> On Wed, Jul 31 2024, Viresh Kumar <viresh.kumar@linaro.org> wrote:
> >> 
> >> > On 30-07-24, 09:14, Michael S. Tsirkin wrote:
> >> >> Let's order it sensibly though, in the order in which stuff is used
> >> >
> >> > Right.
> >> >
> >> > diff --git a/newtransport.tex b/newtransport.tex
> >> > new file mode 100644
> >> > index 000000000000..3b760250a4c0
> >> > --- /dev/null
> >> > +++ b/newtransport.tex
> >> > @@ -0,0 +1,44 @@
> >> > +\chapter{Creating New Transports}\label{sec:Creating New Transports}
> >> > +
> >> > +Devices and drivers utilize various transport methods to facilitate
> >> > +communication, such as PCI, MMIO, or Channel I/O. These transport
> >> > +methods determine multiple aspects of the interaction between the device
> >> > +and the driver, including device discovery, capability exchange,
> >> > +interrupt handling, and data transfer. For instance, in a host/guest
> >> > +architecture, the host might expose a device to the guest via a virtual
> >> > +PCI bus, and the guest would employ a PCI device driver to interface
> >> > +with the device.
> >> > +
> >> > +This section outlines the mandatory requirements that a transport method
> >> > +implements.
> >> > +
> >> > +A transport provides a mechanism to implement configuration space for
> >> > +the device.
> >> > +
> >> > +A transport provides a mechanism for the driver to identify the device
> >> > +type.
> >> > +
> >> > +A transport provides a mechanism for the driver to read the device's
> >> > +status bit.
> >> 
> >> Either "status bits", or "status" (as below.)
> >
> > It is actually "FEATURES_OK status bit" I think.
> 
> Also DEVICE_NEEDS_RESET?

Good point.

> I don't think it makes sense to say that the
> driver needs a way to read individual bits, it should be able to read
> the whole status.

It depends on the transport, I can imagine a transport that
saves some space by not keeping a copy of e.g. DRIVER.

-- 
MST

Re: [PATCH V8] virtio-transport: Add a section to define mandatory transport requirements

[Viresh Kumar]

On 31-07-24, 08:16, Michael S. Tsirkin wrote:
> On Wed, Jul 31, 2024 at 12:15:30PM +0200, Cornelia Huck wrote:
> > On Wed, Jul 31 2024, "Michael S. Tsirkin" <mst@redhat.com> wrote:
> > > On Wed, Jul 31, 2024 at 11:43:13AM +0200, Cornelia Huck wrote:
> > >> On Wed, Jul 31 2024, Viresh Kumar <viresh.kumar@linaro.org> wrote:
> > >> > +A transport provides a mechanism for the driver to read the device's
> > >> > +status bit.
> > >> 
> > >> Either "status bits", or "status" (as below.)
> > >
> > > It is actually "FEATURES_OK status bit" I think.
> > 
> > Also DEVICE_NEEDS_RESET?
> 
> Good point.
> 
> > I don't think it makes sense to say that the
> > driver needs a way to read individual bits, it should be able to read
> > the whole status.
> 
> It depends on the transport, I can imagine a transport that
> saves some space by not keeping a copy of e.g. DRIVER.

Should I rewrite as:

A transport provides a mechanism for the driver to read the device's FEATURES_OK
and DEVICE_NEEDS_RESET status bits.

?

-- 
viresh