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     int slave_fd;
 230     uint64_t log_size;
 231     uint8_t *log_table;
 232     uint64_t features;
 233     uint64_t protocol_features;
 234     bool broken;
 235
 236     /* @set_watch: add or update the given fd to the watch set,
 237      * call cb when condition is met */
 238     vu_set_watch_cb set_watch;
 239
 240     /* @remove_watch: remove the given fd from the watch set */
 241     vu_remove_watch_cb remove_watch;
 242
 243     /* @panic: encountered an unrecoverable error, you may try to
 244      * re-initialize */
 245     vu_panic_cb panic;
 246     const VuDevIface *iface;
 247 };
 248
 249 typedef struct VuVirtqElement {
 250     unsigned int index;
 251     unsigned int out_num;
 252     unsigned int in_num;
 253     struct iovec *in_sg;
 254     struct iovec *out_sg;
 255 } VuVirtqElement;
 256
 257 /**
 258  * vu_init:
 259  * @dev: a VuDev context
 260  * @socket: the socket connected to vhost-user master
 261  * @panic: a panic callback
 262  * @set_watch: a set_watch callback
 263  * @remove_watch: a remove_watch callback
 264  * @iface: a VuDevIface structure with vhost-user device callbacks
 265  *
 266  * Intializes a VuDev vhost-user context.
 267  **/
 268 void vu_init(VuDev *dev,
 269              int socket,
 270              vu_panic_cb panic,
 271              vu_set_watch_cb set_watch,
 272              vu_remove_watch_cb remove_watch,
 273              const VuDevIface *iface);
 274
 275
 276 /**
 277  * vu_deinit:
 278  * @dev: a VuDev context
 279  *
 280  * Cleans up the VuDev context
 281  */
 282 void vu_deinit(VuDev *dev);
 283
 284 /**
 285  * vu_dispatch:
 286  * @dev: a VuDev context
 287  *
 288  * Process one vhost-user message.
 289  *
 290  * Returns: TRUE on success, FALSE on failure.
 291  */
 292 bool vu_dispatch(VuDev *dev);
 293
 294 /**
 295  * vu_gpa_to_va:
 296  * @dev: a VuDev context
 297  * @guest_addr: guest address
 298  *
 299  * Translate a guest address to a pointer. Returns NULL on failure.
 300  */
 301 void *vu_gpa_to_va(VuDev *dev, uint64_t guest_addr);
 302
 303 /**
 304  * vu_get_queue:
 305  * @dev: a VuDev context
 306  * @qidx: queue index
 307  *
 308  * Returns the queue number @qidx.
 309  */
 310 VuVirtq *vu_get_queue(VuDev *dev, int qidx);
 311
 312 /**
 313  * vu_set_queue_handler:
 314  * @dev: a VuDev context
 315  * @vq: a VuVirtq queue
 316  * @handler: the queue handler callback
 317  *
 318  * Set the queue handler. This function may be called several times
 319  * for the same queue. If called with NULL @handler, the handler is
 320  * removed.
 321  */
 322 void vu_set_queue_handler(VuDev *dev, VuVirtq *vq,
 323                           vu_queue_handler_cb handler);
 324
 325
 326 /**
 327  * vu_queue_set_notification:
 328  * @dev: a VuDev context
 329  * @vq: a VuVirtq queue
 330  * @enable: state
 331  *
 332  * Set whether the queue notifies (via event index or interrupt)
 333  */
 334 void vu_queue_set_notification(VuDev *dev, VuVirtq *vq, int enable);
 335
 336 /**
 337  * vu_queue_enabled:
 338  * @dev: a VuDev context
 339  * @vq: a VuVirtq queue
 340  *
 341  * Returns: whether the queue is enabled.
 342  */
 343 bool vu_queue_enabled(VuDev *dev, VuVirtq *vq);
 344
 345 /**
 346  * vu_queue_started:
 347  * @dev: a VuDev context
 348  * @vq: a VuVirtq queue
 349  *
 350  * Returns: whether the queue is started.
 351  */
 352 bool vu_queue_started(const VuDev *dev, const VuVirtq *vq);
 353
 354 /**
 355  * vu_queue_empty:
 356  * @dev: a VuDev context
 357  * @vq: a VuVirtq queue
 358  *
 359  * Returns: true if the queue is empty or not ready.
 360  */
 361 bool vu_queue_empty(VuDev *dev, VuVirtq *vq);
 362
 363 /**
 364  * vu_queue_notify:
 365  * @dev: a VuDev context
 366  * @vq: a VuVirtq queue
 367  *
 368  * Request to notify the queue via callfd (skipped if unnecessary)
 369  */
 370 void vu_queue_notify(VuDev *dev, VuVirtq *vq);
 371
 372 /**
 373  * vu_queue_pop:
 374  * @dev: a VuDev context
 375  * @vq: a VuVirtq queue
 376  * @sz: the size of struct to return (must be >= VuVirtqElement)
 377  *
 378  * Returns: a VuVirtqElement filled from the queue or NULL. The
 379  * returned element must be free()-d by the caller.
 380  */
 381 void *vu_queue_pop(VuDev *dev, VuVirtq *vq, size_t sz);
 382
 383 /**
 384  * vu_queue_rewind:
 385  * @dev: a VuDev context
 386  * @vq: a VuVirtq queue
 387  * @num: number of elements to push back
 388  *
 389  * Pretend that elements weren't popped from the virtqueue.  The next
 390  * virtqueue_pop() will refetch the oldest element.
 391  *
 392  * Returns: true on success, false if @num is greater than the number of in use
 393  * elements.
 394  */
 395 bool vu_queue_rewind(VuDev *dev, VuVirtq *vq, unsigned int num);
 396
 397 /**
 398  * vu_queue_fill:
 399  * @dev: a VuDev context
 400  * @vq: a VuVirtq queue
 401  * @elem: a VuVirtqElement
 402  * @len: length in bytes to write
 403  * @idx: optional offset for the used ring index (0 in general)
 404  *
 405  * Fill the used ring with @elem element.
 406  */
 407 void vu_queue_fill(VuDev *dev, VuVirtq *vq,
 408                    const VuVirtqElement *elem,
 409                    unsigned int len, unsigned int idx);
 410
 411 /**
 412  * vu_queue_push:
 413  * @dev: a VuDev context
 414  * @vq: a VuVirtq queue
 415  * @elem: a VuVirtqElement
 416  * @len: length in bytes to write
 417  *
 418  * Helper that combines vu_queue_fill() with a vu_queue_flush().
 419  */
 420 void vu_queue_push(VuDev *dev, VuVirtq *vq,
 421                    const VuVirtqElement *elem, unsigned int len);
 422
 423 /**
 424  * vu_queue_flush:
 425  * @dev: a VuDev context
 426  * @vq: a VuVirtq queue
 427  * @num: number of elements to flush
 428  *
 429  * Mark the last number of elements as done (used.idx is updated by
 430  * num elements).
 431 */
 432 void vu_queue_flush(VuDev *dev, VuVirtq *vq, unsigned int num);
 433
 434 /**
 435  * vu_queue_get_avail_bytes:
 436  * @dev: a VuDev context
 437  * @vq: a VuVirtq queue
 438  * @in_bytes: in bytes
 439  * @out_bytes: out bytes
 440  * @max_in_bytes: stop counting after max_in_bytes
 441  * @max_out_bytes: stop counting after max_out_bytes
 442  *
 443  * Count the number of available bytes, up to max_in_bytes/max_out_bytes.
 444  */
 445 void vu_queue_get_avail_bytes(VuDev *vdev, VuVirtq *vq, unsigned int *in_bytes,
 446                               unsigned int *out_bytes,
 447                               unsigned max_in_bytes, unsigned max_out_bytes);
 448
 449 /**
 450  * vu_queue_avail_bytes:
 451  * @dev: a VuDev context
 452  * @vq: a VuVirtq queue
 453  * @in_bytes: expected in bytes
 454  * @out_bytes: expected out bytes
 455  *
 456  * Returns: true if in_bytes <= in_total && out_bytes <= out_total
 457  */
 458 bool vu_queue_avail_bytes(VuDev *dev, VuVirtq *vq, unsigned int in_bytes,
 459                           unsigned int out_bytes);
 460
 461 #endif /* LIBVHOST_USER_H */