1.. SPDX-License-Identifier: GPL-2.0 2 3.. _writing_virtio_drivers: 4 5====================== 6Writing Virtio Drivers 7====================== 8 9Introduction 10============ 11 12This document serves as a basic guideline for driver programmers that 13need to hack a new virtio driver or understand the essentials of the 14existing ones. See :ref:`Virtio on Linux <virtio>` for a general 15overview of virtio. 16 17 18Driver boilerplate 19================== 20 21As a bare minimum, a virtio driver needs to register in the virtio bus 22and configure the virtqueues for the device according to its spec, the 23configuration of the virtqueues in the driver side must match the 24virtqueue definitions in the device. A basic driver skeleton could look 25like 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 111The device id ``VIRTIO_ID_DUMMY`` here is a placeholder, virtio drivers 112should be added only for devices that are defined in the spec, see 113include/uapi/linux/virtio_ids.h. Device ids need to be at least reserved 114in the virtio spec before being added to that file. 115 116If 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 118reduce the amount of boilerplate code. 119 120The ``probe`` method does the minimum driver setup in this case 121(memory allocation for the device data) and initializes the 122virtqueue. virtio_device_ready() is used to enable the virtqueue and to 123notify the device that the driver is ready to manage the device 124("DRIVER_OK"). The virtqueues are anyway enabled automatically by the 125core after ``probe`` returns. 126 127.. kernel-doc:: include/linux/virtio_config.h 128 :identifiers: virtio_device_ready 129 130In any case, the virtqueues need to be enabled before adding buffers to 131them. 132 133Sending and receiving data 134========================== 135 136The virtio_dummy_recv_cb() callback in the code above will be triggered 137when the device notifies the driver after it finishes processing a 138descriptor or descriptor chain, either for reading or writing. However, 139that's only the second half of the virtio device-driver communication 140process, as the communication is always started by the driver regardless 141of the direction of the data transfer. 142 143To configure a buffer transfer from the driver to the device, first you 144have to add the buffers -- packed as `scatterlists` -- to the 145appropriate virtqueue using any of the virtqueue_add_inbuf(), 146virtqueue_add_outbuf() or virtqueue_add_sgs(), depending on whether you 147need to add one input `scatterlist` (for the device to fill in), one 148output `scatterlist` (for the device to consume) or multiple 149`scatterlists`, respectively. Then, once the virtqueue is set up, a call 150to virtqueue_kick() sends a notification that will be serviced by the 151hypervisor 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 167Then, after the device has read or written the buffers prepared by the 168driver and notifies it back, the driver can call virtqueue_get_buf() to 169read the data produced by the device (if the virtqueue was set up with 170input buffers) or simply to reclaim the buffers if they were already 171consumed by the device: 172 173.. kernel-doc:: drivers/virtio/virtio_ring.c 174 :identifiers: virtqueue_get_buf_ctx 175 176The virtqueue callbacks can be disabled and re-enabled using the 177virtqueue_disable_cb() and the family of virtqueue_enable_cb() functions 178respectively. 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 186But note that some spurious callbacks can still be triggered under 187certain scenarios. The way to disable callbacks reliably is to reset the 188device or the virtqueue (virtio_reset_device()). 189 190 191References 192========== 193 194_`[1]` Virtio Spec v1.2: 195https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html 196 197Check for later versions of the spec as well. 198