1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2010-2017 Intel Corporation 3 */ 4 5 #ifndef _RTE_VHOST_H_ 6 #define _RTE_VHOST_H_ 7 8 /** 9 * @file 10 * Interface to vhost-user 11 */ 12 13 #include <stdint.h> 14 #include <sys/eventfd.h> 15 16 #include <rte_memory.h> 17 #include <rte_mempool.h> 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /* These are not C++-aware. */ 24 #include <linux/vhost.h> 25 #include <linux/virtio_ring.h> 26 27 #define RTE_VHOST_USER_CLIENT (1ULL << 0) 28 #define RTE_VHOST_USER_NO_RECONNECT (1ULL << 1) 29 #define RTE_VHOST_USER_DEQUEUE_ZERO_COPY (1ULL << 2) 30 #define RTE_VHOST_USER_IOMMU_SUPPORT (1ULL << 3) 31 #define RTE_VHOST_USER_POSTCOPY_SUPPORT (1ULL << 4) 32 33 /** Protocol features. */ 34 #ifndef VHOST_USER_PROTOCOL_F_MQ 35 #define VHOST_USER_PROTOCOL_F_MQ 0 36 #endif 37 38 #ifndef VHOST_USER_PROTOCOL_F_LOG_SHMFD 39 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD 1 40 #endif 41 42 #ifndef VHOST_USER_PROTOCOL_F_RARP 43 #define VHOST_USER_PROTOCOL_F_RARP 2 44 #endif 45 46 #ifndef VHOST_USER_PROTOCOL_F_REPLY_ACK 47 #define VHOST_USER_PROTOCOL_F_REPLY_ACK 3 48 #endif 49 50 #ifndef VHOST_USER_PROTOCOL_F_NET_MTU 51 #define VHOST_USER_PROTOCOL_F_NET_MTU 4 52 #endif 53 54 #ifndef VHOST_USER_PROTOCOL_F_SLAVE_REQ 55 #define VHOST_USER_PROTOCOL_F_SLAVE_REQ 5 56 #endif 57 58 #ifndef VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 59 #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7 60 #endif 61 62 #ifndef VHOST_USER_PROTOCOL_F_PAGEFAULT 63 #define VHOST_USER_PROTOCOL_F_PAGEFAULT 8 64 #endif 65 66 #ifndef VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD 67 #define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD 10 68 #endif 69 70 #ifndef VHOST_USER_PROTOCOL_F_HOST_NOTIFIER 71 #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER 11 72 #endif 73 74 /** Indicate whether protocol features negotiation is supported. */ 75 #ifndef VHOST_USER_F_PROTOCOL_FEATURES 76 #define VHOST_USER_F_PROTOCOL_FEATURES 30 77 #endif 78 79 /** 80 * Information relating to memory regions including offsets to 81 * addresses in QEMUs memory file. 82 */ 83 struct rte_vhost_mem_region { 84 uint64_t guest_phys_addr; 85 uint64_t guest_user_addr; 86 uint64_t host_user_addr; 87 uint64_t size; 88 void *mmap_addr; 89 uint64_t mmap_size; 90 int fd; 91 }; 92 93 /** 94 * Memory structure includes region and mapping information. 95 */ 96 struct rte_vhost_memory { 97 uint32_t nregions; 98 struct rte_vhost_mem_region regions[]; 99 }; 100 101 struct rte_vhost_vring { 102 struct vring_desc *desc; 103 struct vring_avail *avail; 104 struct vring_used *used; 105 uint64_t log_guest_addr; 106 107 /** Deprecated, use rte_vhost_vring_call() instead. */ 108 int callfd; 109 110 int kickfd; 111 uint16_t size; 112 }; 113 114 /** 115 * Device and vring operations. 116 */ 117 struct vhost_device_ops { 118 int (*new_device)(int vid); /**< Add device. */ 119 void (*destroy_device)(int vid); /**< Remove device. */ 120 121 int (*vring_state_changed)(int vid, uint16_t queue_id, int enable); /**< triggered when a vring is enabled or disabled */ 122 123 /** 124 * Features could be changed after the feature negotiation. 125 * For example, VHOST_F_LOG_ALL will be set/cleared at the 126 * start/end of live migration, respectively. This callback 127 * is used to inform the application on such change. 128 */ 129 int (*features_changed)(int vid, uint64_t features); 130 131 int (*new_connection)(int vid); 132 void (*destroy_connection)(int vid); 133 134 void *reserved[2]; /**< Reserved for future extension */ 135 }; 136 137 /** 138 * Convert guest physical address to host virtual address 139 * 140 * This function is deprecated because unsafe. 141 * New rte_vhost_va_from_guest_pa() should be used instead to ensure 142 * guest physical ranges are fully and contiguously mapped into 143 * process virtual address space. 144 * 145 * @param mem 146 * the guest memory regions 147 * @param gpa 148 * the guest physical address for querying 149 * @return 150 * the host virtual address on success, 0 on failure 151 */ 152 __rte_deprecated 153 static __rte_always_inline uint64_t 154 rte_vhost_gpa_to_vva(struct rte_vhost_memory *mem, uint64_t gpa) 155 { 156 struct rte_vhost_mem_region *reg; 157 uint32_t i; 158 159 for (i = 0; i < mem->nregions; i++) { 160 reg = &mem->regions[i]; 161 if (gpa >= reg->guest_phys_addr && 162 gpa < reg->guest_phys_addr + reg->size) { 163 return gpa - reg->guest_phys_addr + 164 reg->host_user_addr; 165 } 166 } 167 168 return 0; 169 } 170 171 /** 172 * Convert guest physical address to host virtual address safely 173 * 174 * This variant of rte_vhost_gpa_to_vva() takes care all the 175 * requested length is mapped and contiguous in process address 176 * space. 177 * 178 * @param mem 179 * the guest memory regions 180 * @param gpa 181 * the guest physical address for querying 182 * @param len 183 * the size of the requested area to map, updated with actual size mapped 184 * @return 185 * the host virtual address on success, 0 on failure 186 */ 187 static __rte_always_inline uint64_t 188 rte_vhost_va_from_guest_pa(struct rte_vhost_memory *mem, 189 uint64_t gpa, uint64_t *len) 190 { 191 struct rte_vhost_mem_region *r; 192 uint32_t i; 193 194 for (i = 0; i < mem->nregions; i++) { 195 r = &mem->regions[i]; 196 if (gpa >= r->guest_phys_addr && 197 gpa < r->guest_phys_addr + r->size) { 198 199 if (unlikely(*len > r->guest_phys_addr + r->size - gpa)) 200 *len = r->guest_phys_addr + r->size - gpa; 201 202 return gpa - r->guest_phys_addr + 203 r->host_user_addr; 204 } 205 } 206 *len = 0; 207 208 return 0; 209 } 210 211 #define RTE_VHOST_NEED_LOG(features) ((features) & (1ULL << VHOST_F_LOG_ALL)) 212 213 /** 214 * Log the memory write start with given address. 215 * 216 * This function only need be invoked when the live migration starts. 217 * Therefore, we won't need call it at all in the most of time. For 218 * making the performance impact be minimum, it's suggested to do a 219 * check before calling it: 220 * 221 * if (unlikely(RTE_VHOST_NEED_LOG(features))) 222 * rte_vhost_log_write(vid, addr, len); 223 * 224 * @param vid 225 * vhost device ID 226 * @param addr 227 * the starting address for write 228 * @param len 229 * the length to write 230 */ 231 void rte_vhost_log_write(int vid, uint64_t addr, uint64_t len); 232 233 /** 234 * Log the used ring update start at given offset. 235 * 236 * Same as rte_vhost_log_write, it's suggested to do a check before 237 * calling it: 238 * 239 * if (unlikely(RTE_VHOST_NEED_LOG(features))) 240 * rte_vhost_log_used_vring(vid, vring_idx, offset, len); 241 * 242 * @param vid 243 * vhost device ID 244 * @param vring_idx 245 * the vring index 246 * @param offset 247 * the offset inside the used ring 248 * @param len 249 * the length to write 250 */ 251 void rte_vhost_log_used_vring(int vid, uint16_t vring_idx, 252 uint64_t offset, uint64_t len); 253 254 int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable); 255 256 /** 257 * Register vhost driver. path could be different for multiple 258 * instance support. 259 */ 260 int rte_vhost_driver_register(const char *path, uint64_t flags); 261 262 /* Unregister vhost driver. This is only meaningful to vhost user. */ 263 int rte_vhost_driver_unregister(const char *path); 264 265 /** 266 * Set the vdpa device id, enforce single connection per socket 267 * 268 * @param path 269 * The vhost-user socket file path 270 * @param did 271 * Device id 272 * @return 273 * 0 on success, -1 on failure 274 */ 275 int __rte_experimental 276 rte_vhost_driver_attach_vdpa_device(const char *path, int did); 277 278 /** 279 * Unset the vdpa device id 280 * 281 * @param path 282 * The vhost-user socket file path 283 * @return 284 * 0 on success, -1 on failure 285 */ 286 int __rte_experimental 287 rte_vhost_driver_detach_vdpa_device(const char *path); 288 289 /** 290 * Get the device id 291 * 292 * @param path 293 * The vhost-user socket file path 294 * @return 295 * Device id, -1 on failure 296 */ 297 int __rte_experimental 298 rte_vhost_driver_get_vdpa_device_id(const char *path); 299 300 /** 301 * Set the feature bits the vhost-user driver supports. 302 * 303 * @param path 304 * The vhost-user socket file path 305 * @param features 306 * Supported features 307 * @return 308 * 0 on success, -1 on failure 309 */ 310 int rte_vhost_driver_set_features(const char *path, uint64_t features); 311 312 /** 313 * Enable vhost-user driver features. 314 * 315 * Note that 316 * - the param features should be a subset of the feature bits provided 317 * by rte_vhost_driver_set_features(). 318 * - it must be invoked before vhost-user negotiation starts. 319 * 320 * @param path 321 * The vhost-user socket file path 322 * @param features 323 * Features to enable 324 * @return 325 * 0 on success, -1 on failure 326 */ 327 int rte_vhost_driver_enable_features(const char *path, uint64_t features); 328 329 /** 330 * Disable vhost-user driver features. 331 * 332 * The two notes at rte_vhost_driver_enable_features() also apply here. 333 * 334 * @param path 335 * The vhost-user socket file path 336 * @param features 337 * Features to disable 338 * @return 339 * 0 on success, -1 on failure 340 */ 341 int rte_vhost_driver_disable_features(const char *path, uint64_t features); 342 343 /** 344 * Get the feature bits before feature negotiation. 345 * 346 * @param path 347 * The vhost-user socket file path 348 * @param features 349 * A pointer to store the queried feature bits 350 * @return 351 * 0 on success, -1 on failure 352 */ 353 int rte_vhost_driver_get_features(const char *path, uint64_t *features); 354 355 /** 356 * Get the protocol feature bits before feature negotiation. 357 * 358 * @param path 359 * The vhost-user socket file path 360 * @param protocol_features 361 * A pointer to store the queried protocol feature bits 362 * @return 363 * 0 on success, -1 on failure 364 */ 365 int __rte_experimental 366 rte_vhost_driver_get_protocol_features(const char *path, 367 uint64_t *protocol_features); 368 369 /** 370 * Get the queue number bits before feature negotiation. 371 * 372 * @param path 373 * The vhost-user socket file path 374 * @param queue_num 375 * A pointer to store the queried queue number bits 376 * @return 377 * 0 on success, -1 on failure 378 */ 379 int __rte_experimental 380 rte_vhost_driver_get_queue_num(const char *path, uint32_t *queue_num); 381 382 /** 383 * Get the feature bits after negotiation 384 * 385 * @param vid 386 * Vhost device ID 387 * @param features 388 * A pointer to store the queried feature bits 389 * @return 390 * 0 on success, -1 on failure 391 */ 392 int rte_vhost_get_negotiated_features(int vid, uint64_t *features); 393 394 /* Register callbacks. */ 395 int rte_vhost_driver_callback_register(const char *path, 396 struct vhost_device_ops const * const ops); 397 398 /** 399 * 400 * Start the vhost-user driver. 401 * 402 * This function triggers the vhost-user negotiation. 403 * 404 * @param path 405 * The vhost-user socket file path 406 * @return 407 * 0 on success, -1 on failure 408 */ 409 int rte_vhost_driver_start(const char *path); 410 411 /** 412 * Get the MTU value of the device if set in QEMU. 413 * 414 * @param vid 415 * virtio-net device ID 416 * @param mtu 417 * The variable to store the MTU value 418 * 419 * @return 420 * 0: success 421 * -EAGAIN: device not yet started 422 * -ENOTSUP: device does not support MTU feature 423 */ 424 int rte_vhost_get_mtu(int vid, uint16_t *mtu); 425 426 /** 427 * Get the numa node from which the virtio net device's memory 428 * is allocated. 429 * 430 * @param vid 431 * vhost device ID 432 * 433 * @return 434 * The numa node, -1 on failure 435 */ 436 int rte_vhost_get_numa_node(int vid); 437 438 /** 439 * @deprecated 440 * Get the number of queues the device supports. 441 * 442 * Note this function is deprecated, as it returns a queue pair number, 443 * which is vhost specific. Instead, rte_vhost_get_vring_num should 444 * be used. 445 * 446 * @param vid 447 * vhost device ID 448 * 449 * @return 450 * The number of queues, 0 on failure 451 */ 452 __rte_deprecated 453 uint32_t rte_vhost_get_queue_num(int vid); 454 455 /** 456 * Get the number of vrings the device supports. 457 * 458 * @param vid 459 * vhost device ID 460 * 461 * @return 462 * The number of vrings, 0 on failure 463 */ 464 uint16_t rte_vhost_get_vring_num(int vid); 465 466 /** 467 * Get the virtio net device's ifname, which is the vhost-user socket 468 * file path. 469 * 470 * @param vid 471 * vhost device ID 472 * @param buf 473 * The buffer to stored the queried ifname 474 * @param len 475 * The length of buf 476 * 477 * @return 478 * 0 on success, -1 on failure 479 */ 480 int rte_vhost_get_ifname(int vid, char *buf, size_t len); 481 482 /** 483 * Get how many avail entries are left in the queue 484 * 485 * @param vid 486 * vhost device ID 487 * @param queue_id 488 * virtio queue index 489 * 490 * @return 491 * num of avail entries left 492 */ 493 uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id); 494 495 struct rte_mbuf; 496 struct rte_mempool; 497 /** 498 * This function adds buffers to the virtio devices RX virtqueue. Buffers can 499 * be received from the physical port or from another virtual device. A packet 500 * count is returned to indicate the number of packets that were successfully 501 * added to the RX queue. 502 * @param vid 503 * vhost device ID 504 * @param queue_id 505 * virtio queue index in mq case 506 * @param pkts 507 * array to contain packets to be enqueued 508 * @param count 509 * packets num to be enqueued 510 * @return 511 * num of packets enqueued 512 */ 513 uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id, 514 struct rte_mbuf **pkts, uint16_t count); 515 516 /** 517 * This function gets guest buffers from the virtio device TX virtqueue, 518 * construct host mbufs, copies guest buffer content to host mbufs and 519 * store them in pkts to be processed. 520 * @param vid 521 * vhost device ID 522 * @param queue_id 523 * virtio queue index in mq case 524 * @param mbuf_pool 525 * mbuf_pool where host mbuf is allocated. 526 * @param pkts 527 * array to contain packets to be dequeued 528 * @param count 529 * packets num to be dequeued 530 * @return 531 * num of packets dequeued 532 */ 533 uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id, 534 struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count); 535 536 /** 537 * Get guest mem table: a list of memory regions. 538 * 539 * An rte_vhost_vhost_memory object will be allocated internally, to hold the 540 * guest memory regions. Application should free it at destroy_device() 541 * callback. 542 * 543 * @param vid 544 * vhost device ID 545 * @param mem 546 * To store the returned mem regions 547 * @return 548 * 0 on success, -1 on failure 549 */ 550 int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem); 551 552 /** 553 * Get guest vring info, including the vring address, vring size, etc. 554 * 555 * @param vid 556 * vhost device ID 557 * @param vring_idx 558 * vring index 559 * @param vring 560 * the structure to hold the requested vring info 561 * @return 562 * 0 on success, -1 on failure 563 */ 564 int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx, 565 struct rte_vhost_vring *vring); 566 567 /** 568 * Notify the guest that used descriptors have been added to the vring. This 569 * function acts as a memory barrier. 570 * 571 * @param vid 572 * vhost device ID 573 * @param vring_idx 574 * vring index 575 * @return 576 * 0 on success, -1 on failure 577 */ 578 int rte_vhost_vring_call(int vid, uint16_t vring_idx); 579 580 /** 581 * Get vhost RX queue avail count. 582 * 583 * @param vid 584 * vhost device ID 585 * @param qid 586 * virtio queue index in mq case 587 * @return 588 * num of desc available 589 */ 590 uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid); 591 592 /** 593 * Get log base and log size of the vhost device 594 * 595 * @param vid 596 * vhost device ID 597 * @param log_base 598 * vhost log base 599 * @param log_size 600 * vhost log size 601 * @return 602 * 0 on success, -1 on failure 603 */ 604 int __rte_experimental 605 rte_vhost_get_log_base(int vid, uint64_t *log_base, uint64_t *log_size); 606 607 /** 608 * Get last_avail/used_idx of the vhost virtqueue 609 * 610 * @param vid 611 * vhost device ID 612 * @param queue_id 613 * vhost queue index 614 * @param last_avail_idx 615 * vhost last_avail_idx to get 616 * @param last_used_idx 617 * vhost last_used_idx to get 618 * @return 619 * 0 on success, -1 on failure 620 */ 621 int __rte_experimental 622 rte_vhost_get_vring_base(int vid, uint16_t queue_id, 623 uint16_t *last_avail_idx, uint16_t *last_used_idx); 624 625 /** 626 * Set last_avail/used_idx of the vhost virtqueue 627 * 628 * @param vid 629 * vhost device ID 630 * @param queue_id 631 * vhost queue index 632 * @param last_avail_idx 633 * last_avail_idx to set 634 * @param last_used_idx 635 * last_used_idx to set 636 * @return 637 * 0 on success, -1 on failure 638 */ 639 int __rte_experimental 640 rte_vhost_set_vring_base(int vid, uint16_t queue_id, 641 uint16_t last_avail_idx, uint16_t last_used_idx); 642 643 /** 644 * Get vdpa device id for vhost device. 645 * 646 * @param vid 647 * vhost device id 648 * @return 649 * device id 650 */ 651 int __rte_experimental 652 rte_vhost_get_vdpa_device_id(int vid); 653 654 #ifdef __cplusplus 655 } 656 #endif 657 658 #endif /* _RTE_VHOST_H_ */ 659