[virtio-comment] [RFC PATCH] introduction.tex: introduce a glossary of terms

[virtio-comment] [RFC PATCH] introduction.tex: introduce a glossary of terms

[Alex Bennée]

It is useful to have a glossary of common terms at the front of the
document to define common terms we are going to use throughout the
specification. Whilst writing this list I notice we refer to a device
in host terms - perhaps we need slightly tighter definitions of what a
device is? For discussion I've defined a Device Interface in terms of
the guest visible side and a Device Backend in terms of what runs on
the host.

Cc: Nikos Dragazis <ndragazis@arrikto.com>
Cc: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 introduction.tex | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/introduction.tex b/introduction.tex
index 33da3ec..c84a112 100644
--- a/introduction.tex
+++ b/introduction.tex
@@ -81,6 +81,36 @@ \section{Terminology}\label{Terminology}
 
 The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}.
 
+\subsection{Glossary}\label{intro:Glossary}
+
+The following are definitions of common terms used throughout the specification.
+
+\begin{description}
+\item[Guest]
+  A virtual machine hosted by a hypervisor.
+\item[Host]
+  The system hosting a virtual machine. It may consist of multiple
+  components including a hypervisor, primary OS and it's user-space.
+\item[Device Interface]
+  The series of configuration, control and operation mechanisms
+  visible to the guest that make a Virtio device.
+\item[Device Driver]
+  The software (usually part of a kernel) running on the guest which
+  accesses the device interface.
+\item[Device Backend]
+  The software running on the host that services requests made of the
+  device interface. The implementation details of the backend should
+  be transparent to the guest.
+\item[Notification]
+  An asynchronous signal sent to either the device backend or the
+  device driver to indicate a virtqueue has been updated. For guests
+  this is typically a device interrupt.
+\item[Doorbell Register]
+  A guest visible register that when accessed will trigger a
+  notification to the backend via some implementation defined
+  mechanism.
+\end{description}
+
 \subsection{Legacy Interface: Terminology}\label{intro:Legacy
 Interface: Terminology}
 
-- 
2.26.0.103.g3bab5d5625


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [RFC PATCH] introduction.tex: introduce a glossary of terms

[Stefan Hajnoczi]

[-- Attachment #1: Type: text/plain, Size: 3808 bytes --]

On Mon, Jul 20, 2020 at 03:54:51PM +0100, Alex Bennée wrote:
> It is useful to have a glossary of common terms at the front of the
> document to define common terms we are going to use throughout the
> specification. Whilst writing this list I notice we refer to a device
> in host terms - perhaps we need slightly tighter definitions of what a
> device is? For discussion I've defined a Device Interface in terms of
> the guest visible side and a Device Backend in terms of what runs on
> the host.
> 
> Cc: Nikos Dragazis <ndragazis@arrikto.com>
> Cc: Stefan Hajnoczi <stefanha@redhat.com>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  introduction.tex | 30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/introduction.tex b/introduction.tex
> index 33da3ec..c84a112 100644
> --- a/introduction.tex
> +++ b/introduction.tex
> @@ -81,6 +81,36 @@ \section{Terminology}\label{Terminology}
>  
>  The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}.
>  
> +\subsection{Glossary}\label{intro:Glossary}
> +
> +The following are definitions of common terms used throughout the specification.
> +
> +\begin{description}
> +\item[Guest]
> +  A virtual machine hosted by a hypervisor.
> +\item[Host]
> +  The system hosting a virtual machine. It may consist of multiple
> +  components including a hypervisor, primary OS and it's user-space.

Please avoid using guest/host terminology. Guest/host does not apply to
all VIRTIO use cases. For example, the "device backend" definition above
is specific to software implementation of VIRTIO devices on the host,
but VIRTIO devices can be implemented in hardware too.

Another example: it is possible to use VIRTIO devices on bare metal
without virtualization in Linux (either hardware or software vDPA
implementations).

There are device types that are specifically designed for virtualization
(e.g. memory ballooning) and there it is fine to use guest/host
terminology. But the terminology should only be used when necessary and
not as the base for defining general terms like "device" and "driver".

> +\item[Device Interface]
> +  The series of configuration, control and operation mechanisms
> +  visible to the guest that make a Virtio device.
> +\item[Device Driver]
> +  The software (usually part of a kernel) running on the guest which
> +  accesses the device interface.
> +\item[Device Backend]
> +  The software running on the host that services requests made of the
> +  device interface. The implementation details of the backend should
> +  be transparent to the guest.

The VIRTIO spec typically uses just "driver" and "device", not "device
driver" and "device backend". Any instances of the latter should be
fixed up in the spec.

Let's avoid using "backend" in VIRTIO because it already has a meaning
in the context of vhost-user.

> +\item[Notification]
> +  An asynchronous signal sent to either the device backend or the
> +  device driver to indicate a virtqueue has been updated. For guests
> +  this is typically a device interrupt.

The configuration change notification is not specific to a virtqueue.
This definition should be more general:

s/a virtqueue has been updated/an event has occurred/

> +\item[Doorbell Register]
> +  A guest visible register that when accessed will trigger a
> +  notification to the backend via some implementation defined
> +  mechanism.

Rewriting this with the above points in mind:

  A register that triggers a notification to the device when accessed by
  the driver.

Stefan

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

[virtio-comment] Re: [RFC PATCH] introduction.tex: introduce a glossary of terms

[Alex Bennée]

Stefan Hajnoczi <stefanha@redhat.com> writes:

> On Mon, Jul 20, 2020 at 03:54:51PM +0100, Alex Bennée wrote:
>> It is useful to have a glossary of common terms at the front of the
>> document to define common terms we are going to use throughout the
>> specification. Whilst writing this list I notice we refer to a device
>> in host terms - perhaps we need slightly tighter definitions of what a
>> device is? For discussion I've defined a Device Interface in terms of
>> the guest visible side and a Device Backend in terms of what runs on
>> the host.
>> 
>> Cc: Nikos Dragazis <ndragazis@arrikto.com>
>> Cc: Stefan Hajnoczi <stefanha@redhat.com>
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>>  introduction.tex | 30 ++++++++++++++++++++++++++++++
>>  1 file changed, 30 insertions(+)
>> 
>> diff --git a/introduction.tex b/introduction.tex
>> index 33da3ec..c84a112 100644
>> --- a/introduction.tex
>> +++ b/introduction.tex
>> @@ -81,6 +81,36 @@ \section{Terminology}\label{Terminology}
>>  
>>  The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'', ``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL'' in this document are to be interpreted as described in \hyperref[intro:rfc2119]{[RFC2119]}.
>>  
>> +\subsection{Glossary}\label{intro:Glossary}
>> +
>> +The following are definitions of common terms used throughout the specification.
>> +
>> +\begin{description}
>> +\item[Guest]
>> +  A virtual machine hosted by a hypervisor.
>> +\item[Host]
>> +  The system hosting a virtual machine. It may consist of multiple
>> +  components including a hypervisor, primary OS and it's user-space.
>
> Please avoid using guest/host terminology. Guest/host does not apply to
> all VIRTIO use cases. For example, the "device backend" definition above
> is specific to software implementation of VIRTIO devices on the host,
> but VIRTIO devices can be implemented in hardware too.
>
> Another example: it is possible to use VIRTIO devices on bare metal
> without virtualization in Linux (either hardware or software vDPA
> implementations).
>
> There are device types that are specifically designed for virtualization
> (e.g. memory ballooning) and there it is fine to use guest/host
> terminology. But the terminology should only be used when necessary and
> not as the base for defining general terms like "device" and "driver".

OK - I was hoping it would make things clearer as I was getting confused
with the device/driver terminology for the vhost-user-device. 

>> +\item[Device Interface]
>> +  The series of configuration, control and operation mechanisms
>> +  visible to the guest that make a Virtio device.
>> +\item[Device Driver]
>> +  The software (usually part of a kernel) running on the guest which
>> +  accesses the device interface.
>> +\item[Device Backend]
>> +  The software running on the host that services requests made of the
>> +  device interface. The implementation details of the backend should
>> +  be transparent to the guest.
>
> The VIRTIO spec typically uses just "driver" and "device", not "device
> driver" and "device backend". Any instances of the latter should be
> fixed up in the spec.

OK how about:

  Device:

  The series of configuration, control and operation mechanisms
  visible to the driver that make up a Virtio device. The implementation
  of the device should be transparent to the Driver.

  Driver

  The software (usually part of a kernel) which accesses the device
  interface.


> Let's avoid using "backend" in VIRTIO because it already has a meaning
> in the context of vhost-user.
>
>> +\item[Notification]
>> +  An asynchronous signal sent to either the device backend or the
>> +  device driver to indicate a virtqueue has been updated. For guests
>> +  this is typically a device interrupt.
>
> The configuration change notification is not specific to a virtqueue.
> This definition should be more general:
>
> s/a virtqueue has been updated/an event has occurred/

OK - can we say anything else about it. Are notifications essential or
there to avoid polling.

>
>> +\item[Doorbell Register]
>> +  A guest visible register that when accessed will trigger a
>> +  notification to the backend via some implementation defined
>> +  mechanism.
>
> Rewriting this with the above points in mind:
>
>   A register that triggers a notification to the device when accessed by
>   the driver.
>
> Stefan



-- 
Alex Bennée

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/