lib/librte_vhost/rte_virtio_net.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 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 _VIRTIO_NET_H_
  35 #define _VIRTIO_NET_H_
  36
  37 /**
  38  * @file
  39  * Interface to vhost net
  40  */
  41
  42 #include <stdint.h>
  43 #include <linux/vhost.h>
  44 #include <linux/virtio_ring.h>
  45 #include <sys/eventfd.h>
  46
  47 #include <rte_memory.h>
  48 #include <rte_mempool.h>
  49
  50 #define RTE_VHOST_USER_CLIENT           (1ULL << 0)
  51 #define RTE_VHOST_USER_NO_RECONNECT     (1ULL << 1)
  52 #define RTE_VHOST_USER_DEQUEUE_ZERO_COPY        (1ULL << 2)
  53
  54 /**
  55  * Information relating to memory regions including offsets to
  56  * addresses in QEMUs memory file.
  57  */
  58 struct rte_vhost_mem_region {
  59         uint64_t guest_phys_addr;
  60         uint64_t guest_user_addr;
  61         uint64_t host_user_addr;
  62         uint64_t size;
  63         void     *mmap_addr;
  64         uint64_t mmap_size;
  65         int fd;
  66 };
  67
  68 /**
  69  * Memory structure includes region and mapping information.
  70  */
  71 struct rte_vhost_memory {
  72         uint32_t nregions;
  73         struct rte_vhost_mem_region regions[0];
  74 };
  75
  76 struct rte_vhost_vring {
  77         struct vring_desc       *desc;
  78         struct vring_avail      *avail;
  79         struct vring_used       *used;
  80         uint64_t                log_guest_addr;
  81
  82         int                     callfd;
  83         int                     kickfd;
  84         uint16_t                size;
  85 };
  86
  87 /**
  88  * Device and vring operations.
  89  */
  90 struct virtio_net_device_ops {
  91         int (*new_device)(int vid);             /**< Add device. */
  92         void (*destroy_device)(int vid);        /**< Remove device. */
  93
  94         int (*vring_state_changed)(int vid, uint16_t queue_id, int enable);     /**< triggered when a vring is enabled or disabled */
  95
  96         void *reserved[5]; /**< Reserved for future extension */
  97 };
  98
  99 /**
 100  * Convert guest physical address to host virtual address
 101  *
 102  * @param mem
 103  *  the guest memory regions
 104  * @param gpa
 105  *  the guest physical address for querying
 106  * @return
 107  *  the host virtual address on success, 0 on failure
 108  */
 109 static inline uint64_t __attribute__((always_inline))
 110 rte_vhost_gpa_to_vva(struct rte_vhost_memory *mem, uint64_t gpa)
 111 {
 112         struct rte_vhost_mem_region *reg;
 113         uint32_t i;
 114
 115         for (i = 0; i < mem->nregions; i++) {
 116                 reg = &mem->regions[i];
 117                 if (gpa >= reg->guest_phys_addr &&
 118                     gpa <  reg->guest_phys_addr + reg->size) {
 119                         return gpa - reg->guest_phys_addr +
 120                                reg->host_user_addr;
 121                 }
 122         }
 123
 124         return 0;
 125 }
 126
 127 int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable);
 128
 129 /**
 130  * Register vhost driver. path could be different for multiple
 131  * instance support.
 132  */
 133 int rte_vhost_driver_register(const char *path, uint64_t flags);
 134
 135 /* Unregister vhost driver. This is only meaningful to vhost user. */
 136 int rte_vhost_driver_unregister(const char *path);
 137
 138 /**
 139  * Set the feature bits the vhost-user driver supports.
 140  *
 141  * @param path
 142  *  The vhost-user socket file path
 143  * @param features
 144  *  Supported features
 145  * @return
 146  *  0 on success, -1 on failure
 147  */
 148 int rte_vhost_driver_set_features(const char *path, uint64_t features);
 149
 150 /**
 151  * Enable vhost-user driver features.
 152  *
 153  * Note that
 154  * - the param features should be a subset of the feature bits provided
 155  *   by rte_vhost_driver_set_features().
 156  * - it must be invoked before vhost-user negotiation starts.
 157  *
 158  * @param path
 159  *  The vhost-user socket file path
 160  * @param features
 161  *  Features to enable
 162  * @return
 163  *  0 on success, -1 on failure
 164  */
 165 int rte_vhost_driver_enable_features(const char *path, uint64_t features);
 166
 167 /**
 168  * Disable vhost-user driver features.
 169  *
 170  * The two notes at rte_vhost_driver_enable_features() also apply here.
 171  *
 172  * @param path
 173  *  The vhost-user socket file path
 174  * @param features
 175  *  Features to disable
 176  * @return
 177  *  0 on success, -1 on failure
 178  */
 179 int rte_vhost_driver_disable_features(const char *path, uint64_t features);
 180
 181 /**
 182  * Get the feature bits before feature negotiation.
 183  *
 184  * @param path
 185  *  The vhost-user socket file path
 186  * @param features
 187  *  A pointer to store the queried feature bits
 188  * @return
 189  *  0 on success, -1 on failure
 190  */
 191 int rte_vhost_driver_get_features(const char *path, uint64_t *features);
 192
 193 /**
 194  * Get the feature bits after negotiation
 195  *
 196  * @param vid
 197  *  Vhost device ID
 198  * @param features
 199  *  A pointer to store the queried feature bits
 200  * @return
 201  *  0 on success, -1 on failure
 202  */
 203 int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
 204
 205 /* Register callbacks. */
 206 int rte_vhost_driver_callback_register(const char *path,
 207         struct virtio_net_device_ops const * const ops);
 208 /* Start vhost driver session blocking loop. */
 209 int rte_vhost_driver_session_start(void);
 210
 211 /**
 212  * Get the MTU value of the device if set in QEMU.
 213  *
 214  * @param vid
 215  *  virtio-net device ID
 216  * @param mtu
 217  *  The variable to store the MTU value
 218  *
 219  * @return
 220  *  0: success
 221  *  -EAGAIN: device not yet started
 222  *  -ENOTSUP: device does not support MTU feature
 223  */
 224 int rte_vhost_get_mtu(int vid, uint16_t *mtu);
 225
 226 /**
 227  * Get the numa node from which the virtio net device's memory
 228  * is allocated.
 229  *
 230  * @param vid
 231  *  virtio-net device ID
 232  *
 233  * @return
 234  *  The numa node, -1 on failure
 235  */
 236 int rte_vhost_get_numa_node(int vid);
 237
 238 /**
 239  * @deprecated
 240  * Get the number of queues the device supports.
 241  *
 242  * Note this function is deprecated, as it returns a queue pair number,
 243  * which is virtio-net specific. Instead, rte_vhost_get_vring_num should
 244  * be used.
 245  *
 246  * @param vid
 247  *  virtio-net device ID
 248  *
 249  * @return
 250  *  The number of queues, 0 on failure
 251  */
 252 __rte_deprecated
 253 uint32_t rte_vhost_get_queue_num(int vid);
 254
 255 /**
 256  * Get the number of vrings the device supports.
 257  *
 258  * @param vid
 259  *  vhost device ID
 260  *
 261  * @return
 262  *  The number of vrings, 0 on failure
 263  */
 264 uint16_t rte_vhost_get_vring_num(int vid);
 265
 266 /**
 267  * Get the virtio net device's ifname, which is the vhost-user socket
 268  * file path.
 269  *
 270  * @param vid
 271  *  virtio-net device ID
 272  * @param buf
 273  *  The buffer to stored the queried ifname
 274  * @param len
 275  *  The length of buf
 276  *
 277  * @return
 278  *  0 on success, -1 on failure
 279  */
 280 int rte_vhost_get_ifname(int vid, char *buf, size_t len);
 281
 282 /**
 283  * Get how many avail entries are left in the queue
 284  *
 285  * @param vid
 286  *  virtio-net device ID
 287  * @param queue_id
 288  *  virtio queue index
 289  *
 290  * @return
 291  *  num of avail entires left
 292  */
 293 uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id);
 294
 295 /**
 296  * This function adds buffers to the virtio devices RX virtqueue. Buffers can
 297  * be received from the physical port or from another virtual device. A packet
 298  * count is returned to indicate the number of packets that were succesfully
 299  * added to the RX queue.
 300  * @param vid
 301  *  virtio-net device ID
 302  * @param queue_id
 303  *  virtio queue index in mq case
 304  * @param pkts
 305  *  array to contain packets to be enqueued
 306  * @param count
 307  *  packets num to be enqueued
 308  * @return
 309  *  num of packets enqueued
 310  */
 311 uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id,
 312         struct rte_mbuf **pkts, uint16_t count);
 313
 314 /**
 315  * This function gets guest buffers from the virtio device TX virtqueue,
 316  * construct host mbufs, copies guest buffer content to host mbufs and
 317  * store them in pkts to be processed.
 318  * @param vid
 319  *  virtio-net device
 320  * @param queue_id
 321  *  virtio queue index in mq case
 322  * @param mbuf_pool
 323  *  mbuf_pool where host mbuf is allocated.
 324  * @param pkts
 325  *  array to contain packets to be dequeued
 326  * @param count
 327  *  packets num to be dequeued
 328  * @return
 329  *  num of packets dequeued
 330  */
 331 uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id,
 332         struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count);
 333
 334 /**
 335  * Get guest mem table: a list of memory regions.
 336  *
 337  * An rte_vhost_vhost_memory object will be allocated internaly, to hold the
 338  * guest memory regions. Application should free it at destroy_device()
 339  * callback.
 340  *
 341  * @param vid
 342  *  vhost device ID
 343  * @param mem
 344  *  To store the returned mem regions
 345  * @return
 346  *  0 on success, -1 on failure
 347  */
 348 int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem);
 349
 350 /**
 351  * Get guest vring info, including the vring address, vring size, etc.
 352  *
 353  * @param vid
 354  *  vhost device ID
 355  * @param vring_idx
 356  *  vring index
 357  * @param vring
 358  *  the structure to hold the requested vring info
 359  * @return
 360  *  0 on success, -1 on failure
 361  */
 362 int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx,
 363                               struct rte_vhost_vring *vring);
 364
 365 #endif /* _VIRTIO_NET_H_ */