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