Re: [PATCH v2 2/2] docs: driver-api: virtio: virtio on Linux

[Cornelia Huck <cohuck@redhat.com>]

On Thu, Aug 04 2022, Ricardo Cañuelo <ricardo.canuelo@collabora.com> wrote:

> Basic doc about Virtio on Linux and a short tutorial on Virtio drivers.
>
> Signed-off-by: Ricardo Cañuelo <ricardo.canuelo@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." ?