xref: /openbmc/qemu/docs/devel/virtio-backends.rst (revision ab1b2ba9)
1..
2   Copyright (c) 2022, Linaro Limited
3   Written by Alex Bennée
4
5Writing VirtIO backends for QEMU
6================================
7
8This document attempts to outline the information a developer needs to
9know to write device emulations in QEMU. It is specifically focused on
10implementing VirtIO devices. For VirtIO the frontend is the driver
11running on the guest. The backend is the everything that QEMU needs to
12do to handle the emulation of the VirtIO device. This can be done
13entirely in QEMU, divided between QEMU and the kernel (vhost) or
14handled by a separate process which is configured by QEMU
15(vhost-user).
16
17VirtIO Transports
18-----------------
19
20VirtIO supports a number of different transports. While the details of
21the configuration and operation of the device will generally be the
22same QEMU represents them as different devices depending on the
23transport they use. For example -device virtio-foo represents the foo
24device using mmio and -device virtio-foo-pci is the same class of
25device using the PCI transport.
26
27Using the QEMU Object Model (QOM)
28---------------------------------
29
30Generally all devices in QEMU are super classes of ``TYPE_DEVICE``
31however VirtIO devices should be based on ``TYPE_VIRTIO_DEVICE`` which
32itself is derived from the base class. For example:
33
34.. code:: c
35
36  static const TypeInfo virtio_blk_info = {
37      .name = TYPE_VIRTIO_BLK,
38      .parent = TYPE_VIRTIO_DEVICE,
39      .instance_size = sizeof(VirtIOBlock),
40      .instance_init = virtio_blk_instance_init,
41      .class_init = virtio_blk_class_init,
42  };
43
44The author may decide to have a more expansive class hierarchy to
45support multiple device types. For example the Virtio GPU device:
46
47.. code:: c
48
49  static const TypeInfo virtio_gpu_base_info = {
50      .name = TYPE_VIRTIO_GPU_BASE,
51      .parent = TYPE_VIRTIO_DEVICE,
52      .instance_size = sizeof(VirtIOGPUBase),
53      .class_size = sizeof(VirtIOGPUBaseClass),
54      .class_init = virtio_gpu_base_class_init,
55      .abstract = true
56  };
57
58  static const TypeInfo vhost_user_gpu_info = {
59      .name = TYPE_VHOST_USER_GPU,
60      .parent = TYPE_VIRTIO_GPU_BASE,
61      .instance_size = sizeof(VhostUserGPU),
62      .instance_init = vhost_user_gpu_instance_init,
63      .instance_finalize = vhost_user_gpu_instance_finalize,
64      .class_init = vhost_user_gpu_class_init,
65  };
66
67  static const TypeInfo virtio_gpu_info = {
68      .name = TYPE_VIRTIO_GPU,
69      .parent = TYPE_VIRTIO_GPU_BASE,
70      .instance_size = sizeof(VirtIOGPU),
71      .class_size = sizeof(VirtIOGPUClass),
72      .class_init = virtio_gpu_class_init,
73  };
74
75defines a base class for the VirtIO GPU and then specialises two
76versions, one for the internal implementation and the other for the
77vhost-user version.
78
79VirtIOPCIProxy
80^^^^^^^^^^^^^^
81
82[AJB: the following is supposition and welcomes more informed
83opinions]
84
85Probably due to legacy from the pre-QOM days PCI VirtIO devices don't
86follow the normal hierarchy. Instead the a standalone object is based
87on the VirtIOPCIProxy class and the specific VirtIO instance is
88manually instantiated:
89
90.. code:: c
91
92  /*
93   * virtio-blk-pci: This extends VirtioPCIProxy.
94   */
95  #define TYPE_VIRTIO_BLK_PCI "virtio-blk-pci-base"
96  DECLARE_INSTANCE_CHECKER(VirtIOBlkPCI, VIRTIO_BLK_PCI,
97                           TYPE_VIRTIO_BLK_PCI)
98
99  struct VirtIOBlkPCI {
100      VirtIOPCIProxy parent_obj;
101      VirtIOBlock vdev;
102  };
103
104  static Property virtio_blk_pci_properties[] = {
105      DEFINE_PROP_UINT32("class", VirtIOPCIProxy, class_code, 0),
106      DEFINE_PROP_BIT("ioeventfd", VirtIOPCIProxy, flags,
107                      VIRTIO_PCI_FLAG_USE_IOEVENTFD_BIT, true),
108      DEFINE_PROP_UINT32("vectors", VirtIOPCIProxy, nvectors,
109                         DEV_NVECTORS_UNSPECIFIED),
110      DEFINE_PROP_END_OF_LIST(),
111  };
112
113  static void virtio_blk_pci_realize(VirtIOPCIProxy *vpci_dev, Error **errp)
114  {
115      VirtIOBlkPCI *dev = VIRTIO_BLK_PCI(vpci_dev);
116      DeviceState *vdev = DEVICE(&dev->vdev);
117
118      ...
119
120      qdev_realize(vdev, BUS(&vpci_dev->bus), errp);
121  }
122
123  static void virtio_blk_pci_class_init(ObjectClass *klass, void *data)
124  {
125      DeviceClass *dc = DEVICE_CLASS(klass);
126      VirtioPCIClass *k = VIRTIO_PCI_CLASS(klass);
127      PCIDeviceClass *pcidev_k = PCI_DEVICE_CLASS(klass);
128
129      set_bit(DEVICE_CATEGORY_STORAGE, dc->categories);
130      device_class_set_props(dc, virtio_blk_pci_properties);
131      k->realize = virtio_blk_pci_realize;
132      pcidev_k->vendor_id = PCI_VENDOR_ID_REDHAT_QUMRANET;
133      pcidev_k->device_id = PCI_DEVICE_ID_VIRTIO_BLOCK;
134      pcidev_k->revision = VIRTIO_PCI_ABI_VERSION;
135      pcidev_k->class_id = PCI_CLASS_STORAGE_SCSI;
136  }
137
138  static void virtio_blk_pci_instance_init(Object *obj)
139  {
140      VirtIOBlkPCI *dev = VIRTIO_BLK_PCI(obj);
141
142      virtio_instance_init_common(obj, &dev->vdev, sizeof(dev->vdev),
143                                  TYPE_VIRTIO_BLK);
144      object_property_add_alias(obj, "bootindex", OBJECT(&dev->vdev),
145                                "bootindex");
146  }
147
148  static const VirtioPCIDeviceTypeInfo virtio_blk_pci_info = {
149      .base_name              = TYPE_VIRTIO_BLK_PCI,
150      .generic_name           = "virtio-blk-pci",
151      .transitional_name      = "virtio-blk-pci-transitional",
152      .non_transitional_name  = "virtio-blk-pci-non-transitional",
153      .instance_size = sizeof(VirtIOBlkPCI),
154      .instance_init = virtio_blk_pci_instance_init,
155      .class_init    = virtio_blk_pci_class_init,
156  };
157
158Here you can see the instance_init has to manually instantiate the
159underlying ``TYPE_VIRTIO_BLOCK`` object and link an alias for one of
160it's properties to the PCI device.
161
162
163Back End Implementations
164------------------------
165
166There are a number of places where the implementation of the backend
167can be done:
168
169* in QEMU itself
170* in the host kernel (a.k.a vhost)
171* in a separate process (a.k.a. vhost-user)
172
173vhost_ops vs TYPE_VHOST_USER_BACKEND
174^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
175
176There are two choices to how to implement vhost code. Most of the code
177which has to work with either vhost or vhost-user uses
178``vhost_dev_init()`` to instantiate the appropriate backend. This
179means including a ``struct vhost_dev`` in the main object structure.
180
181For vhost-user devices you also need to add code to track the
182initialisation of the ``chardev`` device used for the control socket
183between QEMU and the external vhost-user process.
184
185If you only need to implement a vhost-user backed the other option is
186a use a QOM-ified version of vhost-user.
187
188.. code:: c
189
190  static void
191  vhost_user_gpu_instance_init(Object *obj)
192  {
193      VhostUserGPU *g = VHOST_USER_GPU(obj);
194
195      g->vhost = VHOST_USER_BACKEND(object_new(TYPE_VHOST_USER_BACKEND));
196      object_property_add_alias(obj, "chardev",
197                                OBJECT(g->vhost), "chardev");
198  }
199
200  static const TypeInfo vhost_user_gpu_info = {
201      .name = TYPE_VHOST_USER_GPU,
202      .parent = TYPE_VIRTIO_GPU_BASE,
203      .instance_size = sizeof(VhostUserGPU),
204      .instance_init = vhost_user_gpu_instance_init,
205      .instance_finalize = vhost_user_gpu_instance_finalize,
206      .class_init = vhost_user_gpu_class_init,
207  };
208
209Using it this way entails adding a ``struct VhostUserBackend`` to your
210core object structure and manually instantiating the backend. This
211sub-structure tracks both the ``vhost_dev`` and ``CharDev`` types
212needed for the connection. Instead of calling ``vhost_dev_init`` you
213would call ``vhost_user_backend_dev_init`` which does what is needed
214on your behalf.
215