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
 136 typedef struct VuDevIface {
 137     /* called by VHOST_USER_GET_FEATURES to get the features bitmask */
 138     vu_get_features_cb get_features;
 139     /* enable vhost implementation features */
 140     vu_set_features_cb set_features;
 141     /* get the protocol feature bitmask from the underlying vhost
 142      * implementation */
 143     vu_get_features_cb get_protocol_features;
 144     /* enable protocol features in the underlying vhost implementation. */
 145     vu_set_features_cb set_protocol_features;
 146     /* process_msg is called for each vhost-user message received */
 147     /* skip libvhost-user processing if return value != 0 */
 148     vu_process_msg_cb process_msg;
 149     /* tells when queues can be processed */
 150     vu_queue_set_started_cb queue_set_started;
 151 } VuDevIface;
 152
 153 typedef void (*vu_queue_handler_cb) (VuDev *dev, int qidx);
 154
 155 typedef struct VuRing {
 156     unsigned int num;
 157     struct vring_desc *desc;
 158     struct vring_avail *avail;
 159     struct vring_used *used;
 160     uint64_t log_guest_addr;
 161     uint32_t flags;
 162 } VuRing;
 163
 164 typedef struct VuVirtq {
 165     VuRing vring;
 166
 167     /* Next head to pop */
 168     uint16_t last_avail_idx;
 169
 170     /* Last avail_idx read from VQ. */
 171     uint16_t shadow_avail_idx;
 172
 173     uint16_t used_idx;
 174
 175     /* Last used index value we have signalled on */
 176     uint16_t signalled_used;
 177
 178     /* Last used index value we have signalled on */
 179     bool signalled_used_valid;
 180
 181     /* Notification enabled? */
 182     bool notification;
 183
 184     int inuse;
 185
 186     vu_queue_handler_cb handler;
 187
 188     int call_fd;
 189     int kick_fd;
 190     int err_fd;
 191     unsigned int enable;
 192     bool started;
 193 } VuVirtq;
 194
 195 enum VuWatchCondtion {
 196     VU_WATCH_IN = POLLIN,
 197     VU_WATCH_OUT = POLLOUT,
 198     VU_WATCH_PRI = POLLPRI,
 199     VU_WATCH_ERR = POLLERR,
 200     VU_WATCH_HUP = POLLHUP,
 201 };
 202
 203 typedef void (*vu_panic_cb) (VuDev *dev, const char *err);
 204 typedef void (*vu_watch_cb) (VuDev *dev, int condition, void *data);
 205 typedef void (*vu_set_watch_cb) (VuDev *dev, int fd, int condition,
 206                                  vu_watch_cb cb, void *data);
 207 typedef void (*vu_remove_watch_cb) (VuDev *dev, int fd);
 208
 209 struct VuDev {
 210     int sock;
 211     uint32_t nregions;
 212     VuDevRegion regions[VHOST_MEMORY_MAX_NREGIONS];
 213     VuVirtq vq[VHOST_MAX_NR_VIRTQUEUE];
 214     int log_call_fd;
 215     uint64_t log_size;
 216     uint8_t *log_table;
 217     uint64_t features;
 218     uint64_t protocol_features;
 219     bool broken;
 220
 221     /* @set_watch: add or update the given fd to the watch set,
 222      * call cb when condition is met */
 223     vu_set_watch_cb set_watch;
 224
 225     /* @remove_watch: remove the given fd from the watch set */
 226     vu_remove_watch_cb remove_watch;
 227
 228     /* @panic: encountered an unrecoverable error, you may try to
 229      * re-initialize */
 230     vu_panic_cb panic;
 231     const VuDevIface *iface;
 232 };
 233
 234 typedef struct VuVirtqElement {
 235     unsigned int index;
 236     unsigned int out_num;
 237     unsigned int in_num;
 238     struct iovec *in_sg;
 239     struct iovec *out_sg;
 240 } VuVirtqElement;
 241
 242 /**
 243  * vu_init:
 244  * @dev: a VuDev context
 245  * @socket: the socket connected to vhost-user master
 246  * @panic: a panic callback
 247  * @set_watch: a set_watch callback
 248  * @remove_watch: a remove_watch callback
 249  * @iface: a VuDevIface structure with vhost-user device callbacks
 250  *
 251  * Intializes a VuDev vhost-user context.
 252  **/
 253 void vu_init(VuDev *dev,
 254              int socket,
 255              vu_panic_cb panic,
 256              vu_set_watch_cb set_watch,
 257              vu_remove_watch_cb remove_watch,
 258              const VuDevIface *iface);
 259
 260
 261 /**
 262  * vu_deinit:
 263  * @dev: a VuDev context
 264  *
 265  * Cleans up the VuDev context
 266  */
 267 void vu_deinit(VuDev *dev);
 268
 269 /**
 270  * vu_dispatch:
 271  * @dev: a VuDev context
 272  *
 273  * Process one vhost-user message.
 274  *
 275  * Returns: TRUE on success, FALSE on failure.
 276  */
 277 bool vu_dispatch(VuDev *dev);
 278
 279 /**
 280  * vu_gpa_to_va:
 281  * @dev: a VuDev context
 282  * @guest_addr: guest address
 283  *
 284  * Translate a guest address to a pointer. Returns NULL on failure.
 285  */
 286 void *vu_gpa_to_va(VuDev *dev, uint64_t guest_addr);
 287
 288 /**
 289  * vu_get_queue:
 290  * @dev: a VuDev context
 291  * @qidx: queue index
 292  *
 293  * Returns the queue number @qidx.
 294  */
 295 VuVirtq *vu_get_queue(VuDev *dev, int qidx);
 296
 297 /**
 298  * vu_set_queue_handler:
 299  * @dev: a VuDev context
 300  * @vq: a VuVirtq queue
 301  * @handler: the queue handler callback
 302  *
 303  * Set the queue handler. This function may be called several times
 304  * for the same queue. If called with NULL @handler, the handler is
 305  * removed.
 306  */
 307 void vu_set_queue_handler(VuDev *dev, VuVirtq *vq,
 308                           vu_queue_handler_cb handler);
 309
 310
 311 /**
 312  * vu_queue_set_notification:
 313  * @dev: a VuDev context
 314  * @vq: a VuVirtq queue
 315  * @enable: state
 316  *
 317  * Set whether the queue notifies (via event index or interrupt)
 318  */
 319 void vu_queue_set_notification(VuDev *dev, VuVirtq *vq, int enable);
 320
 321 /**
 322  * vu_queue_enabled:
 323  * @dev: a VuDev context
 324  * @vq: a VuVirtq queue
 325  *
 326  * Returns: whether the queue is enabled.
 327  */
 328 bool vu_queue_enabled(VuDev *dev, VuVirtq *vq);
 329
 330 /**
 331  * vu_queue_empty:
 332  * @dev: a VuDev context
 333  * @vq: a VuVirtq queue
 334  *
 335  * Returns: true if the queue is empty or not ready.
 336  */
 337 bool vu_queue_empty(VuDev *dev, VuVirtq *vq);
 338
 339 /**
 340  * vu_queue_notify:
 341  * @dev: a VuDev context
 342  * @vq: a VuVirtq queue
 343  *
 344  * Request to notify the queue via callfd (skipped if unnecessary)
 345  */
 346 void vu_queue_notify(VuDev *dev, VuVirtq *vq);
 347
 348 /**
 349  * vu_queue_pop:
 350  * @dev: a VuDev context
 351  * @vq: a VuVirtq queue
 352  * @sz: the size of struct to return (must be >= VuVirtqElement)
 353  *
 354  * Returns: a VuVirtqElement filled from the queue or NULL.
 355  */
 356 void *vu_queue_pop(VuDev *dev, VuVirtq *vq, size_t sz);
 357
 358 /**
 359  * vu_queue_rewind:
 360  * @dev: a VuDev context
 361  * @vq: a VuVirtq queue
 362  * @num: number of elements to push back
 363  *
 364  * Pretend that elements weren't popped from the virtqueue.  The next
 365  * virtqueue_pop() will refetch the oldest element.
 366  *
 367  * Returns: true on success, false if @num is greater than the number of in use
 368  * elements.
 369  */
 370 bool vu_queue_rewind(VuDev *dev, VuVirtq *vq, unsigned int num);
 371
 372 /**
 373  * vu_queue_fill:
 374  * @dev: a VuDev context
 375  * @vq: a VuVirtq queue
 376  * @elem: a VuVirtqElement
 377  * @len: length in bytes to write
 378  * @idx: optional offset for the used ring index (0 in general)
 379  *
 380  * Fill the used ring with @elem element.
 381  */
 382 void vu_queue_fill(VuDev *dev, VuVirtq *vq,
 383                    const VuVirtqElement *elem,
 384                    unsigned int len, unsigned int idx);
 385
 386 /**
 387  * vu_queue_push:
 388  * @dev: a VuDev context
 389  * @vq: a VuVirtq queue
 390  * @elem: a VuVirtqElement
 391  * @len: length in bytes to write
 392  *
 393  * Helper that combines vu_queue_fill() with a vu_queue_flush().
 394  */
 395 void vu_queue_push(VuDev *dev, VuVirtq *vq,
 396                    const VuVirtqElement *elem, unsigned int len);
 397
 398 /**
 399  * vu_queue_flush:
 400  * @dev: a VuDev context
 401  * @vq: a VuVirtq queue
 402  * @num: number of elements to flush
 403  *
 404  * Mark the last number of elements as done (used.idx is updated by
 405  * num elements).
 406 */
 407 void vu_queue_flush(VuDev *dev, VuVirtq *vq, unsigned int num);
 408
 409 /**
 410  * vu_queue_get_avail_bytes:
 411  * @dev: a VuDev context
 412  * @vq: a VuVirtq queue
 413  * @in_bytes: in bytes
 414  * @out_bytes: out bytes
 415  * @max_in_bytes: stop counting after max_in_bytes
 416  * @max_out_bytes: stop counting after max_out_bytes
 417  *
 418  * Count the number of available bytes, up to max_in_bytes/max_out_bytes.
 419  */
 420 void vu_queue_get_avail_bytes(VuDev *vdev, VuVirtq *vq, unsigned int *in_bytes,
 421                               unsigned int *out_bytes,
 422                               unsigned max_in_bytes, unsigned max_out_bytes);
 423
 424 /**
 425  * vu_queue_avail_bytes:
 426  * @dev: a VuDev context
 427  * @vq: a VuVirtq queue
 428  * @in_bytes: expected in bytes
 429  * @out_bytes: expected out bytes
 430  *
 431  * Returns: true if in_bytes <= in_total && out_bytes <= out_total
 432  */
 433 bool vu_queue_avail_bytes(VuDev *dev, VuVirtq *vq, unsigned int in_bytes,
 434                           unsigned int out_bytes);
 435
 436 #endif /* LIBVHOST_USER_H */