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