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

[Rusty Russell <rusty@au1.ibm.com>]

Cornelia Huck <cornelia.huck@de.ibm.com> writes:
> 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.

Thanks for fixes, I've applied them to the tex version (along with my
previous changes) and am about to commit to SVN once it's all done.

Cheers,
Rusty.

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