On Tue, Aug 02 2022, Ricardo Cañuelo <ricardo.canuelo@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> > --- > 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.
