Re: [PATCH 1/3] Terminology: Device and driver, not host and guest.

[Cornelia Huck <cornelia.huck@de.ibm.com>]

On Tue, 26 Nov 2013 13:41:13 +1030
Rusty Russell <rusty@au1.ibm.com> wrote:

> We've mixed both together, whereas from a spec-reader point of view,
> "driver" and "device" is probably clearer.
> 
> I avoided changing the CCW part of the spec, since the guest/host
> language is probably more typical in that world.

OTOH, having different terminology for different transports might be
confusing (and we do talk about devices presented via a control unit).
The uncommon term is "driver"; s390 documentation usually talks about
"the program". host/guest makes sense when talking about the whole
picture as in host->guest notification.

I'll talk to some folks here to get a second opinion on this.

> 
> Signed-off-by: Rusty Russell <rusty@au.ibm.com>
> ---
>  virtio-v1.0-wd01-part1-specification.txt | 255 ++++++++++++++++---------------
>  1 file changed, 134 insertions(+), 121 deletions(-)
> 
> diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
> index 3be1bef..3ca180f 100644
> --- a/virtio-v1.0-wd01-part1-specification.txt
> +++ b/virtio-v1.0-wd01-part1-specification.txt

> @@ -98,7 +111,7 @@ To reinforce this the examples use typenames like "le16" instead of "uint16_t".
>  2.1.1. Device Status Field
>  -------------------------
> 
> -The Device Status field is updated by the guest to indicate its
> +The Device Status field is updated by the OS and driver to indicate its

How about "guest/driver"? We haven't defined OS anywhere :)

>  progress. This provides a simple low-level diagnostic: it's most
>  useful to imagine them hooked up to traffic lights on the console
>  indicating the status of each device.
> @@ -119,7 +132,7 @@ This field is 0 upon reset, otherwise at least one bit should be set:
>    DRIVER_OK (4) Indicates that the driver is set up and ready to
>    drive the device.
> 
> -  FAILED (128) Indicates that something went wrong in the guest,
> +  FAILED (128) Indicates that something went wrong in the guest OS,

I'd keep this at "guest".

>    and it has given up on the device. This could be an internal
>    error, or the driver didn't like the device for some reason, or
>    even a fatal error during device operation. The device must be

> @@ -757,11 +770,11 @@ buffer:
>      at 65536 as well:
>  	(u16)(new_idx - used_event - 1) < (u16)(new_idx - old_idx)
> 
> -For each ring, guest should then disable interrupts by writing
> +For each ring, driver should then disable interrupts by writing

s/driver/the driver/

>  VRING_AVAIL_F_NO_INTERRUPT flag in avail structure, if required.
>  It can then process used ring entries finally enabling interrupts
>  by clearing the VRING_AVAIL_F_NO_INTERRUPT flag or updating the
> -EVENT_IDX field in the available structure.  The guest should then
> +EVENT_IDX field in the available structure.  The driver should then
>  execute a memory barrier, and then recheck the ring empty
>  condition. This is necessary to handle the case where after the
>  last check and before enabling interrupts, an interrupt has been