linux-user: arm: Remove ARM_cpsr and similar #defines
[qemu.git] / 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 * Log description
91    ---------------------------
92    | log size | log offset |
93    ---------------------------
94    log size: size of area used for logging
95    log offset: offset from start of supplied file descriptor
96        where logging starts (i.e. where guest address 0 would be logged)
97
98 In QEMU the vhost-user message is implemented with the following struct:
99
100 typedef struct VhostUserMsg {
101     VhostUserRequest request;
102     uint32_t flags;
103     uint32_t size;
104     union {
105         uint64_t u64;
106         struct vhost_vring_state state;
107         struct vhost_vring_addr addr;
108         VhostUserMemory memory;
109         VhostUserLog log;
110     };
111 } QEMU_PACKED VhostUserMsg;
112
113 Communication
114 -------------
115
116 The protocol for vhost-user is based on the existing implementation of vhost
117 for the Linux Kernel. Most messages that can be sent via the Unix domain socket
118 implementing vhost-user have an equivalent ioctl to the kernel implementation.
119
120 The communication consists of master sending message requests and slave sending
121 message replies. Most of the requests don't require replies. Here is a list of
122 the ones that do:
123
124  * VHOST_GET_FEATURES
125  * VHOST_GET_PROTOCOL_FEATURES
126  * VHOST_GET_VRING_BASE
127  * VHOST_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
128
129 There are several messages that the master sends with file descriptors passed
130 in the ancillary data:
131
132  * VHOST_SET_MEM_TABLE
133  * VHOST_SET_LOG_BASE (if VHOST_USER_PROTOCOL_F_LOG_SHMFD)
134  * VHOST_SET_LOG_FD
135  * VHOST_SET_VRING_KICK
136  * VHOST_SET_VRING_CALL
137  * VHOST_SET_VRING_ERR
138
139 If Master is unable to send the full message or receives a wrong reply it will
140 close the connection. An optional reconnection mechanism can be implemented.
141
142 Any protocol extensions are gated by protocol feature bits,
143 which allows full backwards compatibility on both master
144 and slave.
145 As older slaves don't support negotiating protocol features,
146 a feature bit was dedicated for this purpose:
147 #define VHOST_USER_F_PROTOCOL_FEATURES 30
148
149 Starting and stopping rings
150 ----------------------
151 Client must only process each ring when it is started.
152
153 Client must only pass data between the ring and the
154 backend, when the ring is enabled.
155
156 If ring is started but disabled, client must process the
157 ring without talking to the backend.
158
159 For example, for a networking device, in the disabled state
160 client must not supply any new RX packets, but must process
161 and discard any TX packets.
162
163 If VHOST_USER_F_PROTOCOL_FEATURES has not been negotiated, the ring is initialized
164 in an enabled state.
165
166 If VHOST_USER_F_PROTOCOL_FEATURES has been negotiated, the ring is initialized
167 in a disabled state. Client must not pass data to/from the backend until ring is enabled by
168 VHOST_USER_SET_VRING_ENABLE with parameter 1, or after it has been disabled by
169 VHOST_USER_SET_VRING_ENABLE with parameter 0.
170
171 Each ring is initialized in a stopped state, client must not process it until
172 ring is started, or after it has been stopped.
173
174 Client must start ring upon receiving a kick (that is, detecting that file
175 descriptor is readable) on the descriptor specified by
176 VHOST_USER_SET_VRING_KICK, and stop ring upon receiving
177 VHOST_USER_GET_VRING_BASE.
178
179 While processing the rings (whether they are enabled or not), client must
180 support changing some configuration aspects on the fly.
181
182 Multiple queue support
183 ----------------------
184
185 Multiple queue is treated as a protocol extension, hence the slave has to
186 implement protocol features first. The multiple queues feature is supported
187 only when the protocol feature VHOST_USER_PROTOCOL_F_MQ (bit 0) is set.
188
189 The max number of queues the slave supports can be queried with message
190 VHOST_USER_GET_PROTOCOL_FEATURES. Master should stop when the number of
191 requested queues is bigger than that.
192
193 As all queues share one connection, the master uses a unique index for each
194 queue in the sent message to identify a specified queue. One queue pair
195 is enabled initially. More queues are enabled dynamically, by sending
196 message VHOST_USER_SET_VRING_ENABLE.
197
198 Migration
199 ---------
200
201 During live migration, the master may need to track the modifications
202 the slave makes to the memory mapped regions. The client should mark
203 the dirty pages in a log. Once it complies to this logging, it may
204 declare the VHOST_F_LOG_ALL vhost feature.
205
206 To start/stop logging of data/used ring writes, server may send messages
207 VHOST_USER_SET_FEATURES with VHOST_F_LOG_ALL and VHOST_USER_SET_VRING_ADDR with
208 VHOST_VRING_F_LOG in ring's flags set to 1/0, respectively.
209
210 All the modifications to memory pointed by vring "descriptor" should
211 be marked. Modifications to "used" vring should be marked if
212 VHOST_VRING_F_LOG is part of ring's flags.
213
214 Dirty pages are of size:
215 #define VHOST_LOG_PAGE 0x1000
216
217 The log memory fd is provided in the ancillary data of
218 VHOST_USER_SET_LOG_BASE message when the slave has
219 VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol feature.
220
221 The size of the log is supplied as part of VhostUserMsg
222 which should be large enough to cover all known guest
223 addresses. Log starts at the supplied offset in the
224 supplied file descriptor.
225 The log covers from address 0 to the maximum of guest
226 regions. In pseudo-code, to mark page at "addr" as dirty:
227
228 page = addr / VHOST_LOG_PAGE
229 log[page / 8] |= 1 << page % 8
230
231 Where addr is the guest physical address.
232
233 Use atomic operations, as the log may be concurrently manipulated.
234
235 Note that when logging modifications to the used ring (when VHOST_VRING_F_LOG
236 is set for this ring), log_guest_addr should be used to calculate the log
237 offset: the write to first byte of the used ring is logged at this offset from
238 log start. Also note that this value might be outside the legal guest physical
239 address range (i.e. does not have to be covered by the VhostUserMemory table),
240 but the bit offset of the last byte of the ring must fall within
241 the size supplied by VhostUserLog.
242
243 VHOST_USER_SET_LOG_FD is an optional message with an eventfd in
244 ancillary data, it may be used to inform the master that the log has
245 been modified.
246
247 Once the source has finished migration, rings will be stopped by
248 the source. No further update must be done before rings are
249 restarted.
250
251 Protocol features
252 -----------------
253
254 #define VHOST_USER_PROTOCOL_F_MQ             0
255 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD      1
256 #define VHOST_USER_PROTOCOL_F_RARP           2
257
258 Message types
259 -------------
260
261  * VHOST_USER_GET_FEATURES
262
263       Id: 1
264       Equivalent ioctl: VHOST_GET_FEATURES
265       Master payload: N/A
266       Slave payload: u64
267
268       Get from the underlying vhost implementation the features bitmask.
269       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
270       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
271
272  * VHOST_USER_SET_FEATURES
273
274       Id: 2
275       Ioctl: VHOST_SET_FEATURES
276       Master payload: u64
277
278       Enable features in the underlying vhost implementation using a bitmask.
279       Feature bit VHOST_USER_F_PROTOCOL_FEATURES signals slave support for
280       VHOST_USER_GET_PROTOCOL_FEATURES and VHOST_USER_SET_PROTOCOL_FEATURES.
281
282  * VHOST_USER_GET_PROTOCOL_FEATURES
283
284       Id: 15
285       Equivalent ioctl: VHOST_GET_FEATURES
286       Master payload: N/A
287       Slave payload: u64
288
289       Get the protocol feature bitmask from the underlying vhost implementation.
290       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
291       VHOST_USER_GET_FEATURES.
292       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
293       this message even before VHOST_USER_SET_FEATURES was called.
294
295  * VHOST_USER_SET_PROTOCOL_FEATURES
296
297       Id: 16
298       Ioctl: VHOST_SET_FEATURES
299       Master payload: u64
300
301       Enable protocol features in the underlying vhost implementation.
302       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
303       VHOST_USER_GET_FEATURES.
304       Note: slave that reported VHOST_USER_F_PROTOCOL_FEATURES must support
305       this message even before VHOST_USER_SET_FEATURES was called.
306
307  * VHOST_USER_SET_OWNER
308
309       Id: 3
310       Equivalent ioctl: VHOST_SET_OWNER
311       Master payload: N/A
312
313       Issued when a new connection is established. It sets the current Master
314       as an owner of the session. This can be used on the Slave as a
315       "session start" flag.
316
317  * VHOST_USER_RESET_OWNER
318
319       Id: 4
320       Master payload: N/A
321
322       This is no longer used. Used to be sent to request disabling
323       all rings, but some clients interpreted it to also discard
324       connection state (this interpretation would lead to bugs).
325       It is recommended that clients either ignore this message,
326       or use it to disable all rings.
327
328  * VHOST_USER_SET_MEM_TABLE
329
330       Id: 5
331       Equivalent ioctl: VHOST_SET_MEM_TABLE
332       Master payload: memory regions description
333
334       Sets the memory map regions on the slave so it can translate the vring
335       addresses. In the ancillary data there is an array of file descriptors
336       for each memory mapped region. The size and ordering of the fds matches
337       the number and ordering of memory regions.
338
339  * VHOST_USER_SET_LOG_BASE
340
341       Id: 6
342       Equivalent ioctl: VHOST_SET_LOG_BASE
343       Master payload: u64
344       Slave payload: N/A
345
346       Sets logging shared memory space.
347       When slave has VHOST_USER_PROTOCOL_F_LOG_SHMFD protocol
348       feature, the log memory fd is provided in the ancillary data of
349       VHOST_USER_SET_LOG_BASE message, the size and offset of shared
350       memory area provided in the message.
351
352
353  * VHOST_USER_SET_LOG_FD
354
355       Id: 7
356       Equivalent ioctl: VHOST_SET_LOG_FD
357       Master payload: N/A
358
359       Sets the logging file descriptor, which is passed as ancillary data.
360
361  * VHOST_USER_SET_VRING_NUM
362
363       Id: 8
364       Equivalent ioctl: VHOST_SET_VRING_NUM
365       Master payload: vring state description
366
367       Set the size of the queue.
368
369  * VHOST_USER_SET_VRING_ADDR
370
371       Id: 9
372       Equivalent ioctl: VHOST_SET_VRING_ADDR
373       Master payload: vring address description
374       Slave payload: N/A
375
376       Sets the addresses of the different aspects of the vring.
377
378  * VHOST_USER_SET_VRING_BASE
379
380       Id: 10
381       Equivalent ioctl: VHOST_SET_VRING_BASE
382       Master payload: vring state description
383
384       Sets the base offset in the available vring.
385
386  * VHOST_USER_GET_VRING_BASE
387
388       Id: 11
389       Equivalent ioctl: VHOST_USER_GET_VRING_BASE
390       Master payload: vring state description
391       Slave payload: vring state description
392
393       Get the available vring base offset.
394
395  * VHOST_USER_SET_VRING_KICK
396
397       Id: 12
398       Equivalent ioctl: VHOST_SET_VRING_KICK
399       Master payload: u64
400
401       Set the event file descriptor for adding buffers to the vring. It
402       is passed in the ancillary data.
403       Bits (0-7) of the payload contain the vring index. Bit 8 is the
404       invalid FD flag. This flag is set when there is no file descriptor
405       in the ancillary data. This signals that polling should be used
406       instead of waiting for a kick.
407
408  * VHOST_USER_SET_VRING_CALL
409
410       Id: 13
411       Equivalent ioctl: VHOST_SET_VRING_CALL
412       Master payload: u64
413
414       Set the event file descriptor to signal when buffers are used. It
415       is passed in the ancillary data.
416       Bits (0-7) of the payload contain the vring index. Bit 8 is the
417       invalid FD flag. This flag is set when there is no file descriptor
418       in the ancillary data. This signals that polling will be used
419       instead of waiting for the call.
420
421  * VHOST_USER_SET_VRING_ERR
422
423       Id: 14
424       Equivalent ioctl: VHOST_SET_VRING_ERR
425       Master payload: u64
426
427       Set the event file descriptor to signal when error occurs. It
428       is passed in the ancillary data.
429       Bits (0-7) of the payload contain the vring index. Bit 8 is the
430       invalid FD flag. This flag is set when there is no file descriptor
431       in the ancillary data.
432
433  * VHOST_USER_GET_QUEUE_NUM
434
435       Id: 17
436       Equivalent ioctl: N/A
437       Master payload: N/A
438       Slave payload: u64
439
440       Query how many queues the backend supports. This request should be
441       sent only when VHOST_USER_PROTOCOL_F_MQ is set in queried protocol
442       features by VHOST_USER_GET_PROTOCOL_FEATURES.
443
444  * VHOST_USER_SET_VRING_ENABLE
445
446       Id: 18
447       Equivalent ioctl: N/A
448       Master payload: vring state description
449
450       Signal slave to enable or disable corresponding vring.
451       This request should be sent only when VHOST_USER_F_PROTOCOL_FEATURES
452       has been negotiated.
453
454  * VHOST_USER_SEND_RARP
455
456       Id: 19
457       Equivalent ioctl: N/A
458       Master payload: u64
459
460       Ask vhost user backend to broadcast a fake RARP to notify the migration
461       is terminated for guest that does not support GUEST_ANNOUNCE.
462       Only legal if feature bit VHOST_USER_F_PROTOCOL_FEATURES is present in
463       VHOST_USER_GET_FEATURES and protocol feature bit VHOST_USER_PROTOCOL_F_RARP
464       is present in VHOST_USER_GET_PROTOCOL_FEATURES.
465       The first 6 bytes of the payload contain the mac address of the guest to
466       allow the vhost user backend to construct and broadcast the fake RARP.