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