Re: [PATCH] content: Replace guest OS with driver

["Michael S. Tsirkin" <mst@redhat.com>]

On Tue, May 16, 2023 at 10:24:12AM +0200, Cornelia Huck wrote:
> On Tue, May 16 2023, "Michael S. Tsirkin" <mst@redhat.com> wrote:
> 
> > On Tue, May 16, 2023 at 06:01:39AM +0300, Parav Pandit wrote:
> >> diff --git a/content.tex b/content.tex
> >> index 9df81b8..417d476 100644
> >> --- a/content.tex
> >> +++ b/content.tex
> >> @@ -26,10 +26,10 @@ \section{\field{Device Status} Field}\label{sec:Basic Facilities of a Virtio Dev
> >>  following bits are defined (listed below in the order in which
> >>  they would be typically set):
> >>  \begin{description}
> >> -\item[ACKNOWLEDGE (1)] Indicates that the guest OS has found the
> >> +\item[ACKNOWLEDGE (1)] Indicates that the driver has found the
> >>    device and recognized it as a valid virtio device.
> >>  
> >> -\item[DRIVER (2)] Indicates that the guest OS knows how to drive the
> >> +\item[DRIVER (2)] Indicates that the driver knows how to drive the
> >>    device.
> >>    \begin{note}
> >>      There could be a significant (or infinite) delay before setting
> >
> > Actually, there is a subtle difference here that this is losing.
> > "guest OS" really refers to e.g. Linux virtio core code here.
> >
> >
> > ACKNOWLEDGE and DRIVER are used by virtio core.
> >
> > ACKNOWLEDGE tells you virtio core attached to device, and DRIVER
> > tells you core found a device specific driver.
> >
> >
> >
> > If you really want to make things better, let's find a way to explain
> > all this.
> 
> Agreed, this is a really old part of the spec, and likely had been
> written with the Linux device probing sequence in mind.
> 
> Basically, we want to distinguish between "something on the driver side
> has discovered the device" and "something on the driver side knows how
> to drive this specific device". If we consider "driver" as a catch-all
> of the whole thing talking to a device, we need to be extra descriptive
> (and we can add examples, as this is a non-normative section.)
> 
> For ACKNOWLEDGE, maybe "indicates that the driver has discovered the
> device and recognized it as a valid virtio device" (i.e. mostly what we
> have now), but also add "For example, this can indicate that non-device
> specific virtio driver code has attached to the device."
> 
> For DRIVER, maybe "indicates that the driver has discovered that it
> knows how to drive this device specifically. For example, this can
> indicate that device-specific driver code has attached to the device."


I feel examples are a weak way to document it - if we can not say
what this is specifically, what purpose does it serve?
Actually, we do have a distinction, between transport and device type.
Can't we use that? It seems more consistent than "non-device
specific" and "device specific".


SO I propose:

\item[ACKNOWLEDGE (1)] Indicates that a transport driver has found the
    device and recognized it as a valid virtio device transport.
  
\item[DRIVER (2)] Indicates that a device type specific driver was found
    and will attempt to attach to the device.



BTW somewhat related, I would maybe fix
device-types/mem/description.tex:change
not to say "device driver", just "driver" for brevity.





> Probably need some more overhaul :) Not an editorial change in any case.
> 
> >> @@ -473,13 +473,13 @@ \section{Device Initialization}\label{sec:General Initialization And Device Oper
> >>  \begin{enumerate}
> >>  \item Reset the device.
> >>  
> >> -\item Set the ACKNOWLEDGE status bit: the guest OS has noticed the device.
> >> +\item Set the ACKNOWLEDGE status bit: the driver has noticed the device.
> >>  
> >> -\item Set the DRIVER status bit: the guest OS knows how to drive the device.
> >> +\item Set the DRIVER status bit: the driver knows how to drive the device.
> >
> > besides the above, "drivers knows how to drive" sounds bad.
> >
> >>  \item\label{itm:General Initialization And Device Operation /
> >>  Device Initialization / Read feature bits} Read device feature bits, and write the subset of feature bits
> >> -   understood by the OS and driver to the device.  During this step the
> >> +   understood by the driver to the device.  During this step the
> >
> > Again the "the OS" here referred to core virtio (e.g. ring features).
> > Less of a problem to remove but if we come up with
> > a better terminology for ACKNOWLEDGE/DRIVER then I guess we can use it
> > here, too.
> 
> Hm, I'm not sure how far we need to distinguish between generic and
> device-specific features in this case. The "driver" as the whole entity
> driving the device needs to decide on the subset; at this stage, it does
> not really matter which parts of the driver code accepted which
> feature. We probably want to be explicit that features are ring,
> transport, and device features, though.

OK.

-- 
MST