lib/librte_vhost/rte_vhost.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2017 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  17  *     * Neither the name of Intel Corporation nor the names of its
  18  *       contributors may be used to endorse or promote products derived
  19  *       from this software without specific prior written permission.
  20  *
  21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef _RTE_VHOST_H_
  35 #define _RTE_VHOST_H_
  36
  37 /**
  38  * @file
  39  * Interface to vhost-user
  40  */
  41
  42 #include <stdint.h>
  43 #include <sys/eventfd.h>
  44
  45 #include <rte_memory.h>
  46 #include <rte_mempool.h>
  47
  48 #ifdef __cplusplus
  49 extern "C" {
  50 #endif
  51
  52 /* These are not C++-aware. */
  53 #include <linux/vhost.h>
  54 #include <linux/virtio_ring.h>
  55
  56 #define RTE_VHOST_USER_CLIENT           (1ULL << 0)
  57 #define RTE_VHOST_USER_NO_RECONNECT     (1ULL << 1)
  58 #define RTE_VHOST_USER_DEQUEUE_ZERO_COPY        (1ULL << 2)
  59
  60 /**
  61  * Information relating to memory regions including offsets to
  62  * addresses in QEMUs memory file.
  63  */
  64 struct rte_vhost_mem_region {
  65         uint64_t guest_phys_addr;
  66         uint64_t guest_user_addr;
  67         uint64_t host_user_addr;
  68         uint64_t size;
  69         void     *mmap_addr;
  70         uint64_t mmap_size;
  71         int fd;
  72 };
  73
  74 /**
  75  * Memory structure includes region and mapping information.
  76  */
  77 struct rte_vhost_memory {
  78         uint32_t nregions;
  79         struct rte_vhost_mem_region regions[];
  80 };
  81
  82 struct rte_vhost_vring {
  83         struct vring_desc       *desc;
  84         struct vring_avail      *avail;
  85         struct vring_used       *used;
  86         uint64_t                log_guest_addr;
  87
  88         int                     callfd;
  89         int                     kickfd;
  90         uint16_t                size;
  91 };
  92
  93 /**
  94  * Device and vring operations.
  95  */
  96 struct vhost_device_ops {
  97         int (*new_device)(int vid);             /**< Add device. */
  98         void (*destroy_device)(int vid);        /**< Remove device. */
  99
 100         int (*vring_state_changed)(int vid, uint16_t queue_id, int enable);     /**< triggered when a vring is enabled or disabled */
 101
 102         /**
 103          * Features could be changed after the feature negotiation.
 104          * For example, VHOST_F_LOG_ALL will be set/cleared at the
 105          * start/end of live migration, respectively. This callback
 106          * is used to inform the application on such change.
 107          */
 108         int (*features_changed)(int vid, uint64_t features);
 109
 110         void *reserved[4]; /**< Reserved for future extension */
 111 };
 112
 113 /**
 114  * Convert guest physical address to host virtual address
 115  *
 116  * @param mem
 117  *  the guest memory regions
 118  * @param gpa
 119  *  the guest physical address for querying
 120  * @return
 121  *  the host virtual address on success, 0 on failure
 122  */
 123 static __rte_always_inline uint64_t
 124 rte_vhost_gpa_to_vva(struct rte_vhost_memory *mem, uint64_t gpa)
 125 {
 126         struct rte_vhost_mem_region *reg;
 127         uint32_t i;
 128
 129         for (i = 0; i < mem->nregions; i++) {
 130                 reg = &mem->regions[i];
 131                 if (gpa >= reg->guest_phys_addr &&
 132                     gpa <  reg->guest_phys_addr + reg->size) {
 133                         return gpa - reg->guest_phys_addr +
 134                                reg->host_user_addr;
 135                 }
 136         }
 137
 138         return 0;
 139 }
 140
 141 #define RTE_VHOST_NEED_LOG(features)    ((features) & (1ULL << VHOST_F_LOG_ALL))
 142
 143 /**
 144  * Log the memory write start with given address.
 145  *
 146  * This function only need be invoked when the live migration starts.
 147  * Therefore, we won't need call it at all in the most of time. For
 148  * making the performance impact be minimum, it's suggested to do a
 149  * check before calling it:
 150  *
 151  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
 152  *                rte_vhost_log_write(vid, addr, len);
 153  *
 154  * @param vid
 155  *  vhost device ID
 156  * @param addr
 157  *  the starting address for write
 158  * @param len
 159  *  the length to write
 160  */
 161 void rte_vhost_log_write(int vid, uint64_t addr, uint64_t len);
 162
 163 /**
 164  * Log the used ring update start at given offset.
 165  *
 166  * Same as rte_vhost_log_write, it's suggested to do a check before
 167  * calling it:
 168  *
 169  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
 170  *                rte_vhost_log_used_vring(vid, vring_idx, offset, len);
 171  *
 172  * @param vid
 173  *  vhost device ID
 174  * @param vring_idx
 175  *  the vring index
 176  * @param offset
 177  *  the offset inside the used ring
 178  * @param len
 179  *  the length to write
 180  */
 181 void rte_vhost_log_used_vring(int vid, uint16_t vring_idx,
 182                               uint64_t offset, uint64_t len);
 183
 184 int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable);
 185
 186 /**
 187  * Register vhost driver. path could be different for multiple
 188  * instance support.
 189  */
 190 int rte_vhost_driver_register(const char *path, uint64_t flags);
 191
 192 /* Unregister vhost driver. This is only meaningful to vhost user. */
 193 int rte_vhost_driver_unregister(const char *path);
 194
 195 /**
 196  * Set the feature bits the vhost-user driver supports.
 197  *
 198  * @param path
 199  *  The vhost-user socket file path
 200  * @param features
 201  *  Supported features
 202  * @return
 203  *  0 on success, -1 on failure
 204  */
 205 int rte_vhost_driver_set_features(const char *path, uint64_t features);
 206
 207 /**
 208  * Enable vhost-user driver features.
 209  *
 210  * Note that
 211  * - the param features should be a subset of the feature bits provided
 212  *   by rte_vhost_driver_set_features().
 213  * - it must be invoked before vhost-user negotiation starts.
 214  *
 215  * @param path
 216  *  The vhost-user socket file path
 217  * @param features
 218  *  Features to enable
 219  * @return
 220  *  0 on success, -1 on failure
 221  */
 222 int rte_vhost_driver_enable_features(const char *path, uint64_t features);
 223
 224 /**
 225  * Disable vhost-user driver features.
 226  *
 227  * The two notes at rte_vhost_driver_enable_features() also apply here.
 228  *
 229  * @param path
 230  *  The vhost-user socket file path
 231  * @param features
 232  *  Features to disable
 233  * @return
 234  *  0 on success, -1 on failure
 235  */
 236 int rte_vhost_driver_disable_features(const char *path, uint64_t features);
 237
 238 /**
 239  * Get the feature bits before feature negotiation.
 240  *
 241  * @param path
 242  *  The vhost-user socket file path
 243  * @param features
 244  *  A pointer to store the queried feature bits
 245  * @return
 246  *  0 on success, -1 on failure
 247  */
 248 int rte_vhost_driver_get_features(const char *path, uint64_t *features);
 249
 250 /**
 251  * Get the feature bits after negotiation
 252  *
 253  * @param vid
 254  *  Vhost device ID
 255  * @param features
 256  *  A pointer to store the queried feature bits
 257  * @return
 258  *  0 on success, -1 on failure
 259  */
 260 int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
 261
 262 /* Register callbacks. */
 263 int rte_vhost_driver_callback_register(const char *path,
 264         struct vhost_device_ops const * const ops);
 265
 266 /**
 267  *
 268  * Start the vhost-user driver.
 269  *
 270  * This function triggers the vhost-user negotiation.
 271  *
 272  * @param path
 273  *  The vhost-user socket file path
 274  * @return
 275  *  0 on success, -1 on failure
 276  */
 277 int rte_vhost_driver_start(const char *path);
 278
 279 /**
 280  * Get the MTU value of the device if set in QEMU.
 281  *
 282  * @param vid
 283  *  virtio-net device ID
 284  * @param mtu
 285  *  The variable to store the MTU value
 286  *
 287  * @return
 288  *  0: success
 289  *  -EAGAIN: device not yet started
 290  *  -ENOTSUP: device does not support MTU feature
 291  */
 292 int rte_vhost_get_mtu(int vid, uint16_t *mtu);
 293
 294 /**
 295  * Get the numa node from which the virtio net device's memory
 296  * is allocated.
 297  *
 298  * @param vid
 299  *  vhost device ID
 300  *
 301  * @return
 302  *  The numa node, -1 on failure
 303  */
 304 int rte_vhost_get_numa_node(int vid);
 305
 306 /**
 307  * @deprecated
 308  * Get the number of queues the device supports.
 309  *
 310  * Note this function is deprecated, as it returns a queue pair number,
 311  * which is vhost specific. Instead, rte_vhost_get_vring_num should
 312  * be used.
 313  *
 314  * @param vid
 315  *  vhost device ID
 316  *
 317  * @return
 318  *  The number of queues, 0 on failure
 319  */
 320 __rte_deprecated
 321 uint32_t rte_vhost_get_queue_num(int vid);
 322
 323 /**
 324  * Get the number of vrings the device supports.
 325  *
 326  * @param vid
 327  *  vhost device ID
 328  *
 329  * @return
 330  *  The number of vrings, 0 on failure
 331  */
 332 uint16_t rte_vhost_get_vring_num(int vid);
 333
 334 /**
 335  * Get the virtio net device's ifname, which is the vhost-user socket
 336  * file path.
 337  *
 338  * @param vid
 339  *  vhost device ID
 340  * @param buf
 341  *  The buffer to stored the queried ifname
 342  * @param len
 343  *  The length of buf
 344  *
 345  * @return
 346  *  0 on success, -1 on failure
 347  */
 348 int rte_vhost_get_ifname(int vid, char *buf, size_t len);
 349
 350 /**
 351  * Get how many avail entries are left in the queue
 352  *
 353  * @param vid
 354  *  vhost device ID
 355  * @param queue_id
 356  *  virtio queue index
 357  *
 358  * @return
 359  *  num of avail entires left
 360  */
 361 uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id);
 362
 363 struct rte_mbuf;
 364 struct rte_mempool;
 365 /**
 366  * This function adds buffers to the virtio devices RX virtqueue. Buffers can
 367  * be received from the physical port or from another virtual device. A packet
 368  * count is returned to indicate the number of packets that were successfully
 369  * added to the RX queue.
 370  * @param vid
 371  *  vhost device ID
 372  * @param queue_id
 373  *  virtio queue index in mq case
 374  * @param pkts
 375  *  array to contain packets to be enqueued
 376  * @param count
 377  *  packets num to be enqueued
 378  * @return
 379  *  num of packets enqueued
 380  */
 381 uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id,
 382         struct rte_mbuf **pkts, uint16_t count);
 383
 384 /**
 385  * This function gets guest buffers from the virtio device TX virtqueue,
 386  * construct host mbufs, copies guest buffer content to host mbufs and
 387  * store them in pkts to be processed.
 388  * @param vid
 389  *  vhost device ID
 390  * @param queue_id
 391  *  virtio queue index in mq case
 392  * @param mbuf_pool
 393  *  mbuf_pool where host mbuf is allocated.
 394  * @param pkts
 395  *  array to contain packets to be dequeued
 396  * @param count
 397  *  packets num to be dequeued
 398  * @return
 399  *  num of packets dequeued
 400  */
 401 uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id,
 402         struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count);
 403
 404 /**
 405  * Get guest mem table: a list of memory regions.
 406  *
 407  * An rte_vhost_vhost_memory object will be allocated internaly, to hold the
 408  * guest memory regions. Application should free it at destroy_device()
 409  * callback.
 410  *
 411  * @param vid
 412  *  vhost device ID
 413  * @param mem
 414  *  To store the returned mem regions
 415  * @return
 416  *  0 on success, -1 on failure
 417  */
 418 int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem);
 419
 420 /**
 421  * Get guest vring info, including the vring address, vring size, etc.
 422  *
 423  * @param vid
 424  *  vhost device ID
 425  * @param vring_idx
 426  *  vring index
 427  * @param vring
 428  *  the structure to hold the requested vring info
 429  * @return
 430  *  0 on success, -1 on failure
 431  */
 432 int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx,
 433                               struct rte_vhost_vring *vring);
 434
 435 /**
 436  * Get vhost RX queue avail count.
 437  *
 438  * @param vid
 439  *  vhost device ID
 440  * @param qid
 441  *  virtio queue index in mq case
 442  * @return
 443  *  num of desc available
 444  */
 445 uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid);
 446
 447 #ifdef __cplusplus
 448 }
 449 #endif
 450
 451 #endif /* _RTE_VHOST_H_ */