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

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

On Tue, May 16, 2023 at 06:01:39AM +0300, Parav Pandit wrote:
> Currently device status field description and driver requirements
> section uses mix of terminology for the driver. These two sections
> sometimes call the driver as 'the guest OS' or 'the driver'.
> 
> Most of the cleanup around 'guest Os' was already done around commit
> 212c0cf3 in past. Clean up the remaining few references to just
> refer it as 'driver'.
> 
> This is an editorial change.

No, editorial changes are things like formatting, correcting cross
references, resolving simple patch conflicts.  We also have a minor
cleanups rule including spelling and typos.  I feel we've been through
this discussion, no?

I'm insisting on clarifying this because you want to be an editor, and
we could benefit from more editors, but given editors have commit access
it's important to be clear what the role of an editor is, which is not
to make decisions about content - it's a technical role.


> Signed-off-by: Parav Pandit <parav@nvidia.com>
> ---
>  content.tex | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> 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.





> @@ -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.


>     driver MAY read (but MUST NOT write) the device-specific configuration fields to check that it can support the device before accepting it.
>  
>  \item\label{itm:General Initialization And Device Operation / Device Initialization / Set FEATURES-OK} Set the FEATURES_OK status bit.  The driver MUST NOT accept
> -- 
> 2.26.2