Virtualization - Aug 2022 - [PATCH v2 2/2] docs: driver-api: virtio: virtio on Linux

On Thu, Aug 04 2022, Ricardo Ca?uelo <ricardo.canuelo at collabora.com>
wrote:
> Basic doc about Virtio on Linux and a short tutorial on Virtio drivers.
>
> Signed-off-by: Ricardo Ca?uelo <ricardo.canuelo at collabora.com>
> ---
>  Documentation/driver-api/index.rst            |   1 +
>  Documentation/driver-api/virtio/index.rst     |  11 +
>  Documentation/driver-api/virtio/virtio.rst    | 151 ++++++++++++++
>  .../virtio/writing_virtio_drivers.rst         | 189 ++++++++++++++++++
>  MAINTAINERS                                   |   1 +
>  5 files changed, 353 insertions(+)
>  create mode 100644 Documentation/driver-api/virtio/index.rst
>  create mode 100644 Documentation/driver-api/virtio/virtio.rst
>  create mode 100644
Documentation/driver-api/virtio/writing_virtio_drivers.rst
(...)
> diff --git a/Documentation/driver-api/virtio/virtio.rst
b/Documentation/driver-api/virtio/virtio.rst
> new file mode 100644
> index 000000000000..4b73c705c94c
> --- /dev/null
> +++ b/Documentation/driver-api/virtio/virtio.rst
> @@ -0,0 +1,151 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _virtio:
> +
> +==============> +Virtio on Linux
> +==============> +
> +Introduction
> +===========> +
> +Virtio is an open standard interface for virtual machines to access
> +paravirtualized devices, ie. devices that aren't emulated by a
> +hypervisor but rather real host devices that are exposed by the
> +hypervisor to the guest to achieve native performance. In other words,
> +it provides a communication mechanism for a guest OS to use devices on
> +the host machine. Additionally, some devices also implement the virtio
> +interface in hardware.
> +
> +For paravirtualized devices, the concrete hardware details of the real
> +host devices are abstracted in the hypervisor, which provides a set of
> +simplified virtual devices that implement the virtio protocol. These
> +devices are defined in Chapter 5 ("Device Types") of the virtio
spec [1]
> +and they're the devices that the guest OS will ultimately handle. So,
in
> +that regard, the guest OS knows it's running in a virtual environment
> +and that it needs to use the appropriate virtio drivers to handle the
> +devices instead of the regular device drivers it'd use in a native or
> +purely virtual environment (with emulated devices).
Hm... so I'm not quite happy with those two paragraphs, but I'm not sure
how to make it better.

- While the origins of virtio are hypervisor implementations, the
  standard is describing the mechanisms of device <-> driver
  communication, regardless whether the device is a hardware entity or
  something emulated by a hypervisor.
- I'm not quite sure what you are referring to with "real host
  devices". We can have e.g. a real disk that is handed to a guest via
  virtio-blk as a whole, or we can have some kind of file that is
  exposed via virtio-blk. Other device types can also be completely
  emulated.
- The OS picks the driver depending on what device is discovers; virtio
  device drivers are not any different from other device drivers in that
  regard.

So I think the key pieces of virtio are the following:

- it is an open standard
- it describes a protocol, which can be used to implement a lot of
  different device types
- those devices are exposed to the operating system via standard
  mechanisms such as PCI
- virtio devices can be implemented in various ways, such as in
  hypervisors (more common) or as a real hardware device

For the remainder of this document, it is probably fine to focus on the
hypervisor use case.

(...)
> +How a virtio device is found and configured by the kernel depends on how
> +the hypervisor defines it. Taking the `QEMU virtio-console
>
+<https://gitlab.com/qemu-project/qemu/-/blob/master/hw/char/virtio-console.c>`__
> +device as an example. When using PCI as a transport method, the device
> +will present itself in the PCI bus with vendor 0x1af4 (RedHat, Inc.) and
s/in/on/ ?
s/RedHat/Red Hat/ :)
> +device id 0x1003 (virtio console), as defined in the spec, so the kernel
> +will detect it as it would do with any other PCI device.
(...)
> diff --git a/Documentation/driver-api/virtio/writing_virtio_drivers.rst
b/Documentation/driver-api/virtio/writing_virtio_drivers.rst
> new file mode 100644
> index 000000000000..139c785a38ef
> --- /dev/null
> +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst
> @@ -0,0 +1,189 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _writing_virtio_drivers:
> +
> +=====================> +Writing Virtio Drivers
> +=====================> +
> +Introduction
> +===========> +
> +Chapter 5 ("Device Types") in the virtio specification [1]
defines all
> +the supported virtio device types. Since these devices are, by
> +definition, meant as abstractions for a wide variety of real hardware,
See my comments above, virtio devices can also be fully emulated or real
hardware devices.
> +the addition of new virtio drivers is not expected to be very
> +frequent. Still, this document serves as a basic guideline for driver
I think we should not make any statement regarding frequency of new
additions; sometimes, there's a flurry of activity, sometimes, there's
nothing for ages :)
> +programmers that need to hack a new virtio driver or understand the
> +essentials of the existing ones. See :ref:`Virtio on Linux <virtio>`
for
> +a general overview of virtio.
> +
> +
> +Driver boilerplate
> +=================> +
> +As a bare minimum, a virtio driver should register in the virtio bus and
s/should/needs to/ ?
> +configure the virtqueues for the device according to its spec, the
> +configuration of the virtqueues in the driver side must match the
> +virtqueue definitions in the device. A basic driver skeleton could look
> +like this::
(...)
> +The device id ``VIRTIO_ID_DUMMY`` here is a placeholder, virtio
> +drivers should be defined only for devices that are defined in the
s/defined/added/ ?
> +spec. See include/uapi/linux/virtio_ids.h.
Maybe "Device ids need to be at least reserved in the virtio spec before
being added to that file." ?

Hi Cornelia,

Thanks for the insightful comments and ideas. Answers below:

On lun, ago 08 2022 at 15:47:06, Cornelia Huck <cohuck at redhat.com>
wrote:
> Hm... so I'm not quite happy with those two paragraphs, but I'm not
sure
> how to make it better.
>
> - While the origins of virtio are hypervisor implementations, the
>   standard is describing the mechanisms of device <-> driver
>   communication, regardless whether the device is a hardware entity or
>   something emulated by a hypervisor.
> - I'm not quite sure what you are referring to with "real host
>   devices". We can have e.g. a real disk that is handed to a guest via
>   virtio-blk as a whole, or we can have some kind of file that is
>   exposed via virtio-blk. Other device types can also be completely
>   emulated.
> - The OS picks the driver depending on what device is discovers; virtio
>   device drivers are not any different from other device drivers in that
>   regard.
>
> So I think the key pieces of virtio are the following:
>
> - it is an open standard
> - it describes a protocol, which can be used to implement a lot of
>   different device types
> - those devices are exposed to the operating system via standard
>   mechanisms such as PCI
> - virtio devices can be implemented in various ways, such as in
>   hypervisors (more common) or as a real hardware device
>
> For the remainder of this document, it is probably fine to focus on the
> hypervisor use case.
How about this as an introduction?

    Virtio is an open standard that defines a protocol to communicate
    drivers and devices of different types, see Chapter 5 ("Device
    Types") of the virtio spec `[1]`_. Originally developed as a
    standard for paravirtualized devices implemented by a hypervisor, it
    can be used to interface any compliant device (real or emulated)
    with a driver.

    For illustrative purposes, this document will focus on the common
    case of a Linux kernel running in a virtual machine and using
    paravirtualized devices provided by the hypervisor, which exposes
    them as virtio devices via standard mechanisms such as PCI.
> s/in/on/ ?
> s/RedHat/Red Hat/ :)
Got it.
> See my comments above, virtio devices can also be fully emulated or real
> hardware devices.
>
> [...]
>
> I think we should not make any statement regarding frequency of new
> additions; sometimes, there's a flurry of activity, sometimes,
there's
> nothing for ages :)
Ok, I'll simplify the intro to this:

    This document serves as a basic guideline for driver programmers
    that need to hack a new virtio driver or understand the essentials
    of the existing ones. See :ref:`Virtio on Linux <virtio>` for a
    general overview of virtio.
> s/should/needs to/ ?
Ack.
> s/defined/added/ ?
Ack.
> Maybe "Device ids need to be at least reserved in the virtio spec
before
> being added to that file." ?
Sure, I'll add all of these to the next version.

Cheers,
Ricardo