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);
106 	MODULE_DEVICE_TABLE(virtio, id_table);
107 	MODULE_DESCRIPTION("Dummy virtio driver");
110 The device id ``VIRTIO_ID_DUMMY`` here is a placeholder, virtio drivers
112 include/uapi/linux/virtio_ids.h. Device ids need to be at least reserved
113 in the virtio spec before being added to that file.
120 (memory allocation for the device data) and initializes the
122 notify the device that the driver is ready to manage the device
126 .. kernel-doc:: include/linux/virtio_config.h
136 when the device notifies the driver after it finishes processing a
138 that's only the second half of the virtio device-driver communication
142 To configure a buffer transfer from the driver to the device, first you
143 have to add the buffers -- packed as `scatterlists` -- to the
146 need to add one input `scatterlist` (for the device to fill in), one
147 output `scatterlist` (for the device to consume) or multiple
150 hypervisor that implements the device::
154 	virtqueue_add_inbuf(dev->vq, sg, 1, buffer, GFP_ATOMIC);
155 	virtqueue_kick(dev->vq);
157 .. kernel-doc:: drivers/virtio/virtio_ring.c
160 .. kernel-doc:: drivers/virtio/virtio_ring.c
163 .. kernel-doc:: drivers/virtio/virtio_ring.c
166 Then, after the device has read or written the buffers prepared by the
168 read the data produced by the device (if the virtqueue was set up with
170 consumed by the device:
172 .. kernel-doc:: drivers/virtio/virtio_ring.c
175 The virtqueue callbacks can be disabled and re-enabled using the
177 respectively. See drivers/virtio/virtio_ring.c for more details:
179 .. kernel-doc:: drivers/virtio/virtio_ring.c
182 .. kernel-doc:: drivers/virtio/virtio_ring.c
187 device or the virtqueue (virtio_reset_device()).
193 _`[1]` Virtio Spec v1.2:
194 https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html