driver-api/virtio/writing_virtio_drivers.rst

1 .. SPDX-License-Identifier: GPL-2.0
6 Writing Virtio Drivers
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.
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
24 virtqueue definitions in the device. A basic driver skeleton could look
27 	#include <linux/virtio.h>
32 	/* device private data (one per device) */
39 		struct virtio_dummy_dev *dev = vq->vdev->priv;
43 		while ((buf = virtqueue_get_buf(dev->vq, &len)) != NULL) {
52 		/* initialize device data */
55 			return -ENOMEM;
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)) {
61 			return PTR_ERR(dev->vq);
64 		vdev->priv = dev;
66 		/* from this point on, the device can notify and get callbacks */
74 		struct virtio_dummy_dev *dev = vdev->priv;
78 		 * vdev->config->reset(vdev)
83 		while ((buf = virtqueue_detach_unused_buf(dev->vq)) != NULL) {
88 		vdev->config->del_vqs(vdev);
107 	MODULE_DEVICE_TABLE(virtio, id_table);
108 	MODULE_DESCRIPTION("Dummy virtio driver");
111 The device id ``VIRTIO_ID_DUMMY`` here is a placeholder, virtio drivers
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.
121 (memory allocation for the device data) and initializes the
123 notify the device that the driver is ready to manage the device
127 .. kernel-doc:: include/linux/virtio_config.h
137 when the device notifies the driver after it finishes processing a
139 that's only the second half of the virtio device-driver communication
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
147 need to add one input `scatterlist` (for the device to fill in), one
148 output `scatterlist` (for the device to consume) or multiple
151 hypervisor that implements the device::
155 	virtqueue_add_inbuf(dev->vq, sg, 1, buffer, GFP_ATOMIC);
156 	virtqueue_kick(dev->vq);
158 .. kernel-doc:: drivers/virtio/virtio_ring.c
161 .. kernel-doc:: drivers/virtio/virtio_ring.c
164 .. kernel-doc:: drivers/virtio/virtio_ring.c
167 Then, after the device has read or written the buffers prepared by the
169 read the data produced by the device (if the virtqueue was set up with
171 consumed by the device:
173 .. kernel-doc:: drivers/virtio/virtio_ring.c
176 The virtqueue callbacks can be disabled and re-enabled using the
178 respectively. See drivers/virtio/virtio_ring.c for more details:
180 .. kernel-doc:: drivers/virtio/virtio_ring.c
183 .. kernel-doc:: drivers/virtio/virtio_ring.c
188 device or the virtqueue (virtio_reset_device()).
194 _`[1]` Virtio Spec v1.2:
195 https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html