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