meson: convert hw/vfio
[qemu.git] / docs / interop / vhost-user.rst
1 ===================
2 Vhost-user Protocol
3 ===================
4 :Copyright: 2014 Virtual Open Systems Sarl.
5 :Copyright: 2019 Intel Corporation
6 :Licence: This work is licensed under the terms of the GNU GPL,
7           version 2 or later. See the COPYING file in the top-level
8           directory.
9
10 .. contents:: Table of Contents
11
12 Introduction
13 ============
14
15 This protocol is aiming to complement the ``ioctl`` interface used to
16 control the vhost implementation in the Linux kernel. It implements
17 the control plane needed to establish virtqueue sharing with a user
18 space process on the same host. It uses communication over a Unix
19 domain socket to share file descriptors in the ancillary data of the
20 message.
21
22 The protocol defines 2 sides of the communication, *master* and
23 *slave*. *Master* is the application that shares its virtqueues, in
24 our case QEMU. *Slave* is the consumer of the virtqueues.
25
26 In the current implementation QEMU is the *master*, and the *slave* is
27 the external process consuming the virtio queues, for example a
28 software Ethernet switch running in user space, such as Snabbswitch,
29 or a block device backend processing read & write to a virtual
30 disk. In order to facilitate interoperability between various backend
31 implementations, it is recommended to follow the :ref:`Backend program
32 conventions <backend_conventions>`.
33
34 *Master* and *slave* can be either a client (i.e. connecting) or
35 server (listening) in the socket communication.
36
37 Message Specification
38 =====================
39
40 .. Note:: All numbers are in the machine native byte order.
41
42 A vhost-user message consists of 3 header fields and a payload.
43
44 +---------+-------+------+---------+
45 | request | flags | size | payload |
46 +---------+-------+------+---------+
47
48 Header
49 ------
50
51 :request: 32-bit type of the request
52
53 :flags: 32-bit bit field
54
55 - Lower 2 bits are the version (currently 0x01)
56 - Bit 2 is the reply flag - needs to be sent on each reply from the slave
57 - Bit 3 is the need_reply flag - see :ref:`REPLY_ACK <reply_ack>` for
58   details.
59
60 :size: 32-bit size of the payload
61
62 Payload
63 -------
64
65 Depending on the request type, **payload** can be:
66
67 A single 64-bit integer
68 ^^^^^^^^^^^^^^^^^^^^^^^
69
70 +-----+
71 | u64 |
72 +-----+
73
74 :u64: a 64-bit unsigned integer
75
76 A vring state description
77 ^^^^^^^^^^^^^^^^^^^^^^^^^
78
79 +-------+-----+
80 | index | num |
81 +-------+-----+
82
83 :index: a 32-bit index
84
85 :num: a 32-bit number
86
87 A vring address description
88 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
89
90 +-------+-------+------+------------+------+-----------+-----+
91 | index | flags | size | descriptor | used | available | log |
92 +-------+-------+------+------------+------+-----------+-----+
93
94 :index: a 32-bit vring index
95
96 :flags: a 32-bit vring flags
97
98 :descriptor: a 64-bit ring address of the vring descriptor table
99
100 :used: a 64-bit ring address of the vring used ring
101
102 :available: a 64-bit ring address of the vring available ring
103
104 :log: a 64-bit guest address for logging
105
106 Note that a ring address is an IOVA if ``VIRTIO_F_IOMMU_PLATFORM`` has
107 been negotiated. Otherwise it is a user address.
108
109 Memory regions description
110 ^^^^^^^^^^^^^^^^^^^^^^^^^^
111
112 +-------------+---------+---------+-----+---------+
113 | num regions | padding | region0 | ... | region7 |
114 +-------------+---------+---------+-----+---------+
115
116 :num regions: a 32-bit number of regions
117
118 :padding: 32-bit
119
120 A region is:
121
122 +---------------+------+--------------+-------------+
123 | guest address | size | user address | mmap offset |
124 +---------------+------+--------------+-------------+
125
126 :guest address: a 64-bit guest address of the region
127
128 :size: a 64-bit size
129
130 :user address: a 64-bit user address
131
132 :mmap offset: 64-bit offset where region starts in the mapped memory
133
134 Log description
135 ^^^^^^^^^^^^^^^
136
137 +----------+------------+
138 | log size | log offset |
139 +----------+------------+
140
141 :log size: size of area used for logging
142
143 :log offset: offset from start of supplied file descriptor where
144              logging starts (i.e. where guest address 0 would be
145              logged)
146
147 An IOTLB message
148 ^^^^^^^^^^^^^^^^
149
150 +------+------+--------------+-------------------+------+
151 | iova | size | user address | permissions flags | type |
152 +------+------+--------------+-------------------+------+
153
154 :iova: a 64-bit I/O virtual address programmed by the guest
155
156 :size: a 64-bit size
157
158 :user address: a 64-bit user address
159
160 :permissions flags: an 8-bit value:
161   - 0: No access
162   - 1: Read access
163   - 2: Write access
164   - 3: Read/Write access
165
166 :type: an 8-bit IOTLB message type:
167   - 1: IOTLB miss
168   - 2: IOTLB update
169   - 3: IOTLB invalidate
170   - 4: IOTLB access fail
171
172 Virtio device config space
173 ^^^^^^^^^^^^^^^^^^^^^^^^^^
174
175 +--------+------+-------+---------+
176 | offset | size | flags | payload |
177 +--------+------+-------+---------+
178
179 :offset: a 32-bit offset of virtio device's configuration space
180
181 :size: a 32-bit configuration space access size in bytes
182
183 :flags: a 32-bit value:
184   - 0: Vhost master messages used for writeable fields
185   - 1: Vhost master messages used for live migration
186
187 :payload: Size bytes array holding the contents of the virtio
188           device's configuration space
189
190 Vring area description
191 ^^^^^^^^^^^^^^^^^^^^^^
192
193 +-----+------+--------+
194 | u64 | size | offset |
195 +-----+------+--------+
196
197 :u64: a 64-bit integer contains vring index and flags
198
199 :size: a 64-bit size of this area
200
201 :offset: a 64-bit offset of this area from the start of the
202          supplied file descriptor
203
204 Inflight description
205 ^^^^^^^^^^^^^^^^^^^^
206
207 +-----------+-------------+------------+------------+
208 | mmap size | mmap offset | num queues | queue size |
209 +-----------+-------------+------------+------------+
210
211 :mmap size: a 64-bit size of area to track inflight I/O
212
213 :mmap offset: a 64-bit offset of this area from the start
214               of the supplied file descriptor
215
216 :num queues: a 16-bit number of virtqueues
217
218 :queue size: a 16-bit size of virtqueues
219
220 C structure
221 -----------
222
223 In QEMU the vhost-user message is implemented with the following struct:
224
225 .. code:: c
226
227   typedef struct VhostUserMsg {
228       VhostUserRequest request;
229       uint32_t flags;
230       uint32_t size;
231       union {
232           uint64_t u64;
233           struct vhost_vring_state state;
234           struct vhost_vring_addr addr;
235           VhostUserMemory memory;
236           VhostUserLog log;
237           struct vhost_iotlb_msg iotlb;
238           VhostUserConfig config;
239           VhostUserVringArea area;
240           VhostUserInflight inflight;
241       };
242   } QEMU_PACKED VhostUserMsg;
243
244 Communication
245 =============
246
247 The protocol for vhost-user is based on the existing implementation of
248 vhost for the Linux Kernel. Most messages that can be sent via the
249 Unix domain socket implementing vhost-user have an equivalent ioctl to
250 the kernel implementation.
251
252 The communication consists of *master* sending message requests and
253 *slave* sending message replies. Most of the requests don't require
254 replies. Here is a list of the ones that do:
255
256 * ``VHOST_USER_GET_FEATURES``
257 * ``VHOST_USER_GET_PROTOCOL_FEATURES``
258 * ``VHOST_USER_GET_VRING_BASE``
259 * ``VHOST_USER_SET_LOG_BASE`` (if ``VHOST_USER_PROTOCOL_F_LOG_SHMFD``)
260 * ``VHOST_USER_GET_INFLIGHT_FD`` (if ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD``)
261
262 .. seealso::
263
264    :ref:`REPLY_ACK <reply_ack>`
265        The section on ``REPLY_ACK`` protocol extension.
266
267 There are several messages that the master sends with file descriptors passed
268 in the ancillary data:
269
270 * ``VHOST_USER_SET_MEM_TABLE``
271 * ``VHOST_USER_SET_LOG_BASE`` (if ``VHOST_USER_PROTOCOL_F_LOG_SHMFD``)
272 * ``VHOST_USER_SET_LOG_FD``
273 * ``VHOST_USER_SET_VRING_KICK``
274 * ``VHOST_USER_SET_VRING_CALL``
275 * ``VHOST_USER_SET_VRING_ERR``
276 * ``VHOST_USER_SET_SLAVE_REQ_FD``
277 * ``VHOST_USER_SET_INFLIGHT_FD`` (if ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD``)
278
279 If *master* is unable to send the full message or receives a wrong
280 reply it will close the connection. An optional reconnection mechanism
281 can be implemented.
282
283 If *slave* detects some error such as incompatible features, it may also
284 close the connection. This should only happen in exceptional circumstances.
285
286 Any protocol extensions are gated by protocol feature bits, which
287 allows full backwards compatibility on both master and slave.  As
288 older slaves don't support negotiating protocol features, a feature
289 bit was dedicated for this purpose::
290
291   #define VHOST_USER_F_PROTOCOL_FEATURES 30
292
293 Starting and stopping rings
294 ---------------------------
295
296 Client must only process each ring when it is started.
297
298 Client must only pass data between the ring and the backend, when the
299 ring is enabled.
300
301 If ring is started but disabled, client must process the ring without
302 talking to the backend.
303
304 For example, for a networking device, in the disabled state client
305 must not supply any new RX packets, but must process and discard any
306 TX packets.
307
308 If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the
309 ring is initialized in an enabled state.
310
311 If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is
312 initialized in a disabled state. Client must not pass data to/from the
313 backend until ring is enabled by ``VHOST_USER_SET_VRING_ENABLE`` with
314 parameter 1, or after it has been disabled by
315 ``VHOST_USER_SET_VRING_ENABLE`` with parameter 0.
316
317 Each ring is initialized in a stopped state, client must not process
318 it until ring is started, or after it has been stopped.
319
320 Client must start ring upon receiving a kick (that is, detecting that
321 file descriptor is readable) on the descriptor specified by
322 ``VHOST_USER_SET_VRING_KICK`` or receiving the in-band message
323 ``VHOST_USER_VRING_KICK`` if negotiated, and stop ring upon receiving
324 ``VHOST_USER_GET_VRING_BASE``.
325
326 While processing the rings (whether they are enabled or not), client
327 must support changing some configuration aspects on the fly.
328
329 Multiple queue support
330 ----------------------
331
332 Many devices have a fixed number of virtqueues.  In this case the master
333 already knows the number of available virtqueues without communicating with the
334 slave.
335
336 Some devices do not have a fixed number of virtqueues.  Instead the maximum
337 number of virtqueues is chosen by the slave.  The number can depend on host
338 resource availability or slave implementation details.  Such devices are called
339 multiple queue devices.
340
341 Multiple queue support allows the slave to advertise the maximum number of
342 queues.  This is treated as a protocol extension, hence the slave has to
343 implement protocol features first. The multiple queues feature is supported
344 only when the protocol feature ``VHOST_USER_PROTOCOL_F_MQ`` (bit 0) is set.
345
346 The max number of queues the slave supports can be queried with message
347 ``VHOST_USER_GET_QUEUE_NUM``. Master should stop when the number of requested
348 queues is bigger than that.
349
350 As all queues share one connection, the master uses a unique index for each
351 queue in the sent message to identify a specified queue.
352
353 The master enables queues by sending message ``VHOST_USER_SET_VRING_ENABLE``.
354 vhost-user-net has historically automatically enabled the first queue pair.
355
356 Slaves should always implement the ``VHOST_USER_PROTOCOL_F_MQ`` protocol
357 feature, even for devices with a fixed number of virtqueues, since it is simple
358 to implement and offers a degree of introspection.
359
360 Masters must not rely on the ``VHOST_USER_PROTOCOL_F_MQ`` protocol feature for
361 devices with a fixed number of virtqueues.  Only true multiqueue devices
362 require this protocol feature.
363
364 Migration
365 ---------
366
367 During live migration, the master may need to track the modifications
368 the slave makes to the memory mapped regions. The client should mark
369 the dirty pages in a log. Once it complies to this logging, it may
370 declare the ``VHOST_F_LOG_ALL`` vhost feature.
371
372 To start/stop logging of data/used ring writes, server may send
373 messages ``VHOST_USER_SET_FEATURES`` with ``VHOST_F_LOG_ALL`` and
374 ``VHOST_USER_SET_VRING_ADDR`` with ``VHOST_VRING_F_LOG`` in ring's
375 flags set to 1/0, respectively.
376
377 All the modifications to memory pointed by vring "descriptor" should
378 be marked. Modifications to "used" vring should be marked if
379 ``VHOST_VRING_F_LOG`` is part of ring's flags.
380
381 Dirty pages are of size::
382
383   #define VHOST_LOG_PAGE 0x1000
384
385 The log memory fd is provided in the ancillary data of
386 ``VHOST_USER_SET_LOG_BASE`` message when the slave has
387 ``VHOST_USER_PROTOCOL_F_LOG_SHMFD`` protocol feature.
388
389 The size of the log is supplied as part of ``VhostUserMsg`` which
390 should be large enough to cover all known guest addresses. Log starts
391 at the supplied offset in the supplied file descriptor.  The log
392 covers from address 0 to the maximum of guest regions. In pseudo-code,
393 to mark page at ``addr`` as dirty::
394
395   page = addr / VHOST_LOG_PAGE
396   log[page / 8] |= 1 << page % 8
397
398 Where ``addr`` is the guest physical address.
399
400 Use atomic operations, as the log may be concurrently manipulated.
401
402 Note that when logging modifications to the used ring (when
403 ``VHOST_VRING_F_LOG`` is set for this ring), ``log_guest_addr`` should
404 be used to calculate the log offset: the write to first byte of the
405 used ring is logged at this offset from log start. Also note that this
406 value might be outside the legal guest physical address range
407 (i.e. does not have to be covered by the ``VhostUserMemory`` table), but
408 the bit offset of the last byte of the ring must fall within the size
409 supplied by ``VhostUserLog``.
410
411 ``VHOST_USER_SET_LOG_FD`` is an optional message with an eventfd in
412 ancillary data, it may be used to inform the master that the log has
413 been modified.
414
415 Once the source has finished migration, rings will be stopped by the
416 source. No further update must be done before rings are restarted.
417
418 In postcopy migration the slave is started before all the memory has
419 been received from the source host, and care must be taken to avoid
420 accessing pages that have yet to be received.  The slave opens a
421 'userfault'-fd and registers the memory with it; this fd is then
422 passed back over to the master.  The master services requests on the
423 userfaultfd for pages that are accessed and when the page is available
424 it performs WAKE ioctl's on the userfaultfd to wake the stalled
425 slave.  The client indicates support for this via the
426 ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` feature.
427
428 Memory access
429 -------------
430
431 The master sends a list of vhost memory regions to the slave using the
432 ``VHOST_USER_SET_MEM_TABLE`` message.  Each region has two base
433 addresses: a guest address and a user address.
434
435 Messages contain guest addresses and/or user addresses to reference locations
436 within the shared memory.  The mapping of these addresses works as follows.
437
438 User addresses map to the vhost memory region containing that user address.
439
440 When the ``VIRTIO_F_IOMMU_PLATFORM`` feature has not been negotiated:
441
442 * Guest addresses map to the vhost memory region containing that guest
443   address.
444
445 When the ``VIRTIO_F_IOMMU_PLATFORM`` feature has been negotiated:
446
447 * Guest addresses are also called I/O virtual addresses (IOVAs).  They are
448   translated to user addresses via the IOTLB.
449
450 * The vhost memory region guest address is not used.
451
452 IOMMU support
453 -------------
454
455 When the ``VIRTIO_F_IOMMU_PLATFORM`` feature has been negotiated, the
456 master sends IOTLB entries update & invalidation by sending
457 ``VHOST_USER_IOTLB_MSG`` requests to the slave with a ``struct
458 vhost_iotlb_msg`` as payload. For update events, the ``iotlb`` payload
459 has to be filled with the update message type (2), the I/O virtual
460 address, the size, the user virtual address, and the permissions
461 flags. Addresses and size must be within vhost memory regions set via
462 the ``VHOST_USER_SET_MEM_TABLE`` request. For invalidation events, the
463 ``iotlb`` payload has to be filled with the invalidation message type
464 (3), the I/O virtual address and the size. On success, the slave is
465 expected to reply with a zero payload, non-zero otherwise.
466
467 The slave relies on the slave communcation channel (see :ref:`Slave
468 communication <slave_communication>` section below) to send IOTLB miss
469 and access failure events, by sending ``VHOST_USER_SLAVE_IOTLB_MSG``
470 requests to the master with a ``struct vhost_iotlb_msg`` as
471 payload. For miss events, the iotlb payload has to be filled with the
472 miss message type (1), the I/O virtual address and the permissions
473 flags. For access failure event, the iotlb payload has to be filled
474 with the access failure message type (4), the I/O virtual address and
475 the permissions flags.  For synchronization purpose, the slave may
476 rely on the reply-ack feature, so the master may send a reply when
477 operation is completed if the reply-ack feature is negotiated and
478 slaves requests a reply. For miss events, completed operation means
479 either master sent an update message containing the IOTLB entry
480 containing requested address and permission, or master sent nothing if
481 the IOTLB miss message is invalid (invalid IOVA or permission).
482
483 The master isn't expected to take the initiative to send IOTLB update
484 messages, as the slave sends IOTLB miss messages for the guest virtual
485 memory areas it needs to access.
486
487 .. _slave_communication:
488
489 Slave communication
490 -------------------
491
492 An optional communication channel is provided if the slave declares
493 ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` protocol feature, to allow the
494 slave to make requests to the master.
495
496 The fd is provided via ``VHOST_USER_SET_SLAVE_REQ_FD`` ancillary data.
497
498 A slave may then send ``VHOST_USER_SLAVE_*`` messages to the master
499 using this fd communication channel.
500
501 If ``VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD`` protocol feature is
502 negotiated, slave can send file descriptors (at most 8 descriptors in
503 each message) to master via ancillary data using this fd communication
504 channel.
505
506 Inflight I/O tracking
507 ---------------------
508
509 To support reconnecting after restart or crash, slave may need to
510 resubmit inflight I/Os. If virtqueue is processed in order, we can
511 easily achieve that by getting the inflight descriptors from
512 descriptor table (split virtqueue) or descriptor ring (packed
513 virtqueue). However, it can't work when we process descriptors
514 out-of-order because some entries which store the information of
515 inflight descriptors in available ring (split virtqueue) or descriptor
516 ring (packed virtqueue) might be overrided by new entries. To solve
517 this problem, slave need to allocate an extra buffer to store this
518 information of inflight descriptors and share it with master for
519 persistent. ``VHOST_USER_GET_INFLIGHT_FD`` and
520 ``VHOST_USER_SET_INFLIGHT_FD`` are used to transfer this buffer
521 between master and slave. And the format of this buffer is described
522 below:
523
524 +---------------+---------------+-----+---------------+
525 | queue0 region | queue1 region | ... | queueN region |
526 +---------------+---------------+-----+---------------+
527
528 N is the number of available virtqueues. Slave could get it from num
529 queues field of ``VhostUserInflight``.
530
531 For split virtqueue, queue region can be implemented as:
532
533 .. code:: c
534
535   typedef struct DescStateSplit {
536       /* Indicate whether this descriptor is inflight or not.
537        * Only available for head-descriptor. */
538       uint8_t inflight;
539
540       /* Padding */
541       uint8_t padding[5];
542
543       /* Maintain a list for the last batch of used descriptors.
544        * Only available when batching is used for submitting */
545       uint16_t next;
546
547       /* Used to preserve the order of fetching available descriptors.
548        * Only available for head-descriptor. */
549       uint64_t counter;
550   } DescStateSplit;
551
552   typedef struct QueueRegionSplit {
553       /* The feature flags of this region. Now it's initialized to 0. */
554       uint64_t features;
555
556       /* The version of this region. It's 1 currently.
557        * Zero value indicates an uninitialized buffer */
558       uint16_t version;
559
560       /* The size of DescStateSplit array. It's equal to the virtqueue
561        * size. Slave could get it from queue size field of VhostUserInflight. */
562       uint16_t desc_num;
563
564       /* The head of list that track the last batch of used descriptors. */
565       uint16_t last_batch_head;
566
567       /* Store the idx value of used ring */
568       uint16_t used_idx;
569
570       /* Used to track the state of each descriptor in descriptor table */
571       DescStateSplit desc[];
572   } QueueRegionSplit;
573
574 To track inflight I/O, the queue region should be processed as follows:
575
576 When receiving available buffers from the driver:
577
578 #. Get the next available head-descriptor index from available ring, ``i``
579
580 #. Set ``desc[i].counter`` to the value of global counter
581
582 #. Increase global counter by 1
583
584 #. Set ``desc[i].inflight`` to 1
585
586 When supplying used buffers to the driver:
587
588 1. Get corresponding used head-descriptor index, i
589
590 2. Set ``desc[i].next`` to ``last_batch_head``
591
592 3. Set ``last_batch_head`` to ``i``
593
594 #. Steps 1,2,3 may be performed repeatedly if batching is possible
595
596 #. Increase the ``idx`` value of used ring by the size of the batch
597
598 #. Set the ``inflight`` field of each ``DescStateSplit`` entry in the batch to 0
599
600 #. Set ``used_idx`` to the ``idx`` value of used ring
601
602 When reconnecting:
603
604 #. If the value of ``used_idx`` does not match the ``idx`` value of
605    used ring (means the inflight field of ``DescStateSplit`` entries in
606    last batch may be incorrect),
607
608    a. Subtract the value of ``used_idx`` from the ``idx`` value of
609       used ring to get last batch size of ``DescStateSplit`` entries
610
611    #. Set the ``inflight`` field of each ``DescStateSplit`` entry to 0 in last batch
612       list which starts from ``last_batch_head``
613
614    #. Set ``used_idx`` to the ``idx`` value of used ring
615
616 #. Resubmit inflight ``DescStateSplit`` entries in order of their
617    counter value
618
619 For packed virtqueue, queue region can be implemented as:
620
621 .. code:: c
622
623   typedef struct DescStatePacked {
624       /* Indicate whether this descriptor is inflight or not.
625        * Only available for head-descriptor. */
626       uint8_t inflight;
627
628       /* Padding */
629       uint8_t padding;
630
631       /* Link to the next free entry */
632       uint16_t next;
633
634       /* Link to the last entry of descriptor list.
635        * Only available for head-descriptor. */
636       uint16_t last;
637
638       /* The length of descriptor list.
639        * Only available for head-descriptor. */
640       uint16_t num;
641
642       /* Used to preserve the order of fetching available descriptors.
643        * Only available for head-descriptor. */
644       uint64_t counter;
645
646       /* The buffer id */
647       uint16_t id;
648
649       /* The descriptor flags */
650       uint16_t flags;
651
652       /* The buffer length */
653       uint32_t len;
654
655       /* The buffer address */
656       uint64_t addr;
657   } DescStatePacked;
658
659   typedef struct QueueRegionPacked {
660       /* The feature flags of this region. Now it's initialized to 0. */
661       uint64_t features;
662
663       /* The version of this region. It's 1 currently.
664        * Zero value indicates an uninitialized buffer */
665       uint16_t version;
666
667       /* The size of DescStatePacked array. It's equal to the virtqueue
668        * size. Slave could get it from queue size field of VhostUserInflight. */
669       uint16_t desc_num;
670
671       /* The head of free DescStatePacked entry list */
672       uint16_t free_head;
673
674       /* The old head of free DescStatePacked entry list */
675       uint16_t old_free_head;
676
677       /* The used index of descriptor ring */
678       uint16_t used_idx;
679
680       /* The old used index of descriptor ring */
681       uint16_t old_used_idx;
682
683       /* Device ring wrap counter */
684       uint8_t used_wrap_counter;
685
686       /* The old device ring wrap counter */
687       uint8_t old_used_wrap_counter;
688
689       /* Padding */
690       uint8_t padding[7];
691
692       /* Used to track the state of each descriptor fetched from descriptor ring */
693       DescStatePacked desc[];
694   } QueueRegionPacked;
695
696 To track inflight I/O, the queue region should be processed as follows:
697
698 When receiving available buffers from the driver:
699
700 #. Get the next available descriptor entry from descriptor ring, ``d``
701
702 #. If ``d`` is head descriptor,
703
704    a. Set ``desc[old_free_head].num`` to 0
705
706    #. Set ``desc[old_free_head].counter`` to the value of global counter
707
708    #. Increase global counter by 1
709
710    #. Set ``desc[old_free_head].inflight`` to 1
711
712 #. If ``d`` is last descriptor, set ``desc[old_free_head].last`` to
713    ``free_head``
714
715 #. Increase ``desc[old_free_head].num`` by 1
716
717 #. Set ``desc[free_head].addr``, ``desc[free_head].len``,
718    ``desc[free_head].flags``, ``desc[free_head].id`` to ``d.addr``,
719    ``d.len``, ``d.flags``, ``d.id``
720
721 #. Set ``free_head`` to ``desc[free_head].next``
722
723 #. If ``d`` is last descriptor, set ``old_free_head`` to ``free_head``
724
725 When supplying used buffers to the driver:
726
727 1. Get corresponding used head-descriptor entry from descriptor ring,
728    ``d``
729
730 2. Get corresponding ``DescStatePacked`` entry, ``e``
731
732 3. Set ``desc[e.last].next`` to ``free_head``
733
734 4. Set ``free_head`` to the index of ``e``
735
736 #. Steps 1,2,3,4 may be performed repeatedly if batching is possible
737
738 #. Increase ``used_idx`` by the size of the batch and update
739    ``used_wrap_counter`` if needed
740
741 #. Update ``d.flags``
742
743 #. Set the ``inflight`` field of each head ``DescStatePacked`` entry
744    in the batch to 0
745
746 #. Set ``old_free_head``,  ``old_used_idx``, ``old_used_wrap_counter``
747    to ``free_head``, ``used_idx``, ``used_wrap_counter``
748
749 When reconnecting:
750
751 #. If ``used_idx`` does not match ``old_used_idx`` (means the
752    ``inflight`` field of ``DescStatePacked`` entries in last batch may
753    be incorrect),
754
755    a. Get the next descriptor ring entry through ``old_used_idx``, ``d``
756
757    #. Use ``old_used_wrap_counter`` to calculate the available flags
758
759    #. If ``d.flags`` is not equal to the calculated flags value (means
760       slave has submitted the buffer to guest driver before crash, so
761       it has to commit the in-progres update), set ``old_free_head``,
762       ``old_used_idx``, ``old_used_wrap_counter`` to ``free_head``,
763       ``used_idx``, ``used_wrap_counter``
764
765 #. Set ``free_head``, ``used_idx``, ``used_wrap_counter`` to
766    ``old_free_head``, ``old_used_idx``, ``old_used_wrap_counter``
767    (roll back any in-progress update)
768
769 #. Set the ``inflight`` field of each ``DescStatePacked`` entry in
770    free list to 0
771
772 #. Resubmit inflight ``DescStatePacked`` entries in order of their
773    counter value
774
775 In-band notifications
776 ---------------------
777
778 In some limited situations (e.g. for simulation) it is desirable to
779 have the kick, call and error (if used) signals done via in-band
780 messages instead of asynchronous eventfd notifications. This can be
781 done by negotiating the ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS``
782 protocol feature.
783
784 Note that due to the fact that too many messages on the sockets can
785 cause the sending application(s) to block, it is not advised to use
786 this feature unless absolutely necessary. It is also considered an
787 error to negotiate this feature without also negotiating
788 ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` and ``VHOST_USER_PROTOCOL_F_REPLY_ACK``,
789 the former is necessary for getting a message channel from the slave
790 to the master, while the latter needs to be used with the in-band
791 notification messages to block until they are processed, both to avoid
792 blocking later and for proper processing (at least in the simulation
793 use case.) As it has no other way of signalling this error, the slave
794 should close the connection as a response to a
795 ``VHOST_USER_SET_PROTOCOL_FEATURES`` message that sets the in-band
796 notifications feature flag without the other two.
797
798 Protocol features
799 -----------------
800
801 .. code:: c
802
803   #define VHOST_USER_PROTOCOL_F_MQ                    0
804   #define VHOST_USER_PROTOCOL_F_LOG_SHMFD             1
805   #define VHOST_USER_PROTOCOL_F_RARP                  2
806   #define VHOST_USER_PROTOCOL_F_REPLY_ACK             3
807   #define VHOST_USER_PROTOCOL_F_MTU                   4
808   #define VHOST_USER_PROTOCOL_F_SLAVE_REQ             5
809   #define VHOST_USER_PROTOCOL_F_CROSS_ENDIAN          6
810   #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION        7
811   #define VHOST_USER_PROTOCOL_F_PAGEFAULT             8
812   #define VHOST_USER_PROTOCOL_F_CONFIG                9
813   #define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD        10
814   #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER        11
815   #define VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD       12
816   #define VHOST_USER_PROTOCOL_F_RESET_DEVICE         13
817   #define VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS 14
818   #define VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS  15
819   #define VHOST_USER_PROTOCOL_F_STATUS               16
820
821 Master message types
822 --------------------
823
824 ``VHOST_USER_GET_FEATURES``
825   :id: 1
826   :equivalent ioctl: ``VHOST_GET_FEATURES``
827   :master payload: N/A
828   :slave payload: ``u64``
829
830   Get from the underlying vhost implementation the features bitmask.
831   Feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` signals slave support
832   for ``VHOST_USER_GET_PROTOCOL_FEATURES`` and
833   ``VHOST_USER_SET_PROTOCOL_FEATURES``.
834
835 ``VHOST_USER_SET_FEATURES``
836   :id: 2
837   :equivalent ioctl: ``VHOST_SET_FEATURES``
838   :master payload: ``u64``
839
840   Enable features in the underlying vhost implementation using a
841   bitmask.  Feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` signals
842   slave support for ``VHOST_USER_GET_PROTOCOL_FEATURES`` and
843   ``VHOST_USER_SET_PROTOCOL_FEATURES``.
844
845 ``VHOST_USER_GET_PROTOCOL_FEATURES``
846   :id: 15
847   :equivalent ioctl: ``VHOST_GET_FEATURES``
848   :master payload: N/A
849   :slave payload: ``u64``
850
851   Get the protocol feature bitmask from the underlying vhost
852   implementation.  Only legal if feature bit
853   ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in
854   ``VHOST_USER_GET_FEATURES``.
855
856 .. Note::
857    Slave that reported ``VHOST_USER_F_PROTOCOL_FEATURES`` must
858    support this message even before ``VHOST_USER_SET_FEATURES`` was
859    called.
860
861 ``VHOST_USER_SET_PROTOCOL_FEATURES``
862   :id: 16
863   :equivalent ioctl: ``VHOST_SET_FEATURES``
864   :master payload: ``u64``
865
866   Enable protocol features in the underlying vhost implementation.
867
868   Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in
869   ``VHOST_USER_GET_FEATURES``.
870
871 .. Note::
872    Slave that reported ``VHOST_USER_F_PROTOCOL_FEATURES`` must support
873    this message even before ``VHOST_USER_SET_FEATURES`` was called.
874
875 ``VHOST_USER_SET_OWNER``
876   :id: 3
877   :equivalent ioctl: ``VHOST_SET_OWNER``
878   :master payload: N/A
879
880   Issued when a new connection is established. It sets the current
881   *master* as an owner of the session. This can be used on the *slave*
882   as a "session start" flag.
883
884 ``VHOST_USER_RESET_OWNER``
885   :id: 4
886   :master payload: N/A
887
888 .. admonition:: Deprecated
889
890    This is no longer used. Used to be sent to request disabling all
891    rings, but some clients interpreted it to also discard connection
892    state (this interpretation would lead to bugs).  It is recommended
893    that clients either ignore this message, or use it to disable all
894    rings.
895
896 ``VHOST_USER_SET_MEM_TABLE``
897   :id: 5
898   :equivalent ioctl: ``VHOST_SET_MEM_TABLE``
899   :master payload: memory regions description
900   :slave payload: (postcopy only) memory regions description
901
902   Sets the memory map regions on the slave so it can translate the
903   vring addresses. In the ancillary data there is an array of file
904   descriptors for each memory mapped region. The size and ordering of
905   the fds matches the number and ordering of memory regions.
906
907   When ``VHOST_USER_POSTCOPY_LISTEN`` has been received,
908   ``SET_MEM_TABLE`` replies with the bases of the memory mapped
909   regions to the master.  The slave must have mmap'd the regions but
910   not yet accessed them and should not yet generate a userfault
911   event.
912
913 .. Note::
914    ``NEED_REPLY_MASK`` is not set in this case.  QEMU will then
915    reply back to the list of mappings with an empty
916    ``VHOST_USER_SET_MEM_TABLE`` as an acknowledgement; only upon
917    reception of this message may the guest start accessing the memory
918    and generating faults.
919
920 ``VHOST_USER_SET_LOG_BASE``
921   :id: 6
922   :equivalent ioctl: ``VHOST_SET_LOG_BASE``
923   :master payload: u64
924   :slave payload: N/A
925
926   Sets logging shared memory space.
927
928   When slave has ``VHOST_USER_PROTOCOL_F_LOG_SHMFD`` protocol feature,
929   the log memory fd is provided in the ancillary data of
930   ``VHOST_USER_SET_LOG_BASE`` message, the size and offset of shared
931   memory area provided in the message.
932
933 ``VHOST_USER_SET_LOG_FD``
934   :id: 7
935   :equivalent ioctl: ``VHOST_SET_LOG_FD``
936   :master payload: N/A
937
938   Sets the logging file descriptor, which is passed as ancillary data.
939
940 ``VHOST_USER_SET_VRING_NUM``
941   :id: 8
942   :equivalent ioctl: ``VHOST_SET_VRING_NUM``
943   :master payload: vring state description
944
945   Set the size of the queue.
946
947 ``VHOST_USER_SET_VRING_ADDR``
948   :id: 9
949   :equivalent ioctl: ``VHOST_SET_VRING_ADDR``
950   :master payload: vring address description
951   :slave payload: N/A
952
953   Sets the addresses of the different aspects of the vring.
954
955 ``VHOST_USER_SET_VRING_BASE``
956   :id: 10
957   :equivalent ioctl: ``VHOST_SET_VRING_BASE``
958   :master payload: vring state description
959
960   Sets the base offset in the available vring.
961
962 ``VHOST_USER_GET_VRING_BASE``
963   :id: 11
964   :equivalent ioctl: ``VHOST_USER_GET_VRING_BASE``
965   :master payload: vring state description
966   :slave payload: vring state description
967
968   Get the available vring base offset.
969
970 ``VHOST_USER_SET_VRING_KICK``
971   :id: 12
972   :equivalent ioctl: ``VHOST_SET_VRING_KICK``
973   :master payload: ``u64``
974
975   Set the event file descriptor for adding buffers to the vring. It is
976   passed in the ancillary data.
977
978   Bits (0-7) of the payload contain the vring index. Bit 8 is the
979   invalid FD flag. This flag is set when there is no file descriptor
980   in the ancillary data. This signals that polling should be used
981   instead of waiting for the kick. Note that if the protocol feature
982   ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` has been negotiated
983   this message isn't necessary as the ring is also started on the
984   ``VHOST_USER_VRING_KICK`` message, it may however still be used to
985   set an event file descriptor (which will be preferred over the
986   message) or to enable polling.
987
988 ``VHOST_USER_SET_VRING_CALL``
989   :id: 13
990   :equivalent ioctl: ``VHOST_SET_VRING_CALL``
991   :master payload: ``u64``
992
993   Set the event file descriptor to signal when buffers are used. It is
994   passed in the ancillary data.
995
996   Bits (0-7) of the payload contain the vring index. Bit 8 is the
997   invalid FD flag. This flag is set when there is no file descriptor
998   in the ancillary data. This signals that polling will be used
999   instead of waiting for the call. Note that if the protocol features
1000   ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` and
1001   ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` have been negotiated this message
1002   isn't necessary as the ``VHOST_USER_SLAVE_VRING_CALL`` message can be
1003   used, it may however still be used to set an event file descriptor
1004   or to enable polling.
1005
1006 ``VHOST_USER_SET_VRING_ERR``
1007   :id: 14
1008   :equivalent ioctl: ``VHOST_SET_VRING_ERR``
1009   :master payload: ``u64``
1010
1011   Set the event file descriptor to signal when error occurs. It is
1012   passed in the ancillary data.
1013
1014   Bits (0-7) of the payload contain the vring index. Bit 8 is the
1015   invalid FD flag. This flag is set when there is no file descriptor
1016   in the ancillary data. Note that if the protocol features
1017   ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` and
1018   ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` have been negotiated this message
1019   isn't necessary as the ``VHOST_USER_SLAVE_VRING_ERR`` message can be
1020   used, it may however still be used to set an event file descriptor
1021   (which will be preferred over the message).
1022
1023 ``VHOST_USER_GET_QUEUE_NUM``
1024   :id: 17
1025   :equivalent ioctl: N/A
1026   :master payload: N/A
1027   :slave payload: u64
1028
1029   Query how many queues the backend supports.
1030
1031   This request should be sent only when ``VHOST_USER_PROTOCOL_F_MQ``
1032   is set in queried protocol features by
1033   ``VHOST_USER_GET_PROTOCOL_FEATURES``.
1034
1035 ``VHOST_USER_SET_VRING_ENABLE``
1036   :id: 18
1037   :equivalent ioctl: N/A
1038   :master payload: vring state description
1039
1040   Signal slave to enable or disable corresponding vring.
1041
1042   This request should be sent only when
1043   ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated.
1044
1045 ``VHOST_USER_SEND_RARP``
1046   :id: 19
1047   :equivalent ioctl: N/A
1048   :master payload: ``u64``
1049
1050   Ask vhost user backend to broadcast a fake RARP to notify the migration
1051   is terminated for guest that does not support GUEST_ANNOUNCE.
1052
1053   Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is
1054   present in ``VHOST_USER_GET_FEATURES`` and protocol feature bit
1055   ``VHOST_USER_PROTOCOL_F_RARP`` is present in
1056   ``VHOST_USER_GET_PROTOCOL_FEATURES``.  The first 6 bytes of the
1057   payload contain the mac address of the guest to allow the vhost user
1058   backend to construct and broadcast the fake RARP.
1059
1060 ``VHOST_USER_NET_SET_MTU``
1061   :id: 20
1062   :equivalent ioctl: N/A
1063   :master payload: ``u64``
1064
1065   Set host MTU value exposed to the guest.
1066
1067   This request should be sent only when ``VIRTIO_NET_F_MTU`` feature
1068   has been successfully negotiated, ``VHOST_USER_F_PROTOCOL_FEATURES``
1069   is present in ``VHOST_USER_GET_FEATURES`` and protocol feature bit
1070   ``VHOST_USER_PROTOCOL_F_NET_MTU`` is present in
1071   ``VHOST_USER_GET_PROTOCOL_FEATURES``.
1072
1073   If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, slave must
1074   respond with zero in case the specified MTU is valid, or non-zero
1075   otherwise.
1076
1077 ``VHOST_USER_SET_SLAVE_REQ_FD``
1078   :id: 21
1079   :equivalent ioctl: N/A
1080   :master payload: N/A
1081
1082   Set the socket file descriptor for slave initiated requests. It is passed
1083   in the ancillary data.
1084
1085   This request should be sent only when
1086   ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, and protocol
1087   feature bit ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` bit is present in
1088   ``VHOST_USER_GET_PROTOCOL_FEATURES``.  If
1089   ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, slave must
1090   respond with zero for success, non-zero otherwise.
1091
1092 ``VHOST_USER_IOTLB_MSG``
1093   :id: 22
1094   :equivalent ioctl: N/A (equivalent to ``VHOST_IOTLB_MSG`` message type)
1095   :master payload: ``struct vhost_iotlb_msg``
1096   :slave payload: ``u64``
1097
1098   Send IOTLB messages with ``struct vhost_iotlb_msg`` as payload.
1099
1100   Master sends such requests to update and invalidate entries in the
1101   device IOTLB. The slave has to acknowledge the request with sending
1102   zero as ``u64`` payload for success, non-zero otherwise.
1103
1104   This request should be send only when ``VIRTIO_F_IOMMU_PLATFORM``
1105   feature has been successfully negotiated.
1106
1107 ``VHOST_USER_SET_VRING_ENDIAN``
1108   :id: 23
1109   :equivalent ioctl: ``VHOST_SET_VRING_ENDIAN``
1110   :master payload: vring state description
1111
1112   Set the endianness of a VQ for legacy devices. Little-endian is
1113   indicated with state.num set to 0 and big-endian is indicated with
1114   state.num set to 1. Other values are invalid.
1115
1116   This request should be sent only when
1117   ``VHOST_USER_PROTOCOL_F_CROSS_ENDIAN`` has been negotiated.
1118   Backends that negotiated this feature should handle both
1119   endiannesses and expect this message once (per VQ) during device
1120   configuration (ie. before the master starts the VQ).
1121
1122 ``VHOST_USER_GET_CONFIG``
1123   :id: 24
1124   :equivalent ioctl: N/A
1125   :master payload: virtio device config space
1126   :slave payload: virtio device config space
1127
1128   When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, this message is
1129   submitted by the vhost-user master to fetch the contents of the
1130   virtio device configuration space, vhost-user slave's payload size
1131   MUST match master's request, vhost-user slave uses zero length of
1132   payload to indicate an error to vhost-user master. The vhost-user
1133   master may cache the contents to avoid repeated
1134   ``VHOST_USER_GET_CONFIG`` calls.
1135
1136 ``VHOST_USER_SET_CONFIG``
1137   :id: 25
1138   :equivalent ioctl: N/A
1139   :master payload: virtio device config space
1140   :slave payload: N/A
1141
1142   When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, this message is
1143   submitted by the vhost-user master when the Guest changes the virtio
1144   device configuration space and also can be used for live migration
1145   on the destination host. The vhost-user slave must check the flags
1146   field, and slaves MUST NOT accept SET_CONFIG for read-only
1147   configuration space fields unless the live migration bit is set.
1148
1149 ``VHOST_USER_CREATE_CRYPTO_SESSION``
1150   :id: 26
1151   :equivalent ioctl: N/A
1152   :master payload: crypto session description
1153   :slave payload: crypto session description
1154
1155   Create a session for crypto operation. The server side must return
1156   the session id, 0 or positive for success, negative for failure.
1157   This request should be sent only when
1158   ``VHOST_USER_PROTOCOL_F_CRYPTO_SESSION`` feature has been
1159   successfully negotiated.  It's a required feature for crypto
1160   devices.
1161
1162 ``VHOST_USER_CLOSE_CRYPTO_SESSION``
1163   :id: 27
1164   :equivalent ioctl: N/A
1165   :master payload: ``u64``
1166
1167   Close a session for crypto operation which was previously
1168   created by ``VHOST_USER_CREATE_CRYPTO_SESSION``.
1169
1170   This request should be sent only when
1171   ``VHOST_USER_PROTOCOL_F_CRYPTO_SESSION`` feature has been
1172   successfully negotiated.  It's a required feature for crypto
1173   devices.
1174
1175 ``VHOST_USER_POSTCOPY_ADVISE``
1176   :id: 28
1177   :master payload: N/A
1178   :slave payload: userfault fd
1179
1180   When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, the master
1181   advises slave that a migration with postcopy enabled is underway,
1182   the slave must open a userfaultfd for later use.  Note that at this
1183   stage the migration is still in precopy mode.
1184
1185 ``VHOST_USER_POSTCOPY_LISTEN``
1186   :id: 29
1187   :master payload: N/A
1188
1189   Master advises slave that a transition to postcopy mode has
1190   happened.  The slave must ensure that shared memory is registered
1191   with userfaultfd to cause faulting of non-present pages.
1192
1193   This is always sent sometime after a ``VHOST_USER_POSTCOPY_ADVISE``,
1194   and thus only when ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported.
1195
1196 ``VHOST_USER_POSTCOPY_END``
1197   :id: 30
1198   :slave payload: ``u64``
1199
1200   Master advises that postcopy migration has now completed.  The slave
1201   must disable the userfaultfd. The response is an acknowledgement
1202   only.
1203
1204   When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, this message
1205   is sent at the end of the migration, after
1206   ``VHOST_USER_POSTCOPY_LISTEN`` was previously sent.
1207
1208   The value returned is an error indication; 0 is success.
1209
1210 ``VHOST_USER_GET_INFLIGHT_FD``
1211   :id: 31
1212   :equivalent ioctl: N/A
1213   :master payload: inflight description
1214
1215   When ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD`` protocol feature has
1216   been successfully negotiated, this message is submitted by master to
1217   get a shared buffer from slave. The shared buffer will be used to
1218   track inflight I/O by slave. QEMU should retrieve a new one when vm
1219   reset.
1220
1221 ``VHOST_USER_SET_INFLIGHT_FD``
1222   :id: 32
1223   :equivalent ioctl: N/A
1224   :master payload: inflight description
1225
1226   When ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD`` protocol feature has
1227   been successfully negotiated, this message is submitted by master to
1228   send the shared inflight buffer back to slave so that slave could
1229   get inflight I/O after a crash or restart.
1230
1231 ``VHOST_USER_GPU_SET_SOCKET``
1232   :id: 33
1233   :equivalent ioctl: N/A
1234   :master payload: N/A
1235
1236   Sets the GPU protocol socket file descriptor, which is passed as
1237   ancillary data. The GPU protocol is used to inform the master of
1238   rendering state and updates. See vhost-user-gpu.rst for details.
1239
1240 ``VHOST_USER_RESET_DEVICE``
1241   :id: 34
1242   :equivalent ioctl: N/A
1243   :master payload: N/A
1244   :slave payload: N/A
1245
1246   Ask the vhost user backend to disable all rings and reset all
1247   internal device state to the initial state, ready to be
1248   reinitialized. The backend retains ownership of the device
1249   throughout the reset operation.
1250
1251   Only valid if the ``VHOST_USER_PROTOCOL_F_RESET_DEVICE`` protocol
1252   feature is set by the backend.
1253
1254 ``VHOST_USER_VRING_KICK``
1255   :id: 35
1256   :equivalent ioctl: N/A
1257   :slave payload: vring state description
1258   :master payload: N/A
1259
1260   When the ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` protocol
1261   feature has been successfully negotiated, this message may be
1262   submitted by the master to indicate that a buffer was added to
1263   the vring instead of signalling it using the vring's kick file
1264   descriptor or having the slave rely on polling.
1265
1266   The state.num field is currently reserved and must be set to 0.
1267
1268 ``VHOST_USER_GET_MAX_MEM_SLOTS``
1269   :id: 36
1270   :equivalent ioctl: N/A
1271   :slave payload: u64
1272
1273   When the ``VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS`` protocol
1274   feature has been successfully negotiated, this message is submitted
1275   by master to the slave. The slave should return the message with a
1276   u64 payload containing the maximum number of memory slots for
1277   QEMU to expose to the guest. The value returned by the backend
1278   will be capped at the maximum number of ram slots which can be
1279   supported by the target platform.
1280
1281 ``VHOST_USER_ADD_MEM_REG``
1282   :id: 37
1283   :equivalent ioctl: N/A
1284   :slave payload: memory region
1285
1286   When the ``VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS`` protocol
1287   feature has been successfully negotiated, this message is submitted
1288   by the master to the slave. The message payload contains a memory
1289   region descriptor struct, describing a region of guest memory which
1290   the slave device must map in. When the
1291   ``VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS`` protocol feature has
1292   been successfully negotiated, along with the
1293   ``VHOST_USER_REM_MEM_REG`` message, this message is used to set and
1294   update the memory tables of the slave device.
1295
1296 ``VHOST_USER_REM_MEM_REG``
1297   :id: 38
1298   :equivalent ioctl: N/A
1299   :slave payload: memory region
1300
1301   When the ``VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS`` protocol
1302   feature has been successfully negotiated, this message is submitted
1303   by the master to the slave. The message payload contains a memory
1304   region descriptor struct, describing a region of guest memory which
1305   the slave device must unmap. When the
1306   ``VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS`` protocol feature has
1307   been successfully negotiated, along with the
1308   ``VHOST_USER_ADD_MEM_REG`` message, this message is used to set and
1309   update the memory tables of the slave device.
1310
1311 ``VHOST_USER_SET_STATUS``
1312   :id: 39
1313   :equivalent ioctl: VHOST_VDPA_SET_STATUS
1314   :slave payload: N/A
1315   :master payload: ``u64``
1316
1317   When the ``VHOST_USER_PROTOCOL_F_STATUS`` protocol feature has been
1318   successfully negotiated, this message is submitted by the master to
1319   notify the backend with updated device status as defined in the Virtio
1320   specification.
1321
1322 ``VHOST_USER_GET_STATUS``
1323   :id: 40
1324   :equivalent ioctl: VHOST_VDPA_GET_STATUS
1325   :slave payload: ``u64``
1326   :master payload: N/A
1327
1328   When the ``VHOST_USER_PROTOCOL_F_STATUS`` protocol feature has been
1329   successfully negotiated, this message is submitted by the master to
1330   query the backend for its device status as defined in the Virtio
1331   specification.
1332
1333
1334 Slave message types
1335 -------------------
1336
1337 ``VHOST_USER_SLAVE_IOTLB_MSG``
1338   :id: 1
1339   :equivalent ioctl: N/A (equivalent to ``VHOST_IOTLB_MSG`` message type)
1340   :slave payload: ``struct vhost_iotlb_msg``
1341   :master payload: N/A
1342
1343   Send IOTLB messages with ``struct vhost_iotlb_msg`` as payload.
1344   Slave sends such requests to notify of an IOTLB miss, or an IOTLB
1345   access failure. If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is
1346   negotiated, and slave set the ``VHOST_USER_NEED_REPLY`` flag, master
1347   must respond with zero when operation is successfully completed, or
1348   non-zero otherwise.  This request should be send only when
1349   ``VIRTIO_F_IOMMU_PLATFORM`` feature has been successfully
1350   negotiated.
1351
1352 ``VHOST_USER_SLAVE_CONFIG_CHANGE_MSG``
1353   :id: 2
1354   :equivalent ioctl: N/A
1355   :slave payload: N/A
1356   :master payload: N/A
1357
1358   When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, vhost-user
1359   slave sends such messages to notify that the virtio device's
1360   configuration space has changed, for those host devices which can
1361   support such feature, host driver can send ``VHOST_USER_GET_CONFIG``
1362   message to slave to get the latest content. If
1363   ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and slave set the
1364   ``VHOST_USER_NEED_REPLY`` flag, master must respond with zero when
1365   operation is successfully completed, or non-zero otherwise.
1366
1367 ``VHOST_USER_SLAVE_VRING_HOST_NOTIFIER_MSG``
1368   :id: 3
1369   :equivalent ioctl: N/A
1370   :slave payload: vring area description
1371   :master payload: N/A
1372
1373   Sets host notifier for a specified queue. The queue index is
1374   contained in the ``u64`` field of the vring area description. The
1375   host notifier is described by the file descriptor (typically it's a
1376   VFIO device fd) which is passed as ancillary data and the size
1377   (which is mmap size and should be the same as host page size) and
1378   offset (which is mmap offset) carried in the vring area
1379   description. QEMU can mmap the file descriptor based on the size and
1380   offset to get a memory range. Registering a host notifier means
1381   mapping this memory range to the VM as the specified queue's notify
1382   MMIO region. Slave sends this request to tell QEMU to de-register
1383   the existing notifier if any and register the new notifier if the
1384   request is sent with a file descriptor.
1385
1386   This request should be sent only when
1387   ``VHOST_USER_PROTOCOL_F_HOST_NOTIFIER`` protocol feature has been
1388   successfully negotiated.
1389
1390 ``VHOST_USER_SLAVE_VRING_CALL``
1391   :id: 4
1392   :equivalent ioctl: N/A
1393   :slave payload: vring state description
1394   :master payload: N/A
1395
1396   When the ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` protocol
1397   feature has been successfully negotiated, this message may be
1398   submitted by the slave to indicate that a buffer was used from
1399   the vring instead of signalling this using the vring's call file
1400   descriptor or having the master relying on polling.
1401
1402   The state.num field is currently reserved and must be set to 0.
1403
1404 ``VHOST_USER_SLAVE_VRING_ERR``
1405   :id: 5
1406   :equivalent ioctl: N/A
1407   :slave payload: vring state description
1408   :master payload: N/A
1409
1410   When the ``VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS`` protocol
1411   feature has been successfully negotiated, this message may be
1412   submitted by the slave to indicate that an error occurred on the
1413   specific vring, instead of signalling the error file descriptor
1414   set by the master via ``VHOST_USER_SET_VRING_ERR``.
1415
1416   The state.num field is currently reserved and must be set to 0.
1417
1418 .. _reply_ack:
1419
1420 VHOST_USER_PROTOCOL_F_REPLY_ACK
1421 -------------------------------
1422
1423 The original vhost-user specification only demands replies for certain
1424 commands. This differs from the vhost protocol implementation where
1425 commands are sent over an ``ioctl()`` call and block until the client
1426 has completed.
1427
1428 With this protocol extension negotiated, the sender (QEMU) can set the
1429 ``need_reply`` [Bit 3] flag to any command. This indicates that the
1430 client MUST respond with a Payload ``VhostUserMsg`` indicating success
1431 or failure. The payload should be set to zero on success or non-zero
1432 on failure, unless the message already has an explicit reply body.
1433
1434 The response payload gives QEMU a deterministic indication of the result
1435 of the command. Today, QEMU is expected to terminate the main vhost-user
1436 loop upon receiving such errors. In future, qemu could be taught to be more
1437 resilient for selective requests.
1438
1439 For the message types that already solicit a reply from the client,
1440 the presence of ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` or need_reply bit
1441 being set brings no behavioural change. (See the Communication_
1442 section for details.)
1443
1444 .. _backend_conventions:
1445
1446 Backend program conventions
1447 ===========================
1448
1449 vhost-user backends can provide various devices & services and may
1450 need to be configured manually depending on the use case. However, it
1451 is a good idea to follow the conventions listed here when
1452 possible. Users, QEMU or libvirt, can then rely on some common
1453 behaviour to avoid heterogenous configuration and management of the
1454 backend programs and facilitate interoperability.
1455
1456 Each backend installed on a host system should come with at least one
1457 JSON file that conforms to the vhost-user.json schema. Each file
1458 informs the management applications about the backend type, and binary
1459 location. In addition, it defines rules for management apps for
1460 picking the highest priority backend when multiple match the search
1461 criteria (see ``@VhostUserBackend`` documentation in the schema file).
1462
1463 If the backend is not capable of enabling a requested feature on the
1464 host (such as 3D acceleration with virgl), or the initialization
1465 failed, the backend should fail to start early and exit with a status
1466 != 0. It may also print a message to stderr for further details.
1467
1468 The backend program must not daemonize itself, but it may be
1469 daemonized by the management layer. It may also have a restricted
1470 access to the system.
1471
1472 File descriptors 0, 1 and 2 will exist, and have regular
1473 stdin/stdout/stderr usage (they may have been redirected to /dev/null
1474 by the management layer, or to a log handler).
1475
1476 The backend program must end (as quickly and cleanly as possible) when
1477 the SIGTERM signal is received. Eventually, it may receive SIGKILL by
1478 the management layer after a few seconds.
1479
1480 The following command line options have an expected behaviour. They
1481 are mandatory, unless explicitly said differently:
1482
1483 --socket-path=PATH
1484
1485   This option specify the location of the vhost-user Unix domain socket.
1486   It is incompatible with --fd.
1487
1488 --fd=FDNUM
1489
1490   When this argument is given, the backend program is started with the
1491   vhost-user socket as file descriptor FDNUM. It is incompatible with
1492   --socket-path.
1493
1494 --print-capabilities
1495
1496   Output to stdout the backend capabilities in JSON format, and then
1497   exit successfully. Other options and arguments should be ignored, and
1498   the backend program should not perform its normal function.  The
1499   capabilities can be reported dynamically depending on the host
1500   capabilities.
1501
1502 The JSON output is described in the ``vhost-user.json`` schema, by
1503 ```@VHostUserBackendCapabilities``.  Example:
1504
1505 .. code:: json
1506
1507   {
1508     "type": "foo",
1509     "features": [
1510       "feature-a",
1511       "feature-b"
1512     ]
1513   }
1514
1515 vhost-user-input
1516 ----------------
1517
1518 Command line options:
1519
1520 --evdev-path=PATH
1521
1522   Specify the linux input device.
1523
1524   (optional)
1525
1526 --no-grab
1527
1528   Do no request exclusive access to the input device.
1529
1530   (optional)
1531
1532 vhost-user-gpu
1533 --------------
1534
1535 Command line options:
1536
1537 --render-node=PATH
1538
1539   Specify the GPU DRM render node.
1540
1541   (optional)
1542
1543 --virgl
1544
1545   Enable virgl rendering support.
1546
1547   (optional)
1548
1549 vhost-user-blk
1550 --------------
1551
1552 Command line options:
1553
1554 --blk-file=PATH
1555
1556   Specify block device or file path.
1557
1558   (optional)
1559
1560 --read-only
1561
1562   Enable read-only.
1563
1564   (optional)