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