docs/specs/vhost-user.txt

   1 Vhost-user Protocol
   2 ===================
   3
   4 Copyright (c) 2014 Virtual Open Systems Sarl.
   5
   6 This work is licensed under the terms of the GNU GPL, version 2 or later.
   7 See the COPYING file in the top-level directory.
   8 ===================
   9
  10 This protocol is aiming to complement the ioctl interface used to control the
  11 vhost implementation in the Linux kernel. It implements the control plane needed
  12 to establish virtqueue sharing with a user space process on the same host. It
  13 uses communication over a Unix domain socket to share file descriptors in the
  14 ancillary data of the message.
  15
  16 The protocol defines 2 sides of the communication, master and slave. Master is
  17 the application that shares its virtqueues, in our case QEMU. Slave is the
  18 consumer of the virtqueues.
  19
  20 In the current implementation QEMU is the Master, and the Slave is intended to
  21 be a software Ethernet switch running in user space, such as Snabbswitch.
  22
  23 Master and slave can be either a client (i.e. connecting) or server (listening)
  24 in the socket communication.
  25
  26 Message Specification
  27 ---------------------
  28
  29 Note that all numbers are in the machine native byte order. A vhost-user message
  30 consists of 3 header fields and a payload:
  31
  32 ------------------------------------
  33 | request | flags | size | payload |
  34 ------------------------------------
  35
  36  * Request: 32-bit type of the request
  37  * Flags: 32-bit bit field:
  38    - Lower 2 bits are the version (currently 0x01)
  39    - Bit 2 is the reply flag - needs to be sent on each reply from the slave
  40    - Bit 3 is the need_reply flag - see VHOST_USER_PROTOCOL_F_REPLY_ACK for
  41      details.
  42  * Size - 32-bit size of the payload
  43
  44
  45 Depending on the request type, payload can be:
  46
  47  * A single 64-bit integer
  48    -------
  49    | u64 |
  50    -------
  51
  52    u64: a 64-bit unsigned integer
  53
  54  * A vring state description
  55    ---------------
  56   | index | num |
  57   ---------------
  58
  59    Index: a 32-bit index
  60    Num: a 32-bit number
  61
  62  * A vring address description
  63    --------------------------------------------------------------
  64    | index | flags | size | descriptor | used | available | log |
  65    --------------------------------------------------------------
  66
  67    Index: a 32-bit vring index
  68    Flags: a 32-bit vring flags
  69    Descriptor: a 64-bit user address of the vring descriptor table
  70    Used: a 64-bit user address of the vring used ring
  71    Available: a 64-bit user address of the vring available ring
  72    Log: a 64-bit guest address for logging
  73
  74  * Memory regions description
  75    ---------------------------------------------------
  76    | num regions | padding | region0 | ... | region7 |
  77    ---------------------------------------------------
  78
  79    Num regions: a 32-bit number of regions
  80    Padding: 32-bit
  81
  82    A region is:
  83    -----------------------------------------------------
  84    | guest address | size | user address | mmap offset |
  85    -----------------------------------------------------
  86
  87    Guest address: a 64-bit guest address of the region
  88    Size: a 64-bit size
  89    User address: a 64-bit user address
  90    mmap offset: 64-bit offset where region starts in the mapped memory
  91
  92 * Log description
  93    ---------------------------
  94    | log size | log offset |
  95    ---------------------------
  96    log size: size of area used for logging
  97    log offset: offset from start of supplied file descriptor
  98        where logging starts (i.e. where guest address 0 would be logged)
  99
 100  * An IOTLB message
 101    ---------------------------------------------------------
 102    | iova | size | user address | permissions flags | type |
 103    ---------------------------------------------------------
 104
 105    IOVA: a 64-bit I/O virtual address programmed by the guest
 106    Size: a 64-bit size
 107    User address: a 64-bit user address
 108    Permissions: a 8-bit value:
 109     - 0: No access
 110     - 1: Read access
 111     - 2: Write access
 112     - 3: Read/Write access
 113    Type: a 8-bit IOTLB message type:
 114     - 1: IOTLB miss
 115     - 2: IOTLB update
 116     - 3: IOTLB invalidate
 117     - 4: IOTLB access fail
 118
 119 In QEMU the vhost-user message is implemented with the following struct:
 120
 121 typedef struct VhostUserMsg {
 122     VhostUserRequest request;
 123     uint32_t flags;
 124     uint32_t size;
 125     union {
 126         uint64_t u64;
 127         struct vhost_vring_state state;
 128         struct vhost_vring_addr addr;
 129         VhostUserMemory memory;
 130         VhostUserLog log;
 131         struct vhost_iotlb_msg iotlb;
 132     };
 133 } QEMU_PACKED VhostUserMsg;
 134
 135 Communication
 136 -------------
 137
 138 The protocol for vhost-user is based on the existing implementation of vhost
 139 for the Linux Kernel. Most messages that can be sent via the Unix domain socket
 140 implementing vhost-user have an equivalent ioctl to the kernel implementation.
 141
 142 The communication consists of master sending message requests and slave sending
 143 message replies. Most of the requests don't require replies. Here is a list of
 144 the ones that do:
 145
 146  * VHOST_USER_GET_FEATURES
 147  * VHOST_USER_GET_PROTOCOL_FEATURES
 148  * VHOST_USER_GET_VRING_BASE
 149  * VHOST_USER_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
 150
 151 [ Also see the section on REPLY_ACK protocol extension. ]
 152
 153 There are several messages that the master sends with file descriptors passed
 154 in the ancillary data:
 155
 156  * VHOST_USER_SET_MEM_TABLE
 157  * VHOST_USER_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
 158  * VHOST_USER_SET_LOG_FD
 159  * VHOST_USER_SET_VRING_KICK
 160  * VHOST_USER_SET_VRING_CALL
 161  * VHOST_USER_SET_VRING_ERR
 162  * VHOST_USER_SET_SLAVE_REQ_FD
 163
 164 If Master is unable to send the full message or receives a wrong reply it will
 165 close the connection. An optional reconnection mechanism can be implemented.
 166
 167 Any protocol extensions are gated by protocol feature bits,
 168 which allows full backwards compatibility on both master
 169 and slave.
 170 As older slaves don't support negotiating protocol features,
 171 a feature bit was dedicated for this purpose:
 172 #define VHOST_USER_F_PROTOCOL_FEATURES 30
 173
 174 Starting and stopping rings
 175 ----------------------
 176 Client must only process each ring when it is started.
 177
 178 Client must only pass data between the ring and the
 179 backend, when the ring is enabled.
 180
 181 If ring is started but disabled, client must process the
 182 ring without talking to the backend.
 183
 184 For example, for a networking device, in the disabled state
 185 client must not supply any new RX packets, but must process
 186 and discard any TX packets.
 187
 188 If VHOST_USER_F_PROTOCOL_FEATURES has not been negotiated, the ring is initialized
 189 in an enabled state.
 190
 191 If VHOST_USER_F_PROTOCOL_FEATURES has been negotiated, the ring is initialized
 192 in a disabled state. Client must not pass data to/from the backend until ring is enabled by
 193 VHOST_USER_SET_VRING_ENABLE with parameter 1, or after it has been disabled by
 194 VHOST_USER_SET_VRING_ENABLE with parameter 0.
 195
 196 Each ring is initialized in a stopped state, client must not process it until
 197 ring is started, or after it has been stopped.
 198
 199 Client must start ring upon receiving a kick (that is, detecting that file
 200 descriptor is readable) on the descriptor specified by
 201 VHOST_USER_SET_VRING_KICK, and stop ring upon receiving
 202 VHOST_USER_GET_VRING_BASE.
 203
 204 While processing the rings (whether they are enabled or not), client must
 205 support changing some configuration aspects on the fly.
 206
 207 Multiple queue support
 208 ----------------------
 209
 210 Multiple queue is treated as a protocol extension, hence the slave has to
 211 implement protocol features first. The multiple queues feature is supported
 212 only when the protocol feature VHOST_USER_PROTOCOL_F_MQ (bit 0) is set.
 213
 214 The max number of queues the slave supports can be queried with message
 215 VHOST_USER_GET_PROTOCOL_FEATURES. Master should stop when the number of
 216 requested queues is bigger than that.
 217
 218 As all queues share one connection, the master uses a unique index for each
 219 queue in the sent message to identify a specified queue. One queue pair
 220 is enabled initially. More queues are enabled dynamically, by sending
 221 message VHOST_USER_SET_VRING_ENABLE.
 222
 223 Migration
 224 ---------
 225
 226 During live migration, the master may need to track the modifications
 227 the slave makes to the memory mapped regions. The client should mark
 228 the dirty pages in a log. Once it complies to this logging, it may
 229 declare the VHOST_F_LOG_ALL vhost feature.
 230
 231 To start/stop logging of data/used ring writes, server may send messages
 232 VHOST_USER_SET_FEATURES with VHOST_F_LOG_ALL and VHOST_USER_SET_VRING_ADDR with
 233 VHOST_VRING_F_LOG in ring's flags set to 1/0, respectively.
 234
 235 All the modifications to memory pointed by vring "descriptor" should
 236 be marked. Modifications to "used" vring should be marked if
 237 VHOST_VRING_F_LOG is part of ring's flags.
 238
 239 Dirty pages are of size:
 240 #define VHOST_LOG_PAGE 0x1000
 241
 242 The log memory fd is provided in the ancillary data of
 243 VHOST_USER_SET_LOG_BASE message when the slave has
 244 VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol feature.
 245
 246 The size of the log is supplied as part of VhostUserMsg
 247 which should be large enough to cover all known guest
 248 addresses. Log starts at the supplied offset in the
 249 supplied file descriptor.
 250 The log covers from address 0 to the maximum of guest
 251 regions. In pseudo-code, to mark page at "addr" as dirty:
 252
 253 page = addr / VHOST_LOG_PAGE
 254 log[page / 8] |= 1 << page % 8
 255
 256 Where addr is the guest physical address.
 257
 258 Use atomic operations, as the log may be concurrently manipulated.
 259
 260 Note that when logging modifications to the used ring (when VHOST_VRING_F_LOG
 261 is set for this ring), log_guest_addr should be used to calculate the log
 262 offset: the write to first byte of the used ring is logged at this offset from
 263 log start. Also note that this value might be outside the legal guest physical
 264 address range (i.e. does not have to be covered by the VhostUserMemory table),
 265 but the bit offset of the last byte of the ring must fall within
 266 the size supplied by VhostUserLog.
 267
 268 VHOST_USER_SET_LOG_FD is an optional message with an eventfd in
 269 ancillary data, it may be used to inform the master that the log has
 270 been modified.
 271
 272 Once the source has finished migration, rings will be stopped by
 273 the source. No further update must be done before rings are
 274 restarted.
 275
 276 IOMMU support
 277 -------------
 278
 279 When the VIRTIO_F_IOMMU_PLATFORM feature has been negotiated, the master
 280 sends IOTLB entries update & invalidation by sending VHOST_USER_IOTLB_MSG
 281 requests to the slave with a struct vhost_iotlb_msg as payload. For update
 282 events, the iotlb payload has to be filled with the update message type (2),
 283 the I/O virtual address, the size, the user virtual address, and the
 284 permissions flags. Addresses and size must be within vhost memory regions set
 285 via the VHOST_USER_SET_MEM_TABLE request. For invalidation events, the iotlb
 286 payload has to be filled with the invalidation message type (3), the I/O virtual
 287 address and the size. On success, the slave is expected to reply with a zero
 288 payload, non-zero otherwise.
 289
 290 The slave relies on the slave communcation channel (see "Slave communication"
 291 section below) to send IOTLB miss and access failure events, by sending
 292 VHOST_USER_SLAVE_IOTLB_MSG requests to the master with a struct vhost_iotlb_msg
 293 as payload. For miss events, the iotlb payload has to be filled with the miss
 294 message type (1), the I/O virtual address and the permissions flags. For access
 295 failure event, the iotlb payload has to be filled with the access failure
 296 message type (4), the I/O virtual address and the permissions flags.
 297 For synchronization purpose, the slave may rely on the reply-ack feature,
 298 so the master may send a reply when operation is completed if the reply-ack
 299 feature is negotiated and slaves requests a reply. For miss events, completed
 300 operation means either master sent an update message containing the IOTLB entry
 301 containing requested address and permission, or master sent nothing if the IOTLB
 302 miss message is invalid (invalid IOVA or permission).
 303
 304 The master isn't expected to take the initiative to send IOTLB update messages,
 305 as the slave sends IOTLB miss messages for the guest virtual memory areas it
 306 needs to access.
 307
 308 Slave communication
 309 -------------------
 310
 311 An optional communication channel is provided if the slave declares
 312 VHOST_USER_PROTOCOL_F_SLAVE_REQ protocol feature, to allow the slave to make
 313 requests to the master.
 314
 315 The fd is provided via VHOST_USER_SET_SLAVE_REQ_FD ancillary data.
 316
 317 A slave may then send VHOST_USER_SLAVE_* messages to the master
 318 using this fd communication channel.
 319
 320 Protocol features
 321 -----------------
 322
 323 #define VHOST_USER_PROTOCOL_F_MQ             0
 324 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD      1
 325 #define VHOST_USER_PROTOCOL_F_RARP           2
 326 #define VHOST_USER_PROTOCOL_F_REPLY_ACK      3
 327 #define VHOST_USER_PROTOCOL_F_MTU            4
 328 #define VHOST_USER_PROTOCOL_F_SLAVE_REQ      5
 329
 330 Master message types
 331 --------------------
 332
 333  * VHOST_USER_GET_FEATURES
 334
 335       Id: 1
 336       Equivalent ioctl: VHOST_GET_FEATURES
 337       Master payload: N/A
 338       Slave payload: u64
 339
 340       Get from the underlying vhost implementation the features bitmask.
 341       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 342       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 343
 344  * VHOST_USER_SET_FEATURES
 345
 346       Id: 2
 347       Ioctl: VHOST_SET_FEATURES
 348       Master payload: u64
 349
 350       Enable features in the underlying vhost implementation using a bitmask.
 351       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 352       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 353
 354  * VHOST_USER_GET_PROTOCOL_FEATURES
 355
 356       Id: 15
 357       Equivalent ioctl: VHOST_GET_FEATURES
 358       Master payload: N/A
 359       Slave payload: u64
 360
 361       Get the protocol feature bitmask from the underlying vhost implementation.
 362       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 363       VHOST_USER_GET_FEATURES.
 364       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 365       this message even before VHOST_USER_SET_FEATURES was called.
 366
 367  * VHOST_USER_SET_PROTOCOL_FEATURES
 368
 369       Id: 16
 370       Ioctl: VHOST_SET_FEATURES
 371       Master payload: u64
 372
 373       Enable protocol features in the underlying vhost implementation.
 374       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 375       VHOST_USER_GET_FEATURES.
 376       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 377       this message even before VHOST_USER_SET_FEATURES was called.
 378
 379  * VHOST_USER_SET_OWNER
 380
 381       Id: 3
 382       Equivalent ioctl: VHOST_SET_OWNER
 383       Master payload: N/A
 384
 385       Issued when a new connection is established. It sets the current Master
 386       as an owner of the session. This can be used on the Slave as a
 387       "session start" flag.
 388
 389  * VHOST_USER_RESET_OWNER
 390
 391       Id: 4
 392       Master payload: N/A
 393
 394       This is no longer used. Used to be sent to request disabling
 395       all rings, but some clients interpreted it to also discard
 396       connection state (this interpretation would lead to bugs).
 397       It is recommended that clients either ignore this message,
 398       or use it to disable all rings.
 399
 400  * VHOST_USER_SET_MEM_TABLE
 401
 402       Id: 5
 403       Equivalent ioctl: VHOST_SET_MEM_TABLE
 404       Master payload: memory regions description
 405
 406       Sets the memory map regions on the slave so it can translate the vring
 407       addresses. In the ancillary data there is an array of file descriptors
 408       for each memory mapped region. The size and ordering of the fds matches
 409       the number and ordering of memory regions.
 410
 411  * VHOST_USER_SET_LOG_BASE
 412
 413       Id: 6
 414       Equivalent ioctl: VHOST_SET_LOG_BASE
 415       Master payload: u64
 416       Slave payload: N/A
 417
 418       Sets logging shared memory space.
 419       When slave has VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol
 420       feature, the log memory fd is provided in the ancillary data of
 421       VHOST_USER_SET_LOG_BASE message, the size and offset of shared
 422       memory area provided in the message.
 423
 424
 425  * VHOST_USER_SET_LOG_FD
 426
 427       Id: 7
 428       Equivalent ioctl: VHOST_SET_LOG_FD
 429       Master payload: N/A
 430
 431       Sets the logging file descriptor, which is passed as ancillary data.
 432
 433  * VHOST_USER_SET_VRING_NUM
 434
 435       Id: 8
 436       Equivalent ioctl: VHOST_SET_VRING_NUM
 437       Master payload: vring state description
 438
 439       Set the size of the queue.
 440
 441  * VHOST_USER_SET_VRING_ADDR
 442
 443       Id: 9
 444       Equivalent ioctl: VHOST_SET_VRING_ADDR
 445       Master payload: vring address description
 446       Slave payload: N/A
 447
 448       Sets the addresses of the different aspects of the vring.
 449
 450  * VHOST_USER_SET_VRING_BASE
 451
 452       Id: 10
 453       Equivalent ioctl: VHOST_SET_VRING_BASE
 454       Master payload: vring state description
 455
 456       Sets the base offset in the available vring.
 457
 458  * VHOST_USER_GET_VRING_BASE
 459
 460       Id: 11
 461       Equivalent ioctl: VHOST_USER_GET_VRING_BASE
 462       Master payload: vring state description
 463       Slave payload: vring state description
 464
 465       Get the available vring base offset.
 466
 467  * VHOST_USER_SET_VRING_KICK
 468
 469       Id: 12
 470       Equivalent ioctl: VHOST_SET_VRING_KICK
 471       Master payload: u64
 472
 473       Set the event file descriptor for adding buffers to the vring. It
 474       is passed in the ancillary data.
 475       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 476       invalid FD flag. This flag is set when there is no file descriptor
 477       in the ancillary data. This signals that polling should be used
 478       instead of waiting for a kick.
 479
 480  * VHOST_USER_SET_VRING_CALL
 481
 482       Id: 13
 483       Equivalent ioctl: VHOST_SET_VRING_CALL
 484       Master payload: u64
 485
 486       Set the event file descriptor to signal when buffers are used. It
 487       is passed in the ancillary data.
 488       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 489       invalid FD flag. This flag is set when there is no file descriptor
 490       in the ancillary data. This signals that polling will be used
 491       instead of waiting for the call.
 492
 493  * VHOST_USER_SET_VRING_ERR
 494
 495       Id: 14
 496       Equivalent ioctl: VHOST_SET_VRING_ERR
 497       Master payload: u64
 498
 499       Set the event file descriptor to signal when error occurs. It
 500       is passed in the ancillary data.
 501       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 502       invalid FD flag. This flag is set when there is no file descriptor
 503       in the ancillary data.
 504
 505  * VHOST_USER_GET_QUEUE_NUM
 506
 507       Id: 17
 508       Equivalent ioctl: N/A
 509       Master payload: N/A
 510       Slave payload: u64
 511
 512       Query how many queues the backend supports. This request should be
 513       sent only when VHOST_USER_PROTOCOL_F_MQ is set in queried protocol
 514       features by VHOST_USER_GET_PROTOCOL_FEATURES.
 515
 516  * VHOST_USER_SET_VRING_ENABLE
 517
 518       Id: 18
 519       Equivalent ioctl: N/A
 520       Master payload: vring state description
 521
 522       Signal slave to enable or disable corresponding vring.
 523       This request should be sent only when VHOST_USER_F_PROTOCOL_FEATURES
 524       has been negotiated.
 525
 526  * VHOST_USER_SEND_RARP
 527
 528       Id: 19
 529       Equivalent ioctl: N/A
 530       Master payload: u64
 531
 532       Ask vhost user backend to broadcast a fake RARP to notify the migration
 533       is terminated for guest that does not support GUEST_ANNOUNCE.
 534       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 535       VHOST_USER_GET_FEATURES and protocol feature bit VHOST_USER_PROTOCOL_F_RARP
 536       is present in VHOST_USER_GET_PROTOCOL_FEATURES.
 537       The first 6 bytes of the payload contain the mac address of the guest to
 538       allow the vhost user backend to construct and broadcast the fake RARP.
 539
 540  * VHOST_USER_NET_SET_MTU
 541
 542       Id: 20
 543       Equivalent ioctl: N/A
 544       Master payload: u64
 545
 546       Set host MTU value exposed to the guest.
 547       This request should be sent only when VIRTIO_NET_F_MTU feature has been
 548       successfully negotiated, VHOST_USER_F_PROTOCOL_FEATURES is present in
 549       VHOST_USER_GET_FEATURES and protocol feature bit
 550       VHOST_USER_PROTOCOL_F_NET_MTU is present in
 551       VHOST_USER_GET_PROTOCOL_FEATURES.
 552       If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated, slave must respond
 553       with zero in case the specified MTU is valid, or non-zero otherwise.
 554
 555  * VHOST_USER_SET_SLAVE_REQ_FD
 556
 557       Id: 21
 558       Equivalent ioctl: N/A
 559       Master payload: N/A
 560
 561       Set the socket file descriptor for slave initiated requests. It is passed
 562       in the ancillary data.
 563       This request should be sent only when VHOST_USER_F_PROTOCOL_FEATURES
 564       has been negotiated, and protocol feature bit VHOST_USER_PROTOCOL_F_SLAVE_REQ
 565       bit is present in VHOST_USER_GET_PROTOCOL_FEATURES.
 566       If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated, slave must respond
 567       with zero for success, non-zero otherwise.
 568
 569  * VHOST_USER_IOTLB_MSG
 570
 571       Id: 22
 572       Equivalent ioctl: N/A (equivalent to VHOST_IOTLB_MSG message type)
 573       Master payload: struct vhost_iotlb_msg
 574       Slave payload: u64
 575
 576       Send IOTLB messages with struct vhost_iotlb_msg as payload.
 577       Master sends such requests to update and invalidate entries in the device
 578       IOTLB. The slave has to acknowledge the request with sending zero as u64
 579       payload for success, non-zero otherwise.
 580       This request should be send only when VIRTIO_F_IOMMU_PLATFORM feature
 581       has been successfully negotiated.
 582
 583 Slave message types
 584 -------------------
 585
 586  * VHOST_USER_SLAVE_IOTLB_MSG
 587
 588       Id: 1
 589       Equivalent ioctl: N/A (equivalent to VHOST_IOTLB_MSG message type)
 590       Slave payload: struct vhost_iotlb_msg
 591       Master payload: N/A
 592
 593       Send IOTLB messages with struct vhost_iotlb_msg as payload.
 594       Slave sends such requests to notify of an IOTLB miss, or an IOTLB
 595       access failure. If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated,
 596       and slave set the VHOST_USER_NEED_REPLY flag, master must respond with
 597       zero when operation is successfully completed, or non-zero otherwise.
 598       This request should be send only when VIRTIO_F_IOMMU_PLATFORM feature
 599       has been successfully negotiated.
 600
 601 VHOST_USER_PROTOCOL_F_REPLY_ACK:
 602 -------------------------------
 603 The original vhost-user specification only demands replies for certain
 604 commands. This differs from the vhost protocol implementation where commands
 605 are sent over an ioctl() call and block until the client has completed.
 606
 607 With this protocol extension negotiated, the sender (QEMU) can set the
 608 "need_reply" [Bit 3] flag to any command. This indicates that
 609 the client MUST respond with a Payload VhostUserMsg indicating success or
 610 failure. The payload should be set to zero on success or non-zero on failure,
 611 unless the message already has an explicit reply body.
 612
 613 The response payload gives QEMU a deterministic indication of the result
 614 of the command. Today, QEMU is expected to terminate the main vhost-user
 615 loop upon receiving such errors. In future, qemu could be taught to be more
 616 resilient for selective requests.
 617
 618 For the message types that already solicit a reply from the client, the
 619 presence of VHOST_USER_PROTOCOL_F_REPLY_ACK or need_reply bit being set brings
 620 no behavioural change. (See the 'Communication' section for details.)