Re: [PATCH V3 Resend] virtio-transport: Clarify requirements

[Cornelia Huck <cohuck@redhat.com>]

On Tue, May 21 2024, "Michael S. Tsirkin" <mst@redhat.com> wrote:

> On Tue, May 21, 2024 at 04:27:06PM +0530, Viresh Kumar wrote:
>> On 20-05-24, 09:27, Michael S. Tsirkin wrote:
>> > On Mon, May 20, 2024 at 02:59:40PM +0530, Viresh Kumar wrote:
>> > > diff --git a/content.tex b/content.tex
>> > > index 0a62dce5f65f..a79993b5ed69 100644
>> > > --- a/content.tex
>> > > +++ b/content.tex
>> > > @@ -631,8 +631,82 @@ \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 is split into sections describing general virtio
>> > > +implementation and transport-specific sections.
>> > > +
>> > 
>> > This makes it seem like trasport is distinct from both
>> > device and driver. Makes no sense to me.
>> 
>> Yeah, looks wrongly worded. I think we can just retain the earlier
>> statement here:
>> 
>> Virtio can use various different buses, thus the standard is split
>> into virtio general and bus-specific sections.

I don't really like the "bus" term here: PCI is a bus, but there is no
need for a transport to be implemented via a bus.

Maybe

"The standard contains sections describing the transport-agnostic parts
of virtio, and sections describing how individual transports implement
virtio."

>> 
>> > > +\devicenormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements}
>> > > +
>> > > +The device MUST keep any data associated with a device-initiated
>> > > +transaction accessible to the driver until the driver acknowledges the
>> > > +transaction to be complete.
>> > > +
>> > > +The device MUST NOT 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 MUST NOT access or modify buffers on a virtqueue after it has
>> > > +notified the driver about their availability.
>> > > +
>> > > +The device MUST reset the virtqueues if requested by the driver, in a
>> > > +transport defined way, if the transport provides such a method.
>> > > +
>> > > +\drivernormative{\subsection}{Virtio Transport Requirements}{Virtio Transport Options / Virtio Transport Requirements}
>> > > +
>> > > +The driver MUST acknowledge device notifications, as mandated by the
>> > > +transport.
>> > > +
>> > > +The driver MUST NOT access virtqueue contents before the device notifies
>> > > +about the readiness of the same.
>> > > +
>> > > +The driver MUST NOT access buffers, after it has added them to the
>> > > +virtqueue and notified the device about their availability. The driver
>> > > +MAY access them after the device has processed them and notified the
>> > > +driver of their availability, in a transport defined way.
>> > > +
>> > > +The driver MAY ask the device to reset the virtqueues if, for example,
>> > > +the driver times out waiting for a notification from the device for a
>> > > +previously queued request.
>> > >  
>> > 
>> > This makes no sense in a normative section.
>> 
>> I am okay with wherever you and Cornelia decide to put this.
>> 
>> > Normative statements are for implementations not spec writers.
>> 
>> Hmm.

So anyone implementing a transport needs to be able to figure out
conformance just by looking at the individual transport's normative
statements? Have we cross-checked whether things are clear? Because
then...

>> 
>> > If you think of defining lots of new transports
>> > (questionable)
>> 
>> There is just one in discussion at the moment on the ARM side,
>> virtio-msg (for communication between the VMs), but nothing is
>> finalized yet.
>
>
> I feel a non-normative section is enough for this.
> Just convert should/must to direct speech.

...I think this would be fine.

>
>> > I think a new non-normative section
>> > along the lines of newdevice.tex will make sense.

[Generally, I'm not sure how consistent we are for the individual
transports. PCI is what most people are focusing on; CCW does not really
see much development anymore (at least in the projects that I'm aware
of); not sure how well-loved MMIO still is.]