introduction.tex: introduce a glossary of terms
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.
--- introduction.tex | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)
introduction.tex +30 -0
@@ -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/
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]>Signed-off-by Alex Bennée <[email protected]>--- introduction.tex | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)introduction.tex +0
-0@@ -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
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]>Signed-off-by Alex Bennée <[email protected]>--- introduction.tex | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+)introduction.tex +0
-0@@ -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/