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 /**
  33  * Information relating to memory regions including offsets to
  34  * addresses in QEMUs memory file.
  35  */
  36 struct rte_vhost_mem_region {
  37         uint64_t guest_phys_addr;
  38         uint64_t guest_user_addr;
  39         uint64_t host_user_addr;
  40         uint64_t size;
  41         void     *mmap_addr;
  42         uint64_t mmap_size;
  43         int fd;
  44 };
  45
  46 /**
  47  * Memory structure includes region and mapping information.
  48  */
  49 struct rte_vhost_memory {
  50         uint32_t nregions;
  51         struct rte_vhost_mem_region regions[];
  52 };
  53
  54 struct rte_vhost_vring {
  55         struct vring_desc       *desc;
  56         struct vring_avail      *avail;
  57         struct vring_used       *used;
  58         uint64_t                log_guest_addr;
  59
  60         /** Deprecated, use rte_vhost_vring_call() instead. */
  61         int                     callfd;
  62
  63         int                     kickfd;
  64         uint16_t                size;
  65 };
  66
  67 /**
  68  * Device and vring operations.
  69  */
  70 struct vhost_device_ops {
  71         int (*new_device)(int vid);             /**< Add device. */
  72         void (*destroy_device)(int vid);        /**< Remove device. */
  73
  74         int (*vring_state_changed)(int vid, uint16_t queue_id, int enable);     /**< triggered when a vring is enabled or disabled */
  75
  76         /**
  77          * Features could be changed after the feature negotiation.
  78          * For example, VHOST_F_LOG_ALL will be set/cleared at the
  79          * start/end of live migration, respectively. This callback
  80          * is used to inform the application on such change.
  81          */
  82         int (*features_changed)(int vid, uint64_t features);
  83
  84         int (*new_connection)(int vid);
  85         void (*destroy_connection)(int vid);
  86
  87         void *reserved[2]; /**< Reserved for future extension */
  88 };
  89
  90 /**
  91  * Convert guest physical address to host virtual address
  92  *
  93  * This function is deprecated because unsafe.
  94  * New rte_vhost_va_from_guest_pa() should be used instead to ensure
  95  * guest physical ranges are fully and contiguously mapped into
  96  * process virtual address space.
  97  *
  98  * @param mem
  99  *  the guest memory regions
 100  * @param gpa
 101  *  the guest physical address for querying
 102  * @return
 103  *  the host virtual address on success, 0 on failure
 104  */
 105 __rte_deprecated
 106 static __rte_always_inline uint64_t
 107 rte_vhost_gpa_to_vva(struct rte_vhost_memory *mem, uint64_t gpa)
 108 {
 109         struct rte_vhost_mem_region *reg;
 110         uint32_t i;
 111
 112         for (i = 0; i < mem->nregions; i++) {
 113                 reg = &mem->regions[i];
 114                 if (gpa >= reg->guest_phys_addr &&
 115                     gpa <  reg->guest_phys_addr + reg->size) {
 116                         return gpa - reg->guest_phys_addr +
 117                                reg->host_user_addr;
 118                 }
 119         }
 120
 121         return 0;
 122 }
 123
 124 /**
 125  * Convert guest physical address to host virtual address safely
 126  *
 127  * This variant of rte_vhost_gpa_to_vva() takes care all the
 128  * requested length is mapped and contiguous in process address
 129  * space.
 130  *
 131  * @param mem
 132  *  the guest memory regions
 133  * @param gpa
 134  *  the guest physical address for querying
 135  * @param len
 136  *  the size of the requested area to map, updated with actual size mapped
 137  * @return
 138  *  the host virtual address on success, 0 on failure
 139  */
 140 static __rte_always_inline uint64_t
 141 rte_vhost_va_from_guest_pa(struct rte_vhost_memory *mem,
 142                                                    uint64_t gpa, uint64_t *len)
 143 {
 144         struct rte_vhost_mem_region *r;
 145         uint32_t i;
 146
 147         for (i = 0; i < mem->nregions; i++) {
 148                 r = &mem->regions[i];
 149                 if (gpa >= r->guest_phys_addr &&
 150                     gpa <  r->guest_phys_addr + r->size) {
 151
 152                         if (unlikely(*len > r->guest_phys_addr + r->size - gpa))
 153                                 *len = r->guest_phys_addr + r->size - gpa;
 154
 155                         return gpa - r->guest_phys_addr +
 156                                r->host_user_addr;
 157                 }
 158         }
 159         *len = 0;
 160
 161         return 0;
 162 }
 163
 164 #define RTE_VHOST_NEED_LOG(features)    ((features) & (1ULL << VHOST_F_LOG_ALL))
 165
 166 /**
 167  * Log the memory write start with given address.
 168  *
 169  * This function only need be invoked when the live migration starts.
 170  * Therefore, we won't need call it at all in the most of time. For
 171  * making the performance impact be minimum, it's suggested to do a
 172  * check before calling it:
 173  *
 174  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
 175  *                rte_vhost_log_write(vid, addr, len);
 176  *
 177  * @param vid
 178  *  vhost device ID
 179  * @param addr
 180  *  the starting address for write
 181  * @param len
 182  *  the length to write
 183  */
 184 void rte_vhost_log_write(int vid, uint64_t addr, uint64_t len);
 185
 186 /**
 187  * Log the used ring update start at given offset.
 188  *
 189  * Same as rte_vhost_log_write, it's suggested to do a check before
 190  * calling it:
 191  *
 192  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
 193  *                rte_vhost_log_used_vring(vid, vring_idx, offset, len);
 194  *
 195  * @param vid
 196  *  vhost device ID
 197  * @param vring_idx
 198  *  the vring index
 199  * @param offset
 200  *  the offset inside the used ring
 201  * @param len
 202  *  the length to write
 203  */
 204 void rte_vhost_log_used_vring(int vid, uint16_t vring_idx,
 205                               uint64_t offset, uint64_t len);
 206
 207 int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable);
 208
 209 /**
 210  * Register vhost driver. path could be different for multiple
 211  * instance support.
 212  */
 213 int rte_vhost_driver_register(const char *path, uint64_t flags);
 214
 215 /* Unregister vhost driver. This is only meaningful to vhost user. */
 216 int rte_vhost_driver_unregister(const char *path);
 217
 218 /**
 219  * Set the feature bits the vhost-user driver supports.
 220  *
 221  * @param path
 222  *  The vhost-user socket file path
 223  * @param features
 224  *  Supported features
 225  * @return
 226  *  0 on success, -1 on failure
 227  */
 228 int rte_vhost_driver_set_features(const char *path, uint64_t features);
 229
 230 /**
 231  * Enable vhost-user driver features.
 232  *
 233  * Note that
 234  * - the param features should be a subset of the feature bits provided
 235  *   by rte_vhost_driver_set_features().
 236  * - it must be invoked before vhost-user negotiation starts.
 237  *
 238  * @param path
 239  *  The vhost-user socket file path
 240  * @param features
 241  *  Features to enable
 242  * @return
 243  *  0 on success, -1 on failure
 244  */
 245 int rte_vhost_driver_enable_features(const char *path, uint64_t features);
 246
 247 /**
 248  * Disable vhost-user driver features.
 249  *
 250  * The two notes at rte_vhost_driver_enable_features() also apply here.
 251  *
 252  * @param path
 253  *  The vhost-user socket file path
 254  * @param features
 255  *  Features to disable
 256  * @return
 257  *  0 on success, -1 on failure
 258  */
 259 int rte_vhost_driver_disable_features(const char *path, uint64_t features);
 260
 261 /**
 262  * Get the feature bits before feature negotiation.
 263  *
 264  * @param path
 265  *  The vhost-user socket file path
 266  * @param features
 267  *  A pointer to store the queried feature bits
 268  * @return
 269  *  0 on success, -1 on failure
 270  */
 271 int rte_vhost_driver_get_features(const char *path, uint64_t *features);
 272
 273 /**
 274  * Get the feature bits after negotiation
 275  *
 276  * @param vid
 277  *  Vhost device ID
 278  * @param features
 279  *  A pointer to store the queried feature bits
 280  * @return
 281  *  0 on success, -1 on failure
 282  */
 283 int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
 284
 285 /* Register callbacks. */
 286 int rte_vhost_driver_callback_register(const char *path,
 287         struct vhost_device_ops const * const ops);
 288
 289 /**
 290  *
 291  * Start the vhost-user driver.
 292  *
 293  * This function triggers the vhost-user negotiation.
 294  *
 295  * @param path
 296  *  The vhost-user socket file path
 297  * @return
 298  *  0 on success, -1 on failure
 299  */
 300 int rte_vhost_driver_start(const char *path);
 301
 302 /**
 303  * Get the MTU value of the device if set in QEMU.
 304  *
 305  * @param vid
 306  *  virtio-net device ID
 307  * @param mtu
 308  *  The variable to store the MTU value
 309  *
 310  * @return
 311  *  0: success
 312  *  -EAGAIN: device not yet started
 313  *  -ENOTSUP: device does not support MTU feature
 314  */
 315 int rte_vhost_get_mtu(int vid, uint16_t *mtu);
 316
 317 /**
 318  * Get the numa node from which the virtio net device's memory
 319  * is allocated.
 320  *
 321  * @param vid
 322  *  vhost device ID
 323  *
 324  * @return
 325  *  The numa node, -1 on failure
 326  */
 327 int rte_vhost_get_numa_node(int vid);
 328
 329 /**
 330  * @deprecated
 331  * Get the number of queues the device supports.
 332  *
 333  * Note this function is deprecated, as it returns a queue pair number,
 334  * which is vhost specific. Instead, rte_vhost_get_vring_num should
 335  * be used.
 336  *
 337  * @param vid
 338  *  vhost device ID
 339  *
 340  * @return
 341  *  The number of queues, 0 on failure
 342  */
 343 __rte_deprecated
 344 uint32_t rte_vhost_get_queue_num(int vid);
 345
 346 /**
 347  * Get the number of vrings the device supports.
 348  *
 349  * @param vid
 350  *  vhost device ID
 351  *
 352  * @return
 353  *  The number of vrings, 0 on failure
 354  */
 355 uint16_t rte_vhost_get_vring_num(int vid);
 356
 357 /**
 358  * Get the virtio net device's ifname, which is the vhost-user socket
 359  * file path.
 360  *
 361  * @param vid
 362  *  vhost device ID
 363  * @param buf
 364  *  The buffer to stored the queried ifname
 365  * @param len
 366  *  The length of buf
 367  *
 368  * @return
 369  *  0 on success, -1 on failure
 370  */
 371 int rte_vhost_get_ifname(int vid, char *buf, size_t len);
 372
 373 /**
 374  * Get how many avail entries are left in the queue
 375  *
 376  * @param vid
 377  *  vhost device ID
 378  * @param queue_id
 379  *  virtio queue index
 380  *
 381  * @return
 382  *  num of avail entires left
 383  */
 384 uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id);
 385
 386 struct rte_mbuf;
 387 struct rte_mempool;
 388 /**
 389  * This function adds buffers to the virtio devices RX virtqueue. Buffers can
 390  * be received from the physical port or from another virtual device. A packet
 391  * count is returned to indicate the number of packets that were successfully
 392  * added to the RX queue.
 393  * @param vid
 394  *  vhost device ID
 395  * @param queue_id
 396  *  virtio queue index in mq case
 397  * @param pkts
 398  *  array to contain packets to be enqueued
 399  * @param count
 400  *  packets num to be enqueued
 401  * @return
 402  *  num of packets enqueued
 403  */
 404 uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id,
 405         struct rte_mbuf **pkts, uint16_t count);
 406
 407 /**
 408  * This function gets guest buffers from the virtio device TX virtqueue,
 409  * construct host mbufs, copies guest buffer content to host mbufs and
 410  * store them in pkts to be processed.
 411  * @param vid
 412  *  vhost device ID
 413  * @param queue_id
 414  *  virtio queue index in mq case
 415  * @param mbuf_pool
 416  *  mbuf_pool where host mbuf is allocated.
 417  * @param pkts
 418  *  array to contain packets to be dequeued
 419  * @param count
 420  *  packets num to be dequeued
 421  * @return
 422  *  num of packets dequeued
 423  */
 424 uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id,
 425         struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count);
 426
 427 /**
 428  * Get guest mem table: a list of memory regions.
 429  *
 430  * An rte_vhost_vhost_memory object will be allocated internaly, to hold the
 431  * guest memory regions. Application should free it at destroy_device()
 432  * callback.
 433  *
 434  * @param vid
 435  *  vhost device ID
 436  * @param mem
 437  *  To store the returned mem regions
 438  * @return
 439  *  0 on success, -1 on failure
 440  */
 441 int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem);
 442
 443 /**
 444  * Get guest vring info, including the vring address, vring size, etc.
 445  *
 446  * @param vid
 447  *  vhost device ID
 448  * @param vring_idx
 449  *  vring index
 450  * @param vring
 451  *  the structure to hold the requested vring info
 452  * @return
 453  *  0 on success, -1 on failure
 454  */
 455 int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx,
 456                               struct rte_vhost_vring *vring);
 457
 458 /**
 459  * Notify the guest that used descriptors have been added to the vring.  This
 460  * function acts as a memory barrier.
 461  *
 462  * @param vid
 463  *  vhost device ID
 464  * @param vring_idx
 465  *  vring index
 466  * @return
 467  *  0 on success, -1 on failure
 468  */
 469 int rte_vhost_vring_call(int vid, uint16_t vring_idx);
 470
 471 /**
 472  * Get vhost RX queue avail count.
 473  *
 474  * @param vid
 475  *  vhost device ID
 476  * @param qid
 477  *  virtio queue index in mq case
 478  * @return
 479  *  num of desc available
 480  */
 481 uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid);
 482
 483 #ifdef __cplusplus
 484 }
 485 #endif
 486
 487 #endif /* _RTE_VHOST_H_ */