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