libvhost-user: Update and fix feature and request lists
[qemu.git] / contrib / libvhost-user / libvhost-user.h
1 /*
2 * Vhost User library
3 *
4 * Copyright (c) 2016 Red Hat, Inc.
5 *
6 * Authors:
7 * Victor Kaplansky <victork@redhat.com>
8 * Marc-André Lureau <mlureau@redhat.com>
9 *
10 * This work is licensed under the terms of the GNU GPL, version 2 or
11 * later. See the COPYING file in the top-level directory.
12 */
13
14 #ifndef LIBVHOST_USER_H
15 #define LIBVHOST_USER_H
16
17 #include <stdint.h>
18 #include <stdbool.h>
19 #include <stddef.h>
20 #include <sys/poll.h>
21 #include <linux/vhost.h>
22 #include "standard-headers/linux/virtio_ring.h"
23
24 /* Based on qemu/hw/virtio/vhost-user.c */
25 #define VHOST_USER_F_PROTOCOL_FEATURES 30
26 #define VHOST_LOG_PAGE 4096
27
28 #define VHOST_MAX_NR_VIRTQUEUE 8
29 #define VIRTQUEUE_MAX_SIZE 1024
30
31 #define VHOST_MEMORY_MAX_NREGIONS 8
32
33 enum VhostUserProtocolFeature {
34 VHOST_USER_PROTOCOL_F_MQ = 0,
35 VHOST_USER_PROTOCOL_F_LOG_SHMFD = 1,
36 VHOST_USER_PROTOCOL_F_RARP = 2,
37 VHOST_USER_PROTOCOL_F_REPLY_ACK = 3,
38 VHOST_USER_PROTOCOL_F_NET_MTU = 4,
39 VHOST_USER_PROTOCOL_F_SLAVE_REQ = 5,
40 VHOST_USER_PROTOCOL_F_CROSS_ENDIAN = 6,
41
42 VHOST_USER_PROTOCOL_F_MAX
43 };
44
45 #define VHOST_USER_PROTOCOL_FEATURE_MASK ((1 << VHOST_USER_PROTOCOL_F_MAX) - 1)
46
47 typedef enum VhostUserRequest {
48 VHOST_USER_NONE = 0,
49 VHOST_USER_GET_FEATURES = 1,
50 VHOST_USER_SET_FEATURES = 2,
51 VHOST_USER_SET_OWNER = 3,
52 VHOST_USER_RESET_OWNER = 4,
53 VHOST_USER_SET_MEM_TABLE = 5,
54 VHOST_USER_SET_LOG_BASE = 6,
55 VHOST_USER_SET_LOG_FD = 7,
56 VHOST_USER_SET_VRING_NUM = 8,
57 VHOST_USER_SET_VRING_ADDR = 9,
58 VHOST_USER_SET_VRING_BASE = 10,
59 VHOST_USER_GET_VRING_BASE = 11,
60 VHOST_USER_SET_VRING_KICK = 12,
61 VHOST_USER_SET_VRING_CALL = 13,
62 VHOST_USER_SET_VRING_ERR = 14,
63 VHOST_USER_GET_PROTOCOL_FEATURES = 15,
64 VHOST_USER_SET_PROTOCOL_FEATURES = 16,
65 VHOST_USER_GET_QUEUE_NUM = 17,
66 VHOST_USER_SET_VRING_ENABLE = 18,
67 VHOST_USER_SEND_RARP = 19,
68 VHOST_USER_NET_SET_MTU = 20,
69 VHOST_USER_SET_SLAVE_REQ_FD = 21,
70 VHOST_USER_IOTLB_MSG = 22,
71 VHOST_USER_SET_VRING_ENDIAN = 23,
72 VHOST_USER_MAX
73 } VhostUserRequest;
74
75 typedef struct VhostUserMemoryRegion {
76 uint64_t guest_phys_addr;
77 uint64_t memory_size;
78 uint64_t userspace_addr;
79 uint64_t mmap_offset;
80 } VhostUserMemoryRegion;
81
82 typedef struct VhostUserMemory {
83 uint32_t nregions;
84 uint32_t padding;
85 VhostUserMemoryRegion regions[VHOST_MEMORY_MAX_NREGIONS];
86 } VhostUserMemory;
87
88 typedef struct VhostUserLog {
89 uint64_t mmap_size;
90 uint64_t mmap_offset;
91 } VhostUserLog;
92
93 #if defined(_WIN32)
94 # define VU_PACKED __attribute__((gcc_struct, packed))
95 #else
96 # define VU_PACKED __attribute__((packed))
97 #endif
98
99 typedef struct VhostUserMsg {
100 VhostUserRequest request;
101
102 #define VHOST_USER_VERSION_MASK (0x3)
103 #define VHOST_USER_REPLY_MASK (0x1 << 2)
104 uint32_t flags;
105 uint32_t size; /* the following payload size */
106
107 union {
108 #define VHOST_USER_VRING_IDX_MASK (0xff)
109 #define VHOST_USER_VRING_NOFD_MASK (0x1 << 8)
110 uint64_t u64;
111 struct vhost_vring_state state;
112 struct vhost_vring_addr addr;
113 VhostUserMemory memory;
114 VhostUserLog log;
115 } payload;
116
117 int fds[VHOST_MEMORY_MAX_NREGIONS];
118 int fd_num;
119 uint8_t *data;
120 } VU_PACKED VhostUserMsg;
121
122 typedef struct VuDevRegion {
123 /* Guest Physical address. */
124 uint64_t gpa;
125 /* Memory region size. */
126 uint64_t size;
127 /* QEMU virtual address (userspace). */
128 uint64_t qva;
129 /* Starting offset in our mmaped space. */
130 uint64_t mmap_offset;
131 /* Start address of mmaped space. */
132 uint64_t mmap_addr;
133 } VuDevRegion;
134
135 typedef struct VuDev VuDev;
136
137 typedef uint64_t (*vu_get_features_cb) (VuDev *dev);
138 typedef void (*vu_set_features_cb) (VuDev *dev, uint64_t features);
139 typedef int (*vu_process_msg_cb) (VuDev *dev, VhostUserMsg *vmsg,
140 int *do_reply);
141 typedef void (*vu_queue_set_started_cb) (VuDev *dev, int qidx, bool started);
142 typedef bool (*vu_queue_is_processed_in_order_cb) (VuDev *dev, int qidx);
143
144 typedef struct VuDevIface {
145 /* called by VHOST_USER_GET_FEATURES to get the features bitmask */
146 vu_get_features_cb get_features;
147 /* enable vhost implementation features */
148 vu_set_features_cb set_features;
149 /* get the protocol feature bitmask from the underlying vhost
150 * implementation */
151 vu_get_features_cb get_protocol_features;
152 /* enable protocol features in the underlying vhost implementation. */
153 vu_set_features_cb set_protocol_features;
154 /* process_msg is called for each vhost-user message received */
155 /* skip libvhost-user processing if return value != 0 */
156 vu_process_msg_cb process_msg;
157 /* tells when queues can be processed */
158 vu_queue_set_started_cb queue_set_started;
159 /*
160 * If the queue is processed in order, in which case it will be
161 * resumed to vring.used->idx. This can help to support resuming
162 * on unmanaged exit/crash.
163 */
164 vu_queue_is_processed_in_order_cb queue_is_processed_in_order;
165 } VuDevIface;
166
167 typedef void (*vu_queue_handler_cb) (VuDev *dev, int qidx);
168
169 typedef struct VuRing {
170 unsigned int num;
171 struct vring_desc *desc;
172 struct vring_avail *avail;
173 struct vring_used *used;
174 uint64_t log_guest_addr;
175 uint32_t flags;
176 } VuRing;
177
178 typedef struct VuVirtq {
179 VuRing vring;
180
181 /* Next head to pop */
182 uint16_t last_avail_idx;
183
184 /* Last avail_idx read from VQ. */
185 uint16_t shadow_avail_idx;
186
187 uint16_t used_idx;
188
189 /* Last used index value we have signalled on */
190 uint16_t signalled_used;
191
192 /* Last used index value we have signalled on */
193 bool signalled_used_valid;
194
195 /* Notification enabled? */
196 bool notification;
197
198 int inuse;
199
200 vu_queue_handler_cb handler;
201
202 int call_fd;
203 int kick_fd;
204 int err_fd;
205 unsigned int enable;
206 bool started;
207 } VuVirtq;
208
209 enum VuWatchCondtion {
210 VU_WATCH_IN = POLLIN,
211 VU_WATCH_OUT = POLLOUT,
212 VU_WATCH_PRI = POLLPRI,
213 VU_WATCH_ERR = POLLERR,
214 VU_WATCH_HUP = POLLHUP,
215 };
216
217 typedef void (*vu_panic_cb) (VuDev *dev, const char *err);
218 typedef void (*vu_watch_cb) (VuDev *dev, int condition, void *data);
219 typedef void (*vu_set_watch_cb) (VuDev *dev, int fd, int condition,
220 vu_watch_cb cb, void *data);
221 typedef void (*vu_remove_watch_cb) (VuDev *dev, int fd);
222
223 struct VuDev {
224 int sock;
225 uint32_t nregions;
226 VuDevRegion regions[VHOST_MEMORY_MAX_NREGIONS];
227 VuVirtq vq[VHOST_MAX_NR_VIRTQUEUE];
228 int log_call_fd;
229 uint64_t log_size;
230 uint8_t *log_table;
231 uint64_t features;
232 uint64_t protocol_features;
233 bool broken;
234
235 /* @set_watch: add or update the given fd to the watch set,
236 * call cb when condition is met */
237 vu_set_watch_cb set_watch;
238
239 /* @remove_watch: remove the given fd from the watch set */
240 vu_remove_watch_cb remove_watch;
241
242 /* @panic: encountered an unrecoverable error, you may try to
243 * re-initialize */
244 vu_panic_cb panic;
245 const VuDevIface *iface;
246 };
247
248 typedef struct VuVirtqElement {
249 unsigned int index;
250 unsigned int out_num;
251 unsigned int in_num;
252 struct iovec *in_sg;
253 struct iovec *out_sg;
254 } VuVirtqElement;
255
256 /**
257 * vu_init:
258 * @dev: a VuDev context
259 * @socket: the socket connected to vhost-user master
260 * @panic: a panic callback
261 * @set_watch: a set_watch callback
262 * @remove_watch: a remove_watch callback
263 * @iface: a VuDevIface structure with vhost-user device callbacks
264 *
265 * Intializes a VuDev vhost-user context.
266 **/
267 void vu_init(VuDev *dev,
268 int socket,
269 vu_panic_cb panic,
270 vu_set_watch_cb set_watch,
271 vu_remove_watch_cb remove_watch,
272 const VuDevIface *iface);
273
274
275 /**
276 * vu_deinit:
277 * @dev: a VuDev context
278 *
279 * Cleans up the VuDev context
280 */
281 void vu_deinit(VuDev *dev);
282
283 /**
284 * vu_dispatch:
285 * @dev: a VuDev context
286 *
287 * Process one vhost-user message.
288 *
289 * Returns: TRUE on success, FALSE on failure.
290 */
291 bool vu_dispatch(VuDev *dev);
292
293 /**
294 * vu_gpa_to_va:
295 * @dev: a VuDev context
296 * @guest_addr: guest address
297 *
298 * Translate a guest address to a pointer. Returns NULL on failure.
299 */
300 void *vu_gpa_to_va(VuDev *dev, uint64_t guest_addr);
301
302 /**
303 * vu_get_queue:
304 * @dev: a VuDev context
305 * @qidx: queue index
306 *
307 * Returns the queue number @qidx.
308 */
309 VuVirtq *vu_get_queue(VuDev *dev, int qidx);
310
311 /**
312 * vu_set_queue_handler:
313 * @dev: a VuDev context
314 * @vq: a VuVirtq queue
315 * @handler: the queue handler callback
316 *
317 * Set the queue handler. This function may be called several times
318 * for the same queue. If called with NULL @handler, the handler is
319 * removed.
320 */
321 void vu_set_queue_handler(VuDev *dev, VuVirtq *vq,
322 vu_queue_handler_cb handler);
323
324
325 /**
326 * vu_queue_set_notification:
327 * @dev: a VuDev context
328 * @vq: a VuVirtq queue
329 * @enable: state
330 *
331 * Set whether the queue notifies (via event index or interrupt)
332 */
333 void vu_queue_set_notification(VuDev *dev, VuVirtq *vq, int enable);
334
335 /**
336 * vu_queue_enabled:
337 * @dev: a VuDev context
338 * @vq: a VuVirtq queue
339 *
340 * Returns: whether the queue is enabled.
341 */
342 bool vu_queue_enabled(VuDev *dev, VuVirtq *vq);
343
344 /**
345 * vu_queue_started:
346 * @dev: a VuDev context
347 * @vq: a VuVirtq queue
348 *
349 * Returns: whether the queue is started.
350 */
351 bool vu_queue_started(const VuDev *dev, const VuVirtq *vq);
352
353 /**
354 * vu_queue_empty:
355 * @dev: a VuDev context
356 * @vq: a VuVirtq queue
357 *
358 * Returns: true if the queue is empty or not ready.
359 */
360 bool vu_queue_empty(VuDev *dev, VuVirtq *vq);
361
362 /**
363 * vu_queue_notify:
364 * @dev: a VuDev context
365 * @vq: a VuVirtq queue
366 *
367 * Request to notify the queue via callfd (skipped if unnecessary)
368 */
369 void vu_queue_notify(VuDev *dev, VuVirtq *vq);
370
371 /**
372 * vu_queue_pop:
373 * @dev: a VuDev context
374 * @vq: a VuVirtq queue
375 * @sz: the size of struct to return (must be >= VuVirtqElement)
376 *
377 * Returns: a VuVirtqElement filled from the queue or NULL. The
378 * returned element must be free()-d by the caller.
379 */
380 void *vu_queue_pop(VuDev *dev, VuVirtq *vq, size_t sz);
381
382 /**
383 * vu_queue_rewind:
384 * @dev: a VuDev context
385 * @vq: a VuVirtq queue
386 * @num: number of elements to push back
387 *
388 * Pretend that elements weren't popped from the virtqueue. The next
389 * virtqueue_pop() will refetch the oldest element.
390 *
391 * Returns: true on success, false if @num is greater than the number of in use
392 * elements.
393 */
394 bool vu_queue_rewind(VuDev *dev, VuVirtq *vq, unsigned int num);
395
396 /**
397 * vu_queue_fill:
398 * @dev: a VuDev context
399 * @vq: a VuVirtq queue
400 * @elem: a VuVirtqElement
401 * @len: length in bytes to write
402 * @idx: optional offset for the used ring index (0 in general)
403 *
404 * Fill the used ring with @elem element.
405 */
406 void vu_queue_fill(VuDev *dev, VuVirtq *vq,
407 const VuVirtqElement *elem,
408 unsigned int len, unsigned int idx);
409
410 /**
411 * vu_queue_push:
412 * @dev: a VuDev context
413 * @vq: a VuVirtq queue
414 * @elem: a VuVirtqElement
415 * @len: length in bytes to write
416 *
417 * Helper that combines vu_queue_fill() with a vu_queue_flush().
418 */
419 void vu_queue_push(VuDev *dev, VuVirtq *vq,
420 const VuVirtqElement *elem, unsigned int len);
421
422 /**
423 * vu_queue_flush:
424 * @dev: a VuDev context
425 * @vq: a VuVirtq queue
426 * @num: number of elements to flush
427 *
428 * Mark the last number of elements as done (used.idx is updated by
429 * num elements).
430 */
431 void vu_queue_flush(VuDev *dev, VuVirtq *vq, unsigned int num);
432
433 /**
434 * vu_queue_get_avail_bytes:
435 * @dev: a VuDev context
436 * @vq: a VuVirtq queue
437 * @in_bytes: in bytes
438 * @out_bytes: out bytes
439 * @max_in_bytes: stop counting after max_in_bytes
440 * @max_out_bytes: stop counting after max_out_bytes
441 *
442 * Count the number of available bytes, up to max_in_bytes/max_out_bytes.
443 */
444 void vu_queue_get_avail_bytes(VuDev *vdev, VuVirtq *vq, unsigned int *in_bytes,
445 unsigned int *out_bytes,
446 unsigned max_in_bytes, unsigned max_out_bytes);
447
448 /**
449 * vu_queue_avail_bytes:
450 * @dev: a VuDev context
451 * @vq: a VuVirtq queue
452 * @in_bytes: expected in bytes
453 * @out_bytes: expected out bytes
454 *
455 * Returns: true if in_bytes <= in_total && out_bytes <= out_total
456 */
457 bool vu_queue_avail_bytes(VuDev *dev, VuVirtq *vq, unsigned int in_bytes,
458 unsigned int out_bytes);
459
460 #endif /* LIBVHOST_USER_H */