On Tue, Aug 02 2022, Ricardo Ca?uelo <ricardo.canuelo at collabora.com>
wrote:
> Basic doc about Virtio on Linux and a short tutorial on Virtio drivers.
> Minor fixes to existing virtio kerneldocs.
I think kerneldoc updates should be split out into a separate patch.
[No proper review, just some things I noticed below.]
>
> 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 | 274 ++++++++++++++++++
> .../virtio/writing_virtio_drivers.rst | 190 ++++++++++++
> MAINTAINERS | 1 +
> include/linux/virtio.h | 6 +-
> include/linux/virtio_config.h | 6 +-
> include/uapi/linux/virtio_ring.h | 16 +-
> 8 files changed, 494 insertions(+), 11 deletions(-)
> 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..049a8aefad92
> --- /dev/null
> +++ b/Documentation/driver-api/virtio/virtio.rst
> @@ -0,0 +1,274 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _virtio:
> +
> +==============> +Virtio on Linux
> +==============> +
> +Introduction
> +===========> +
> +Virtio is an open standard interface for virtual machines to access
There are devices that implement virtio in hardware.
> +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.
> +
> +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 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).
> +
> +
> +Device - Driver communication: virtqueues
> +========================================> +
> +Although the Virtio devices are really an abstraction layer in the
> +hypervisor, they're exposed to the guest as if they are physical
devices
> +either PCI or MMIO-based. We refer to that as the transport method and
Please also mention CCW (s390 channel devices), as Linux supports it as
well.
> +it's orthogonal to the device itself. The Virtio spec defines these
two
> +and other transport methods in detail, including device discovery,
> +capabilities and interrupt handling.
(...)
> +Device discovery and probing
> +===========================> +
> +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, which uses PCI as a transport method, the device
Should be the "virtio-console (...) device when using PCI...", I
guess?
> +will present itself in the PCI bus with vendor 0x1af4 (RedHat, Inc.) and
> +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.
(...)
> +References
> +=========> +
> +[1] Virtio Spec v1.1:
> +https://docs.oasis-open.org/virtio/virtio/v1.1/virtio-v1.1.html
v1.2 is out now :)
(I think it would be better to refer to the base spec directory?)
> +
> +[2] Virtqueues and virtio ring: How the data travels
> +https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels
> +
> +.. rubric:: Footnotes
> +
> +.. [#f1] that's why they may be also referred as virtrings.
> 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..5cb088b817ae
> --- /dev/null
> +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst
> @@ -0,0 +1,190 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _writing_virtio_drivers:
> +
> +=====================> +Writing Virtio Drivers
> +=====================> +
> +Introduction
> +===========> +
> +The `Virtio spec
>
+<https://docs.oasis-open.org/virtio/virtio/v1.1/cs01/virtio-v1.1-cs01.html#x1-1930005>`__
Chapter 5 ("Device Types") in the virtio specification [1]
(and add the same reference as above in this file)?
> +defines all the supported Virtio device types. Since these devices are,
> +by definition, meant as abstractions for a wide variety of real
> +hardware, the addition of new virtio drivers is not expected to be very
> +frequent. Still, 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.
Very important point here: Don't add a device driver for a device that
has no reserved device id in the spec. Preferably, don't add a device
driver if no spec is available (it is useful to develop
devices/drivers/spec at the same time to avoid incompatibilities/fixups
later; and you can consider a device spec "final" if it has been
accepted into the spec, even if it isn't in a released version yet.)
(...)
> +This assumes the device is of a new virtio device type not defined
> +before: ``VIRTIO_DEVICE_DUMMY``, which we should define in
> +include/uapi/linux/virtio_ids.h. The device has only one virtqueue which
Don't do that :) You need to make clear that VIRTIO_DEVICE_DUMMY is only
a placeholder.
> +is meant to be used to send data from the host to the guest.