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 to `[2]`_ for an illustrated 48overview of how the host device and the guest driver communicate. 49 50The :c:type:`vring_virtqueue` struct models a virtqueue, including the 51ring buffers and management data. Embedded in this struct is the 52:c:type:`virtqueue` struct, which is the data structure that's 53ultimately used by virtio drivers: 54 55.. kernel-doc:: include/linux/virtio.h 56 :identifiers: struct virtqueue 57 58The callback function pointed by this struct is triggered when the 59device has consumed the buffers provided by the driver. More 60specifically, the trigger will be an interrupt issued by the hypervisor 61(see vring_interrupt()). Interrupt request handlers are registered for 62a virtqueue during the virtqueue setup process (transport-specific). 63 64.. kernel-doc:: drivers/virtio/virtio_ring.c 65 :identifiers: vring_interrupt 66 67 68Device discovery and probing 69============================ 70 71In the kernel, the virtio core contains the virtio bus driver and 72transport-specific drivers like `virtio-pci` and `virtio-mmio`. Then 73there are individual virtio drivers for specific device types that are 74registered to the virtio bus driver. 75 76How a virtio device is found and configured by the kernel depends on how 77the hypervisor defines it. Taking the `QEMU virtio-console 78<https://gitlab.com/qemu-project/qemu/-/blob/master/hw/char/virtio-console.c>`__ 79device as an example. When using PCI as a transport method, the device 80will present itself on the PCI bus with vendor 0x1af4 (Red Hat, Inc.) 81and device id 0x1003 (virtio console), as defined in the spec, so the 82kernel will detect it as it would do with any other PCI device. 83 84During the PCI enumeration process, if a device is found to match the 85virtio-pci driver (according to the virtio-pci device table, any PCI 86device with vendor id = 0x1af4):: 87 88 /* Qumranet donated their vendor ID for devices 0x1000 thru 0x10FF. */ 89 static const struct pci_device_id virtio_pci_id_table[] = { 90 { PCI_DEVICE(PCI_VENDOR_ID_REDHAT_QUMRANET, PCI_ANY_ID) }, 91 { 0 } 92 }; 93 94then the virtio-pci driver is probed and, if the probing goes well, the 95device is registered to the virtio bus:: 96 97 static int virtio_pci_probe(struct pci_dev *pci_dev, 98 const struct pci_device_id *id) 99 { 100 ... 101 102 if (force_legacy) { 103 rc = virtio_pci_legacy_probe(vp_dev); 104 /* Also try modern mode if we can't map BAR0 (no IO space). */ 105 if (rc == -ENODEV || rc == -ENOMEM) 106 rc = virtio_pci_modern_probe(vp_dev); 107 if (rc) 108 goto err_probe; 109 } else { 110 rc = virtio_pci_modern_probe(vp_dev); 111 if (rc == -ENODEV) 112 rc = virtio_pci_legacy_probe(vp_dev); 113 if (rc) 114 goto err_probe; 115 } 116 117 ... 118 119 rc = register_virtio_device(&vp_dev->vdev); 120 121When the device is registered to the virtio bus the kernel will look 122for a driver in the bus that can handle the device and call that 123driver's ``probe`` method. 124 125It's at this stage that the virtqueues will be allocated and configured 126by calling the appropriate ``virtio_find`` helper function, such as 127virtio_find_single_vq() or virtio_find_vqs(), which will end up 128calling a transport-specific ``find_vqs`` method. 129 130 131References 132========== 133 134_`[1]` Virtio Spec v1.2: 135https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html 136 137Check for later versions of the spec as well. 138 139_`[2]` Virtqueues and virtio ring: How the data travels 140https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels 141 142.. rubric:: Footnotes 143 144.. [#f1] that's why they may be also referred to as virtrings. 145