Skip to contentSkip to conversation

introduction.tex: introduce a glossary of terms

RFC PATCH In review Alex Bennée 2 participants 3 messages Jul 20, 2020 – Jul 21, 2020

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 introduction.tex: introduce a glossary of terms

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 <[email protected]>
Cc Stefan Hajnoczi <[email protected]>
---
 introduction.tex | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
introduction.tex +30 -0
index 33da3ec..c84a112 100644
@@ -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}
 
Signature · 18 lines
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: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
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/
#1 lore raw
Quoted 23 lines · 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 <[email protected]>
Cc Stefan Hajnoczi <[email protected]>
---
 introduction.tex | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
introduction.tex +0 -0
index 33da3ec..c84a112 100644
@@ -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]}.
 

introduction.tex \section{Terminology}\label{Terminology} · line 93

Quoted 10 lines
introduction.tex +10 -0
+\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".

introduction.tex \section{Terminology}\label{Terminology} · line 103

Quoted 10 lines
introduction.tex +10 -0
+\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.

introduction.tex \section{Terminology}\label{Terminology} · line 107

Quoted 4 lines
introduction.tex +4 -0
+\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/

introduction.tex \section{Terminology}\label{Terminology} · line 111

Quoted 4 lines
introduction.tex +4 -0
+\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

#2 lore raw
Quoted 40 lines · Stefan Hajnoczi
Quoted 23 lines · 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 <[email protected]>
Cc Stefan Hajnoczi <[email protected]>
---
 introduction.tex | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
introduction.tex +0 -0
index 33da3ec..c84a112 100644
@@ -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]}.
 

introduction.tex \section{Terminology}\label{Terminology} · line 93

Quoted 10 lines
introduction.tex +10 -0
+\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.

Quoted 8 lines

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.

Quoted 11 lines

introduction.tex \section{Terminology}\label{Terminology} · line 103

Quoted 10 lines
introduction.tex +10 -0
+\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.
Quoted 3 lines

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.

Quoted 8 lines

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

introduction.tex \section{Terminology}\label{Terminology} · line 107

Quoted 4 lines
introduction.tex +4 -0
+\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.
Quoted 4 lines

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.

Quoted 12 lines

introduction.tex \section{Terminology}\label{Terminology} · line 111

Quoted 5 lines
introduction.tex +4 -0
+\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

Signature · 17 lines
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: [email protected]
Unsubscribe: [email protected]
List help: [email protected]
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/