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