Documentation/driver-api/virtio/virtio.rst

   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 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
  15 for paravirtualized devices implemented by a hypervisor, it can be used
  16 to interface any compliant device (real or emulated) with a driver.
  17
  18 For illustrative purposes, this document will focus on the common case
  19 of a Linux kernel running in a virtual machine and using paravirtualized
  20 devices provided by the hypervisor, which exposes them as virtio devices
  21 via standard mechanisms such as PCI.
  22
  23
  24 Device - Driver communication: virtqueues
  25 =========================================
  26
  27 Although the virtio devices are really an abstraction layer in the
  28 hypervisor, they're exposed to the guest as if they are physical devices
  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
  32 interrupt handling.
  33
  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
  36 devices so efficient) using specialized data structures called
  37 virtqueues, which are actually ring buffers [#f1]_ of buffer descriptors
  38 similar to the ones used in a network device:
  39
  40 .. kernel-doc:: include/uapi/linux/virtio_ring.h
  41     :identifiers: struct vring_desc
  42
  43 All the buffers the descriptors point to are allocated by the guest and
  44 used by the host either for reading or for writing but not for both.
  45
  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
  48 the data travels" blog post (`[2]`_) for an illustrated overview of how
  49 the host device and the guest driver communicate.
  50
  51 The :c:type:`vring_virtqueue` struct models a virtqueue, including the
  52 ring buffers and management data. Embedded in this struct is the
  53 :c:type:`virtqueue` struct, which is the data structure that's
  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 is triggered when the
  60 device has consumed the buffers provided by the driver. More
  61 specifically, the trigger will be an interrupt issued by the hypervisor
  62 (see vring_interrupt()). Interrupt request handlers are registered for
  63 a virtqueue during the virtqueue setup process (transport-specific).
  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 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.
  76
  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
  81 will present itself on the PCI bus with vendor 0x1af4 (Red Hat, Inc.)
  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.
  84
  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)::
  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
  95 then the virtio-pci driver is probed and, if the probing goes well, the
  96 device 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
 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
 124 driver's ``probe`` method.
 125
 126 At this point, the virtqueues will be allocated and configured by
 127 calling the appropriate ``virtio_find`` helper function, such as
 128 virtio_find_single_vq() or virtio_find_vqs(), which will end up calling
 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/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
 141 https://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.