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
 119 There are several messages that the master sends with file descriptors passed
 120 in the ancillary data:
 121
 122  * VHOST_SET_MEM_TABLE
 123  * VHOST_SET_LOG_FD
 124  * VHOST_SET_VRING_KICK
 125  * VHOST_SET_VRING_CALL
 126  * VHOST_SET_VRING_ERR
 127
 128 If Master is unable to send the full message or receives a wrong reply it will
 129 close the connection. An optional reconnection mechanism can be implemented.
 130
 131 Any protocol extensions are gated by protocol feature bits,
 132 which allows full backwards compatibility on both master
 133 and slave.
 134 As older slaves don't support negotiating protocol features,
 135 a feature bit was dedicated for this purpose:
 136 #define VHOST_USER_F_PROTOCOL_FEATURES 30
 137
 138 Multiple queue support
 139 ----------------------
 140
 141 Multiple queue is treated as a protocol extension, hence the slave has to
 142 implement protocol features first. The multiple queues feature is supported
 143 only when the protocol feature VHOST_USER_PROTOCOL_F_MQ (bit 0) is set:
 144 #define VHOST_USER_PROTOCOL_F_MQ    0
 145
 146 The max number of queues the slave supports can be queried with message
 147 VHOST_USER_GET_PROTOCOL_FEATURES. Master should stop when the number of
 148 requested queues is bigger than that.
 149
 150 As all queues share one connection, the master uses a unique index for each
 151 queue in the sent message to identify a specified queue. One queue pair
 152 is enabled initially. More queues are enabled dynamically, by sending
 153 message VHOST_USER_SET_VRING_ENABLE.
 154
 155 Message types
 156 -------------
 157
 158  * VHOST_USER_GET_FEATURES
 159
 160       Id: 1
 161       Equivalent ioctl: VHOST_GET_FEATURES
 162       Master payload: N/A
 163       Slave payload: u64
 164
 165       Get from the underlying vhost implementation the features bitmask.
 166       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 167       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 168
 169  * VHOST_USER_SET_FEATURES
 170
 171       Id: 2
 172       Ioctl: VHOST_SET_FEATURES
 173       Master payload: u64
 174
 175       Enable features in the underlying vhost implementation using a bitmask.
 176       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
 177       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
 178
 179  * VHOST_USER_GET_PROTOCOL_FEATURES
 180
 181       Id: 15
 182       Equivalent ioctl: VHOST_GET_FEATURES
 183       Master payload: N/A
 184       Slave payload: u64
 185
 186       Get the protocol feature bitmask from the underlying vhost implementation.
 187       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 188       VHOST_USER_GET_FEATURES.
 189       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 190       this message even before VHOST_USER_SET_FEATURES was called.
 191
 192  * VHOST_USER_SET_PROTOCOL_FEATURES
 193
 194       Id: 16
 195       Ioctl: VHOST_SET_FEATURES
 196       Master payload: u64
 197
 198       Enable protocol features in the underlying vhost implementation.
 199       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
 200       VHOST_USER_GET_FEATURES.
 201       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
 202       this message even before VHOST_USER_SET_FEATURES was called.
 203
 204  * VHOST_USER_SET_OWNER
 205
 206       Id: 3
 207       Equivalent ioctl: VHOST_SET_OWNER
 208       Master payload: N/A
 209
 210       Issued when a new connection is established. It sets the current Master
 211       as an owner of the session. This can be used on the Slave as a
 212       "session start" flag.
 213
 214  * VHOST_USER_RESET_DEVICE
 215
 216       Id: 4
 217       Equivalent ioctl: VHOST_RESET_DEVICE
 218       Master payload: N/A
 219
 220       Issued when a new connection is about to be closed. The Master will no
 221       longer own this connection (and will usually close it).
 222
 223  * VHOST_USER_SET_MEM_TABLE
 224
 225       Id: 5
 226       Equivalent ioctl: VHOST_SET_MEM_TABLE
 227       Master payload: memory regions description
 228
 229       Sets the memory map regions on the slave so it can translate the vring
 230       addresses. In the ancillary data there is an array of file descriptors
 231       for each memory mapped region. The size and ordering of the fds matches
 232       the number and ordering of memory regions.
 233
 234  * VHOST_USER_SET_LOG_BASE
 235
 236       Id: 6
 237       Equivalent ioctl: VHOST_SET_LOG_BASE
 238       Master payload: u64
 239
 240       Sets the logging base address.
 241
 242  * VHOST_USER_SET_LOG_FD
 243
 244       Id: 7
 245       Equivalent ioctl: VHOST_SET_LOG_FD
 246       Master payload: N/A
 247
 248       Sets the logging file descriptor, which is passed as ancillary data.
 249
 250  * VHOST_USER_SET_VRING_NUM
 251
 252       Id: 8
 253       Equivalent ioctl: VHOST_SET_VRING_NUM
 254       Master payload: vring state description
 255
 256       Sets the number of vrings for this owner.
 257
 258  * VHOST_USER_SET_VRING_ADDR
 259
 260       Id: 9
 261       Equivalent ioctl: VHOST_SET_VRING_ADDR
 262       Master payload: vring address description
 263       Slave payload: N/A
 264
 265       Sets the addresses of the different aspects of the vring.
 266
 267  * VHOST_USER_SET_VRING_BASE
 268
 269       Id: 10
 270       Equivalent ioctl: VHOST_SET_VRING_BASE
 271       Master payload: vring state description
 272
 273       Sets the base offset in the available vring.
 274
 275  * VHOST_USER_GET_VRING_BASE
 276
 277       Id: 11
 278       Equivalent ioctl: VHOST_USER_GET_VRING_BASE
 279       Master payload: vring state description
 280       Slave payload: vring state description
 281
 282       Get the available vring base offset.
 283
 284  * VHOST_USER_SET_VRING_KICK
 285
 286       Id: 12
 287       Equivalent ioctl: VHOST_SET_VRING_KICK
 288       Master payload: u64
 289
 290       Set the event file descriptor for adding buffers to the vring. It
 291       is passed in the ancillary data.
 292       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 293       invalid FD flag. This flag is set when there is no file descriptor
 294       in the ancillary data. This signals that polling should be used
 295       instead of waiting for a kick.
 296
 297  * VHOST_USER_SET_VRING_CALL
 298
 299       Id: 13
 300       Equivalent ioctl: VHOST_SET_VRING_CALL
 301       Master payload: u64
 302
 303       Set the event file descriptor to signal when buffers are used. It
 304       is passed in the ancillary data.
 305       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 306       invalid FD flag. This flag is set when there is no file descriptor
 307       in the ancillary data. This signals that polling will be used
 308       instead of waiting for the call.
 309
 310  * VHOST_USER_SET_VRING_ERR
 311
 312       Id: 14
 313       Equivalent ioctl: VHOST_SET_VRING_ERR
 314       Master payload: u64
 315
 316       Set the event file descriptor to signal when error occurs. It
 317       is passed in the ancillary data.
 318       Bits (0-7) of the payload contain the vring index. Bit 8 is the
 319       invalid FD flag. This flag is set when there is no file descriptor
 320       in the ancillary data.
 321
 322  * VHOST_USER_GET_QUEUE_NUM
 323
 324       Id: 17
 325       Equivalent ioctl: N/A
 326       Master payload: N/A
 327       Slave payload: u64
 328
 329       Query how many queues the backend supports. This request should be
 330       sent only when VHOST_USER_PROTOCOL_F_MQ is set in quried protocol
 331       features by VHOST_USER_GET_PROTOCOL_FEATURES.
 332
 333  * VHOST_USER_SET_VRING_ENABLE
 334
 335       Id: 18
 336       Equivalent ioctl: N/A
 337       Master payload: vring state description
 338
 339       Signal slave to enable or disable corresponding vring.