Documentation/driver-api/virtio/writing_virtio_drivers.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 .. _writing_virtio_drivers:
   4
   5 ======================
   6 Writing Virtio Drivers
   7 ======================
   8
   9 Introduction
  10 ============
  11
  12 This document serves as a basic guideline for driver programmers that
  13 need to hack a new virtio driver or understand the essentials of the
  14 existing ones. See :ref:`Virtio on Linux <virtio>` for a general
  15 overview of virtio.
  16
  17
  18 Driver boilerplate
  19 ==================
  20
  21 As a bare minimum, a virtio driver needs to register in the virtio bus
  22 and configure the virtqueues for the device according to its spec, the
  23 configuration of the virtqueues in the driver side must match the
  24 virtqueue definitions in the device. A basic driver skeleton could look
  25 like this::
  26
  27         #include <linux/virtio.h>
  28         #include <linux/virtio_ids.h>
  29         #include <linux/virtio_config.h>
  30         #include <linux/module.h>
  31
  32         /* device private data (one per device) */
  33         struct virtio_dummy_dev {
  34                 struct virtqueue *vq;
  35         };
  36
  37         static void virtio_dummy_recv_cb(struct virtqueue *vq)
  38         {
  39                 struct virtio_dummy_dev *dev = vq->vdev->priv;
  40                 char *buf;
  41                 unsigned int len;
  42
  43                 while ((buf = virtqueue_get_buf(dev->vq, &len)) != NULL) {
  44                         /* process the received data */
  45                 }
  46         }
  47
  48         static int virtio_dummy_probe(struct virtio_device *vdev)
  49         {
  50                 struct virtio_dummy_dev *dev = NULL;
  51
  52                 /* initialize device data */
  53                 dev = kzalloc(sizeof(struct virtio_dummy_dev), GFP_KERNEL);
  54                 if (!dev)
  55                         return -ENOMEM;
  56
  57                 /* the device has a single virtqueue */
  58                 dev->vq = virtio_find_single_vq(vdev, virtio_dummy_recv_cb, "input");
  59                 if (IS_ERR(dev->vq)) {
  60                         kfree(dev);
  61                         return PTR_ERR(dev->vq);
  62
  63                 }
  64                 vdev->priv = dev;
  65
  66                 /* from this point on, the device can notify and get callbacks */
  67                 virtio_device_ready(vdev);
  68
  69                 return 0;
  70         }
  71
  72         static void virtio_dummy_remove(struct virtio_device *vdev)
  73         {
  74                 struct virtio_dummy_dev *dev = vdev->priv;
  75
  76                 /*
  77                  * disable vq interrupts: equivalent to
  78                  * vdev->config->reset(vdev)
  79                  */
  80                 virtio_reset_device(vdev);
  81
  82                 /* detach unused buffers */
  83                 while ((buf = virtqueue_detach_unused_buf(dev->vq)) != NULL) {
  84                         kfree(buf);
  85                 }
  86
  87                 /* remove virtqueues */
  88                 vdev->config->del_vqs(vdev);
  89
  90                 kfree(dev);
  91         }
  92
  93         static const struct virtio_device_id id_table[] = {
  94                 { VIRTIO_ID_DUMMY, VIRTIO_DEV_ANY_ID },
  95                 { 0 },
  96         };
  97
  98         static struct virtio_driver virtio_dummy_driver = {
  99                 .driver.name =  KBUILD_MODNAME,
 100                 .driver.owner = THIS_MODULE,
 101                 .id_table =     id_table,
 102                 .probe =        virtio_dummy_probe,
 103                 .remove =       virtio_dummy_remove,
 104         };
 105
 106         module_virtio_driver(virtio_dummy_driver);
 107         MODULE_DEVICE_TABLE(virtio, id_table);
 108         MODULE_DESCRIPTION("Dummy virtio driver");
 109         MODULE_LICENSE("GPL");
 110
 111 The device id ``VIRTIO_ID_DUMMY`` here is a placeholder, virtio drivers
 112 should be added only for devices that are defined in the spec, see
 113 include/uapi/linux/virtio_ids.h. Device ids need to be at least reserved
 114 in the virtio spec before being added to that file.
 115
 116 If your driver doesn't have to do anything special in its ``init`` and
 117 ``exit`` methods, you can use the module_virtio_driver() helper to
 118 reduce the amount of boilerplate code.
 119
 120 The ``probe`` method does the minimum driver setup in this case
 121 (memory allocation for the device data) and initializes the
 122 virtqueue. virtio_device_ready() is used to enable the virtqueue and to
 123 notify the device that the driver is ready to manage the device
 124 ("DRIVER_OK"). The virtqueues are anyway enabled automatically by the
 125 core after ``probe`` returns.
 126
 127 .. kernel-doc:: include/linux/virtio_config.h
 128     :identifiers: virtio_device_ready
 129
 130 In any case, the virtqueues need to be enabled before adding buffers to
 131 them.
 132
 133 Sending and receiving data
 134 ==========================
 135
 136 The virtio_dummy_recv_cb() callback in the code above will be triggered
 137 when the device notifies the driver after it finishes processing a
 138 descriptor or descriptor chain, either for reading or writing. However,
 139 that's only the second half of the virtio device-driver communication
 140 process, as the communication is always started by the driver regardless
 141 of the direction of the data transfer.
 142
 143 To configure a buffer transfer from the driver to the device, first you
 144 have to add the buffers -- packed as `scatterlists` -- to the
 145 appropriate virtqueue using any of the virtqueue_add_inbuf(),
 146 virtqueue_add_outbuf() or virtqueue_add_sgs(), depending on whether you
 147 need to add one input `scatterlist` (for the device to fill in), one
 148 output `scatterlist` (for the device to consume) or multiple
 149 `scatterlists`, respectively. Then, once the virtqueue is set up, a call
 150 to virtqueue_kick() sends a notification that will be serviced by the
 151 hypervisor that implements the device::
 152
 153         struct scatterlist sg[1];
 154         sg_init_one(sg, buffer, BUFLEN);
 155         virtqueue_add_inbuf(dev->vq, sg, 1, buffer, GFP_ATOMIC);
 156         virtqueue_kick(dev->vq);
 157
 158 .. kernel-doc:: drivers/virtio/virtio_ring.c
 159     :identifiers: virtqueue_add_inbuf
 160
 161 .. kernel-doc:: drivers/virtio/virtio_ring.c
 162     :identifiers: virtqueue_add_outbuf
 163
 164 .. kernel-doc:: drivers/virtio/virtio_ring.c
 165     :identifiers: virtqueue_add_sgs
 166
 167 Then, after the device has read or written the buffers prepared by the
 168 driver and notifies it back, the driver can call virtqueue_get_buf() to
 169 read the data produced by the device (if the virtqueue was set up with
 170 input buffers) or simply to reclaim the buffers if they were already
 171 consumed by the device:
 172
 173 .. kernel-doc:: drivers/virtio/virtio_ring.c
 174     :identifiers: virtqueue_get_buf_ctx
 175
 176 The virtqueue callbacks can be disabled and re-enabled using the
 177 virtqueue_disable_cb() and the family of virtqueue_enable_cb() functions
 178 respectively. See drivers/virtio/virtio_ring.c for more details:
 179
 180 .. kernel-doc:: drivers/virtio/virtio_ring.c
 181     :identifiers: virtqueue_disable_cb
 182
 183 .. kernel-doc:: drivers/virtio/virtio_ring.c
 184     :identifiers: virtqueue_enable_cb
 185
 186 But note that some spurious callbacks can still be triggered under
 187 certain scenarios. The way to disable callbacks reliably is to reset the
 188 device or the virtqueue (virtio_reset_device()).
 189
 190
 191 References
 192 ==========
 193
 194 _`[1]` Virtio Spec v1.2:
 195 https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
 196
 197 Check for later versions of the spec as well.