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