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