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  * Size - 32-bit size of the payload
  41
  42
  43 Depending on the request type, payload can be:
  44
  45  * A single 64-bit integer
  46    -------
  47    | u64 |
  48    -------
  49
  50    u64: a 64-bit unsigned integer
  51
  52  * A vring state description
  53    ---------------
  54   | index | num |
  55   ---------------
  56
  57    Index: a 32-bit index
  58    Num: a 32-bit number
  59
  60  * A vring address description
  61    --------------------------------------------------------------
  62    | index | flags | size | descriptor | used | available | log |
  63    --------------------------------------------------------------
  64
  65    Index: a 32-bit vring index
  66    Flags: a 32-bit vring flags
  67    Descriptor: a 64-bit user address of the vring descriptor table
  68    Used: a 64-bit user address of the vring used ring
  69    Available: a 64-bit user address of the vring available ring
  70    Log: a 64-bit guest address for logging
  71
  72  * Memory regions description
  73    ---------------------------------------------------
  74    | num regions | padding | region0 | ... | region7 |
  75    ---------------------------------------------------
  76
  77    Num regions: a 32-bit number of regions
  78    Padding: 32-bit
  79
  80    A region is:
  81    -----------------------------------------------------
  82    | guest address | size | user address | mmap offset |
  83    -----------------------------------------------------
  84
  85    Guest address: a 64-bit guest address of the region
  86    Size: a 64-bit size
  87    User address: a 64-bit user address
  88    mmap offset: 64-bit offset where region starts in the mapped memory
  89
  90 In QEMU the vhost-user message is implemented with the following struct:
  91
  92 typedef struct VhostUserMsg {
  93     VhostUserRequest request;
  94     uint32_t flags;
  95     uint32_t size;
  96     union {
  97         uint64_t u64;
  98         struct vhost_vring_state state;
  99         struct vhost_vring_addr addr;
 100         VhostUserMemory memory;
 101     };
 102 } QEMU_PACKED VhostUserMsg;
 103
 104 Communication
 105 -------------
 106
 107 The protocol for vhost-user is based on the existing implementation of vhost
 108 for the Linux Kernel. Most messages that can be sent via the Unix domain socket
 109 implementing vhost-user have an equivalent ioctl to the kernel implementation.
 110
 111 The communication consists of master sending message requests and slave sending
 112 message replies. Most of the requests don't require replies. Here is a list of
 113 the ones that do:
 114
 115  * VHOST_GET_FEATURES
 116  * VHOST_GET_PROTOCOL_FEATURES
 117  * VHOST_GET_VRING_BASE
 118  * VHOST_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
 119
 120 There are several messages that the master sends with file descriptors passed
 121 in the ancillary data:
 122
 123  * VHOST_SET_MEM_TABLE
 124  * VHOST_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
 125  * VHOST_SET_LOG_FD
 126  * VHOST_SET_VRING_KICK
 127  * VHOST_SET_VRING_CALL
 128  * VHOST_SET_VRING_ERR
 129
 130 If Master is unable to send the full message or receives a wrong reply it will
 131 close the connection. An optional reconnection mechanism can be implemented.
 132
 133 Any protocol extensions are gated by protocol feature bits,
 134 which allows full backwards compatibility on both master
 135 and slave.
 136 As older slaves don't support negotiating protocol features,
 137 a feature bit was dedicated for this purpose:
 138 #define VHOST_USER_F_PROTOCOL_FEATURES 30
 139
 140 Multiple queue support
 141 ----------------------
 142
 143 Multiple queue is treated as a protocol extension, hence the slave has to
 144 implement protocol features first. The multiple queues feature is supported
 145 only when the protocol feature VHOST_USER_PROTOCOL_F_MQ (bit 0) is set.
 146
 147 The max number of queues the slave supports can be queried with message
 148 VHOST_USER_GET_PROTOCOL_FEATURES. Master should stop when the number of
 149 requested queues is bigger than that.
 150
 151 As all queues share one connection, the master uses a unique index for each
 152 queue in the sent message to identify a specified queue. One queue pair
 153 is enabled initially. More queues are enabled dynamically, by sending
 154 message VHOST_USER_SET_VRING_ENABLE.
 155
 156 Migration
 157 ---------
 158
 159 During live migration, the master may need to track the modifications
 160 the slave makes to the memory mapped regions. The client should mark
 161 the dirty pages in a log. Once it complies to this logging, it may
 162 declare the VHOST_F_LOG_ALL vhost feature.
 163
 164 All the modifications to memory pointed by vring "descriptor" should
 165 be marked. Modifications to "used" vring should be marked if
 166 VHOST_VRING_F_LOG is part of ring's features.
 167
 168 Dirty pages are of size:
 169 #define VHOST_LOG_PAGE 0x1000
 170
 171 The log memory fd is provided in the ancillary data of
 172 VHOST_USER_SET_LOG_BASE message when the slave has
 173 VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol feature.
 174
 175 The size of the log may be computed by using all the known guest
 176 addresses. The log covers from address 0 to the maximum of guest
 177 regions. In pseudo-code, to mark page at "addr" as dirty:
 178
 179 page = addr / VHOST_LOG_PAGE
 180 log[page / 8] |= 1 << page % 8
 181
 182 Use atomic operations, as the log may be concurrently manipulated.
 183
 184 VHOST_USER_SET_LOG_FD is an optional message with an eventfd in
 185 ancillary data, it may be used to inform the master that the log has
 186 been modified.
 187
 188 Once the source has finished migration, VHOST_USER_RESET_OWNER message
 189 will be sent by the source. No further update must be done before the
 190 destination takes over with new regions & rings.
 191
 192 Protocol features
 193 -----------------
 194
 195 #define VHOST_USER_PROTOCOL_F_MQ             0
 196 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD      1
 197 #define VHOST_USER_PROTOCOL_F_RARP           2
 198
 199 Message types
 200 -------------
 201
 202  * VHOST_USER_GET_FEATURES
 203
 204       Id: 1
 205       Equivalent ioctl: VHOST_GET_FEATURES
 206       Master payload: N/A
 207       Slave payload: u64
 208
 209       Get from the underlying vhost implementation the features bitmask.
 210       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 211       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 212
 213  * VHOST_USER_SET_FEATURES
 214
 215       Id: 2
 216       Ioctl: VHOST_SET_FEATURES
 217       Master payload: u64
 218
 219       Enable features in the underlying vhost implementation using a bitmask.
 220       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 221       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 222
 223  * VHOST_USER_GET_PROTOCOL_FEATURES
 224
 225       Id: 15
 226       Equivalent ioctl: VHOST_GET_FEATURES
 227       Master payload: N/A
 228       Slave payload: u64
 229
 230       Get the protocol feature bitmask from the underlying vhost implementation.
 231       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 232       VHOST_USER_GET_FEATURES.
 233       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 234       this message even before VHOST_USER_SET_FEATURES was called.
 235
 236  * VHOST_USER_SET_PROTOCOL_FEATURES
 237
 238       Id: 16
 239       Ioctl: VHOST_SET_FEATURES
 240       Master payload: u64
 241
 242       Enable protocol features in the underlying vhost implementation.
 243       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 244       VHOST_USER_GET_FEATURES.
 245       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 246       this message even before VHOST_USER_SET_FEATURES was called.
 247
 248  * VHOST_USER_SET_OWNER
 249
 250       Id: 3
 251       Equivalent ioctl: VHOST_SET_OWNER
 252       Master payload: N/A
 253
 254       Issued when a new connection is established. It sets the current Master
 255       as an owner of the session. This can be used on the Slave as a
 256       "session start" flag.
 257
 258  * VHOST_USER_RESET_DEVICE
 259
 260       Id: 4
 261       Equivalent ioctl: VHOST_RESET_DEVICE
 262       Master payload: N/A
 263
 264       Issued when a new connection is about to be closed. The Master will no
 265       longer own this connection (and will usually close it).
 266
 267  * VHOST_USER_SET_MEM_TABLE
 268
 269       Id: 5
 270       Equivalent ioctl: VHOST_SET_MEM_TABLE
 271       Master payload: memory regions description
 272
 273       Sets the memory map regions on the slave so it can translate the vring
 274       addresses. In the ancillary data there is an array of file descriptors
 275       for each memory mapped region. The size and ordering of the fds matches
 276       the number and ordering of memory regions.
 277
 278  * VHOST_USER_SET_LOG_BASE
 279
 280       Id: 6
 281       Equivalent ioctl: VHOST_SET_LOG_BASE
 282       Master payload: u64
 283       Slave payload: N/A
 284
 285       Sets the logging base address.
 286
 287  * VHOST_USER_SET_LOG_FD
 288
 289       Id: 7
 290       Equivalent ioctl: VHOST_SET_LOG_FD
 291       Master payload: N/A
 292
 293       Sets the logging file descriptor, which is passed as ancillary data.
 294
 295  * VHOST_USER_SET_VRING_NUM
 296
 297       Id: 8
 298       Equivalent ioctl: VHOST_SET_VRING_NUM
 299       Master payload: vring state description
 300
 301       Sets the number of vrings for this owner.
 302
 303  * VHOST_USER_SET_VRING_ADDR
 304
 305       Id: 9
 306       Equivalent ioctl: VHOST_SET_VRING_ADDR
 307       Master payload: vring address description
 308       Slave payload: N/A
 309
 310       Sets the addresses of the different aspects of the vring.
 311
 312  * VHOST_USER_SET_VRING_BASE
 313
 314       Id: 10
 315       Equivalent ioctl: VHOST_SET_VRING_BASE
 316       Master payload: vring state description
 317
 318       Sets the base offset in the available vring.
 319
 320  * VHOST_USER_GET_VRING_BASE
 321
 322       Id: 11
 323       Equivalent ioctl: VHOST_USER_GET_VRING_BASE
 324       Master payload: vring state description
 325       Slave payload: vring state description
 326
 327       Get the available vring base offset.
 328
 329  * VHOST_USER_SET_VRING_KICK
 330
 331       Id: 12
 332       Equivalent ioctl: VHOST_SET_VRING_KICK
 333       Master payload: u64
 334
 335       Set the event file descriptor for adding buffers to the vring. It
 336       is passed in the ancillary data.
 337       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 338       invalid FD flag. This flag is set when there is no file descriptor
 339       in the ancillary data. This signals that polling should be used
 340       instead of waiting for a kick.
 341
 342  * VHOST_USER_SET_VRING_CALL
 343
 344       Id: 13
 345       Equivalent ioctl: VHOST_SET_VRING_CALL
 346       Master payload: u64
 347
 348       Set the event file descriptor to signal when buffers are used. It
 349       is passed in the ancillary data.
 350       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 351       invalid FD flag. This flag is set when there is no file descriptor
 352       in the ancillary data. This signals that polling will be used
 353       instead of waiting for the call.
 354
 355  * VHOST_USER_SET_VRING_ERR
 356
 357       Id: 14
 358       Equivalent ioctl: VHOST_SET_VRING_ERR
 359       Master payload: u64
 360
 361       Set the event file descriptor to signal when error occurs. It
 362       is passed in the ancillary data.
 363       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 364       invalid FD flag. This flag is set when there is no file descriptor
 365       in the ancillary data.
 366
 367  * VHOST_USER_GET_QUEUE_NUM
 368
 369       Id: 17
 370       Equivalent ioctl: N/A
 371       Master payload: N/A
 372       Slave payload: u64
 373
 374       Query how many queues the backend supports. This request should be
 375       sent only when VHOST_USER_PROTOCOL_F_MQ is set in quried protocol
 376       features by VHOST_USER_GET_PROTOCOL_FEATURES.
 377
 378  * VHOST_USER_SET_VRING_ENABLE
 379
 380       Id: 18
 381       Equivalent ioctl: N/A
 382       Master payload: vring state description
 383
 384       Signal slave to enable or disable corresponding vring.
 385
 386  * VHOST_USER_SEND_RARP
 387
 388       Id: 19
 389       Equivalent ioctl: N/A
 390       Master payload: u64
 391
 392       Ask vhost user backend to broadcast a fake RARP to notify the migration
 393       is terminated for guest that does not support GUEST_ANNOUNCE.
 394       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 395       VHOST_USER_GET_FEATURES and protocol feature bit VHOST_USER_PROTOCOL_F_RARP
 396       is present in VHOST_USER_GET_PROTOCOL_FEATURES.
 397       The first 6 bytes of the payload contain the mac address of the guest to
 398       allow the vhost user backend to construct and broadcast the fake RARP.