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