Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20200117-1' into...
[qemu/ar7.git] / docs / interop / vhost-user.rst
blob5f8b3a456b5e4ce7fc42a530cd8670ea249c4432
1 ===================
2 Vhost-user Protocol
3 ===================
4 :Copyright: 2014 Virtual Open Systems Sarl.
5 :Licence: This work is licensed under the terms of the GNU GPL,
6           version 2 or later. See the COPYING file in the top-level
7           directory.
9 .. contents:: Table of Contents
11 Introduction
12 ============
14 This protocol is aiming to complement the ``ioctl`` interface used to
15 control the vhost implementation in the Linux kernel. It implements
16 the control plane needed to establish virtqueue sharing with a user
17 space process on the same host. It uses communication over a Unix
18 domain socket to share file descriptors in the ancillary data of the
19 message.
21 The protocol defines 2 sides of the communication, *master* and
22 *slave*. *Master* is the application that shares its virtqueues, in
23 our case QEMU. *Slave* is the consumer of the virtqueues.
25 In the current implementation QEMU is the *master*, and the *slave* is
26 the external process consuming the virtio queues, for example a
27 software Ethernet switch running in user space, such as Snabbswitch,
28 or a block device backend processing read & write to a virtual
29 disk. In order to facilitate interoperability between various backend
30 implementations, it is recommended to follow the :ref:`Backend program
31 conventions <backend_conventions>`.
33 *Master* and *slave* can be either a client (i.e. connecting) or
34 server (listening) in the socket communication.
36 Message Specification
37 =====================
39 .. Note:: All numbers are in the machine native byte order.
41 A vhost-user message consists of 3 header fields and a payload.
43 +---------+-------+------+---------+
44 | request | flags | size | payload |
45 +---------+-------+------+---------+
47 Header
48 ------
50 :request: 32-bit type of the request
52 :flags: 32-bit bit field
54 - Lower 2 bits are the version (currently 0x01)
55 - Bit 2 is the reply flag - needs to be sent on each reply from the slave
56 - Bit 3 is the need_reply flag - see :ref:`REPLY_ACK <reply_ack>` for
57   details.
59 :size: 32-bit size of the payload
61 Payload
62 -------
64 Depending on the request type, **payload** can be:
66 A single 64-bit integer
67 ^^^^^^^^^^^^^^^^^^^^^^^
69 +-----+
70 | u64 |
71 +-----+
73 :u64: a 64-bit unsigned integer
75 A vring state description
76 ^^^^^^^^^^^^^^^^^^^^^^^^^
78 +-------+-----+
79 | index | num |
80 +-------+-----+
82 :index: a 32-bit index
84 :num: a 32-bit number
86 A vring address description
87 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
89 +-------+-------+------+------------+------+-----------+-----+
90 | index | flags | size | descriptor | used | available | log |
91 +-------+-------+------+------------+------+-----------+-----+
93 :index: a 32-bit vring index
95 :flags: a 32-bit vring flags
97 :descriptor: a 64-bit ring address of the vring descriptor table
99 :used: a 64-bit ring address of the vring used ring
101 :available: a 64-bit ring address of the vring available ring
103 :log: a 64-bit guest address for logging
105 Note that a ring address is an IOVA if ``VIRTIO_F_IOMMU_PLATFORM`` has
106 been negotiated. Otherwise it is a user address.
108 Memory regions description
109 ^^^^^^^^^^^^^^^^^^^^^^^^^^
111 +-------------+---------+---------+-----+---------+
112 | num regions | padding | region0 | ... | region7 |
113 +-------------+---------+---------+-----+---------+
115 :num regions: a 32-bit number of regions
117 :padding: 32-bit
119 A region is:
121 +---------------+------+--------------+-------------+
122 | guest address | size | user address | mmap offset |
123 +---------------+------+--------------+-------------+
125 :guest address: a 64-bit guest address of the region
127 :size: a 64-bit size
129 :user address: a 64-bit user address
131 :mmap offset: 64-bit offset where region starts in the mapped memory
133 Log description
134 ^^^^^^^^^^^^^^^
136 +----------+------------+
137 | log size | log offset |
138 +----------+------------+
140 :log size: size of area used for logging
142 :log offset: offset from start of supplied file descriptor where
143              logging starts (i.e. where guest address 0 would be
144              logged)
146 An IOTLB message
147 ^^^^^^^^^^^^^^^^
149 +------+------+--------------+-------------------+------+
150 | iova | size | user address | permissions flags | type |
151 +------+------+--------------+-------------------+------+
153 :iova: a 64-bit I/O virtual address programmed by the guest
155 :size: a 64-bit size
157 :user address: a 64-bit user address
159 :permissions flags: an 8-bit value:
160   - 0: No access
161   - 1: Read access
162   - 2: Write access
163   - 3: Read/Write access
165 :type: an 8-bit IOTLB message type:
166   - 1: IOTLB miss
167   - 2: IOTLB update
168   - 3: IOTLB invalidate
169   - 4: IOTLB access fail
171 Virtio device config space
172 ^^^^^^^^^^^^^^^^^^^^^^^^^^
174 +--------+------+-------+---------+
175 | offset | size | flags | payload |
176 +--------+------+-------+---------+
178 :offset: a 32-bit offset of virtio device's configuration space
180 :size: a 32-bit configuration space access size in bytes
182 :flags: a 32-bit value:
183   - 0: Vhost master messages used for writeable fields
184   - 1: Vhost master messages used for live migration
186 :payload: Size bytes array holding the contents of the virtio
187           device's configuration space
189 Vring area description
190 ^^^^^^^^^^^^^^^^^^^^^^
192 +-----+------+--------+
193 | u64 | size | offset |
194 +-----+------+--------+
196 :u64: a 64-bit integer contains vring index and flags
198 :size: a 64-bit size of this area
200 :offset: a 64-bit offset of this area from the start of the
201          supplied file descriptor
203 Inflight description
204 ^^^^^^^^^^^^^^^^^^^^
206 +-----------+-------------+------------+------------+
207 | mmap size | mmap offset | num queues | queue size |
208 +-----------+-------------+------------+------------+
210 :mmap size: a 64-bit size of area to track inflight I/O
212 :mmap offset: a 64-bit offset of this area from the start
213               of the supplied file descriptor
215 :num queues: a 16-bit number of virtqueues
217 :queue size: a 16-bit size of virtqueues
219 C structure
220 -----------
222 In QEMU the vhost-user message is implemented with the following struct:
224 .. code:: c
226   typedef struct VhostUserMsg {
227       VhostUserRequest request;
228       uint32_t flags;
229       uint32_t size;
230       union {
231           uint64_t u64;
232           struct vhost_vring_state state;
233           struct vhost_vring_addr addr;
234           VhostUserMemory memory;
235           VhostUserLog log;
236           struct vhost_iotlb_msg iotlb;
237           VhostUserConfig config;
238           VhostUserVringArea area;
239           VhostUserInflight inflight;
240       };
241   } QEMU_PACKED VhostUserMsg;
243 Communication
244 =============
246 The protocol for vhost-user is based on the existing implementation of
247 vhost for the Linux Kernel. Most messages that can be sent via the
248 Unix domain socket implementing vhost-user have an equivalent ioctl to
249 the kernel implementation.
251 The communication consists of *master* sending message requests and
252 *slave* sending message replies. Most of the requests don't require
253 replies. Here is a list of the ones that do:
255 * ``VHOST_USER_GET_FEATURES``
256 * ``VHOST_USER_GET_PROTOCOL_FEATURES``
257 * ``VHOST_USER_GET_VRING_BASE``
258 * ``VHOST_USER_SET_LOG_BASE`` (if ``VHOST_USER_PROTOCOL_F_LOG_SHMFD``)
259 * ``VHOST_USER_GET_INFLIGHT_FD`` (if ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD``)
261 .. seealso::
263    :ref:`REPLY_ACK <reply_ack>`
264        The section on ``REPLY_ACK`` protocol extension.
266 There are several messages that the master sends with file descriptors passed
267 in the ancillary data:
269 * ``VHOST_USER_SET_MEM_TABLE``
270 * ``VHOST_USER_SET_LOG_BASE`` (if ``VHOST_USER_PROTOCOL_F_LOG_SHMFD``)
271 * ``VHOST_USER_SET_LOG_FD``
272 * ``VHOST_USER_SET_VRING_KICK``
273 * ``VHOST_USER_SET_VRING_CALL``
274 * ``VHOST_USER_SET_VRING_ERR``
275 * ``VHOST_USER_SET_SLAVE_REQ_FD``
276 * ``VHOST_USER_SET_INFLIGHT_FD`` (if ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD``)
278 If *master* is unable to send the full message or receives a wrong
279 reply it will close the connection. An optional reconnection mechanism
280 can be implemented.
282 Any protocol extensions are gated by protocol feature bits, which
283 allows full backwards compatibility on both master and slave.  As
284 older slaves don't support negotiating protocol features, a feature
285 bit was dedicated for this purpose::
287   #define VHOST_USER_F_PROTOCOL_FEATURES 30
289 Starting and stopping rings
290 ---------------------------
292 Client must only process each ring when it is started.
294 Client must only pass data between the ring and the backend, when the
295 ring is enabled.
297 If ring is started but disabled, client must process the ring without
298 talking to the backend.
300 For example, for a networking device, in the disabled state client
301 must not supply any new RX packets, but must process and discard any
302 TX packets.
304 If ``VHOST_USER_F_PROTOCOL_FEATURES`` has not been negotiated, the
305 ring is initialized in an enabled state.
307 If ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, the ring is
308 initialized in a disabled state. Client must not pass data to/from the
309 backend until ring is enabled by ``VHOST_USER_SET_VRING_ENABLE`` with
310 parameter 1, or after it has been disabled by
311 ``VHOST_USER_SET_VRING_ENABLE`` with parameter 0.
313 Each ring is initialized in a stopped state, client must not process
314 it until ring is started, or after it has been stopped.
316 Client must start ring upon receiving a kick (that is, detecting that
317 file descriptor is readable) on the descriptor specified by
318 ``VHOST_USER_SET_VRING_KICK``, and stop ring upon receiving
319 ``VHOST_USER_GET_VRING_BASE``.
321 While processing the rings (whether they are enabled or not), client
322 must support changing some configuration aspects on the fly.
324 Multiple queue support
325 ----------------------
327 Many devices have a fixed number of virtqueues.  In this case the master
328 already knows the number of available virtqueues without communicating with the
329 slave.
331 Some devices do not have a fixed number of virtqueues.  Instead the maximum
332 number of virtqueues is chosen by the slave.  The number can depend on host
333 resource availability or slave implementation details.  Such devices are called
334 multiple queue devices.
336 Multiple queue support allows the slave to advertise the maximum number of
337 queues.  This is treated as a protocol extension, hence the slave has to
338 implement protocol features first. The multiple queues feature is supported
339 only when the protocol feature ``VHOST_USER_PROTOCOL_F_MQ`` (bit 0) is set.
341 The max number of queues the slave supports can be queried with message
342 ``VHOST_USER_GET_QUEUE_NUM``. Master should stop when the number of requested
343 queues is bigger than that.
345 As all queues share one connection, the master uses a unique index for each
346 queue in the sent message to identify a specified queue.
348 The master enables queues by sending message ``VHOST_USER_SET_VRING_ENABLE``.
349 vhost-user-net has historically automatically enabled the first queue pair.
351 Slaves should always implement the ``VHOST_USER_PROTOCOL_F_MQ`` protocol
352 feature, even for devices with a fixed number of virtqueues, since it is simple
353 to implement and offers a degree of introspection.
355 Masters must not rely on the ``VHOST_USER_PROTOCOL_F_MQ`` protocol feature for
356 devices with a fixed number of virtqueues.  Only true multiqueue devices
357 require this protocol feature.
359 Migration
360 ---------
362 During live migration, the master may need to track the modifications
363 the slave makes to the memory mapped regions. The client should mark
364 the dirty pages in a log. Once it complies to this logging, it may
365 declare the ``VHOST_F_LOG_ALL`` vhost feature.
367 To start/stop logging of data/used ring writes, server may send
368 messages ``VHOST_USER_SET_FEATURES`` with ``VHOST_F_LOG_ALL`` and
369 ``VHOST_USER_SET_VRING_ADDR`` with ``VHOST_VRING_F_LOG`` in ring's
370 flags set to 1/0, respectively.
372 All the modifications to memory pointed by vring "descriptor" should
373 be marked. Modifications to "used" vring should be marked if
374 ``VHOST_VRING_F_LOG`` is part of ring's flags.
376 Dirty pages are of size::
378   #define VHOST_LOG_PAGE 0x1000
380 The log memory fd is provided in the ancillary data of
381 ``VHOST_USER_SET_LOG_BASE`` message when the slave has
382 ``VHOST_USER_PROTOCOL_F_LOG_SHMFD`` protocol feature.
384 The size of the log is supplied as part of ``VhostUserMsg`` which
385 should be large enough to cover all known guest addresses. Log starts
386 at the supplied offset in the supplied file descriptor.  The log
387 covers from address 0 to the maximum of guest regions. In pseudo-code,
388 to mark page at ``addr`` as dirty::
390   page = addr / VHOST_LOG_PAGE
391   log[page / 8] |= 1 << page % 8
393 Where ``addr`` is the guest physical address.
395 Use atomic operations, as the log may be concurrently manipulated.
397 Note that when logging modifications to the used ring (when
398 ``VHOST_VRING_F_LOG`` is set for this ring), ``log_guest_addr`` should
399 be used to calculate the log offset: the write to first byte of the
400 used ring is logged at this offset from log start. Also note that this
401 value might be outside the legal guest physical address range
402 (i.e. does not have to be covered by the ``VhostUserMemory`` table), but
403 the bit offset of the last byte of the ring must fall within the size
404 supplied by ``VhostUserLog``.
406 ``VHOST_USER_SET_LOG_FD`` is an optional message with an eventfd in
407 ancillary data, it may be used to inform the master that the log has
408 been modified.
410 Once the source has finished migration, rings will be stopped by the
411 source. No further update must be done before rings are restarted.
413 In postcopy migration the slave is started before all the memory has
414 been received from the source host, and care must be taken to avoid
415 accessing pages that have yet to be received.  The slave opens a
416 'userfault'-fd and registers the memory with it; this fd is then
417 passed back over to the master.  The master services requests on the
418 userfaultfd for pages that are accessed and when the page is available
419 it performs WAKE ioctl's on the userfaultfd to wake the stalled
420 slave.  The client indicates support for this via the
421 ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` feature.
423 Memory access
424 -------------
426 The master sends a list of vhost memory regions to the slave using the
427 ``VHOST_USER_SET_MEM_TABLE`` message.  Each region has two base
428 addresses: a guest address and a user address.
430 Messages contain guest addresses and/or user addresses to reference locations
431 within the shared memory.  The mapping of these addresses works as follows.
433 User addresses map to the vhost memory region containing that user address.
435 When the ``VIRTIO_F_IOMMU_PLATFORM`` feature has not been negotiated:
437 * Guest addresses map to the vhost memory region containing that guest
438   address.
440 When the ``VIRTIO_F_IOMMU_PLATFORM`` feature has been negotiated:
442 * Guest addresses are also called I/O virtual addresses (IOVAs).  They are
443   translated to user addresses via the IOTLB.
445 * The vhost memory region guest address is not used.
447 IOMMU support
448 -------------
450 When the ``VIRTIO_F_IOMMU_PLATFORM`` feature has been negotiated, the
451 master sends IOTLB entries update & invalidation by sending
452 ``VHOST_USER_IOTLB_MSG`` requests to the slave with a ``struct
453 vhost_iotlb_msg`` as payload. For update events, the ``iotlb`` payload
454 has to be filled with the update message type (2), the I/O virtual
455 address, the size, the user virtual address, and the permissions
456 flags. Addresses and size must be within vhost memory regions set via
457 the ``VHOST_USER_SET_MEM_TABLE`` request. For invalidation events, the
458 ``iotlb`` payload has to be filled with the invalidation message type
459 (3), the I/O virtual address and the size. On success, the slave is
460 expected to reply with a zero payload, non-zero otherwise.
462 The slave relies on the slave communcation channel (see :ref:`Slave
463 communication <slave_communication>` section below) to send IOTLB miss
464 and access failure events, by sending ``VHOST_USER_SLAVE_IOTLB_MSG``
465 requests to the master with a ``struct vhost_iotlb_msg`` as
466 payload. For miss events, the iotlb payload has to be filled with the
467 miss message type (1), the I/O virtual address and the permissions
468 flags. For access failure event, the iotlb payload has to be filled
469 with the access failure message type (4), the I/O virtual address and
470 the permissions flags.  For synchronization purpose, the slave may
471 rely on the reply-ack feature, so the master may send a reply when
472 operation is completed if the reply-ack feature is negotiated and
473 slaves requests a reply. For miss events, completed operation means
474 either master sent an update message containing the IOTLB entry
475 containing requested address and permission, or master sent nothing if
476 the IOTLB miss message is invalid (invalid IOVA or permission).
478 The master isn't expected to take the initiative to send IOTLB update
479 messages, as the slave sends IOTLB miss messages for the guest virtual
480 memory areas it needs to access.
482 .. _slave_communication:
484 Slave communication
485 -------------------
487 An optional communication channel is provided if the slave declares
488 ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` protocol feature, to allow the
489 slave to make requests to the master.
491 The fd is provided via ``VHOST_USER_SET_SLAVE_REQ_FD`` ancillary data.
493 A slave may then send ``VHOST_USER_SLAVE_*`` messages to the master
494 using this fd communication channel.
496 If ``VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD`` protocol feature is
497 negotiated, slave can send file descriptors (at most 8 descriptors in
498 each message) to master via ancillary data using this fd communication
499 channel.
501 Inflight I/O tracking
502 ---------------------
504 To support reconnecting after restart or crash, slave may need to
505 resubmit inflight I/Os. If virtqueue is processed in order, we can
506 easily achieve that by getting the inflight descriptors from
507 descriptor table (split virtqueue) or descriptor ring (packed
508 virtqueue). However, it can't work when we process descriptors
509 out-of-order because some entries which store the information of
510 inflight descriptors in available ring (split virtqueue) or descriptor
511 ring (packed virtqueue) might be overrided by new entries. To solve
512 this problem, slave need to allocate an extra buffer to store this
513 information of inflight descriptors and share it with master for
514 persistent. ``VHOST_USER_GET_INFLIGHT_FD`` and
515 ``VHOST_USER_SET_INFLIGHT_FD`` are used to transfer this buffer
516 between master and slave. And the format of this buffer is described
517 below:
519 +---------------+---------------+-----+---------------+
520 | queue0 region | queue1 region | ... | queueN region |
521 +---------------+---------------+-----+---------------+
523 N is the number of available virtqueues. Slave could get it from num
524 queues field of ``VhostUserInflight``.
526 For split virtqueue, queue region can be implemented as:
528 .. code:: c
530   typedef struct DescStateSplit {
531       /* Indicate whether this descriptor is inflight or not.
532        * Only available for head-descriptor. */
533       uint8_t inflight;
535       /* Padding */
536       uint8_t padding[5];
538       /* Maintain a list for the last batch of used descriptors.
539        * Only available when batching is used for submitting */
540       uint16_t next;
542       /* Used to preserve the order of fetching available descriptors.
543        * Only available for head-descriptor. */
544       uint64_t counter;
545   } DescStateSplit;
547   typedef struct QueueRegionSplit {
548       /* The feature flags of this region. Now it's initialized to 0. */
549       uint64_t features;
551       /* The version of this region. It's 1 currently.
552        * Zero value indicates an uninitialized buffer */
553       uint16_t version;
555       /* The size of DescStateSplit array. It's equal to the virtqueue
556        * size. Slave could get it from queue size field of VhostUserInflight. */
557       uint16_t desc_num;
559       /* The head of list that track the last batch of used descriptors. */
560       uint16_t last_batch_head;
562       /* Store the idx value of used ring */
563       uint16_t used_idx;
565       /* Used to track the state of each descriptor in descriptor table */
566       DescStateSplit desc[0];
567   } QueueRegionSplit;
569 To track inflight I/O, the queue region should be processed as follows:
571 When receiving available buffers from the driver:
573 #. Get the next available head-descriptor index from available ring, ``i``
575 #. Set ``desc[i].counter`` to the value of global counter
577 #. Increase global counter by 1
579 #. Set ``desc[i].inflight`` to 1
581 When supplying used buffers to the driver:
583 1. Get corresponding used head-descriptor index, i
585 2. Set ``desc[i].next`` to ``last_batch_head``
587 3. Set ``last_batch_head`` to ``i``
589 #. Steps 1,2,3 may be performed repeatedly if batching is possible
591 #. Increase the ``idx`` value of used ring by the size of the batch
593 #. Set the ``inflight`` field of each ``DescStateSplit`` entry in the batch to 0
595 #. Set ``used_idx`` to the ``idx`` value of used ring
597 When reconnecting:
599 #. If the value of ``used_idx`` does not match the ``idx`` value of
600    used ring (means the inflight field of ``DescStateSplit`` entries in
601    last batch may be incorrect),
603    a. Subtract the value of ``used_idx`` from the ``idx`` value of
604       used ring to get last batch size of ``DescStateSplit`` entries
606    #. Set the ``inflight`` field of each ``DescStateSplit`` entry to 0 in last batch
607       list which starts from ``last_batch_head``
609    #. Set ``used_idx`` to the ``idx`` value of used ring
611 #. Resubmit inflight ``DescStateSplit`` entries in order of their
612    counter value
614 For packed virtqueue, queue region can be implemented as:
616 .. code:: c
618   typedef struct DescStatePacked {
619       /* Indicate whether this descriptor is inflight or not.
620        * Only available for head-descriptor. */
621       uint8_t inflight;
623       /* Padding */
624       uint8_t padding;
626       /* Link to the next free entry */
627       uint16_t next;
629       /* Link to the last entry of descriptor list.
630        * Only available for head-descriptor. */
631       uint16_t last;
633       /* The length of descriptor list.
634        * Only available for head-descriptor. */
635       uint16_t num;
637       /* Used to preserve the order of fetching available descriptors.
638        * Only available for head-descriptor. */
639       uint64_t counter;
641       /* The buffer id */
642       uint16_t id;
644       /* The descriptor flags */
645       uint16_t flags;
647       /* The buffer length */
648       uint32_t len;
650       /* The buffer address */
651       uint64_t addr;
652   } DescStatePacked;
654   typedef struct QueueRegionPacked {
655       /* The feature flags of this region. Now it's initialized to 0. */
656       uint64_t features;
658       /* The version of this region. It's 1 currently.
659        * Zero value indicates an uninitialized buffer */
660       uint16_t version;
662       /* The size of DescStatePacked array. It's equal to the virtqueue
663        * size. Slave could get it from queue size field of VhostUserInflight. */
664       uint16_t desc_num;
666       /* The head of free DescStatePacked entry list */
667       uint16_t free_head;
669       /* The old head of free DescStatePacked entry list */
670       uint16_t old_free_head;
672       /* The used index of descriptor ring */
673       uint16_t used_idx;
675       /* The old used index of descriptor ring */
676       uint16_t old_used_idx;
678       /* Device ring wrap counter */
679       uint8_t used_wrap_counter;
681       /* The old device ring wrap counter */
682       uint8_t old_used_wrap_counter;
684       /* Padding */
685       uint8_t padding[7];
687       /* Used to track the state of each descriptor fetched from descriptor ring */
688       DescStatePacked desc[0];
689   } QueueRegionPacked;
691 To track inflight I/O, the queue region should be processed as follows:
693 When receiving available buffers from the driver:
695 #. Get the next available descriptor entry from descriptor ring, ``d``
697 #. If ``d`` is head descriptor,
699    a. Set ``desc[old_free_head].num`` to 0
701    #. Set ``desc[old_free_head].counter`` to the value of global counter
703    #. Increase global counter by 1
705    #. Set ``desc[old_free_head].inflight`` to 1
707 #. If ``d`` is last descriptor, set ``desc[old_free_head].last`` to
708    ``free_head``
710 #. Increase ``desc[old_free_head].num`` by 1
712 #. Set ``desc[free_head].addr``, ``desc[free_head].len``,
713    ``desc[free_head].flags``, ``desc[free_head].id`` to ``d.addr``,
714    ``d.len``, ``d.flags``, ``d.id``
716 #. Set ``free_head`` to ``desc[free_head].next``
718 #. If ``d`` is last descriptor, set ``old_free_head`` to ``free_head``
720 When supplying used buffers to the driver:
722 1. Get corresponding used head-descriptor entry from descriptor ring,
723    ``d``
725 2. Get corresponding ``DescStatePacked`` entry, ``e``
727 3. Set ``desc[e.last].next`` to ``free_head``
729 4. Set ``free_head`` to the index of ``e``
731 #. Steps 1,2,3,4 may be performed repeatedly if batching is possible
733 #. Increase ``used_idx`` by the size of the batch and update
734    ``used_wrap_counter`` if needed
736 #. Update ``d.flags``
738 #. Set the ``inflight`` field of each head ``DescStatePacked`` entry
739    in the batch to 0
741 #. Set ``old_free_head``,  ``old_used_idx``, ``old_used_wrap_counter``
742    to ``free_head``, ``used_idx``, ``used_wrap_counter``
744 When reconnecting:
746 #. If ``used_idx`` does not match ``old_used_idx`` (means the
747    ``inflight`` field of ``DescStatePacked`` entries in last batch may
748    be incorrect),
750    a. Get the next descriptor ring entry through ``old_used_idx``, ``d``
752    #. Use ``old_used_wrap_counter`` to calculate the available flags
754    #. If ``d.flags`` is not equal to the calculated flags value (means
755       slave has submitted the buffer to guest driver before crash, so
756       it has to commit the in-progres update), set ``old_free_head``,
757       ``old_used_idx``, ``old_used_wrap_counter`` to ``free_head``,
758       ``used_idx``, ``used_wrap_counter``
760 #. Set ``free_head``, ``used_idx``, ``used_wrap_counter`` to
761    ``old_free_head``, ``old_used_idx``, ``old_used_wrap_counter``
762    (roll back any in-progress update)
764 #. Set the ``inflight`` field of each ``DescStatePacked`` entry in
765    free list to 0
767 #. Resubmit inflight ``DescStatePacked`` entries in order of their
768    counter value
770 Protocol features
771 -----------------
773 .. code:: c
775   #define VHOST_USER_PROTOCOL_F_MQ             0
776   #define VHOST_USER_PROTOCOL_F_LOG_SHMFD      1
777   #define VHOST_USER_PROTOCOL_F_RARP           2
778   #define VHOST_USER_PROTOCOL_F_REPLY_ACK      3
779   #define VHOST_USER_PROTOCOL_F_MTU            4
780   #define VHOST_USER_PROTOCOL_F_SLAVE_REQ      5
781   #define VHOST_USER_PROTOCOL_F_CROSS_ENDIAN   6
782   #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7
783   #define VHOST_USER_PROTOCOL_F_PAGEFAULT      8
784   #define VHOST_USER_PROTOCOL_F_CONFIG         9
785   #define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD  10
786   #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER  11
787   #define VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD 12
788   #define VHOST_USER_PROTOCOL_F_RESET_DEVICE   13
790 Master message types
791 --------------------
793 ``VHOST_USER_GET_FEATURES``
794   :id: 1
795   :equivalent ioctl: ``VHOST_GET_FEATURES``
796   :master payload: N/A
797   :slave payload: ``u64``
799   Get from the underlying vhost implementation the features bitmask.
800   Feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` signals slave support
801   for ``VHOST_USER_GET_PROTOCOL_FEATURES`` and
802   ``VHOST_USER_SET_PROTOCOL_FEATURES``.
804 ``VHOST_USER_SET_FEATURES``
805   :id: 2
806   :equivalent ioctl: ``VHOST_SET_FEATURES``
807   :master payload: ``u64``
809   Enable features in the underlying vhost implementation using a
810   bitmask.  Feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` signals
811   slave support for ``VHOST_USER_GET_PROTOCOL_FEATURES`` and
812   ``VHOST_USER_SET_PROTOCOL_FEATURES``.
814 ``VHOST_USER_GET_PROTOCOL_FEATURES``
815   :id: 15
816   :equivalent ioctl: ``VHOST_GET_FEATURES``
817   :master payload: N/A
818   :slave payload: ``u64``
820   Get the protocol feature bitmask from the underlying vhost
821   implementation.  Only legal if feature bit
822   ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in
823   ``VHOST_USER_GET_FEATURES``.
825 .. Note::
826    Slave that reported ``VHOST_USER_F_PROTOCOL_FEATURES`` must
827    support this message even before ``VHOST_USER_SET_FEATURES`` was
828    called.
830 ``VHOST_USER_SET_PROTOCOL_FEATURES``
831   :id: 16
832   :equivalent ioctl: ``VHOST_SET_FEATURES``
833   :master payload: ``u64``
835   Enable protocol features in the underlying vhost implementation.
837   Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is present in
838   ``VHOST_USER_GET_FEATURES``.
840 .. Note::
841    Slave that reported ``VHOST_USER_F_PROTOCOL_FEATURES`` must support
842    this message even before ``VHOST_USER_SET_FEATURES`` was called.
844 ``VHOST_USER_SET_OWNER``
845   :id: 3
846   :equivalent ioctl: ``VHOST_SET_OWNER``
847   :master payload: N/A
849   Issued when a new connection is established. It sets the current
850   *master* as an owner of the session. This can be used on the *slave*
851   as a "session start" flag.
853 ``VHOST_USER_RESET_OWNER``
854   :id: 4
855   :master payload: N/A
857 .. admonition:: Deprecated
859    This is no longer used. Used to be sent to request disabling all
860    rings, but some clients interpreted it to also discard connection
861    state (this interpretation would lead to bugs).  It is recommended
862    that clients either ignore this message, or use it to disable all
863    rings.
865 ``VHOST_USER_SET_MEM_TABLE``
866   :id: 5
867   :equivalent ioctl: ``VHOST_SET_MEM_TABLE``
868   :master payload: memory regions description
869   :slave payload: (postcopy only) memory regions description
871   Sets the memory map regions on the slave so it can translate the
872   vring addresses. In the ancillary data there is an array of file
873   descriptors for each memory mapped region. The size and ordering of
874   the fds matches the number and ordering of memory regions.
876   When ``VHOST_USER_POSTCOPY_LISTEN`` has been received,
877   ``SET_MEM_TABLE`` replies with the bases of the memory mapped
878   regions to the master.  The slave must have mmap'd the regions but
879   not yet accessed them and should not yet generate a userfault
880   event.
882 .. Note::
883    ``NEED_REPLY_MASK`` is not set in this case.  QEMU will then
884    reply back to the list of mappings with an empty
885    ``VHOST_USER_SET_MEM_TABLE`` as an acknowledgement; only upon
886    reception of this message may the guest start accessing the memory
887    and generating faults.
889 ``VHOST_USER_SET_LOG_BASE``
890   :id: 6
891   :equivalent ioctl: ``VHOST_SET_LOG_BASE``
892   :master payload: u64
893   :slave payload: N/A
895   Sets logging shared memory space.
897   When slave has ``VHOST_USER_PROTOCOL_F_LOG_SHMFD`` protocol feature,
898   the log memory fd is provided in the ancillary data of
899   ``VHOST_USER_SET_LOG_BASE`` message, the size and offset of shared
900   memory area provided in the message.
902 ``VHOST_USER_SET_LOG_FD``
903   :id: 7
904   :equivalent ioctl: ``VHOST_SET_LOG_FD``
905   :master payload: N/A
907   Sets the logging file descriptor, which is passed as ancillary data.
909 ``VHOST_USER_SET_VRING_NUM``
910   :id: 8
911   :equivalent ioctl: ``VHOST_SET_VRING_NUM``
912   :master payload: vring state description
914   Set the size of the queue.
916 ``VHOST_USER_SET_VRING_ADDR``
917   :id: 9
918   :equivalent ioctl: ``VHOST_SET_VRING_ADDR``
919   :master payload: vring address description
920   :slave payload: N/A
922   Sets the addresses of the different aspects of the vring.
924 ``VHOST_USER_SET_VRING_BASE``
925   :id: 10
926   :equivalent ioctl: ``VHOST_SET_VRING_BASE``
927   :master payload: vring state description
929   Sets the base offset in the available vring.
931 ``VHOST_USER_GET_VRING_BASE``
932   :id: 11
933   :equivalent ioctl: ``VHOST_USER_GET_VRING_BASE``
934   :master payload: vring state description
935   :slave payload: vring state description
937   Get the available vring base offset.
939 ``VHOST_USER_SET_VRING_KICK``
940   :id: 12
941   :equivalent ioctl: ``VHOST_SET_VRING_KICK``
942   :master payload: ``u64``
944   Set the event file descriptor for adding buffers to the vring. It is
945   passed in the ancillary data.
947   Bits (0-7) of the payload contain the vring index. Bit 8 is the
948   invalid FD flag. This flag is set when there is no file descriptor
949   in the ancillary data. This signals that polling should be used
950   instead of waiting for a kick.
952 ``VHOST_USER_SET_VRING_CALL``
953   :id: 13
954   :equivalent ioctl: ``VHOST_SET_VRING_CALL``
955   :master payload: ``u64``
957   Set the event file descriptor to signal when buffers are used. It is
958   passed in the ancillary data.
960   Bits (0-7) of the payload contain the vring index. Bit 8 is the
961   invalid FD flag. This flag is set when there is no file descriptor
962   in the ancillary data. This signals that polling will be used
963   instead of waiting for the call.
965 ``VHOST_USER_SET_VRING_ERR``
966   :id: 14
967   :equivalent ioctl: ``VHOST_SET_VRING_ERR``
968   :master payload: ``u64``
970   Set the event file descriptor to signal when error occurs. It is
971   passed in the ancillary data.
973   Bits (0-7) of the payload contain the vring index. Bit 8 is the
974   invalid FD flag. This flag is set when there is no file descriptor
975   in the ancillary data.
977 ``VHOST_USER_GET_QUEUE_NUM``
978   :id: 17
979   :equivalent ioctl: N/A
980   :master payload: N/A
981   :slave payload: u64
983   Query how many queues the backend supports.
985   This request should be sent only when ``VHOST_USER_PROTOCOL_F_MQ``
986   is set in queried protocol features by
987   ``VHOST_USER_GET_PROTOCOL_FEATURES``.
989 ``VHOST_USER_SET_VRING_ENABLE``
990   :id: 18
991   :equivalent ioctl: N/A
992   :master payload: vring state description
994   Signal slave to enable or disable corresponding vring.
996   This request should be sent only when
997   ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated.
999 ``VHOST_USER_SEND_RARP``
1000   :id: 19
1001   :equivalent ioctl: N/A
1002   :master payload: ``u64``
1004   Ask vhost user backend to broadcast a fake RARP to notify the migration
1005   is terminated for guest that does not support GUEST_ANNOUNCE.
1007   Only legal if feature bit ``VHOST_USER_F_PROTOCOL_FEATURES`` is
1008   present in ``VHOST_USER_GET_FEATURES`` and protocol feature bit
1009   ``VHOST_USER_PROTOCOL_F_RARP`` is present in
1010   ``VHOST_USER_GET_PROTOCOL_FEATURES``.  The first 6 bytes of the
1011   payload contain the mac address of the guest to allow the vhost user
1012   backend to construct and broadcast the fake RARP.
1014 ``VHOST_USER_NET_SET_MTU``
1015   :id: 20
1016   :equivalent ioctl: N/A
1017   :master payload: ``u64``
1019   Set host MTU value exposed to the guest.
1021   This request should be sent only when ``VIRTIO_NET_F_MTU`` feature
1022   has been successfully negotiated, ``VHOST_USER_F_PROTOCOL_FEATURES``
1023   is present in ``VHOST_USER_GET_FEATURES`` and protocol feature bit
1024   ``VHOST_USER_PROTOCOL_F_NET_MTU`` is present in
1025   ``VHOST_USER_GET_PROTOCOL_FEATURES``.
1027   If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, slave must
1028   respond with zero in case the specified MTU is valid, or non-zero
1029   otherwise.
1031 ``VHOST_USER_SET_SLAVE_REQ_FD``
1032   :id: 21
1033   :equivalent ioctl: N/A
1034   :master payload: N/A
1036   Set the socket file descriptor for slave initiated requests. It is passed
1037   in the ancillary data.
1039   This request should be sent only when
1040   ``VHOST_USER_F_PROTOCOL_FEATURES`` has been negotiated, and protocol
1041   feature bit ``VHOST_USER_PROTOCOL_F_SLAVE_REQ`` bit is present in
1042   ``VHOST_USER_GET_PROTOCOL_FEATURES``.  If
1043   ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, slave must
1044   respond with zero for success, non-zero otherwise.
1046 ``VHOST_USER_IOTLB_MSG``
1047   :id: 22
1048   :equivalent ioctl: N/A (equivalent to ``VHOST_IOTLB_MSG`` message type)
1049   :master payload: ``struct vhost_iotlb_msg``
1050   :slave payload: ``u64``
1052   Send IOTLB messages with ``struct vhost_iotlb_msg`` as payload.
1054   Master sends such requests to update and invalidate entries in the
1055   device IOTLB. The slave has to acknowledge the request with sending
1056   zero as ``u64`` payload for success, non-zero otherwise.
1058   This request should be send only when ``VIRTIO_F_IOMMU_PLATFORM``
1059   feature has been successfully negotiated.
1061 ``VHOST_USER_SET_VRING_ENDIAN``
1062   :id: 23
1063   :equivalent ioctl: ``VHOST_SET_VRING_ENDIAN``
1064   :master payload: vring state description
1066   Set the endianness of a VQ for legacy devices. Little-endian is
1067   indicated with state.num set to 0 and big-endian is indicated with
1068   state.num set to 1. Other values are invalid.
1070   This request should be sent only when
1071   ``VHOST_USER_PROTOCOL_F_CROSS_ENDIAN`` has been negotiated.
1072   Backends that negotiated this feature should handle both
1073   endiannesses and expect this message once (per VQ) during device
1074   configuration (ie. before the master starts the VQ).
1076 ``VHOST_USER_GET_CONFIG``
1077   :id: 24
1078   :equivalent ioctl: N/A
1079   :master payload: virtio device config space
1080   :slave payload: virtio device config space
1082   When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, this message is
1083   submitted by the vhost-user master to fetch the contents of the
1084   virtio device configuration space, vhost-user slave's payload size
1085   MUST match master's request, vhost-user slave uses zero length of
1086   payload to indicate an error to vhost-user master. The vhost-user
1087   master may cache the contents to avoid repeated
1088   ``VHOST_USER_GET_CONFIG`` calls.
1090 ``VHOST_USER_SET_CONFIG``
1091   :id: 25
1092   :equivalent ioctl: N/A
1093   :master payload: virtio device config space
1094   :slave payload: N/A
1096   When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, this message is
1097   submitted by the vhost-user master when the Guest changes the virtio
1098   device configuration space and also can be used for live migration
1099   on the destination host. The vhost-user slave must check the flags
1100   field, and slaves MUST NOT accept SET_CONFIG for read-only
1101   configuration space fields unless the live migration bit is set.
1103 ``VHOST_USER_CREATE_CRYPTO_SESSION``
1104   :id: 26
1105   :equivalent ioctl: N/A
1106   :master payload: crypto session description
1107   :slave payload: crypto session description
1109   Create a session for crypto operation. The server side must return
1110   the session id, 0 or positive for success, negative for failure.
1111   This request should be sent only when
1112   ``VHOST_USER_PROTOCOL_F_CRYPTO_SESSION`` feature has been
1113   successfully negotiated.  It's a required feature for crypto
1114   devices.
1116 ``VHOST_USER_CLOSE_CRYPTO_SESSION``
1117   :id: 27
1118   :equivalent ioctl: N/A
1119   :master payload: ``u64``
1121   Close a session for crypto operation which was previously
1122   created by ``VHOST_USER_CREATE_CRYPTO_SESSION``.
1124   This request should be sent only when
1125   ``VHOST_USER_PROTOCOL_F_CRYPTO_SESSION`` feature has been
1126   successfully negotiated.  It's a required feature for crypto
1127   devices.
1129 ``VHOST_USER_POSTCOPY_ADVISE``
1130   :id: 28
1131   :master payload: N/A
1132   :slave payload: userfault fd
1134   When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, the master
1135   advises slave that a migration with postcopy enabled is underway,
1136   the slave must open a userfaultfd for later use.  Note that at this
1137   stage the migration is still in precopy mode.
1139 ``VHOST_USER_POSTCOPY_LISTEN``
1140   :id: 29
1141   :master payload: N/A
1143   Master advises slave that a transition to postcopy mode has
1144   happened.  The slave must ensure that shared memory is registered
1145   with userfaultfd to cause faulting of non-present pages.
1147   This is always sent sometime after a ``VHOST_USER_POSTCOPY_ADVISE``,
1148   and thus only when ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported.
1150 ``VHOST_USER_POSTCOPY_END``
1151   :id: 30
1152   :slave payload: ``u64``
1154   Master advises that postcopy migration has now completed.  The slave
1155   must disable the userfaultfd. The response is an acknowledgement
1156   only.
1158   When ``VHOST_USER_PROTOCOL_F_PAGEFAULT`` is supported, this message
1159   is sent at the end of the migration, after
1160   ``VHOST_USER_POSTCOPY_LISTEN`` was previously sent.
1162   The value returned is an error indication; 0 is success.
1164 ``VHOST_USER_GET_INFLIGHT_FD``
1165   :id: 31
1166   :equivalent ioctl: N/A
1167   :master payload: inflight description
1169   When ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD`` protocol feature has
1170   been successfully negotiated, this message is submitted by master to
1171   get a shared buffer from slave. The shared buffer will be used to
1172   track inflight I/O by slave. QEMU should retrieve a new one when vm
1173   reset.
1175 ``VHOST_USER_SET_INFLIGHT_FD``
1176   :id: 32
1177   :equivalent ioctl: N/A
1178   :master payload: inflight description
1180   When ``VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD`` protocol feature has
1181   been successfully negotiated, this message is submitted by master to
1182   send the shared inflight buffer back to slave so that slave could
1183   get inflight I/O after a crash or restart.
1185 ``VHOST_USER_GPU_SET_SOCKET``
1186   :id: 33
1187   :equivalent ioctl: N/A
1188   :master payload: N/A
1190   Sets the GPU protocol socket file descriptor, which is passed as
1191   ancillary data. The GPU protocol is used to inform the master of
1192   rendering state and updates. See vhost-user-gpu.rst for details.
1194 ``VHOST_USER_RESET_DEVICE``
1195   :id: 34
1196   :equivalent ioctl: N/A
1197   :master payload: N/A
1198   :slave payload: N/A
1200   Ask the vhost user backend to disable all rings and reset all
1201   internal device state to the initial state, ready to be
1202   reinitialized. The backend retains ownership of the device
1203   throughout the reset operation.
1205   Only valid if the ``VHOST_USER_PROTOCOL_F_RESET_DEVICE`` protocol
1206   feature is set by the backend.
1208 Slave message types
1209 -------------------
1211 ``VHOST_USER_SLAVE_IOTLB_MSG``
1212   :id: 1
1213   :equivalent ioctl: N/A (equivalent to ``VHOST_IOTLB_MSG`` message type)
1214   :slave payload: ``struct vhost_iotlb_msg``
1215   :master payload: N/A
1217   Send IOTLB messages with ``struct vhost_iotlb_msg`` as payload.
1218   Slave sends such requests to notify of an IOTLB miss, or an IOTLB
1219   access failure. If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is
1220   negotiated, and slave set the ``VHOST_USER_NEED_REPLY`` flag, master
1221   must respond with zero when operation is successfully completed, or
1222   non-zero otherwise.  This request should be send only when
1223   ``VIRTIO_F_IOMMU_PLATFORM`` feature has been successfully
1224   negotiated.
1226 ``VHOST_USER_SLAVE_CONFIG_CHANGE_MSG``
1227   :id: 2
1228   :equivalent ioctl: N/A
1229   :slave payload: N/A
1230   :master payload: N/A
1232   When ``VHOST_USER_PROTOCOL_F_CONFIG`` is negotiated, vhost-user
1233   slave sends such messages to notify that the virtio device's
1234   configuration space has changed, for those host devices which can
1235   support such feature, host driver can send ``VHOST_USER_GET_CONFIG``
1236   message to slave to get the latest content. If
1237   ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and slave set the
1238   ``VHOST_USER_NEED_REPLY`` flag, master must respond with zero when
1239   operation is successfully completed, or non-zero otherwise.
1241 ``VHOST_USER_SLAVE_VRING_HOST_NOTIFIER_MSG``
1242   :id: 3
1243   :equivalent ioctl: N/A
1244   :slave payload: vring area description
1245   :master payload: N/A
1247   Sets host notifier for a specified queue. The queue index is
1248   contained in the ``u64`` field of the vring area description. The
1249   host notifier is described by the file descriptor (typically it's a
1250   VFIO device fd) which is passed as ancillary data and the size
1251   (which is mmap size and should be the same as host page size) and
1252   offset (which is mmap offset) carried in the vring area
1253   description. QEMU can mmap the file descriptor based on the size and
1254   offset to get a memory range. Registering a host notifier means
1255   mapping this memory range to the VM as the specified queue's notify
1256   MMIO region. Slave sends this request to tell QEMU to de-register
1257   the existing notifier if any and register the new notifier if the
1258   request is sent with a file descriptor.
1260   This request should be sent only when
1261   ``VHOST_USER_PROTOCOL_F_HOST_NOTIFIER`` protocol feature has been
1262   successfully negotiated.
1264 .. _reply_ack:
1266 VHOST_USER_PROTOCOL_F_REPLY_ACK
1267 -------------------------------
1269 The original vhost-user specification only demands replies for certain
1270 commands. This differs from the vhost protocol implementation where
1271 commands are sent over an ``ioctl()`` call and block until the client
1272 has completed.
1274 With this protocol extension negotiated, the sender (QEMU) can set the
1275 ``need_reply`` [Bit 3] flag to any command. This indicates that the
1276 client MUST respond with a Payload ``VhostUserMsg`` indicating success
1277 or failure. The payload should be set to zero on success or non-zero
1278 on failure, unless the message already has an explicit reply body.
1280 The response payload gives QEMU a deterministic indication of the result
1281 of the command. Today, QEMU is expected to terminate the main vhost-user
1282 loop upon receiving such errors. In future, qemu could be taught to be more
1283 resilient for selective requests.
1285 For the message types that already solicit a reply from the client,
1286 the presence of ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` or need_reply bit
1287 being set brings no behavioural change. (See the Communication_
1288 section for details.)
1290 .. _backend_conventions:
1292 Backend program conventions
1293 ===========================
1295 vhost-user backends can provide various devices & services and may
1296 need to be configured manually depending on the use case. However, it
1297 is a good idea to follow the conventions listed here when
1298 possible. Users, QEMU or libvirt, can then rely on some common
1299 behaviour to avoid heterogenous configuration and management of the
1300 backend programs and facilitate interoperability.
1302 Each backend installed on a host system should come with at least one
1303 JSON file that conforms to the vhost-user.json schema. Each file
1304 informs the management applications about the backend type, and binary
1305 location. In addition, it defines rules for management apps for
1306 picking the highest priority backend when multiple match the search
1307 criteria (see ``@VhostUserBackend`` documentation in the schema file).
1309 If the backend is not capable of enabling a requested feature on the
1310 host (such as 3D acceleration with virgl), or the initialization
1311 failed, the backend should fail to start early and exit with a status
1312 != 0. It may also print a message to stderr for further details.
1314 The backend program must not daemonize itself, but it may be
1315 daemonized by the management layer. It may also have a restricted
1316 access to the system.
1318 File descriptors 0, 1 and 2 will exist, and have regular
1319 stdin/stdout/stderr usage (they may have been redirected to /dev/null
1320 by the management layer, or to a log handler).
1322 The backend program must end (as quickly and cleanly as possible) when
1323 the SIGTERM signal is received. Eventually, it may receive SIGKILL by
1324 the management layer after a few seconds.
1326 The following command line options have an expected behaviour. They
1327 are mandatory, unless explicitly said differently:
1329 --socket-path=PATH
1331   This option specify the location of the vhost-user Unix domain socket.
1332   It is incompatible with --fd.
1334 --fd=FDNUM
1336   When this argument is given, the backend program is started with the
1337   vhost-user socket as file descriptor FDNUM. It is incompatible with
1338   --socket-path.
1340 --print-capabilities
1342   Output to stdout the backend capabilities in JSON format, and then
1343   exit successfully. Other options and arguments should be ignored, and
1344   the backend program should not perform its normal function.  The
1345   capabilities can be reported dynamically depending on the host
1346   capabilities.
1348 The JSON output is described in the ``vhost-user.json`` schema, by
1349 ```@VHostUserBackendCapabilities``.  Example:
1351 .. code:: json
1353   {
1354     "type": "foo",
1355     "features": [
1356       "feature-a",
1357       "feature-b"
1358     ]
1359   }
1361 vhost-user-input
1362 ----------------
1364 Command line options:
1366 --evdev-path=PATH
1368   Specify the linux input device.
1370   (optional)
1372 --no-grab
1374   Do no request exclusive access to the input device.
1376   (optional)
1378 vhost-user-gpu
1379 --------------
1381 Command line options:
1383 --render-node=PATH
1385   Specify the GPU DRM render node.
1387   (optional)
1389 --virgl
1391   Enable virgl rendering support.
1393   (optional)
1395 vhost-user-blk
1396 --------------
1398 Command line options:
1400 --blk-file=PATH
1402   Specify block device or file path.
1404   (optional)
1406 --read-only
1408   Enable read-only.
1410   (optional)