docs/interop/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 ring address of the vring descriptor table
  70    Used: a 64-bit ring address of the vring used ring
  71    Available: a 64-bit ring address of the vring available ring
  72    Log: a 64-bit guest address for logging
  73
  74    Note that a ring address is an IOVA if VIRTIO_F_IOMMU_PLATFORM has been
  75    negotiated.  Otherwise it is a user address.
  76
  77  * Memory regions description
  78    ---------------------------------------------------
  79    | num regions | padding | region0 | ... | region7 |
  80    ---------------------------------------------------
  81
  82    Num regions: a 32-bit number of regions
  83    Padding: 32-bit
  84
  85    A region is:
  86    -----------------------------------------------------
  87    | guest address | size | user address | mmap offset |
  88    -----------------------------------------------------
  89
  90    Guest address: a 64-bit guest address of the region
  91    Size: a 64-bit size
  92    User address: a 64-bit user address
  93    mmap offset: 64-bit offset where region starts in the mapped memory
  94
  95 * Log description
  96    ---------------------------
  97    | log size | log offset |
  98    ---------------------------
  99    log size: size of area used for logging
 100    log offset: offset from start of supplied file descriptor
 101        where logging starts (i.e. where guest address 0 would be logged)
 102
 103  * An IOTLB message
 104    ---------------------------------------------------------
 105    | iova | size | user address | permissions flags | type |
 106    ---------------------------------------------------------
 107
 108    IOVA: a 64-bit I/O virtual address programmed by the guest
 109    Size: a 64-bit size
 110    User address: a 64-bit user address
 111    Permissions: an 8-bit value:
 112     - 0: No access
 113     - 1: Read access
 114     - 2: Write access
 115     - 3: Read/Write access
 116    Type: an 8-bit IOTLB message type:
 117     - 1: IOTLB miss
 118     - 2: IOTLB update
 119     - 3: IOTLB invalidate
 120     - 4: IOTLB access fail
 121
 122  * Virtio device config space
 123    -----------------------------------
 124    | offset | size | flags | payload |
 125    -----------------------------------
 126
 127    Offset: a 32-bit offset of virtio device's configuration space
 128    Size: a 32-bit configuration space access size in bytes
 129    Flags: a 32-bit value:
 130     - 0: Vhost master messages used for writeable fields
 131     - 1: Vhost master messages used for live migration
 132    Payload: Size bytes array holding the contents of the virtio
 133        device's configuration space
 134
 135  * Vring area description
 136    -----------------------
 137    | u64 | size | offset |
 138    -----------------------
 139
 140    u64: a 64-bit integer contains vring index and flags
 141    Size: a 64-bit size of this area
 142    Offset: a 64-bit offset of this area from the start of the
 143        supplied file descriptor
 144
 145 In QEMU the vhost-user message is implemented with the following struct:
 146
 147 typedef struct VhostUserMsg {
 148     VhostUserRequest request;
 149     uint32_t flags;
 150     uint32_t size;
 151     union {
 152         uint64_t u64;
 153         struct vhost_vring_state state;
 154         struct vhost_vring_addr addr;
 155         VhostUserMemory memory;
 156         VhostUserLog log;
 157         struct vhost_iotlb_msg iotlb;
 158         VhostUserConfig config;
 159         VhostUserVringArea area;
 160     };
 161 } QEMU_PACKED VhostUserMsg;
 162
 163 Communication
 164 -------------
 165
 166 The protocol for vhost-user is based on the existing implementation of vhost
 167 for the Linux Kernel. Most messages that can be sent via the Unix domain socket
 168 implementing vhost-user have an equivalent ioctl to the kernel implementation.
 169
 170 The communication consists of master sending message requests and slave sending
 171 message replies. Most of the requests don't require replies. Here is a list of
 172 the ones that do:
 173
 174  * VHOST_USER_GET_FEATURES
 175  * VHOST_USER_GET_PROTOCOL_FEATURES
 176  * VHOST_USER_GET_VRING_BASE
 177  * VHOST_USER_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
 178
 179 [ Also see the section on REPLY_ACK protocol extension. ]
 180
 181 There are several messages that the master sends with file descriptors passed
 182 in the ancillary data:
 183
 184  * VHOST_USER_SET_MEM_TABLE
 185  * VHOST_USER_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
 186  * VHOST_USER_SET_LOG_FD
 187  * VHOST_USER_SET_VRING_KICK
 188  * VHOST_USER_SET_VRING_CALL
 189  * VHOST_USER_SET_VRING_ERR
 190  * VHOST_USER_SET_SLAVE_REQ_FD
 191
 192 If Master is unable to send the full message or receives a wrong reply it will
 193 close the connection. An optional reconnection mechanism can be implemented.
 194
 195 Any protocol extensions are gated by protocol feature bits,
 196 which allows full backwards compatibility on both master
 197 and slave.
 198 As older slaves don't support negotiating protocol features,
 199 a feature bit was dedicated for this purpose:
 200 #define VHOST_USER_F_PROTOCOL_FEATURES 30
 201
 202 Starting and stopping rings
 203 ----------------------
 204 Client must only process each ring when it is started.
 205
 206 Client must only pass data between the ring and the
 207 backend, when the ring is enabled.
 208
 209 If ring is started but disabled, client must process the
 210 ring without talking to the backend.
 211
 212 For example, for a networking device, in the disabled state
 213 client must not supply any new RX packets, but must process
 214 and discard any TX packets.
 215
 216 If VHOST_USER_F_PROTOCOL_FEATURES has not been negotiated, the ring is initialized
 217 in an enabled state.
 218
 219 If VHOST_USER_F_PROTOCOL_FEATURES has been negotiated, the ring is initialized
 220 in a disabled state. Client must not pass data to/from the backend until ring is enabled by
 221 VHOST_USER_SET_VRING_ENABLE with parameter 1, or after it has been disabled by
 222 VHOST_USER_SET_VRING_ENABLE with parameter 0.
 223
 224 Each ring is initialized in a stopped state, client must not process it until
 225 ring is started, or after it has been stopped.
 226
 227 Client must start ring upon receiving a kick (that is, detecting that file
 228 descriptor is readable) on the descriptor specified by
 229 VHOST_USER_SET_VRING_KICK, and stop ring upon receiving
 230 VHOST_USER_GET_VRING_BASE.
 231
 232 While processing the rings (whether they are enabled or not), client must
 233 support changing some configuration aspects on the fly.
 234
 235 Multiple queue support
 236 ----------------------
 237
 238 Multiple queue is treated as a protocol extension, hence the slave has to
 239 implement protocol features first. The multiple queues feature is supported
 240 only when the protocol feature VHOST_USER_PROTOCOL_F_MQ (bit 0) is set.
 241
 242 The max number of queue pairs the slave supports can be queried with message
 243 VHOST_USER_GET_QUEUE_NUM. Master should stop when the number of
 244 requested queues is bigger than that.
 245
 246 As all queues share one connection, the master uses a unique index for each
 247 queue in the sent message to identify a specified queue. One queue pair
 248 is enabled initially. More queues are enabled dynamically, by sending
 249 message VHOST_USER_SET_VRING_ENABLE.
 250
 251 Migration
 252 ---------
 253
 254 During live migration, the master may need to track the modifications
 255 the slave makes to the memory mapped regions. The client should mark
 256 the dirty pages in a log. Once it complies to this logging, it may
 257 declare the VHOST_F_LOG_ALL vhost feature.
 258
 259 To start/stop logging of data/used ring writes, server may send messages
 260 VHOST_USER_SET_FEATURES with VHOST_F_LOG_ALL and VHOST_USER_SET_VRING_ADDR with
 261 VHOST_VRING_F_LOG in ring's flags set to 1/0, respectively.
 262
 263 All the modifications to memory pointed by vring "descriptor" should
 264 be marked. Modifications to "used" vring should be marked if
 265 VHOST_VRING_F_LOG is part of ring's flags.
 266
 267 Dirty pages are of size:
 268 #define VHOST_LOG_PAGE 0x1000
 269
 270 The log memory fd is provided in the ancillary data of
 271 VHOST_USER_SET_LOG_BASE message when the slave has
 272 VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol feature.
 273
 274 The size of the log is supplied as part of VhostUserMsg
 275 which should be large enough to cover all known guest
 276 addresses. Log starts at the supplied offset in the
 277 supplied file descriptor.
 278 The log covers from address 0 to the maximum of guest
 279 regions. In pseudo-code, to mark page at "addr" as dirty:
 280
 281 page = addr / VHOST_LOG_PAGE
 282 log[page / 8] |= 1 << page % 8
 283
 284 Where addr is the guest physical address.
 285
 286 Use atomic operations, as the log may be concurrently manipulated.
 287
 288 Note that when logging modifications to the used ring (when VHOST_VRING_F_LOG
 289 is set for this ring), log_guest_addr should be used to calculate the log
 290 offset: the write to first byte of the used ring is logged at this offset from
 291 log start. Also note that this value might be outside the legal guest physical
 292 address range (i.e. does not have to be covered by the VhostUserMemory table),
 293 but the bit offset of the last byte of the ring must fall within
 294 the size supplied by VhostUserLog.
 295
 296 VHOST_USER_SET_LOG_FD is an optional message with an eventfd in
 297 ancillary data, it may be used to inform the master that the log has
 298 been modified.
 299
 300 Once the source has finished migration, rings will be stopped by
 301 the source. No further update must be done before rings are
 302 restarted.
 303
 304 In postcopy migration the slave is started before all the memory has been
 305 received from the source host, and care must be taken to avoid accessing pages
 306 that have yet to be received.  The slave opens a 'userfault'-fd and registers
 307 the memory with it; this fd is then passed back over to the master.
 308 The master services requests on the userfaultfd for pages that are accessed
 309 and when the page is available it performs WAKE ioctl's on the userfaultfd
 310 to wake the stalled slave.  The client indicates support for this via the
 311 VHOST_USER_PROTOCOL_F_PAGEFAULT feature.
 312
 313 Memory access
 314 -------------
 315
 316 The master sends a list of vhost memory regions to the slave using the
 317 VHOST_USER_SET_MEM_TABLE message.  Each region has two base addresses: a guest
 318 address and a user address.
 319
 320 Messages contain guest addresses and/or user addresses to reference locations
 321 within the shared memory.  The mapping of these addresses works as follows.
 322
 323 User addresses map to the vhost memory region containing that user address.
 324
 325 When the VIRTIO_F_IOMMU_PLATFORM feature has not been negotiated:
 326
 327  * Guest addresses map to the vhost memory region containing that guest
 328    address.
 329
 330 When the VIRTIO_F_IOMMU_PLATFORM feature has been negotiated:
 331
 332  * Guest addresses are also called I/O virtual addresses (IOVAs).  They are
 333    translated to user addresses via the IOTLB.
 334
 335  * The vhost memory region guest address is not used.
 336
 337 IOMMU support
 338 -------------
 339
 340 When the VIRTIO_F_IOMMU_PLATFORM feature has been negotiated, the master
 341 sends IOTLB entries update & invalidation by sending VHOST_USER_IOTLB_MSG
 342 requests to the slave with a struct vhost_iotlb_msg as payload. For update
 343 events, the iotlb payload has to be filled with the update message type (2),
 344 the I/O virtual address, the size, the user virtual address, and the
 345 permissions flags. Addresses and size must be within vhost memory regions set
 346 via the VHOST_USER_SET_MEM_TABLE request. For invalidation events, the iotlb
 347 payload has to be filled with the invalidation message type (3), the I/O virtual
 348 address and the size. On success, the slave is expected to reply with a zero
 349 payload, non-zero otherwise.
 350
 351 The slave relies on the slave communcation channel (see "Slave communication"
 352 section below) to send IOTLB miss and access failure events, by sending
 353 VHOST_USER_SLAVE_IOTLB_MSG requests to the master with a struct vhost_iotlb_msg
 354 as payload. For miss events, the iotlb payload has to be filled with the miss
 355 message type (1), the I/O virtual address and the permissions flags. For access
 356 failure event, the iotlb payload has to be filled with the access failure
 357 message type (4), the I/O virtual address and the permissions flags.
 358 For synchronization purpose, the slave may rely on the reply-ack feature,
 359 so the master may send a reply when operation is completed if the reply-ack
 360 feature is negotiated and slaves requests a reply. For miss events, completed
 361 operation means either master sent an update message containing the IOTLB entry
 362 containing requested address and permission, or master sent nothing if the IOTLB
 363 miss message is invalid (invalid IOVA or permission).
 364
 365 The master isn't expected to take the initiative to send IOTLB update messages,
 366 as the slave sends IOTLB miss messages for the guest virtual memory areas it
 367 needs to access.
 368
 369 Slave communication
 370 -------------------
 371
 372 An optional communication channel is provided if the slave declares
 373 VHOST_USER_PROTOCOL_F_SLAVE_REQ protocol feature, to allow the slave to make
 374 requests to the master.
 375
 376 The fd is provided via VHOST_USER_SET_SLAVE_REQ_FD ancillary data.
 377
 378 A slave may then send VHOST_USER_SLAVE_* messages to the master
 379 using this fd communication channel.
 380
 381 If VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD protocol feature is negotiated,
 382 slave can send file descriptors (at most 8 descriptors in each message)
 383 to master via ancillary data using this fd communication channel.
 384
 385 Protocol features
 386 -----------------
 387
 388 #define VHOST_USER_PROTOCOL_F_MQ             0
 389 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD      1
 390 #define VHOST_USER_PROTOCOL_F_RARP           2
 391 #define VHOST_USER_PROTOCOL_F_REPLY_ACK      3
 392 #define VHOST_USER_PROTOCOL_F_MTU            4
 393 #define VHOST_USER_PROTOCOL_F_SLAVE_REQ      5
 394 #define VHOST_USER_PROTOCOL_F_CROSS_ENDIAN   6
 395 #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7
 396 #define VHOST_USER_PROTOCOL_F_PAGEFAULT      8
 397 #define VHOST_USER_PROTOCOL_F_CONFIG         9
 398 #define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD  10
 399 #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER  11
 400
 401 Master message types
 402 --------------------
 403
 404  * VHOST_USER_GET_FEATURES
 405
 406       Id: 1
 407       Equivalent ioctl: VHOST_GET_FEATURES
 408       Master payload: N/A
 409       Slave payload: u64
 410
 411       Get from the underlying vhost implementation the features bitmask.
 412       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 413       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 414
 415  * VHOST_USER_SET_FEATURES
 416
 417       Id: 2
 418       Ioctl: VHOST_SET_FEATURES
 419       Master payload: u64
 420
 421       Enable features in the underlying vhost implementation using a bitmask.
 422       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 423       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 424
 425  * VHOST_USER_GET_PROTOCOL_FEATURES
 426
 427       Id: 15
 428       Equivalent ioctl: VHOST_GET_FEATURES
 429       Master payload: N/A
 430       Slave payload: u64
 431
 432       Get the protocol feature bitmask from the underlying vhost implementation.
 433       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 434       VHOST_USER_GET_FEATURES.
 435       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 436       this message even before VHOST_USER_SET_FEATURES was called.
 437
 438  * VHOST_USER_SET_PROTOCOL_FEATURES
 439
 440       Id: 16
 441       Ioctl: VHOST_SET_FEATURES
 442       Master payload: u64
 443
 444       Enable protocol features in the underlying vhost implementation.
 445       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 446       VHOST_USER_GET_FEATURES.
 447       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 448       this message even before VHOST_USER_SET_FEATURES was called.
 449
 450  * VHOST_USER_SET_OWNER
 451
 452       Id: 3
 453       Equivalent ioctl: VHOST_SET_OWNER
 454       Master payload: N/A
 455
 456       Issued when a new connection is established. It sets the current Master
 457       as an owner of the session. This can be used on the Slave as a
 458       "session start" flag.
 459
 460  * VHOST_USER_RESET_OWNER
 461
 462       Id: 4
 463       Master payload: N/A
 464
 465       This is no longer used. Used to be sent to request disabling
 466       all rings, but some clients interpreted it to also discard
 467       connection state (this interpretation would lead to bugs).
 468       It is recommended that clients either ignore this message,
 469       or use it to disable all rings.
 470
 471  * VHOST_USER_SET_MEM_TABLE
 472
 473       Id: 5
 474       Equivalent ioctl: VHOST_SET_MEM_TABLE
 475       Master payload: memory regions description
 476       Slave payload: (postcopy only) memory regions description
 477
 478       Sets the memory map regions on the slave so it can translate the vring
 479       addresses. In the ancillary data there is an array of file descriptors
 480       for each memory mapped region. The size and ordering of the fds matches
 481       the number and ordering of memory regions.
 482
 483       When VHOST_USER_POSTCOPY_LISTEN has been received, SET_MEM_TABLE replies with
 484       the bases of the memory mapped regions to the master.  The slave must
 485       have mmap'd the regions but not yet accessed them and should not yet generate
 486       a userfault event. Note NEED_REPLY_MASK is not set in this case.
 487       QEMU will then reply back to the list of mappings with an empty
 488       VHOST_USER_SET_MEM_TABLE as an acknowledgment; only upon reception of this
 489       message may the guest start accessing the memory and generating faults.
 490
 491  * VHOST_USER_SET_LOG_BASE
 492
 493       Id: 6
 494       Equivalent ioctl: VHOST_SET_LOG_BASE
 495       Master payload: u64
 496       Slave payload: N/A
 497
 498       Sets logging shared memory space.
 499       When slave has VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol
 500       feature, the log memory fd is provided in the ancillary data of
 501       VHOST_USER_SET_LOG_BASE message, the size and offset of shared
 502       memory area provided in the message.
 503
 504
 505  * VHOST_USER_SET_LOG_FD
 506
 507       Id: 7
 508       Equivalent ioctl: VHOST_SET_LOG_FD
 509       Master payload: N/A
 510
 511       Sets the logging file descriptor, which is passed as ancillary data.
 512
 513  * VHOST_USER_SET_VRING_NUM
 514
 515       Id: 8
 516       Equivalent ioctl: VHOST_SET_VRING_NUM
 517       Master payload: vring state description
 518
 519       Set the size of the queue.
 520
 521  * VHOST_USER_SET_VRING_ADDR
 522
 523       Id: 9
 524       Equivalent ioctl: VHOST_SET_VRING_ADDR
 525       Master payload: vring address description
 526       Slave payload: N/A
 527
 528       Sets the addresses of the different aspects of the vring.
 529
 530  * VHOST_USER_SET_VRING_BASE
 531
 532       Id: 10
 533       Equivalent ioctl: VHOST_SET_VRING_BASE
 534       Master payload: vring state description
 535
 536       Sets the base offset in the available vring.
 537
 538  * VHOST_USER_GET_VRING_BASE
 539
 540       Id: 11
 541       Equivalent ioctl: VHOST_USER_GET_VRING_BASE
 542       Master payload: vring state description
 543       Slave payload: vring state description
 544
 545       Get the available vring base offset.
 546
 547  * VHOST_USER_SET_VRING_KICK
 548
 549       Id: 12
 550       Equivalent ioctl: VHOST_SET_VRING_KICK
 551       Master payload: u64
 552
 553       Set the event file descriptor for adding buffers to the vring. It
 554       is passed in the ancillary data.
 555       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 556       invalid FD flag. This flag is set when there is no file descriptor
 557       in the ancillary data. This signals that polling should be used
 558       instead of waiting for a kick.
 559
 560  * VHOST_USER_SET_VRING_CALL
 561
 562       Id: 13
 563       Equivalent ioctl: VHOST_SET_VRING_CALL
 564       Master payload: u64
 565
 566       Set the event file descriptor to signal when buffers are used. It
 567       is passed in the ancillary data.
 568       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 569       invalid FD flag. This flag is set when there is no file descriptor
 570       in the ancillary data. This signals that polling will be used
 571       instead of waiting for the call.
 572
 573  * VHOST_USER_SET_VRING_ERR
 574
 575       Id: 14
 576       Equivalent ioctl: VHOST_SET_VRING_ERR
 577       Master payload: u64
 578
 579       Set the event file descriptor to signal when error occurs. It
 580       is passed in the ancillary data.
 581       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 582       invalid FD flag. This flag is set when there is no file descriptor
 583       in the ancillary data.
 584
 585  * VHOST_USER_GET_QUEUE_NUM
 586
 587       Id: 17
 588       Equivalent ioctl: N/A
 589       Master payload: N/A
 590       Slave payload: u64
 591
 592       Query how many queues the backend supports. This request should be
 593       sent only when VHOST_USER_PROTOCOL_F_MQ is set in queried protocol
 594       features by VHOST_USER_GET_PROTOCOL_FEATURES.
 595
 596  * VHOST_USER_SET_VRING_ENABLE
 597
 598       Id: 18
 599       Equivalent ioctl: N/A
 600       Master payload: vring state description
 601
 602       Signal slave to enable or disable corresponding vring.
 603       This request should be sent only when VHOST_USER_F_PROTOCOL_FEATURES
 604       has been negotiated.
 605
 606  * VHOST_USER_SEND_RARP
 607
 608       Id: 19
 609       Equivalent ioctl: N/A
 610       Master payload: u64
 611
 612       Ask vhost user backend to broadcast a fake RARP to notify the migration
 613       is terminated for guest that does not support GUEST_ANNOUNCE.
 614       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 615       VHOST_USER_GET_FEATURES and protocol feature bit VHOST_USER_PROTOCOL_F_RARP
 616       is present in VHOST_USER_GET_PROTOCOL_FEATURES.
 617       The first 6 bytes of the payload contain the mac address of the guest to
 618       allow the vhost user backend to construct and broadcast the fake RARP.
 619
 620  * VHOST_USER_NET_SET_MTU
 621
 622       Id: 20
 623       Equivalent ioctl: N/A
 624       Master payload: u64
 625
 626       Set host MTU value exposed to the guest.
 627       This request should be sent only when VIRTIO_NET_F_MTU feature has been
 628       successfully negotiated, VHOST_USER_F_PROTOCOL_FEATURES is present in
 629       VHOST_USER_GET_FEATURES and protocol feature bit
 630       VHOST_USER_PROTOCOL_F_NET_MTU is present in
 631       VHOST_USER_GET_PROTOCOL_FEATURES.
 632       If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated, slave must respond
 633       with zero in case the specified MTU is valid, or non-zero otherwise.
 634
 635  * VHOST_USER_SET_SLAVE_REQ_FD
 636
 637       Id: 21
 638       Equivalent ioctl: N/A
 639       Master payload: N/A
 640
 641       Set the socket file descriptor for slave initiated requests. It is passed
 642       in the ancillary data.
 643       This request should be sent only when VHOST_USER_F_PROTOCOL_FEATURES
 644       has been negotiated, and protocol feature bit VHOST_USER_PROTOCOL_F_SLAVE_REQ
 645       bit is present in VHOST_USER_GET_PROTOCOL_FEATURES.
 646       If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated, slave must respond
 647       with zero for success, non-zero otherwise.
 648
 649  * VHOST_USER_IOTLB_MSG
 650
 651       Id: 22
 652       Equivalent ioctl: N/A (equivalent to VHOST_IOTLB_MSG message type)
 653       Master payload: struct vhost_iotlb_msg
 654       Slave payload: u64
 655
 656       Send IOTLB messages with struct vhost_iotlb_msg as payload.
 657       Master sends such requests to update and invalidate entries in the device
 658       IOTLB. The slave has to acknowledge the request with sending zero as u64
 659       payload for success, non-zero otherwise.
 660       This request should be send only when VIRTIO_F_IOMMU_PLATFORM feature
 661       has been successfully negotiated.
 662
 663  * VHOST_USER_SET_VRING_ENDIAN
 664
 665       Id: 23
 666       Equivalent ioctl: VHOST_SET_VRING_ENDIAN
 667       Master payload: vring state description
 668
 669       Set the endianness of a VQ for legacy devices. Little-endian is indicated
 670       with state.num set to 0 and big-endian is indicated with state.num set
 671       to 1. Other values are invalid.
 672       This request should be sent only when VHOST_USER_PROTOCOL_F_CROSS_ENDIAN
 673       has been negotiated.
 674       Backends that negotiated this feature should handle both endiannesses
 675       and expect this message once (per VQ) during device configuration
 676       (ie. before the master starts the VQ).
 677
 678  * VHOST_USER_GET_CONFIG
 679
 680       Id: 24
 681       Equivalent ioctl: N/A
 682       Master payload: virtio device config space
 683       Slave payload: virtio device config space
 684
 685       When VHOST_USER_PROTOCOL_F_CONFIG is negotiated, this message is
 686       submitted by the vhost-user master to fetch the contents of the virtio
 687       device configuration space, vhost-user slave's payload size MUST match
 688       master's request, vhost-user slave uses zero length of payload to
 689       indicate an error to vhost-user master. The vhost-user master may
 690       cache the contents to avoid repeated VHOST_USER_GET_CONFIG calls.
 691
 692 * VHOST_USER_SET_CONFIG
 693
 694       Id: 25
 695       Equivalent ioctl: N/A
 696       Master payload: virtio device config space
 697       Slave payload: N/A
 698
 699       When VHOST_USER_PROTOCOL_F_CONFIG is negotiated, this message is
 700       submitted by the vhost-user master when the Guest changes the virtio
 701       device configuration space and also can be used for live migration
 702       on the destination host. The vhost-user slave must check the flags
 703       field, and slaves MUST NOT accept SET_CONFIG for read-only
 704       configuration space fields unless the live migration bit is set.
 705
 706 * VHOST_USER_CREATE_CRYPTO_SESSION
 707
 708      Id: 26
 709      Equivalent ioctl: N/A
 710      Master payload: crypto session description
 711      Slave payload: crypto session description
 712
 713      Create a session for crypto operation. The server side must return the
 714      session id, 0 or positive for success, negative for failure.
 715      This request should be sent only when VHOST_USER_PROTOCOL_F_CRYPTO_SESSION
 716      feature has been successfully negotiated.
 717      It's a required feature for crypto devices.
 718
 719 * VHOST_USER_CLOSE_CRYPTO_SESSION
 720
 721      Id: 27
 722      Equivalent ioctl: N/A
 723      Master payload: u64
 724
 725      Close a session for crypto operation which was previously
 726      created by VHOST_USER_CREATE_CRYPTO_SESSION.
 727      This request should be sent only when VHOST_USER_PROTOCOL_F_CRYPTO_SESSION
 728      feature has been successfully negotiated.
 729      It's a required feature for crypto devices.
 730
 731  * VHOST_USER_POSTCOPY_ADVISE
 732       Id: 28
 733       Master payload: N/A
 734       Slave payload: userfault fd
 735
 736       When VHOST_USER_PROTOCOL_F_PAGEFAULT is supported, the
 737       master advises slave that a migration with postcopy enabled is underway,
 738       the slave must open a userfaultfd for later use.
 739       Note that at this stage the migration is still in precopy mode.
 740
 741  * VHOST_USER_POSTCOPY_LISTEN
 742       Id: 29
 743       Master payload: N/A
 744
 745       Master advises slave that a transition to postcopy mode has happened.
 746       The slave must ensure that shared memory is registered with userfaultfd
 747       to cause faulting of non-present pages.
 748
 749       This is always sent sometime after a VHOST_USER_POSTCOPY_ADVISE, and
 750       thus only when VHOST_USER_PROTOCOL_F_PAGEFAULT is supported.
 751
 752  * VHOST_USER_POSTCOPY_END
 753       Id: 30
 754       Slave payload: u64
 755
 756       Master advises that postcopy migration has now completed.  The
 757       slave must disable the userfaultfd. The response is an acknowledgement
 758       only.
 759       When VHOST_USER_PROTOCOL_F_PAGEFAULT is supported, this message
 760       is sent at the end of the migration, after VHOST_USER_POSTCOPY_LISTEN
 761       was previously sent.
 762       The value returned is an error indication; 0 is success.
 763
 764 Slave message types
 765 -------------------
 766
 767  * VHOST_USER_SLAVE_IOTLB_MSG
 768
 769       Id: 1
 770       Equivalent ioctl: N/A (equivalent to VHOST_IOTLB_MSG message type)
 771       Slave payload: struct vhost_iotlb_msg
 772       Master payload: N/A
 773
 774       Send IOTLB messages with struct vhost_iotlb_msg as payload.
 775       Slave sends such requests to notify of an IOTLB miss, or an IOTLB
 776       access failure. If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated,
 777       and slave set the VHOST_USER_NEED_REPLY flag, master must respond with
 778       zero when operation is successfully completed, or non-zero otherwise.
 779       This request should be send only when VIRTIO_F_IOMMU_PLATFORM feature
 780       has been successfully negotiated.
 781
 782 * VHOST_USER_SLAVE_CONFIG_CHANGE_MSG
 783
 784      Id: 2
 785      Equivalent ioctl: N/A
 786      Slave payload: N/A
 787      Master payload: N/A
 788
 789      When VHOST_USER_PROTOCOL_F_CONFIG is negotiated, vhost-user slave sends
 790      such messages to notify that the virtio device's configuration space has
 791      changed, for those host devices which can support such feature, host
 792      driver can send VHOST_USER_GET_CONFIG message to slave to get the latest
 793      content. If VHOST_USER_PROTOCOL_F_REPLY_ACK is negotiated, and slave set
 794      the VHOST_USER_NEED_REPLY flag, master must respond with zero when
 795      operation is successfully completed, or non-zero otherwise.
 796
 797  * VHOST_USER_SLAVE_VRING_HOST_NOTIFIER_MSG
 798
 799       Id: 3
 800       Equivalent ioctl: N/A
 801       Slave payload: vring area description
 802       Master payload: N/A
 803
 804       Sets host notifier for a specified queue. The queue index is contained
 805       in the u64 field of the vring area description. The host notifier is
 806       described by the file descriptor (typically it's a VFIO device fd) which
 807       is passed as ancillary data and the size (which is mmap size and should
 808       be the same as host page size) and offset (which is mmap offset) carried
 809       in the vring area description. QEMU can mmap the file descriptor based
 810       on the size and offset to get a memory range. Registering a host notifier
 811       means mapping this memory range to the VM as the specified queue's notify
 812       MMIO region. Slave sends this request to tell QEMU to de-register the
 813       existing notifier if any and register the new notifier if the request is
 814       sent with a file descriptor.
 815       This request should be sent only when VHOST_USER_PROTOCOL_F_HOST_NOTIFIER
 816       protocol feature has been successfully negotiated.
 817
 818 VHOST_USER_PROTOCOL_F_REPLY_ACK:
 819 -------------------------------
 820 The original vhost-user specification only demands replies for certain
 821 commands. This differs from the vhost protocol implementation where commands
 822 are sent over an ioctl() call and block until the client has completed.
 823
 824 With this protocol extension negotiated, the sender (QEMU) can set the
 825 "need_reply" [Bit 3] flag to any command. This indicates that
 826 the client MUST respond with a Payload VhostUserMsg indicating success or
 827 failure. The payload should be set to zero on success or non-zero on failure,
 828 unless the message already has an explicit reply body.
 829
 830 The response payload gives QEMU a deterministic indication of the result
 831 of the command. Today, QEMU is expected to terminate the main vhost-user
 832 loop upon receiving such errors. In future, qemu could be taught to be more
 833 resilient for selective requests.
 834
 835 For the message types that already solicit a reply from the client, the
 836 presence of VHOST_USER_PROTOCOL_F_REPLY_ACK or need_reply bit being set brings
 837 no behavioural change. (See the 'Communication' section for details.)