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