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

[Stefan Hajnoczi <stefanha@redhat.com>]

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: signature.asc
Description: PGP signature