| 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 <poll.h> |
| 21 | #include <linux/vhost.h> |
| 22 | #include <pthread.h> |
| 23 | #include "standard-headers/linux/virtio_ring.h" |
| 24 | |
| 25 | /* Based on qemu/hw/virtio/vhost-user.c */ |
| 26 | #define VHOST_USER_F_PROTOCOL_FEATURES 30 |
| 27 | #define VHOST_LOG_PAGE 4096 |
| 28 | |
| 29 | #define VIRTQUEUE_MAX_SIZE 1024 |
| 30 | |
| 31 | #define VHOST_MEMORY_BASELINE_NREGIONS 8 |
| 32 | |
| 33 | /* |
| 34 | * vhost in the kernel usually supports 509 mem slots. 509 used to be the |
| 35 | * KVM limit, it supported 512, but 3 were used for internal purposes. This |
| 36 | * limit is sufficient to support many DIMMs and virtio-mem in |
| 37 | * "dynamic-memslots" mode. |
| 38 | */ |
| 39 | #define VHOST_USER_MAX_RAM_SLOTS 509 |
| 40 | |
| 41 | #define VHOST_USER_HDR_SIZE offsetof(VhostUserMsg, payload.u64) |
| 42 | |
| 43 | typedef enum VhostSetConfigType { |
| 44 | VHOST_SET_CONFIG_TYPE_FRONTEND = 0, |
| 45 | VHOST_SET_CONFIG_TYPE_MIGRATION = 1, |
| 46 | } VhostSetConfigType; |
| 47 | |
| 48 | /* |
| 49 | * Maximum size of virtio device config space |
| 50 | */ |
| 51 | #define VHOST_USER_MAX_CONFIG_SIZE 256 |
| 52 | |
| 53 | enum VhostUserProtocolFeature { |
| 54 | VHOST_USER_PROTOCOL_F_MQ = 0, |
| 55 | VHOST_USER_PROTOCOL_F_LOG_SHMFD = 1, |
| 56 | VHOST_USER_PROTOCOL_F_RARP = 2, |
| 57 | VHOST_USER_PROTOCOL_F_REPLY_ACK = 3, |
| 58 | VHOST_USER_PROTOCOL_F_NET_MTU = 4, |
| 59 | VHOST_USER_PROTOCOL_F_BACKEND_REQ = 5, |
| 60 | VHOST_USER_PROTOCOL_F_CROSS_ENDIAN = 6, |
| 61 | VHOST_USER_PROTOCOL_F_CRYPTO_SESSION = 7, |
| 62 | VHOST_USER_PROTOCOL_F_PAGEFAULT = 8, |
| 63 | VHOST_USER_PROTOCOL_F_CONFIG = 9, |
| 64 | VHOST_USER_PROTOCOL_F_BACKEND_SEND_FD = 10, |
| 65 | VHOST_USER_PROTOCOL_F_HOST_NOTIFIER = 11, |
| 66 | VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD = 12, |
| 67 | VHOST_USER_PROTOCOL_F_INBAND_NOTIFICATIONS = 14, |
| 68 | VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS = 15, |
| 69 | /* Feature 16 is reserved for VHOST_USER_PROTOCOL_F_STATUS. */ |
| 70 | /* Feature 17 reserved for VHOST_USER_PROTOCOL_F_XEN_MMAP. */ |
| 71 | VHOST_USER_PROTOCOL_F_SHARED_OBJECT = 18, |
| 72 | /* Feature 19 is reserved for VHOST_USER_PROTOCOL_F_DEVICE_STATE */ |
| 73 | /* Feature 20 is reserved for VHOST_USER_PROTOCOL_F_GET_VRING_BASE_INFLIGHT */ |
| 74 | /* Feature 21 is reserved for VHOST_USER_PROTOCOL_F_GPA_ADDRESSES */ |
| 75 | VHOST_USER_PROTOCOL_F_SHMEM = 22, |
| 76 | VHOST_USER_PROTOCOL_F_MAX |
| 77 | }; |
| 78 | |
| 79 | #define VHOST_USER_PROTOCOL_FEATURE_MASK ((1 << VHOST_USER_PROTOCOL_F_MAX) - 1) |
| 80 | |
| 81 | typedef enum VhostUserRequest { |
| 82 | VHOST_USER_NONE = 0, |
| 83 | VHOST_USER_GET_FEATURES = 1, |
| 84 | VHOST_USER_SET_FEATURES = 2, |
| 85 | VHOST_USER_SET_OWNER = 3, |
| 86 | VHOST_USER_RESET_OWNER = 4, |
| 87 | VHOST_USER_SET_MEM_TABLE = 5, |
| 88 | VHOST_USER_SET_LOG_BASE = 6, |
| 89 | VHOST_USER_SET_LOG_FD = 7, |
| 90 | VHOST_USER_SET_VRING_NUM = 8, |
| 91 | VHOST_USER_SET_VRING_ADDR = 9, |
| 92 | VHOST_USER_SET_VRING_BASE = 10, |
| 93 | VHOST_USER_GET_VRING_BASE = 11, |
| 94 | VHOST_USER_SET_VRING_KICK = 12, |
| 95 | VHOST_USER_SET_VRING_CALL = 13, |
| 96 | VHOST_USER_SET_VRING_ERR = 14, |
| 97 | VHOST_USER_GET_PROTOCOL_FEATURES = 15, |
| 98 | VHOST_USER_SET_PROTOCOL_FEATURES = 16, |
| 99 | VHOST_USER_GET_QUEUE_NUM = 17, |
| 100 | VHOST_USER_SET_VRING_ENABLE = 18, |
| 101 | VHOST_USER_SEND_RARP = 19, |
| 102 | VHOST_USER_NET_SET_MTU = 20, |
| 103 | VHOST_USER_SET_BACKEND_REQ_FD = 21, |
| 104 | VHOST_USER_IOTLB_MSG = 22, |
| 105 | VHOST_USER_SET_VRING_ENDIAN = 23, |
| 106 | VHOST_USER_GET_CONFIG = 24, |
| 107 | VHOST_USER_SET_CONFIG = 25, |
| 108 | VHOST_USER_CREATE_CRYPTO_SESSION = 26, |
| 109 | VHOST_USER_CLOSE_CRYPTO_SESSION = 27, |
| 110 | VHOST_USER_POSTCOPY_ADVISE = 28, |
| 111 | VHOST_USER_POSTCOPY_LISTEN = 29, |
| 112 | VHOST_USER_POSTCOPY_END = 30, |
| 113 | VHOST_USER_GET_INFLIGHT_FD = 31, |
| 114 | VHOST_USER_SET_INFLIGHT_FD = 32, |
| 115 | VHOST_USER_GPU_SET_SOCKET = 33, |
| 116 | VHOST_USER_VRING_KICK = 35, |
| 117 | VHOST_USER_GET_MAX_MEM_SLOTS = 36, |
| 118 | VHOST_USER_ADD_MEM_REG = 37, |
| 119 | VHOST_USER_REM_MEM_REG = 38, |
| 120 | VHOST_USER_GET_SHARED_OBJECT = 41, |
| 121 | VHOST_USER_MAX |
| 122 | } VhostUserRequest; |
| 123 | |
| 124 | typedef enum VhostUserBackendRequest { |
| 125 | VHOST_USER_BACKEND_NONE = 0, |
| 126 | VHOST_USER_BACKEND_IOTLB_MSG = 1, |
| 127 | VHOST_USER_BACKEND_CONFIG_CHANGE_MSG = 2, |
| 128 | VHOST_USER_BACKEND_VRING_HOST_NOTIFIER_MSG = 3, |
| 129 | VHOST_USER_BACKEND_VRING_CALL = 4, |
| 130 | VHOST_USER_BACKEND_VRING_ERR = 5, |
| 131 | VHOST_USER_BACKEND_SHARED_OBJECT_ADD = 6, |
| 132 | VHOST_USER_BACKEND_SHARED_OBJECT_REMOVE = 7, |
| 133 | VHOST_USER_BACKEND_SHARED_OBJECT_LOOKUP = 8, |
| 134 | VHOST_USER_BACKEND_SHMEM_MAP = 9, |
| 135 | VHOST_USER_BACKEND_SHMEM_UNMAP = 10, |
| 136 | VHOST_USER_BACKEND_MAX |
| 137 | } VhostUserBackendRequest; |
| 138 | |
| 139 | typedef struct VhostUserMemoryRegion { |
| 140 | uint64_t guest_phys_addr; |
| 141 | uint64_t memory_size; |
| 142 | uint64_t userspace_addr; |
| 143 | uint64_t mmap_offset; |
| 144 | } VhostUserMemoryRegion; |
| 145 | |
| 146 | #define VHOST_USER_MEM_REG_SIZE (sizeof(VhostUserMemoryRegion)) |
| 147 | |
| 148 | typedef struct VhostUserMemory { |
| 149 | uint32_t nregions; |
| 150 | uint32_t padding; |
| 151 | VhostUserMemoryRegion regions[VHOST_MEMORY_BASELINE_NREGIONS]; |
| 152 | } VhostUserMemory; |
| 153 | |
| 154 | typedef struct VhostUserMemRegMsg { |
| 155 | uint64_t padding; |
| 156 | VhostUserMemoryRegion region; |
| 157 | } VhostUserMemRegMsg; |
| 158 | |
| 159 | typedef struct VhostUserLog { |
| 160 | uint64_t mmap_size; |
| 161 | uint64_t mmap_offset; |
| 162 | } VhostUserLog; |
| 163 | |
| 164 | typedef struct VhostUserConfig { |
| 165 | uint32_t offset; |
| 166 | uint32_t size; |
| 167 | uint32_t flags; |
| 168 | uint8_t region[VHOST_USER_MAX_CONFIG_SIZE]; |
| 169 | } VhostUserConfig; |
| 170 | |
| 171 | static VhostUserConfig c __attribute__ ((unused)); |
| 172 | #define VHOST_USER_CONFIG_HDR_SIZE (sizeof(c.offset) \ |
| 173 | + sizeof(c.size) \ |
| 174 | + sizeof(c.flags)) |
| 175 | |
| 176 | typedef struct VhostUserVringArea { |
| 177 | uint64_t u64; |
| 178 | uint64_t size; |
| 179 | uint64_t offset; |
| 180 | } VhostUserVringArea; |
| 181 | |
| 182 | typedef struct VhostUserInflight { |
| 183 | uint64_t mmap_size; |
| 184 | uint64_t mmap_offset; |
| 185 | uint16_t num_queues; |
| 186 | uint16_t queue_size; |
| 187 | } VhostUserInflight; |
| 188 | |
| 189 | #define UUID_LEN 16 |
| 190 | |
| 191 | typedef struct VhostUserShared { |
| 192 | unsigned char uuid[UUID_LEN]; |
| 193 | } VhostUserShared; |
| 194 | |
| 195 | /* For the flags field of VhostUserMMap */ |
| 196 | #define VHOST_USER_FLAG_MAP_RW (1u << 0) |
| 197 | |
| 198 | typedef struct { |
| 199 | /* VIRTIO Shared Memory Region ID */ |
| 200 | uint8_t shmid; |
| 201 | uint8_t padding[7]; |
| 202 | /* File offset */ |
| 203 | uint64_t fd_offset; |
| 204 | /* Offset within the VIRTIO Shared Memory Region */ |
| 205 | uint64_t shm_offset; |
| 206 | /* Size of the mapping */ |
| 207 | uint64_t len; |
| 208 | /* Flags for the mmap operation, from VHOST_USER_FLAG_MAP_* */ |
| 209 | uint64_t flags; |
| 210 | } VhostUserMMap; |
| 211 | |
| 212 | #define VU_PACKED __attribute__((packed)) |
| 213 | |
| 214 | typedef struct VhostUserMsg { |
| 215 | int request; |
| 216 | |
| 217 | #define VHOST_USER_VERSION_MASK (0x3) |
| 218 | #define VHOST_USER_REPLY_MASK (0x1 << 2) |
| 219 | #define VHOST_USER_NEED_REPLY_MASK (0x1 << 3) |
| 220 | uint32_t flags; |
| 221 | uint32_t size; /* the following payload size */ |
| 222 | |
| 223 | union { |
| 224 | #define VHOST_USER_VRING_IDX_MASK (0xff) |
| 225 | #define VHOST_USER_VRING_NOFD_MASK (0x1 << 8) |
| 226 | uint64_t u64; |
| 227 | struct vhost_vring_state state; |
| 228 | struct vhost_vring_addr addr; |
| 229 | VhostUserMemory memory; |
| 230 | VhostUserMemRegMsg memreg; |
| 231 | VhostUserLog log; |
| 232 | VhostUserConfig config; |
| 233 | VhostUserVringArea area; |
| 234 | VhostUserInflight inflight; |
| 235 | VhostUserShared object; |
| 236 | VhostUserMMap mmap; |
| 237 | } payload; |
| 238 | |
| 239 | int fds[VHOST_MEMORY_BASELINE_NREGIONS]; |
| 240 | int fd_num; |
| 241 | uint8_t *data; |
| 242 | } VU_PACKED VhostUserMsg; |
| 243 | |
| 244 | typedef struct VuDevRegion { |
| 245 | /* Guest Physical address. */ |
| 246 | uint64_t gpa; |
| 247 | /* Memory region size. */ |
| 248 | uint64_t size; |
| 249 | /* QEMU virtual address (userspace). */ |
| 250 | uint64_t qva; |
| 251 | /* Starting offset in our mmaped space. */ |
| 252 | uint64_t mmap_offset; |
| 253 | /* Start address of mmaped space. */ |
| 254 | uint64_t mmap_addr; |
| 255 | } VuDevRegion; |
| 256 | |
| 257 | typedef struct VuDev VuDev; |
| 258 | |
| 259 | typedef uint64_t (*vu_get_features_cb) (VuDev *dev); |
| 260 | typedef void (*vu_set_features_cb) (VuDev *dev, uint64_t features); |
| 261 | typedef int (*vu_process_msg_cb) (VuDev *dev, VhostUserMsg *vmsg, |
| 262 | int *do_reply); |
| 263 | typedef bool (*vu_read_msg_cb) (VuDev *dev, int sock, VhostUserMsg *vmsg); |
| 264 | typedef void (*vu_queue_set_started_cb) (VuDev *dev, int qidx, bool started); |
| 265 | typedef bool (*vu_queue_is_processed_in_order_cb) (VuDev *dev, int qidx); |
| 266 | typedef int (*vu_get_config_cb) (VuDev *dev, uint8_t *config, uint32_t len); |
| 267 | typedef int (*vu_set_config_cb) (VuDev *dev, const uint8_t *data, |
| 268 | uint32_t offset, uint32_t size, |
| 269 | uint32_t flags); |
| 270 | typedef int (*vu_get_shared_object_cb) (VuDev *dev, const unsigned char *uuid); |
| 271 | |
| 272 | typedef struct VuDevIface { |
| 273 | /* called by VHOST_USER_GET_FEATURES to get the features bitmask */ |
| 274 | vu_get_features_cb get_features; |
| 275 | /* enable vhost implementation features */ |
| 276 | vu_set_features_cb set_features; |
| 277 | /* get the protocol feature bitmask from the underlying vhost |
| 278 | * implementation */ |
| 279 | vu_get_features_cb get_protocol_features; |
| 280 | /* enable protocol features in the underlying vhost implementation. */ |
| 281 | vu_set_features_cb set_protocol_features; |
| 282 | /* process_msg is called for each vhost-user message received */ |
| 283 | /* skip libvhost-user processing if return value != 0 */ |
| 284 | vu_process_msg_cb process_msg; |
| 285 | /* tells when queues can be processed */ |
| 286 | vu_queue_set_started_cb queue_set_started; |
| 287 | /* |
| 288 | * If the queue is processed in order, in which case it will be |
| 289 | * resumed to vring.used->idx. This can help to support resuming |
| 290 | * on unmanaged exit/crash. |
| 291 | */ |
| 292 | vu_queue_is_processed_in_order_cb queue_is_processed_in_order; |
| 293 | /* get the config space of the device */ |
| 294 | vu_get_config_cb get_config; |
| 295 | /* set the config space of the device */ |
| 296 | vu_set_config_cb set_config; |
| 297 | /* get virtio shared object from the underlying vhost implementation. */ |
| 298 | vu_get_shared_object_cb get_shared_object; |
| 299 | } VuDevIface; |
| 300 | |
| 301 | typedef void (*vu_queue_handler_cb) (VuDev *dev, int qidx); |
| 302 | |
| 303 | typedef struct VuRing { |
| 304 | unsigned int num; |
| 305 | struct vring_desc *desc; |
| 306 | struct vring_avail *avail; |
| 307 | struct vring_used *used; |
| 308 | uint64_t log_guest_addr; |
| 309 | uint32_t flags; |
| 310 | } VuRing; |
| 311 | |
| 312 | typedef struct VuDescStateSplit { |
| 313 | /* Indicate whether this descriptor is inflight or not. |
| 314 | * Only available for head-descriptor. */ |
| 315 | uint8_t inflight; |
| 316 | |
| 317 | /* Padding */ |
| 318 | uint8_t padding[5]; |
| 319 | |
| 320 | /* Maintain a list for the last batch of used descriptors. |
| 321 | * Only available when batching is used for submitting */ |
| 322 | uint16_t next; |
| 323 | |
| 324 | /* Used to preserve the order of fetching available descriptors. |
| 325 | * Only available for head-descriptor. */ |
| 326 | uint64_t counter; |
| 327 | } VuDescStateSplit; |
| 328 | |
| 329 | typedef struct VuVirtqInflight { |
| 330 | /* The feature flags of this region. Now it's initialized to 0. */ |
| 331 | uint64_t features; |
| 332 | |
| 333 | /* The version of this region. It's 1 currently. |
| 334 | * Zero value indicates a vm reset happened. */ |
| 335 | uint16_t version; |
| 336 | |
| 337 | /* |
| 338 | * The size of VuDescStateSplit array. It's equal to the virtqueue size. |
| 339 | * Backend could get it from queue size field of VhostUserInflight. |
| 340 | */ |
| 341 | uint16_t desc_num; |
| 342 | |
| 343 | /* The head of list that track the last batch of used descriptors. */ |
| 344 | uint16_t last_batch_head; |
| 345 | |
| 346 | /* Storing the idx value of used ring */ |
| 347 | uint16_t used_idx; |
| 348 | |
| 349 | /* Used to track the state of each descriptor in descriptor table */ |
| 350 | VuDescStateSplit desc[]; |
| 351 | } VuVirtqInflight; |
| 352 | |
| 353 | typedef struct VuVirtqInflightDesc { |
| 354 | uint16_t index; |
| 355 | uint64_t counter; |
| 356 | } VuVirtqInflightDesc; |
| 357 | |
| 358 | typedef struct VuVirtq { |
| 359 | VuRing vring; |
| 360 | |
| 361 | VuVirtqInflight *inflight; |
| 362 | |
| 363 | VuVirtqInflightDesc *resubmit_list; |
| 364 | |
| 365 | uint16_t resubmit_num; |
| 366 | |
| 367 | uint64_t counter; |
| 368 | |
| 369 | /* Next head to pop */ |
| 370 | uint16_t last_avail_idx; |
| 371 | |
| 372 | /* Last avail_idx read from VQ. */ |
| 373 | uint16_t shadow_avail_idx; |
| 374 | |
| 375 | uint16_t used_idx; |
| 376 | |
| 377 | /* Last used index value we have signalled on */ |
| 378 | uint16_t signalled_used; |
| 379 | |
| 380 | /* Last used index value we have signalled on */ |
| 381 | bool signalled_used_valid; |
| 382 | |
| 383 | /* Notification enabled? */ |
| 384 | bool notification; |
| 385 | |
| 386 | unsigned int inuse; |
| 387 | |
| 388 | vu_queue_handler_cb handler; |
| 389 | |
| 390 | int call_fd; |
| 391 | int kick_fd; |
| 392 | int err_fd; |
| 393 | unsigned int enable; |
| 394 | bool started; |
| 395 | |
| 396 | /* Guest addresses of our ring */ |
| 397 | struct vhost_vring_addr vra; |
| 398 | } VuVirtq; |
| 399 | |
| 400 | enum VuWatchCondtion { |
| 401 | VU_WATCH_IN = POLLIN, |
| 402 | VU_WATCH_OUT = POLLOUT, |
| 403 | VU_WATCH_PRI = POLLPRI, |
| 404 | VU_WATCH_ERR = POLLERR, |
| 405 | VU_WATCH_HUP = POLLHUP, |
| 406 | }; |
| 407 | |
| 408 | typedef void (*vu_panic_cb) (VuDev *dev, const char *err); |
| 409 | typedef void (*vu_watch_cb) (VuDev *dev, int condition, void *data); |
| 410 | typedef void (*vu_set_watch_cb) (VuDev *dev, int fd, int condition, |
| 411 | vu_watch_cb cb, void *data); |
| 412 | typedef void (*vu_remove_watch_cb) (VuDev *dev, int fd); |
| 413 | |
| 414 | typedef struct VuDevInflightInfo { |
| 415 | int fd; |
| 416 | void *addr; |
| 417 | uint64_t size; |
| 418 | } VuDevInflightInfo; |
| 419 | |
| 420 | struct VuDev { |
| 421 | int sock; |
| 422 | uint32_t nregions; |
| 423 | VuDevRegion *regions; |
| 424 | VuVirtq *vq; |
| 425 | VuDevInflightInfo inflight_info; |
| 426 | int log_call_fd; |
| 427 | /* Must be held while using backend_fd */ |
| 428 | pthread_mutex_t backend_mutex; |
| 429 | int backend_fd; |
| 430 | uint64_t log_size; |
| 431 | uint8_t *log_table; |
| 432 | uint64_t features; |
| 433 | uint64_t protocol_features; |
| 434 | bool broken; |
| 435 | uint16_t max_queues; |
| 436 | |
| 437 | /* |
| 438 | * @read_msg: custom method to read vhost-user message |
| 439 | * |
| 440 | * Read data from vhost_user socket fd and fill up |
| 441 | * the passed VhostUserMsg *vmsg struct. |
| 442 | * |
| 443 | * If reading fails, it should close the received set of file |
| 444 | * descriptors as socket message's auxiliary data. |
| 445 | * |
| 446 | * For the details, please refer to vu_message_read in libvhost-user.c |
| 447 | * which will be used by default if not custom method is provided when |
| 448 | * calling vu_init |
| 449 | * |
| 450 | * Returns: true if vhost-user message successfully received, |
| 451 | * otherwise return false. |
| 452 | * |
| 453 | */ |
| 454 | vu_read_msg_cb read_msg; |
| 455 | |
| 456 | /* |
| 457 | * @set_watch: add or update the given fd to the watch set, |
| 458 | * call cb when condition is met. |
| 459 | */ |
| 460 | vu_set_watch_cb set_watch; |
| 461 | |
| 462 | /* @remove_watch: remove the given fd from the watch set */ |
| 463 | vu_remove_watch_cb remove_watch; |
| 464 | |
| 465 | /* |
| 466 | * @panic: encountered an unrecoverable error, you may try to re-initialize |
| 467 | */ |
| 468 | vu_panic_cb panic; |
| 469 | const VuDevIface *iface; |
| 470 | |
| 471 | /* Postcopy data */ |
| 472 | int postcopy_ufd; |
| 473 | bool postcopy_listening; |
| 474 | }; |
| 475 | |
| 476 | typedef struct VuVirtqElement { |
| 477 | unsigned int index; |
| 478 | unsigned int out_num; |
| 479 | unsigned int in_num; |
| 480 | struct iovec *in_sg; |
| 481 | struct iovec *out_sg; |
| 482 | } VuVirtqElement; |
| 483 | |
| 484 | /** |
| 485 | * vu_init: |
| 486 | * @dev: a VuDev context |
| 487 | * @max_queues: maximum number of virtqueues |
| 488 | * @socket: the socket connected to vhost-user frontend |
| 489 | * @panic: a panic callback |
| 490 | * @set_watch: a set_watch callback |
| 491 | * @remove_watch: a remove_watch callback |
| 492 | * @iface: a VuDevIface structure with vhost-user device callbacks |
| 493 | * |
| 494 | * Initializes a VuDev vhost-user context. |
| 495 | * |
| 496 | * Returns: true on success, false on failure. |
| 497 | **/ |
| 498 | bool vu_init(VuDev *dev, |
| 499 | uint16_t max_queues, |
| 500 | int socket, |
| 501 | vu_panic_cb panic, |
| 502 | vu_read_msg_cb read_msg, |
| 503 | vu_set_watch_cb set_watch, |
| 504 | vu_remove_watch_cb remove_watch, |
| 505 | const VuDevIface *iface); |
| 506 | |
| 507 | |
| 508 | /** |
| 509 | * vu_deinit: |
| 510 | * @dev: a VuDev context |
| 511 | * |
| 512 | * Cleans up the VuDev context |
| 513 | */ |
| 514 | void vu_deinit(VuDev *dev); |
| 515 | |
| 516 | |
| 517 | /** |
| 518 | * vu_request_to_string: return string for vhost message request |
| 519 | * @req: VhostUserMsg request |
| 520 | * |
| 521 | * Returns a const string, do not free. |
| 522 | */ |
| 523 | const char *vu_request_to_string(unsigned int req); |
| 524 | |
| 525 | /** |
| 526 | * vu_dispatch: |
| 527 | * @dev: a VuDev context |
| 528 | * |
| 529 | * Process one vhost-user message. |
| 530 | * |
| 531 | * Returns: TRUE on success, FALSE on failure. |
| 532 | */ |
| 533 | bool vu_dispatch(VuDev *dev); |
| 534 | |
| 535 | /** |
| 536 | * vu_gpa_to_va: |
| 537 | * @dev: a VuDev context |
| 538 | * @plen: guest memory size |
| 539 | * @guest_addr: guest address |
| 540 | * |
| 541 | * Translate a guest address to a pointer. Returns NULL on failure. |
| 542 | */ |
| 543 | void *vu_gpa_to_va(VuDev *dev, uint64_t *plen, uint64_t guest_addr); |
| 544 | |
| 545 | /** |
| 546 | * vu_get_queue: |
| 547 | * @dev: a VuDev context |
| 548 | * @qidx: queue index |
| 549 | * |
| 550 | * Returns the queue number @qidx. |
| 551 | */ |
| 552 | VuVirtq *vu_get_queue(VuDev *dev, int qidx); |
| 553 | |
| 554 | /** |
| 555 | * vu_set_queue_handler: |
| 556 | * @dev: a VuDev context |
| 557 | * @vq: a VuVirtq queue |
| 558 | * @handler: the queue handler callback |
| 559 | * |
| 560 | * Set the queue handler. This function may be called several times |
| 561 | * for the same queue. If called with NULL @handler, the handler is |
| 562 | * removed. |
| 563 | */ |
| 564 | void vu_set_queue_handler(VuDev *dev, VuVirtq *vq, |
| 565 | vu_queue_handler_cb handler); |
| 566 | |
| 567 | /** |
| 568 | * vu_set_queue_host_notifier: |
| 569 | * @dev: a VuDev context |
| 570 | * @vq: a VuVirtq queue |
| 571 | * @fd: a file descriptor |
| 572 | * @size: host page size |
| 573 | * @offset: notifier offset in @fd file |
| 574 | * |
| 575 | * Set queue's host notifier. This function may be called several |
| 576 | * times for the same queue. If called with -1 @fd, the notifier |
| 577 | * is removed. |
| 578 | */ |
| 579 | bool vu_set_queue_host_notifier(VuDev *dev, VuVirtq *vq, int fd, |
| 580 | int size, int offset); |
| 581 | |
| 582 | /** |
| 583 | * vu_lookup_shared_object: |
| 584 | * @dev: a VuDev context |
| 585 | * @uuid: UUID of the shared object |
| 586 | * @dmabuf_fd: output dma-buf file descriptor |
| 587 | * |
| 588 | * Lookup for a virtio shared object (i.e., dma-buf fd) associated with the |
| 589 | * received UUID. Result, if found, is stored in the dmabuf_fd argument. |
| 590 | * |
| 591 | * Returns: whether the virtio object was found. |
| 592 | */ |
| 593 | bool vu_lookup_shared_object(VuDev *dev, unsigned char uuid[UUID_LEN], |
| 594 | int *dmabuf_fd); |
| 595 | |
| 596 | /** |
| 597 | * vu_add_shared_object: |
| 598 | * @dev: a VuDev context |
| 599 | * @uuid: UUID of the shared object |
| 600 | * |
| 601 | * Registers this back-end as the exporter for the object associated with |
| 602 | * the received UUID. |
| 603 | * |
| 604 | * Returns: TRUE on success, FALSE on failure. |
| 605 | */ |
| 606 | bool vu_add_shared_object(VuDev *dev, unsigned char uuid[UUID_LEN]); |
| 607 | |
| 608 | /** |
| 609 | * vu_rm_shared_object: |
| 610 | * @dev: a VuDev context |
| 611 | * @uuid: UUID of the shared object |
| 612 | * |
| 613 | * Removes a shared object entry (i.e., back-end entry) associated with the |
| 614 | * received UUID key from the hash table. |
| 615 | * |
| 616 | * Returns: TRUE on success, FALSE on failure. |
| 617 | */ |
| 618 | bool vu_rm_shared_object(VuDev *dev, unsigned char uuid[UUID_LEN]); |
| 619 | |
| 620 | /** |
| 621 | * vu_shmem_map: |
| 622 | * @dev: a VuDev context |
| 623 | * @shmid: VIRTIO Shared Memory Region ID |
| 624 | * @fd_offset: File offset |
| 625 | * @shm_offset: Offset within the VIRTIO Shared Memory Region |
| 626 | * @len: Size of the mapping |
| 627 | * @flags: Flags for the mmap operation |
| 628 | * @fd: A file descriptor |
| 629 | * |
| 630 | * Advertises a new mapping to be made in a given VIRTIO Shared Memory Region. |
| 631 | * |
| 632 | * Returns: TRUE on success, FALSE on failure. |
| 633 | */ |
| 634 | bool vu_shmem_map(VuDev *dev, uint8_t shmid, uint64_t fd_offset, |
| 635 | uint64_t shm_offset, uint64_t len, uint64_t flags, int fd); |
| 636 | |
| 637 | /** |
| 638 | * vu_shmem_unmap: |
| 639 | * @dev: a VuDev context |
| 640 | * @shmid: VIRTIO Shared Memory Region ID |
| 641 | * @fd_offset: File offset |
| 642 | * @len: Size of the mapping |
| 643 | * |
| 644 | * The front-end un-mmaps a given range in the VIRTIO Shared Memory Region |
| 645 | * with the requested `shmid`. |
| 646 | * |
| 647 | * Returns: TRUE on success, FALSE on failure. |
| 648 | */ |
| 649 | bool vu_shmem_unmap(VuDev *dev, uint8_t shmid, uint64_t shm_offset, |
| 650 | uint64_t len); |
| 651 | |
| 652 | /** |
| 653 | * vu_queue_set_notification: |
| 654 | * @dev: a VuDev context |
| 655 | * @vq: a VuVirtq queue |
| 656 | * @enable: state |
| 657 | * |
| 658 | * Set whether the queue notifies (via event index or interrupt) |
| 659 | */ |
| 660 | void vu_queue_set_notification(VuDev *dev, VuVirtq *vq, int enable); |
| 661 | |
| 662 | /** |
| 663 | * vu_queue_enabled: |
| 664 | * @dev: a VuDev context |
| 665 | * @vq: a VuVirtq queue |
| 666 | * |
| 667 | * Returns: whether the queue is enabled. |
| 668 | */ |
| 669 | bool vu_queue_enabled(VuDev *dev, VuVirtq *vq); |
| 670 | |
| 671 | /** |
| 672 | * vu_queue_started: |
| 673 | * @dev: a VuDev context |
| 674 | * @vq: a VuVirtq queue |
| 675 | * |
| 676 | * Returns: whether the queue is started. |
| 677 | */ |
| 678 | bool vu_queue_started(const VuDev *dev, const VuVirtq *vq); |
| 679 | |
| 680 | /** |
| 681 | * vu_queue_empty: |
| 682 | * @dev: a VuDev context |
| 683 | * @vq: a VuVirtq queue |
| 684 | * |
| 685 | * Returns: true if the queue is empty or not ready. |
| 686 | */ |
| 687 | bool vu_queue_empty(VuDev *dev, VuVirtq *vq); |
| 688 | |
| 689 | /** |
| 690 | * vu_queue_notify: |
| 691 | * @dev: a VuDev context |
| 692 | * @vq: a VuVirtq queue |
| 693 | * |
| 694 | * Request to notify the queue via callfd (skipped if unnecessary) |
| 695 | */ |
| 696 | void vu_queue_notify(VuDev *dev, VuVirtq *vq); |
| 697 | |
| 698 | void vu_config_change_msg(VuDev *dev); |
| 699 | |
| 700 | /** |
| 701 | * vu_queue_notify_sync: |
| 702 | * @dev: a VuDev context |
| 703 | * @vq: a VuVirtq queue |
| 704 | * |
| 705 | * Request to notify the queue via callfd (skipped if unnecessary) |
| 706 | * or sync message if possible. |
| 707 | */ |
| 708 | void vu_queue_notify_sync(VuDev *dev, VuVirtq *vq); |
| 709 | |
| 710 | /** |
| 711 | * vu_queue_pop: |
| 712 | * @dev: a VuDev context |
| 713 | * @vq: a VuVirtq queue |
| 714 | * @sz: the size of struct to return (must be >= VuVirtqElement) |
| 715 | * |
| 716 | * Returns: a VuVirtqElement filled from the queue or NULL. The |
| 717 | * returned element must be free()-d by the caller. |
| 718 | */ |
| 719 | void *vu_queue_pop(VuDev *dev, VuVirtq *vq, size_t sz); |
| 720 | |
| 721 | |
| 722 | /** |
| 723 | * vu_queue_unpop: |
| 724 | * @dev: a VuDev context |
| 725 | * @vq: a VuVirtq queue |
| 726 | * @elem: The #VuVirtqElement |
| 727 | * @len: number of bytes written |
| 728 | * |
| 729 | * Pretend the most recent element wasn't popped from the virtqueue. The next |
| 730 | * call to vu_queue_pop() will refetch the element. |
| 731 | */ |
| 732 | void vu_queue_unpop(VuDev *dev, VuVirtq *vq, VuVirtqElement *elem, |
| 733 | size_t len); |
| 734 | |
| 735 | /** |
| 736 | * vu_queue_rewind: |
| 737 | * @dev: a VuDev context |
| 738 | * @vq: a VuVirtq queue |
| 739 | * @num: number of elements to push back |
| 740 | * |
| 741 | * Pretend that elements weren't popped from the virtqueue. The next |
| 742 | * virtqueue_pop() will refetch the oldest element. |
| 743 | * |
| 744 | * Returns: true on success, false if @num is greater than the number of in use |
| 745 | * elements. |
| 746 | */ |
| 747 | bool vu_queue_rewind(VuDev *dev, VuVirtq *vq, unsigned int num); |
| 748 | |
| 749 | /** |
| 750 | * vu_queue_fill: |
| 751 | * @dev: a VuDev context |
| 752 | * @vq: a VuVirtq queue |
| 753 | * @elem: a VuVirtqElement |
| 754 | * @len: length in bytes to write |
| 755 | * @idx: optional offset for the used ring index (0 in general) |
| 756 | * |
| 757 | * Fill the used ring with @elem element. |
| 758 | */ |
| 759 | void vu_queue_fill(VuDev *dev, VuVirtq *vq, |
| 760 | const VuVirtqElement *elem, |
| 761 | unsigned int len, unsigned int idx); |
| 762 | |
| 763 | /** |
| 764 | * vu_queue_push: |
| 765 | * @dev: a VuDev context |
| 766 | * @vq: a VuVirtq queue |
| 767 | * @elem: a VuVirtqElement |
| 768 | * @len: length in bytes to write |
| 769 | * |
| 770 | * Helper that combines vu_queue_fill() with a vu_queue_flush(). |
| 771 | */ |
| 772 | void vu_queue_push(VuDev *dev, VuVirtq *vq, |
| 773 | const VuVirtqElement *elem, unsigned int len); |
| 774 | |
| 775 | /** |
| 776 | * vu_queue_flush: |
| 777 | * @dev: a VuDev context |
| 778 | * @vq: a VuVirtq queue |
| 779 | * @num: number of elements to flush |
| 780 | * |
| 781 | * Mark the last number of elements as done (used.idx is updated by |
| 782 | * num elements). |
| 783 | */ |
| 784 | void vu_queue_flush(VuDev *dev, VuVirtq *vq, unsigned int num); |
| 785 | |
| 786 | /** |
| 787 | * vu_queue_get_avail_bytes: |
| 788 | * @dev: a VuDev context |
| 789 | * @vq: a VuVirtq queue |
| 790 | * @in_bytes: in bytes |
| 791 | * @out_bytes: out bytes |
| 792 | * @max_in_bytes: stop counting after max_in_bytes |
| 793 | * @max_out_bytes: stop counting after max_out_bytes |
| 794 | * |
| 795 | * Count the number of available bytes, up to max_in_bytes/max_out_bytes. |
| 796 | */ |
| 797 | void vu_queue_get_avail_bytes(VuDev *vdev, VuVirtq *vq, unsigned int *in_bytes, |
| 798 | unsigned int *out_bytes, |
| 799 | unsigned max_in_bytes, unsigned max_out_bytes); |
| 800 | |
| 801 | /** |
| 802 | * vu_queue_avail_bytes: |
| 803 | * @dev: a VuDev context |
| 804 | * @vq: a VuVirtq queue |
| 805 | * @in_bytes: expected in bytes |
| 806 | * @out_bytes: expected out bytes |
| 807 | * |
| 808 | * Returns: true if in_bytes <= in_total && out_bytes <= out_total |
| 809 | */ |
| 810 | bool vu_queue_avail_bytes(VuDev *dev, VuVirtq *vq, unsigned int in_bytes, |
| 811 | unsigned int out_bytes); |
| 812 | |
| 813 | #endif /* LIBVHOST_USER_H */ |