driver-api/virtio/virtio.rst

1 .. SPDX-License-Identifier: GPL-2.0
6 Virtio on Linux
12 Virtio is an open standard that defines a protocol for communication
13 between drivers and devices of different types, see Chapter 5 ("Device
14 Types") of the virtio spec (`[1]`_). Originally developed as a standard
16 to interface any compliant device (real or emulated) with a driver.
20 devices provided by the hypervisor, which exposes them as virtio devices
24 Device - Driver communication: virtqueues
27 Although the virtio devices are really an abstraction layer in the
29 using a specific transport method -- PCI, MMIO or CCW -- that is
30 orthogonal to the device itself. The virtio spec defines these transport
31 methods in detail, including device discovery, capabilities and
34 The communication between the driver in the guest OS and the device in
35 the hypervisor is done through shared memory (that's what makes virtio
38 similar to the ones used in a network device:
40 .. kernel-doc:: include/uapi/linux/virtio_ring.h
46 Refer to Chapter 2.5 ("Virtqueues") of the virtio spec (`[1]`_) for the
47 reference definitions of virtqueues and "Virtqueues and virtio ring: How
49 the host device and the guest driver communicate.
54 ultimately used by virtio drivers:
56 .. kernel-doc:: include/linux/virtio.h
60 device has consumed the buffers provided by the driver. More
63 a virtqueue during the virtqueue setup process (transport-specific).
65 .. kernel-doc:: drivers/virtio/virtio_ring.c
69 Device discovery and probing
72 In the kernel, the virtio core contains the virtio bus driver and
73 transport-specific drivers like `virtio-pci` and `virtio-mmio`. Then
74 there are individual virtio drivers for specific device types that are
75 registered to the virtio bus driver.
77 How a virtio device is found and configured by the kernel depends on how
78 the hypervisor defines it. Taking the `QEMU virtio-console
79 <https://gitlab.com/qemu-project/qemu/-/blob/master/hw/char/virtio-console.c>`__
80 device as an example. When using PCI as a transport method, the device
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 other PCI device.
85 During the PCI enumeration process, if a device is found to match the
86 virtio-pci driver (according to the virtio-pci device table, any PCI
87 device with vendor id = 0x1af4)::
95 then the virtio-pci driver is probed and, if the probing goes well, the
96 device is registered to the virtio bus::
106 			if (rc == -ENODEV || rc == -ENOMEM)
112 			if (rc == -ENODEV)
120 		rc = register_virtio_device(&vp_dev->vdev);
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 device and call that
129 a transport-specific ``find_vqs`` method.
135 _`[1]` Virtio Spec v1.2:
136 https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
140 _`[2]` Virtqueues and virtio ring: How the data travels
141 https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels