lib/vhost/rte_vhost.h

   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 <stdbool.h>
  14 #include <stdint.h>
  15 #include <sys/eventfd.h>
  16
  17 #include <rte_memory.h>
  18 #include <rte_mempool.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /* These are not C++-aware. */
  25 #include <linux/vhost.h>
  26 #include <linux/virtio_ring.h>
  27 #include <linux/virtio_net.h>
  28
  29 #define RTE_VHOST_USER_CLIENT           (1ULL << 0)
  30 #define RTE_VHOST_USER_NO_RECONNECT     (1ULL << 1)
  31 #define RTE_VHOST_USER_RESERVED_1       (1ULL << 2)
  32 #define RTE_VHOST_USER_IOMMU_SUPPORT    (1ULL << 3)
  33 #define RTE_VHOST_USER_POSTCOPY_SUPPORT         (1ULL << 4)
  34 /* support mbuf with external buffer attached */
  35 #define RTE_VHOST_USER_EXTBUF_SUPPORT   (1ULL << 5)
  36 /* support only linear buffers (no chained mbufs) */
  37 #define RTE_VHOST_USER_LINEARBUF_SUPPORT        (1ULL << 6)
  38 #define RTE_VHOST_USER_ASYNC_COPY       (1ULL << 7)
  39 #define RTE_VHOST_USER_NET_COMPLIANT_OL_FLAGS   (1ULL << 8)
  40
  41 /* Features. */
  42 #ifndef VIRTIO_NET_F_GUEST_ANNOUNCE
  43  #define VIRTIO_NET_F_GUEST_ANNOUNCE 21
  44 #endif
  45
  46 #ifndef VIRTIO_NET_F_MQ
  47  #define VIRTIO_NET_F_MQ                22
  48 #endif
  49
  50 #ifndef VIRTIO_NET_F_MTU
  51  #define VIRTIO_NET_F_MTU 3
  52 #endif
  53
  54 #ifndef VIRTIO_F_ANY_LAYOUT
  55  #define VIRTIO_F_ANY_LAYOUT            27
  56 #endif
  57
  58 /** Protocol features. */
  59 #ifndef VHOST_USER_PROTOCOL_F_MQ
  60 #define VHOST_USER_PROTOCOL_F_MQ        0
  61 #endif
  62
  63 #ifndef VHOST_USER_PROTOCOL_F_LOG_SHMFD
  64 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD 1
  65 #endif
  66
  67 #ifndef VHOST_USER_PROTOCOL_F_RARP
  68 #define VHOST_USER_PROTOCOL_F_RARP      2
  69 #endif
  70
  71 #ifndef VHOST_USER_PROTOCOL_F_REPLY_ACK
  72 #define VHOST_USER_PROTOCOL_F_REPLY_ACK 3
  73 #endif
  74
  75 #ifndef VHOST_USER_PROTOCOL_F_NET_MTU
  76 #define VHOST_USER_PROTOCOL_F_NET_MTU   4
  77 #endif
  78
  79 #ifndef VHOST_USER_PROTOCOL_F_SLAVE_REQ
  80 #define VHOST_USER_PROTOCOL_F_SLAVE_REQ 5
  81 #endif
  82
  83 #ifndef VHOST_USER_PROTOCOL_F_CRYPTO_SESSION
  84 #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7
  85 #endif
  86
  87 #ifndef VHOST_USER_PROTOCOL_F_PAGEFAULT
  88 #define VHOST_USER_PROTOCOL_F_PAGEFAULT 8
  89 #endif
  90
  91 #ifndef VHOST_USER_PROTOCOL_F_CONFIG
  92 #define VHOST_USER_PROTOCOL_F_CONFIG 9
  93 #endif
  94
  95 #ifndef VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD
  96 #define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD 10
  97 #endif
  98
  99 #ifndef VHOST_USER_PROTOCOL_F_HOST_NOTIFIER
 100 #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER 11
 101 #endif
 102
 103 #ifndef VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD
 104 #define VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD 12
 105 #endif
 106
 107 #ifndef VHOST_USER_PROTOCOL_F_STATUS
 108 #define VHOST_USER_PROTOCOL_F_STATUS 16
 109 #endif
 110
 111 /** Indicate whether protocol features negotiation is supported. */
 112 #ifndef VHOST_USER_F_PROTOCOL_FEATURES
 113 #define VHOST_USER_F_PROTOCOL_FEATURES  30
 114 #endif
 115
 116 struct rte_vdpa_device;
 117
 118 /**
 119  * Information relating to memory regions including offsets to
 120  * addresses in QEMUs memory file.
 121  */
 122 struct rte_vhost_mem_region {
 123         uint64_t guest_phys_addr;
 124         uint64_t guest_user_addr;
 125         uint64_t host_user_addr;
 126         uint64_t size;
 127         void     *mmap_addr;
 128         uint64_t mmap_size;
 129         int fd;
 130 };
 131
 132 /**
 133  * Memory structure includes region and mapping information.
 134  */
 135 struct rte_vhost_memory {
 136         uint32_t nregions;
 137         struct rte_vhost_mem_region regions[];
 138 };
 139
 140 struct rte_vhost_inflight_desc_split {
 141         uint8_t inflight;
 142         uint8_t padding[5];
 143         uint16_t next;
 144         uint64_t counter;
 145 };
 146
 147 struct rte_vhost_inflight_info_split {
 148         uint64_t features;
 149         uint16_t version;
 150         uint16_t desc_num;
 151         uint16_t last_inflight_io;
 152         uint16_t used_idx;
 153         struct rte_vhost_inflight_desc_split desc[0];
 154 };
 155
 156 struct rte_vhost_inflight_desc_packed {
 157         uint8_t inflight;
 158         uint8_t padding;
 159         uint16_t next;
 160         uint16_t last;
 161         uint16_t num;
 162         uint64_t counter;
 163         uint16_t id;
 164         uint16_t flags;
 165         uint32_t len;
 166         uint64_t addr;
 167 };
 168
 169 struct rte_vhost_inflight_info_packed {
 170         uint64_t features;
 171         uint16_t version;
 172         uint16_t desc_num;
 173         uint16_t free_head;
 174         uint16_t old_free_head;
 175         uint16_t used_idx;
 176         uint16_t old_used_idx;
 177         uint8_t used_wrap_counter;
 178         uint8_t old_used_wrap_counter;
 179         uint8_t padding[7];
 180         struct rte_vhost_inflight_desc_packed desc[0];
 181 };
 182
 183 struct rte_vhost_resubmit_desc {
 184         uint16_t index;
 185         uint64_t counter;
 186 };
 187
 188 struct rte_vhost_resubmit_info {
 189         struct rte_vhost_resubmit_desc *resubmit_list;
 190         uint16_t resubmit_num;
 191 };
 192
 193 struct rte_vhost_ring_inflight {
 194         union {
 195                 struct rte_vhost_inflight_info_split *inflight_split;
 196                 struct rte_vhost_inflight_info_packed *inflight_packed;
 197         };
 198
 199         struct rte_vhost_resubmit_info *resubmit_inflight;
 200 };
 201
 202 struct rte_vhost_vring {
 203         union {
 204                 struct vring_desc *desc;
 205                 struct vring_packed_desc *desc_packed;
 206         };
 207         union {
 208                 struct vring_avail *avail;
 209                 struct vring_packed_desc_event *driver_event;
 210         };
 211         union {
 212                 struct vring_used *used;
 213                 struct vring_packed_desc_event *device_event;
 214         };
 215         uint64_t                log_guest_addr;
 216
 217         /** Deprecated, use rte_vhost_vring_call() instead. */
 218         int                     callfd;
 219
 220         int                     kickfd;
 221         uint16_t                size;
 222 };
 223
 224 /**
 225  * Possible results of the vhost user message handling callbacks
 226  */
 227 enum rte_vhost_msg_result {
 228         /* Message handling failed */
 229         RTE_VHOST_MSG_RESULT_ERR = -1,
 230         /* Message handling successful */
 231         RTE_VHOST_MSG_RESULT_OK =  0,
 232         /* Message handling successful and reply prepared */
 233         RTE_VHOST_MSG_RESULT_REPLY =  1,
 234         /* Message not handled */
 235         RTE_VHOST_MSG_RESULT_NOT_HANDLED,
 236 };
 237
 238 /**
 239  * Function prototype for the vhost backend to handle specific vhost user
 240  * messages.
 241  *
 242  * @param vid
 243  *  vhost device id
 244  * @param msg
 245  *  Message pointer.
 246  * @return
 247  *  RTE_VHOST_MSG_RESULT_OK on success,
 248  *  RTE_VHOST_MSG_RESULT_REPLY on success with reply,
 249  *  RTE_VHOST_MSG_RESULT_ERR on failure,
 250  *  RTE_VHOST_MSG_RESULT_NOT_HANDLED if message was not handled.
 251  */
 252 typedef enum rte_vhost_msg_result (*rte_vhost_msg_handle)(int vid, void *msg);
 253
 254 /**
 255  * Optional vhost user message handlers.
 256  */
 257 struct rte_vhost_user_extern_ops {
 258         /* Called prior to the master message handling. */
 259         rte_vhost_msg_handle pre_msg_handle;
 260         /* Called after the master message handling. */
 261         rte_vhost_msg_handle post_msg_handle;
 262 };
 263
 264 /**
 265  * Device and vring operations.
 266  */
 267 struct vhost_device_ops {
 268         int (*new_device)(int vid);             /**< Add device. */
 269         void (*destroy_device)(int vid);        /**< Remove device. */
 270
 271         int (*vring_state_changed)(int vid, uint16_t queue_id, int enable);     /**< triggered when a vring is enabled or disabled */
 272
 273         /**
 274          * Features could be changed after the feature negotiation.
 275          * For example, VHOST_F_LOG_ALL will be set/cleared at the
 276          * start/end of live migration, respectively. This callback
 277          * is used to inform the application on such change.
 278          */
 279         int (*features_changed)(int vid, uint64_t features);
 280
 281         int (*new_connection)(int vid);
 282         void (*destroy_connection)(int vid);
 283
 284         /**
 285          * This callback gets called each time a guest gets notified
 286          * about waiting packets. This is the interrupt handling through
 287          * the eventfd_write(callfd), which can be used for counting these
 288          * "slow" syscalls.
 289          */
 290         void (*guest_notified)(int vid);
 291
 292         void *reserved[1]; /**< Reserved for future extension */
 293 };
 294
 295 /**
 296  * Convert guest physical address to host virtual address
 297  *
 298  * This function is deprecated because unsafe.
 299  * New rte_vhost_va_from_guest_pa() should be used instead to ensure
 300  * guest physical ranges are fully and contiguously mapped into
 301  * process virtual address space.
 302  *
 303  * @param mem
 304  *  the guest memory regions
 305  * @param gpa
 306  *  the guest physical address for querying
 307  * @return
 308  *  the host virtual address on success, 0 on failure
 309  */
 310 __rte_deprecated
 311 static __rte_always_inline uint64_t
 312 rte_vhost_gpa_to_vva(struct rte_vhost_memory *mem, uint64_t gpa)
 313 {
 314         struct rte_vhost_mem_region *reg;
 315         uint32_t i;
 316
 317         for (i = 0; i < mem->nregions; i++) {
 318                 reg = &mem->regions[i];
 319                 if (gpa >= reg->guest_phys_addr &&
 320                     gpa <  reg->guest_phys_addr + reg->size) {
 321                         return gpa - reg->guest_phys_addr +
 322                                reg->host_user_addr;
 323                 }
 324         }
 325
 326         return 0;
 327 }
 328
 329 /**
 330  * Convert guest physical address to host virtual address safely
 331  *
 332  * This variant of rte_vhost_gpa_to_vva() takes care all the
 333  * requested length is mapped and contiguous in process address
 334  * space.
 335  *
 336  * @param mem
 337  *  the guest memory regions
 338  * @param gpa
 339  *  the guest physical address for querying
 340  * @param len
 341  *  the size of the requested area to map, updated with actual size mapped
 342  * @return
 343  *  the host virtual address on success, 0 on failure
 344  */
 345 __rte_experimental
 346 static __rte_always_inline uint64_t
 347 rte_vhost_va_from_guest_pa(struct rte_vhost_memory *mem,
 348                                                    uint64_t gpa, uint64_t *len)
 349 {
 350         struct rte_vhost_mem_region *r;
 351         uint32_t i;
 352
 353         for (i = 0; i < mem->nregions; i++) {
 354                 r = &mem->regions[i];
 355                 if (gpa >= r->guest_phys_addr &&
 356                     gpa <  r->guest_phys_addr + r->size) {
 357
 358                         if (unlikely(*len > r->guest_phys_addr + r->size - gpa))
 359                                 *len = r->guest_phys_addr + r->size - gpa;
 360
 361                         return gpa - r->guest_phys_addr +
 362                                r->host_user_addr;
 363                 }
 364         }
 365         *len = 0;
 366
 367         return 0;
 368 }
 369
 370 #define RTE_VHOST_NEED_LOG(features)    ((features) & (1ULL << VHOST_F_LOG_ALL))
 371
 372 /**
 373  * Log the memory write start with given address.
 374  *
 375  * This function only need be invoked when the live migration starts.
 376  * Therefore, we won't need call it at all in the most of time. For
 377  * making the performance impact be minimum, it's suggested to do a
 378  * check before calling it:
 379  *
 380  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
 381  *                rte_vhost_log_write(vid, addr, len);
 382  *
 383  * @param vid
 384  *  vhost device ID
 385  * @param addr
 386  *  the starting address for write (in guest physical address space)
 387  * @param len
 388  *  the length to write
 389  */
 390 void rte_vhost_log_write(int vid, uint64_t addr, uint64_t len);
 391
 392 /**
 393  * Log the used ring update start at given offset.
 394  *
 395  * Same as rte_vhost_log_write, it's suggested to do a check before
 396  * calling it:
 397  *
 398  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
 399  *                rte_vhost_log_used_vring(vid, vring_idx, offset, len);
 400  *
 401  * @param vid
 402  *  vhost device ID
 403  * @param vring_idx
 404  *  the vring index
 405  * @param offset
 406  *  the offset inside the used ring
 407  * @param len
 408  *  the length to write
 409  */
 410 void rte_vhost_log_used_vring(int vid, uint16_t vring_idx,
 411                               uint64_t offset, uint64_t len);
 412
 413 int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable);
 414
 415 /**
 416  * Register vhost driver. path could be different for multiple
 417  * instance support.
 418  */
 419 int rte_vhost_driver_register(const char *path, uint64_t flags);
 420
 421 /* Unregister vhost driver. This is only meaningful to vhost user. */
 422 int rte_vhost_driver_unregister(const char *path);
 423
 424 /**
 425  * Set the vdpa device id, enforce single connection per socket
 426  *
 427  * @param path
 428  *  The vhost-user socket file path
 429  * @param dev
 430  *  vDPA device pointer
 431  * @return
 432  *  0 on success, -1 on failure
 433  */
 434 int
 435 rte_vhost_driver_attach_vdpa_device(const char *path,
 436                 struct rte_vdpa_device *dev);
 437
 438 /**
 439  * Unset the vdpa device id
 440  *
 441  * @param path
 442  *  The vhost-user socket file path
 443  * @return
 444  *  0 on success, -1 on failure
 445  */
 446 int
 447 rte_vhost_driver_detach_vdpa_device(const char *path);
 448
 449 /**
 450  * Get the device id
 451  *
 452  * @param path
 453  *  The vhost-user socket file path
 454  * @return
 455  *  vDPA device pointer, NULL on failure
 456  */
 457 struct rte_vdpa_device *
 458 rte_vhost_driver_get_vdpa_device(const char *path);
 459
 460 /**
 461  * Set the feature bits the vhost-user driver supports.
 462  *
 463  * @param path
 464  *  The vhost-user socket file path
 465  * @param features
 466  *  Supported features
 467  * @return
 468  *  0 on success, -1 on failure
 469  */
 470 int rte_vhost_driver_set_features(const char *path, uint64_t features);
 471
 472 /**
 473  * Enable vhost-user driver features.
 474  *
 475  * Note that
 476  * - the param features should be a subset of the feature bits provided
 477  *   by rte_vhost_driver_set_features().
 478  * - it must be invoked before vhost-user negotiation starts.
 479  *
 480  * @param path
 481  *  The vhost-user socket file path
 482  * @param features
 483  *  Features to enable
 484  * @return
 485  *  0 on success, -1 on failure
 486  */
 487 int rte_vhost_driver_enable_features(const char *path, uint64_t features);
 488
 489 /**
 490  * Disable vhost-user driver features.
 491  *
 492  * The two notes at rte_vhost_driver_enable_features() also apply here.
 493  *
 494  * @param path
 495  *  The vhost-user socket file path
 496  * @param features
 497  *  Features to disable
 498  * @return
 499  *  0 on success, -1 on failure
 500  */
 501 int rte_vhost_driver_disable_features(const char *path, uint64_t features);
 502
 503 /**
 504  * Get the feature bits before feature negotiation.
 505  *
 506  * @param path
 507  *  The vhost-user socket file path
 508  * @param features
 509  *  A pointer to store the queried feature bits
 510  * @return
 511  *  0 on success, -1 on failure
 512  */
 513 int rte_vhost_driver_get_features(const char *path, uint64_t *features);
 514
 515 /**
 516  * Set the protocol feature bits before feature negotiation.
 517  *
 518  * @param path
 519  *  The vhost-user socket file path
 520  * @param protocol_features
 521  *  Supported protocol features
 522  * @return
 523  *  0 on success, -1 on failure
 524  */
 525 __rte_experimental
 526 int
 527 rte_vhost_driver_set_protocol_features(const char *path,
 528                 uint64_t protocol_features);
 529
 530 /**
 531  * Get the protocol feature bits before feature negotiation.
 532  *
 533  * @param path
 534  *  The vhost-user socket file path
 535  * @param protocol_features
 536  *  A pointer to store the queried protocol feature bits
 537  * @return
 538  *  0 on success, -1 on failure
 539  */
 540 __rte_experimental
 541 int
 542 rte_vhost_driver_get_protocol_features(const char *path,
 543                 uint64_t *protocol_features);
 544
 545 /**
 546  * Get the queue number bits before feature negotiation.
 547  *
 548  * @param path
 549  *  The vhost-user socket file path
 550  * @param queue_num
 551  *  A pointer to store the queried queue number bits
 552  * @return
 553  *  0 on success, -1 on failure
 554  */
 555 __rte_experimental
 556 int
 557 rte_vhost_driver_get_queue_num(const char *path, uint32_t *queue_num);
 558
 559 /**
 560  * Get the feature bits after negotiation
 561  *
 562  * @param vid
 563  *  Vhost device ID
 564  * @param features
 565  *  A pointer to store the queried feature bits
 566  * @return
 567  *  0 on success, -1 on failure
 568  */
 569 int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
 570
 571 /**
 572  * Get the protocol feature bits after negotiation
 573  *
 574  * @param vid
 575  *  Vhost device ID
 576  * @param protocol_features
 577  *  A pointer to store the queried protocol feature bits
 578  * @return
 579  *  0 on success, -1 on failure
 580  */
 581 __rte_experimental
 582 int
 583 rte_vhost_get_negotiated_protocol_features(int vid,
 584                                            uint64_t *protocol_features);
 585
 586 /* Register callbacks. */
 587 int rte_vhost_driver_callback_register(const char *path,
 588         struct vhost_device_ops const * const ops);
 589
 590 /**
 591  *
 592  * Start the vhost-user driver.
 593  *
 594  * This function triggers the vhost-user negotiation.
 595  *
 596  * @param path
 597  *  The vhost-user socket file path
 598  * @return
 599  *  0 on success, -1 on failure
 600  */
 601 int rte_vhost_driver_start(const char *path);
 602
 603 /**
 604  * Get the MTU value of the device if set in QEMU.
 605  *
 606  * @param vid
 607  *  virtio-net device ID
 608  * @param mtu
 609  *  The variable to store the MTU value
 610  *
 611  * @return
 612  *  0: success
 613  *  -EAGAIN: device not yet started
 614  *  -ENOTSUP: device does not support MTU feature
 615  */
 616 int rte_vhost_get_mtu(int vid, uint16_t *mtu);
 617
 618 /**
 619  * Get the numa node from which the virtio net device's memory
 620  * is allocated.
 621  *
 622  * @param vid
 623  *  vhost device ID
 624  *
 625  * @return
 626  *  The numa node, -1 on failure
 627  */
 628 int rte_vhost_get_numa_node(int vid);
 629
 630 /**
 631  * @deprecated
 632  * Get the number of queues the device supports.
 633  *
 634  * Note this function is deprecated, as it returns a queue pair number,
 635  * which is vhost specific. Instead, rte_vhost_get_vring_num should
 636  * be used.
 637  *
 638  * @param vid
 639  *  vhost device ID
 640  *
 641  * @return
 642  *  The number of queues, 0 on failure
 643  */
 644 __rte_deprecated
 645 uint32_t rte_vhost_get_queue_num(int vid);
 646
 647 /**
 648  * Get the number of vrings the device supports.
 649  *
 650  * @param vid
 651  *  vhost device ID
 652  *
 653  * @return
 654  *  The number of vrings, 0 on failure
 655  */
 656 uint16_t rte_vhost_get_vring_num(int vid);
 657
 658 /**
 659  * Get the virtio net device's ifname, which is the vhost-user socket
 660  * file path.
 661  *
 662  * @param vid
 663  *  vhost device ID
 664  * @param buf
 665  *  The buffer to stored the queried ifname
 666  * @param len
 667  *  The length of buf
 668  *
 669  * @return
 670  *  0 on success, -1 on failure
 671  */
 672 int rte_vhost_get_ifname(int vid, char *buf, size_t len);
 673
 674 /**
 675  * Get how many avail entries are left in the queue
 676  *
 677  * @param vid
 678  *  vhost device ID
 679  * @param queue_id
 680  *  virtio queue index
 681  *
 682  * @return
 683  *  num of avail entries left
 684  */
 685 uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id);
 686
 687 struct rte_mbuf;
 688 struct rte_mempool;
 689 /**
 690  * This function adds buffers to the virtio devices RX virtqueue. Buffers can
 691  * be received from the physical port or from another virtual device. A packet
 692  * count is returned to indicate the number of packets that were successfully
 693  * added to the RX queue.
 694  * @param vid
 695  *  vhost device ID
 696  * @param queue_id
 697  *  virtio queue index in mq case
 698  * @param pkts
 699  *  array to contain packets to be enqueued
 700  * @param count
 701  *  packets num to be enqueued
 702  * @return
 703  *  num of packets enqueued
 704  */
 705 uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id,
 706         struct rte_mbuf **pkts, uint16_t count);
 707
 708 /**
 709  * This function gets guest buffers from the virtio device TX virtqueue,
 710  * construct host mbufs, copies guest buffer content to host mbufs and
 711  * store them in pkts to be processed.
 712  * @param vid
 713  *  vhost device ID
 714  * @param queue_id
 715  *  virtio queue index in mq case
 716  * @param mbuf_pool
 717  *  mbuf_pool where host mbuf is allocated.
 718  * @param pkts
 719  *  array to contain packets to be dequeued
 720  * @param count
 721  *  packets num to be dequeued
 722  * @return
 723  *  num of packets dequeued
 724  */
 725 uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id,
 726         struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count);
 727
 728 /**
 729  * Get guest mem table: a list of memory regions.
 730  *
 731  * An rte_vhost_vhost_memory object will be allocated internally, to hold the
 732  * guest memory regions. Application should free it at destroy_device()
 733  * callback.
 734  *
 735  * @param vid
 736  *  vhost device ID
 737  * @param mem
 738  *  To store the returned mem regions
 739  * @return
 740  *  0 on success, -1 on failure
 741  */
 742 int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem);
 743
 744 /**
 745  * Get guest vring info, including the vring address, vring size, etc.
 746  *
 747  * @param vid
 748  *  vhost device ID
 749  * @param vring_idx
 750  *  vring index
 751  * @param vring
 752  *  the structure to hold the requested vring info
 753  * @return
 754  *  0 on success, -1 on failure
 755  */
 756 int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx,
 757                               struct rte_vhost_vring *vring);
 758
 759 /**
 760  * Get guest inflight vring info, including inflight ring and resubmit list.
 761  *
 762  * @param vid
 763  *  vhost device ID
 764  * @param vring_idx
 765  *  vring index
 766  * @param vring
 767  *  the structure to hold the requested inflight vring info
 768  * @return
 769  *  0 on success, -1 on failure
 770  */
 771 __rte_experimental
 772 int
 773 rte_vhost_get_vhost_ring_inflight(int vid, uint16_t vring_idx,
 774         struct rte_vhost_ring_inflight *vring);
 775
 776 /**
 777  * Set split inflight descriptor.
 778  *
 779  * This function save descriptors that has been comsumed in available
 780  * ring
 781  *
 782  * @param vid
 783  *  vhost device ID
 784  * @param vring_idx
 785  *  vring index
 786  * @param idx
 787  *  inflight entry index
 788  * @return
 789  *  0 on success, -1 on failure
 790  */
 791 __rte_experimental
 792 int
 793 rte_vhost_set_inflight_desc_split(int vid, uint16_t vring_idx,
 794         uint16_t idx);
 795
 796 /**
 797  * Set packed inflight descriptor and get corresponding inflight entry
 798  *
 799  * This function save descriptors that has been comsumed
 800  *
 801  * @param vid
 802  *  vhost device ID
 803  * @param vring_idx
 804  *  vring index
 805  * @param head
 806  *  head of descriptors
 807  * @param last
 808  *  last of descriptors
 809  * @param inflight_entry
 810  *  corresponding inflight entry
 811  * @return
 812  *  0 on success, -1 on failure
 813  */
 814 __rte_experimental
 815 int
 816 rte_vhost_set_inflight_desc_packed(int vid, uint16_t vring_idx,
 817         uint16_t head, uint16_t last, uint16_t *inflight_entry);
 818
 819 /**
 820  * Save the head of list that the last batch of used descriptors.
 821  *
 822  * @param vid
 823  *  vhost device ID
 824  * @param vring_idx
 825  *  vring index
 826  * @param idx
 827  *  descriptor entry index
 828  * @return
 829  *  0 on success, -1 on failure
 830  */
 831 __rte_experimental
 832 int
 833 rte_vhost_set_last_inflight_io_split(int vid,
 834         uint16_t vring_idx, uint16_t idx);
 835
 836 /**
 837  * Update the inflight free_head, used_idx and used_wrap_counter.
 838  *
 839  * This function will update status first before updating descriptors
 840  * to used
 841  *
 842  * @param vid
 843  *  vhost device ID
 844  * @param vring_idx
 845  *  vring index
 846  * @param head
 847  *  head of descriptors
 848  * @return
 849  *  0 on success, -1 on failure
 850  */
 851 __rte_experimental
 852 int
 853 rte_vhost_set_last_inflight_io_packed(int vid,
 854         uint16_t vring_idx, uint16_t head);
 855
 856 /**
 857  * Clear the split inflight status.
 858  *
 859  * @param vid
 860  *  vhost device ID
 861  * @param vring_idx
 862  *  vring index
 863  * @param last_used_idx
 864  *  last used idx of used ring
 865  * @param idx
 866  *  inflight entry index
 867  * @return
 868  *  0 on success, -1 on failure
 869  */
 870 __rte_experimental
 871 int
 872 rte_vhost_clr_inflight_desc_split(int vid, uint16_t vring_idx,
 873         uint16_t last_used_idx, uint16_t idx);
 874
 875 /**
 876  * Clear the packed inflight status.
 877  *
 878  * @param vid
 879  *  vhost device ID
 880  * @param vring_idx
 881  *  vring index
 882  * @param head
 883  *  inflight entry index
 884  * @return
 885  *  0 on success, -1 on failure
 886  */
 887 __rte_experimental
 888 int
 889 rte_vhost_clr_inflight_desc_packed(int vid, uint16_t vring_idx,
 890         uint16_t head);
 891
 892 /**
 893  * Notify the guest that used descriptors have been added to the vring.  This
 894  * function acts as a memory barrier.
 895  *
 896  * @param vid
 897  *  vhost device ID
 898  * @param vring_idx
 899  *  vring index
 900  * @return
 901  *  0 on success, -1 on failure
 902  */
 903 int rte_vhost_vring_call(int vid, uint16_t vring_idx);
 904
 905 /**
 906  * Get vhost RX queue avail count.
 907  *
 908  * @param vid
 909  *  vhost device ID
 910  * @param qid
 911  *  virtio queue index in mq case
 912  * @return
 913  *  num of desc available
 914  */
 915 uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid);
 916
 917 /**
 918  * Get log base and log size of the vhost device
 919  *
 920  * @param vid
 921  *  vhost device ID
 922  * @param log_base
 923  *  vhost log base
 924  * @param log_size
 925  *  vhost log size
 926  * @return
 927  *  0 on success, -1 on failure
 928  */
 929 int
 930 rte_vhost_get_log_base(int vid, uint64_t *log_base, uint64_t *log_size);
 931
 932 /**
 933  * Get last_avail/used_idx of the vhost virtqueue
 934  *
 935  * @param vid
 936  *  vhost device ID
 937  * @param queue_id
 938  *  vhost queue index
 939  * @param last_avail_idx
 940  *  vhost last_avail_idx to get
 941  * @param last_used_idx
 942  *  vhost last_used_idx to get
 943  * @return
 944  *  0 on success, -1 on failure
 945  */
 946 int
 947 rte_vhost_get_vring_base(int vid, uint16_t queue_id,
 948                 uint16_t *last_avail_idx, uint16_t *last_used_idx);
 949
 950 /**
 951  * Get last_avail/last_used of the vhost virtqueue
 952  *
 953  * This function is designed for the reconnection and it's specific for
 954  * the packed ring as we can get the two parameters from the inflight
 955  * queueregion
 956  *
 957  * @param vid
 958  *  vhost device ID
 959  * @param queue_id
 960  *  vhost queue index
 961  * @param last_avail_idx
 962  *  vhost last_avail_idx to get
 963  * @param last_used_idx
 964  *  vhost last_used_idx to get
 965  * @return
 966  *  0 on success, -1 on failure
 967  */
 968 __rte_experimental
 969 int
 970 rte_vhost_get_vring_base_from_inflight(int vid,
 971         uint16_t queue_id, uint16_t *last_avail_idx, uint16_t *last_used_idx);
 972
 973 /**
 974  * Set last_avail/used_idx of the vhost virtqueue
 975  *
 976  * @param vid
 977  *  vhost device ID
 978  * @param queue_id
 979  *  vhost queue index
 980  * @param last_avail_idx
 981  *  last_avail_idx to set
 982  * @param last_used_idx
 983  *  last_used_idx to set
 984  * @return
 985  *  0 on success, -1 on failure
 986  */
 987 int
 988 rte_vhost_set_vring_base(int vid, uint16_t queue_id,
 989                 uint16_t last_avail_idx, uint16_t last_used_idx);
 990
 991 /**
 992  * Register external message handling callbacks
 993  *
 994  * @param vid
 995  *  vhost device ID
 996  * @param ops
 997  *  virtio external callbacks to register
 998  * @param ctx
 999  *  additional context passed to the callbacks
1000  * @return
1001  *  0 on success, -1 on failure
1002  */
1003 __rte_experimental
1004 int
1005 rte_vhost_extern_callback_register(int vid,
1006                 struct rte_vhost_user_extern_ops const * const ops, void *ctx);
1007
1008 /**
1009  * Get vdpa device id for vhost device.
1010  *
1011  * @param vid
1012  *  vhost device id
1013  * @return
1014  *  vDPA device pointer on success, NULL on failure
1015  */
1016 struct rte_vdpa_device *
1017 rte_vhost_get_vdpa_device(int vid);
1018
1019 /**
1020  * Notify the guest that should get virtio configuration space from backend.
1021  *
1022  * @param vid
1023  *  vhost device ID
1024  * @param need_reply
1025  *  wait for the master response the status of this operation
1026  * @return
1027  *  0 on success, < 0 on failure
1028  */
1029 __rte_experimental
1030 int
1031 rte_vhost_slave_config_change(int vid, bool need_reply);
1032
1033 #ifdef __cplusplus
1034 }
1035 #endif
1036
1037 #endif /* _RTE_VHOST_H_ */