virtio.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. _virtio:
  4
  5===============
  6Virtio on Linux
  7===============
  8
  9Introduction
 10============
 11
 12Virtio is an open standard that defines a protocol for communication
 13between drivers and devices of different types, see Chapter 5 ("Device
 14Types") of the virtio spec (`[1]`_). Originally developed as a standard
 15for paravirtualized devices implemented by a hypervisor, it can be used
 16to interface any compliant device (real or emulated) with a driver.
 17
 18For illustrative purposes, this document will focus on the common case
 19of a Linux kernel running in a virtual machine and using paravirtualized
 20devices provided by the hypervisor, which exposes them as virtio devices
 21via standard mechanisms such as PCI.
 22
 23
 24Device - Driver communication: virtqueues
 25=========================================
 26
 27Although the virtio devices are really an abstraction layer in the
 28hypervisor, they're exposed to the guest as if they are physical devices
 29using a specific transport method -- PCI, MMIO or CCW -- that is
 30orthogonal to the device itself. The virtio spec defines these transport
 31methods in detail, including device discovery, capabilities and
 32interrupt handling.
 33
 34The communication between the driver in the guest OS and the device in
 35the hypervisor is done through shared memory (that's what makes virtio
 36devices so efficient) using specialized data structures called
 37virtqueues, which are actually ring buffers [#f1]_ of buffer descriptors
 38similar to the ones used in a network device:
 39
 40.. kernel-doc:: include/uapi/linux/virtio_ring.h
 41    :identifiers: struct vring_desc
 42
 43All the buffers the descriptors point to are allocated by the guest and
 44used by the host either for reading or for writing but not for both.
 45
 46Refer to Chapter 2.5 ("Virtqueues") of the virtio spec (`[1]`_) for the
 47reference definitions of virtqueues and "Virtqueues and virtio ring: How
 48the data travels" blog post (`[2]`_) for an illustrated overview of how
 49the host device and the guest driver communicate.
 50
 51The :c:type:`vring_virtqueue` struct models a virtqueue, including the
 52ring buffers and management data. Embedded in this struct is the
 53:c:type:`virtqueue` struct, which is the data structure that's
 54ultimately used by virtio drivers:
 55
 56.. kernel-doc:: include/linux/virtio.h
 57    :identifiers: struct virtqueue
 58
 59The callback function pointed by this struct is triggered when the
 60device has consumed the buffers provided by the driver. More
 61specifically, the trigger will be an interrupt issued by the hypervisor
 62(see vring_interrupt()). Interrupt request handlers are registered for
 63a virtqueue during the virtqueue setup process (transport-specific).
 64
 65.. kernel-doc:: drivers/virtio/virtio_ring.c
 66    :identifiers: vring_interrupt
 67
 68
 69Device discovery and probing
 70============================
 71
 72In the kernel, the virtio core contains the virtio bus driver and
 73transport-specific drivers like `virtio-pci` and `virtio-mmio`. Then
 74there are individual virtio drivers for specific device types that are
 75registered to the virtio bus driver.
 76
 77How a virtio device is found and configured by the kernel depends on how
 78the hypervisor defines it. Taking the `QEMU virtio-console
 79<https://gitlab.com/qemu-project/qemu/-/blob/master/hw/char/virtio-console.c>`__
 80device as an example. When using PCI as a transport method, the device
 81will present itself on the PCI bus with vendor 0x1af4 (Red Hat, Inc.)
 82and device id 0x1003 (virtio console), as defined in the spec, so the
 83kernel will detect it as it would do with any other PCI device.
 84
 85During the PCI enumeration process, if a device is found to match the
 86virtio-pci driver (according to the virtio-pci device table, any PCI
 87device with vendor id = 0x1af4)::
 88
 89	/* Qumranet donated their vendor ID for devices 0x1000 thru 0x10FF. */
 90	static const struct pci_device_id virtio_pci_id_table[] = {
 91		{ PCI_DEVICE(PCI_VENDOR_ID_REDHAT_QUMRANET, PCI_ANY_ID) },
 92		{ 0 }
 93	};
 94
 95then the virtio-pci driver is probed and, if the probing goes well, the
 96device is registered to the virtio bus::
 97
 98	static int virtio_pci_probe(struct pci_dev *pci_dev,
 99				    const struct pci_device_id *id)
100	{
101		...
102
103		if (force_legacy) {
104			rc = virtio_pci_legacy_probe(vp_dev);
105			/* Also try modern mode if we can't map BAR0 (no IO space). */
106			if (rc == -ENODEV || rc == -ENOMEM)
107				rc = virtio_pci_modern_probe(vp_dev);
108			if (rc)
109				goto err_probe;
110		} else {
111			rc = virtio_pci_modern_probe(vp_dev);
112			if (rc == -ENODEV)
113				rc = virtio_pci_legacy_probe(vp_dev);
114			if (rc)
115				goto err_probe;
116		}
117
118		...
119
120		rc = register_virtio_device(&vp_dev->vdev);
121
122When the device is registered to the virtio bus the kernel will look
123for a driver in the bus that can handle the device and call that
124driver's ``probe`` method.
125
126At this point, the virtqueues will be allocated and configured by
127calling the appropriate ``virtio_find`` helper function, such as
128virtio_find_single_vq() or virtio_find_vqs(), which will end up calling
129a transport-specific ``find_vqs`` method.
130
131
132References
133==========
134
135_`[1]` Virtio Spec v1.2:
136https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
137
138.. Check for later versions of the spec as well.
139
140_`[2]` Virtqueues and virtio ring: How the data travels
141https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels
142
143.. rubric:: Footnotes
144
145.. [#f1] that's why they may be also referred to as virtrings.