Branch data Line data Source code
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 <stdbool.h>
14 : : #include <stdint.h>
15 : : #include <sys/eventfd.h>
16 : :
17 : : #include <rte_compat.h>
18 : : #include <rte_memory.h>
19 : : #include <rte_mempool.h>
20 : :
21 : : #ifndef __cplusplus
22 : : /* These are not C++-aware. */
23 : : #include <linux/vhost.h>
24 : : #include <linux/virtio_ring.h>
25 : : #include <linux/virtio_net.h>
26 : : #endif
27 : :
28 : : #ifdef __cplusplus
29 : : extern "C" {
30 : : #endif
31 : :
32 : : #define RTE_VHOST_USER_CLIENT (1ULL << 0)
33 : : #define RTE_VHOST_USER_NO_RECONNECT (1ULL << 1)
34 : : #define RTE_VHOST_USER_RESERVED_1 (1ULL << 2)
35 : : #define RTE_VHOST_USER_IOMMU_SUPPORT (1ULL << 3)
36 : : #define RTE_VHOST_USER_POSTCOPY_SUPPORT (1ULL << 4)
37 : : /* support mbuf with external buffer attached */
38 : : #define RTE_VHOST_USER_EXTBUF_SUPPORT (1ULL << 5)
39 : : /* support only linear buffers (no chained mbufs) */
40 : : #define RTE_VHOST_USER_LINEARBUF_SUPPORT (1ULL << 6)
41 : : #define RTE_VHOST_USER_ASYNC_COPY (1ULL << 7)
42 : : #define RTE_VHOST_USER_NET_COMPLIANT_OL_FLAGS (1ULL << 8)
43 : : #define RTE_VHOST_USER_NET_STATS_ENABLE (1ULL << 9)
44 : : #define RTE_VHOST_USER_ASYNC_CONNECT (1ULL << 10)
45 : :
46 : : /* Features. */
47 : : #ifndef VIRTIO_NET_F_GUEST_ANNOUNCE
48 : : #define VIRTIO_NET_F_GUEST_ANNOUNCE 21
49 : : #endif
50 : :
51 : : #ifndef VIRTIO_NET_F_MQ
52 : : #define VIRTIO_NET_F_MQ 22
53 : : #endif
54 : :
55 : : #ifndef VIRTIO_NET_F_MTU
56 : : #define VIRTIO_NET_F_MTU 3
57 : : #endif
58 : :
59 : : #ifndef VIRTIO_F_ANY_LAYOUT
60 : : #define VIRTIO_F_ANY_LAYOUT 27
61 : : #endif
62 : :
63 : : /** Protocol features. */
64 : : #ifndef VHOST_USER_PROTOCOL_F_MQ
65 : : #define VHOST_USER_PROTOCOL_F_MQ 0
66 : : #endif
67 : :
68 : : #ifndef VHOST_USER_PROTOCOL_F_LOG_SHMFD
69 : : #define VHOST_USER_PROTOCOL_F_LOG_SHMFD 1
70 : : #endif
71 : :
72 : : #ifndef VHOST_USER_PROTOCOL_F_RARP
73 : : #define VHOST_USER_PROTOCOL_F_RARP 2
74 : : #endif
75 : :
76 : : #ifndef VHOST_USER_PROTOCOL_F_REPLY_ACK
77 : : #define VHOST_USER_PROTOCOL_F_REPLY_ACK 3
78 : : #endif
79 : :
80 : : #ifndef VHOST_USER_PROTOCOL_F_NET_MTU
81 : : #define VHOST_USER_PROTOCOL_F_NET_MTU 4
82 : : #endif
83 : :
84 : : #ifndef VHOST_USER_PROTOCOL_F_BACKEND_REQ
85 : : #define VHOST_USER_PROTOCOL_F_BACKEND_REQ 5
86 : : #endif
87 : :
88 : : #ifndef VHOST_USER_PROTOCOL_F_CRYPTO_SESSION
89 : : #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7
90 : : #endif
91 : :
92 : : #ifndef VHOST_USER_PROTOCOL_F_PAGEFAULT
93 : : #define VHOST_USER_PROTOCOL_F_PAGEFAULT 8
94 : : #endif
95 : :
96 : : #ifndef VHOST_USER_PROTOCOL_F_CONFIG
97 : : #define VHOST_USER_PROTOCOL_F_CONFIG 9
98 : : #endif
99 : :
100 : : #ifndef VHOST_USER_PROTOCOL_F_BACKEND_SEND_FD
101 : : #define VHOST_USER_PROTOCOL_F_BACKEND_SEND_FD 10
102 : : #endif
103 : :
104 : : #ifndef VHOST_USER_PROTOCOL_F_HOST_NOTIFIER
105 : : #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER 11
106 : : #endif
107 : :
108 : : #ifndef VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD
109 : : #define VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD 12
110 : : #endif
111 : :
112 : : #ifndef VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS
113 : : #define VHOST_USER_PROTOCOL_F_CONFIGURE_MEM_SLOTS 15
114 : : #endif
115 : :
116 : : #ifndef VHOST_USER_PROTOCOL_F_STATUS
117 : : #define VHOST_USER_PROTOCOL_F_STATUS 16
118 : : #endif
119 : :
120 : : /** Indicate whether protocol features negotiation is supported. */
121 : : #ifndef VHOST_USER_F_PROTOCOL_FEATURES
122 : : #define VHOST_USER_F_PROTOCOL_FEATURES 30
123 : : #endif
124 : :
125 : : #define RTE_MAX_VHOST_DEVICE 1024
126 : :
127 : : #define RTE_VHOST_VDPA_DEVICE_TYPE_NET 0
128 : : #define RTE_VHOST_VDPA_DEVICE_TYPE_BLK 1
129 : :
130 : : struct rte_vdpa_device;
131 : :
132 : : /**
133 : : * Information relating to memory regions including offsets to
134 : : * addresses in QEMUs memory file.
135 : : */
136 : : struct rte_vhost_mem_region {
137 : : uint64_t guest_phys_addr;
138 : : uint64_t guest_user_addr;
139 : : uint64_t host_user_addr;
140 : : uint64_t size;
141 : : void *mmap_addr;
142 : : uint64_t mmap_size;
143 : : int fd;
144 : : };
145 : :
146 : : /**
147 : : * Memory structure includes region and mapping information.
148 : : */
149 : : struct rte_vhost_memory {
150 : : uint32_t nregions;
151 : : struct rte_vhost_mem_region regions[];
152 : : };
153 : :
154 : : struct rte_vhost_inflight_desc_split {
155 : : uint8_t inflight;
156 : : uint8_t padding[5];
157 : : uint16_t next;
158 : : uint64_t counter;
159 : : };
160 : :
161 : : struct rte_vhost_inflight_info_split {
162 : : uint64_t features;
163 : : uint16_t version;
164 : : uint16_t desc_num;
165 : : uint16_t last_inflight_io;
166 : : uint16_t used_idx;
167 : : struct rte_vhost_inflight_desc_split desc[];
168 : : };
169 : :
170 : : struct rte_vhost_inflight_desc_packed {
171 : : uint8_t inflight;
172 : : uint8_t padding;
173 : : uint16_t next;
174 : : uint16_t last;
175 : : uint16_t num;
176 : : uint64_t counter;
177 : : uint16_t id;
178 : : uint16_t flags;
179 : : uint32_t len;
180 : : uint64_t addr;
181 : : };
182 : :
183 : : struct rte_vhost_inflight_info_packed {
184 : : uint64_t features;
185 : : uint16_t version;
186 : : uint16_t desc_num;
187 : : uint16_t free_head;
188 : : uint16_t old_free_head;
189 : : uint16_t used_idx;
190 : : uint16_t old_used_idx;
191 : : uint8_t used_wrap_counter;
192 : : uint8_t old_used_wrap_counter;
193 : : uint8_t padding[7];
194 : : struct rte_vhost_inflight_desc_packed desc[];
195 : : };
196 : :
197 : : struct rte_vhost_resubmit_desc {
198 : : uint16_t index;
199 : : uint64_t counter;
200 : : };
201 : :
202 : : struct rte_vhost_resubmit_info {
203 : : struct rte_vhost_resubmit_desc *resubmit_list;
204 : : uint16_t resubmit_num;
205 : : };
206 : :
207 : : struct rte_vhost_ring_inflight {
208 : : union {
209 : : struct rte_vhost_inflight_info_split *inflight_split;
210 : : struct rte_vhost_inflight_info_packed *inflight_packed;
211 : : };
212 : :
213 : : struct rte_vhost_resubmit_info *resubmit_inflight;
214 : : };
215 : :
216 : : struct rte_vhost_vring {
217 : : union {
218 : : struct vring_desc *desc;
219 : : struct vring_packed_desc *desc_packed;
220 : : };
221 : : union {
222 : : struct vring_avail *avail;
223 : : struct vring_packed_desc_event *driver_event;
224 : : };
225 : : union {
226 : : struct vring_used *used;
227 : : struct vring_packed_desc_event *device_event;
228 : : };
229 : : uint64_t log_guest_addr;
230 : :
231 : : /** Deprecated, use rte_vhost_vring_call() instead. */
232 : : int callfd;
233 : :
234 : : int kickfd;
235 : : uint16_t size;
236 : : };
237 : :
238 : : /**
239 : : * Possible results of the vhost user message handling callbacks
240 : : */
241 : : enum rte_vhost_msg_result {
242 : : /* Message handling failed */
243 : : RTE_VHOST_MSG_RESULT_ERR = -1,
244 : : /* Message handling successful */
245 : : RTE_VHOST_MSG_RESULT_OK = 0,
246 : : /* Message handling successful and reply prepared */
247 : : RTE_VHOST_MSG_RESULT_REPLY = 1,
248 : : /* Message not handled */
249 : : RTE_VHOST_MSG_RESULT_NOT_HANDLED,
250 : : };
251 : :
252 : : /**
253 : : * Function prototype for the vhost backend to handle specific vhost user
254 : : * messages.
255 : : *
256 : : * @param vid
257 : : * vhost device id
258 : : * @param msg
259 : : * Message pointer.
260 : : * @return
261 : : * RTE_VHOST_MSG_RESULT_OK on success,
262 : : * RTE_VHOST_MSG_RESULT_REPLY on success with reply,
263 : : * RTE_VHOST_MSG_RESULT_ERR on failure,
264 : : * RTE_VHOST_MSG_RESULT_NOT_HANDLED if message was not handled.
265 : : */
266 : : typedef enum rte_vhost_msg_result (*rte_vhost_msg_handle)(int vid, void *msg);
267 : :
268 : : /**
269 : : * Optional vhost user message handlers.
270 : : */
271 : : struct rte_vhost_user_extern_ops {
272 : : /* Called prior to the frontend message handling. */
273 : : rte_vhost_msg_handle pre_msg_handle;
274 : : /* Called after the frontend message handling. */
275 : : rte_vhost_msg_handle post_msg_handle;
276 : : };
277 : :
278 : : /**
279 : : * Device and vring operations.
280 : : */
281 : : struct rte_vhost_device_ops {
282 : : int (*new_device)(int vid); /**< Add device. */
283 : : void (*destroy_device)(int vid); /**< Remove device. */
284 : :
285 : : int (*vring_state_changed)(int vid, uint16_t queue_id, int enable); /**< triggered when a vring is enabled or disabled */
286 : :
287 : : /**
288 : : * Features could be changed after the feature negotiation.
289 : : * For example, VHOST_F_LOG_ALL will be set/cleared at the
290 : : * start/end of live migration, respectively. This callback
291 : : * is used to inform the application on such change.
292 : : */
293 : : int (*features_changed)(int vid, uint64_t features);
294 : :
295 : : int (*new_connection)(int vid);
296 : : void (*destroy_connection)(int vid);
297 : :
298 : : /**
299 : : * This callback gets called each time a guest gets notified
300 : : * about waiting packets. This is the interrupt handling through
301 : : * the eventfd_write(callfd), which can be used for counting these
302 : : * "slow" syscalls.
303 : : */
304 : : void (*guest_notified)(int vid);
305 : :
306 : : /**
307 : : * If this callback is registered, notification to the guest can
308 : : * be handled by the front-end calling rte_vhost_notify_guest().
309 : : * If it's not handled, 'false' should be returned. This can be used
310 : : * to remove the "slow" eventfd_write() syscall from the datapath.
311 : : */
312 : : bool (*guest_notify)(int vid, uint16_t queue_id);
313 : : };
314 : :
315 : : /**
316 : : * Power monitor condition.
317 : : */
318 : : struct rte_vhost_power_monitor_cond {
319 : : /**< Address to monitor for changes */
320 : : volatile void *addr;
321 : : /**< If the `mask` is non-zero, location pointed
322 : : * to by `addr` will be read and masked, then
323 : : * compared with this value.
324 : : */
325 : : uint64_t val;
326 : : /**< 64-bit mask to extract value read from `addr` */
327 : : uint64_t mask;
328 : : /**< Data size (in bytes) that will be read from the
329 : : * monitored memory location (`addr`).
330 : : */
331 : : uint8_t size;
332 : : /**< If 1, and masked value that read from 'addr' equals
333 : : * 'val', the driver should skip core sleep. If 0, and
334 : : * masked value that read from 'addr' does not equal 'val',
335 : : * the driver should skip core sleep.
336 : : */
337 : : uint8_t match;
338 : : };
339 : :
340 : : /** Maximum name length for the statistics counters */
341 : : #define RTE_VHOST_STATS_NAME_SIZE 64
342 : :
343 : : /**
344 : : * Vhost virtqueue statistics structure
345 : : *
346 : : * This structure is used by rte_vhost_vring_stats_get() to provide
347 : : * virtqueue statistics to the calling application.
348 : : * It maps a name ID, corresponding to an index in the array returned
349 : : * by rte_vhost_vring_stats_get_names(), to a statistic value.
350 : : */
351 : : struct rte_vhost_stat {
352 : : uint64_t id; /**< The index in xstats name array. */
353 : : uint64_t value; /**< The statistic counter value. */
354 : : };
355 : :
356 : : /**
357 : : * Vhost virtqueue statistic name element
358 : : *
359 : : * This structure is used by rte_vhost_vring_stats_get_names() to
360 : : * provide virtqueue statistics names to the calling application.
361 : : */
362 : : struct rte_vhost_stat_name {
363 : : char name[RTE_VHOST_STATS_NAME_SIZE]; /**< The statistic name. */
364 : : };
365 : :
366 : : /**
367 : : * Convert guest physical address to host virtual address
368 : : *
369 : : * @param mem
370 : : * the guest memory regions
371 : : * @param gpa
372 : : * the guest physical address for querying
373 : : * @param len
374 : : * the size of the requested area to map, updated with actual size mapped
375 : : * @return
376 : : * the host virtual address on success, 0 on failure
377 : : */
378 : : static __rte_always_inline uint64_t
379 : : rte_vhost_va_from_guest_pa(struct rte_vhost_memory *mem,
380 : : uint64_t gpa, uint64_t *len)
381 : : {
382 : : struct rte_vhost_mem_region *r;
383 : : uint32_t i;
384 : :
385 [ # # # # : 0 : for (i = 0; i < mem->nregions; i++) {
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # #
# ]
386 : : r = &mem->regions[i];
387 [ # # # # : 0 : if (gpa >= r->guest_phys_addr &&
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # #
# ]
388 [ # # # # : 0 : gpa < r->guest_phys_addr + r->size) {
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # #
# ]
389 : :
390 [ # # # # : 0 : if (unlikely(*len > r->guest_phys_addr + r->size - gpa))
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # # #
# # # #
# ]
391 : 0 : *len = r->guest_phys_addr + r->size - gpa;
392 : :
393 : 0 : return gpa - r->guest_phys_addr +
394 : 0 : r->host_user_addr;
395 : : }
396 : : }
397 : 0 : *len = 0;
398 : :
399 : 0 : return 0;
400 : : }
401 : :
402 : : #define RTE_VHOST_NEED_LOG(features) ((features) & (1ULL << VHOST_F_LOG_ALL))
403 : :
404 : : /**
405 : : * Log the memory write start with given address.
406 : : *
407 : : * This function only need be invoked when the live migration starts.
408 : : * Therefore, we won't need call it at all in the most of time. For
409 : : * making the performance impact be minimum, it's suggested to do a
410 : : * check before calling it:
411 : : *
412 : : * if (unlikely(RTE_VHOST_NEED_LOG(features)))
413 : : * rte_vhost_log_write(vid, addr, len);
414 : : *
415 : : * @param vid
416 : : * vhost device ID
417 : : * @param addr
418 : : * the starting address for write (in guest physical address space)
419 : : * @param len
420 : : * the length to write
421 : : */
422 : : void rte_vhost_log_write(int vid, uint64_t addr, uint64_t len);
423 : :
424 : : /**
425 : : * Log the used ring update start at given offset.
426 : : *
427 : : * Same as rte_vhost_log_write, it's suggested to do a check before
428 : : * calling it:
429 : : *
430 : : * if (unlikely(RTE_VHOST_NEED_LOG(features)))
431 : : * rte_vhost_log_used_vring(vid, vring_idx, offset, len);
432 : : *
433 : : * @param vid
434 : : * vhost device ID
435 : : * @param vring_idx
436 : : * the vring index
437 : : * @param offset
438 : : * the offset inside the used ring
439 : : * @param len
440 : : * the length to write
441 : : */
442 : : void rte_vhost_log_used_vring(int vid, uint16_t vring_idx,
443 : : uint64_t offset, uint64_t len);
444 : :
445 : : int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable);
446 : :
447 : : /**
448 : : * @warning
449 : : * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
450 : : *
451 : : * Inject the offloaded interrupt into the vhost device's queue.
452 : : * @see guest_notify vhost device operation
453 : : *
454 : : * @param vid
455 : : * vhost device ID
456 : : * @param queue_id
457 : : * virtio queue index
458 : : */
459 : : __rte_experimental
460 : : void rte_vhost_notify_guest(int vid, uint16_t queue_id);
461 : :
462 : : /**
463 : : * Register vhost driver. path could be different for multiple
464 : : * instance support.
465 : : */
466 : : int rte_vhost_driver_register(const char *path, uint64_t flags);
467 : :
468 : : /* Unregister vhost driver. This is only meaningful to vhost user. */
469 : : int rte_vhost_driver_unregister(const char *path);
470 : :
471 : : /**
472 : : * Set the vdpa device id, enforce single connection per socket
473 : : *
474 : : * @param path
475 : : * The vhost-user socket file path
476 : : * @param dev
477 : : * vDPA device pointer
478 : : * @return
479 : : * 0 on success, -1 on failure
480 : : */
481 : : int
482 : : rte_vhost_driver_attach_vdpa_device(const char *path,
483 : : struct rte_vdpa_device *dev);
484 : :
485 : : /**
486 : : * Unset the vdpa device id
487 : : *
488 : : * @param path
489 : : * The vhost-user socket file path
490 : : * @return
491 : : * 0 on success, -1 on failure
492 : : */
493 : : int
494 : : rte_vhost_driver_detach_vdpa_device(const char *path);
495 : :
496 : : /**
497 : : * Get the device id
498 : : *
499 : : * @param path
500 : : * The vhost-user socket file path
501 : : * @return
502 : : * vDPA device pointer, NULL on failure
503 : : */
504 : : struct rte_vdpa_device *
505 : : rte_vhost_driver_get_vdpa_device(const char *path);
506 : :
507 : : /**
508 : : * Get the device type of the vdpa device.
509 : : *
510 : : * @param path
511 : : * The vhost-user socket file path
512 : : * @param type
513 : : * the device type of the vdpa device
514 : : * @return
515 : : * 0 on success, -1 on failure
516 : : */
517 : : int
518 : : rte_vhost_driver_get_vdpa_dev_type(const char *path, uint32_t *type);
519 : :
520 : : /**
521 : : * Set the feature bits the vhost-user driver supports.
522 : : *
523 : : * @param path
524 : : * The vhost-user socket file path
525 : : * @param features
526 : : * Supported features
527 : : * @return
528 : : * 0 on success, -1 on failure
529 : : */
530 : : int rte_vhost_driver_set_features(const char *path, uint64_t features);
531 : :
532 : : /**
533 : : * Enable vhost-user driver features.
534 : : *
535 : : * Note that
536 : : * - the param features should be a subset of the feature bits provided
537 : : * by rte_vhost_driver_set_features().
538 : : * - it must be invoked before vhost-user negotiation starts.
539 : : *
540 : : * @param path
541 : : * The vhost-user socket file path
542 : : * @param features
543 : : * Features to enable
544 : : * @return
545 : : * 0 on success, -1 on failure
546 : : */
547 : : int rte_vhost_driver_enable_features(const char *path, uint64_t features);
548 : :
549 : : /**
550 : : * Disable vhost-user driver features.
551 : : *
552 : : * The two notes at rte_vhost_driver_enable_features() also apply here.
553 : : *
554 : : * @param path
555 : : * The vhost-user socket file path
556 : : * @param features
557 : : * Features to disable
558 : : * @return
559 : : * 0 on success, -1 on failure
560 : : */
561 : : int rte_vhost_driver_disable_features(const char *path, uint64_t features);
562 : :
563 : : /**
564 : : * Get the feature bits before feature negotiation.
565 : : *
566 : : * @param path
567 : : * The vhost-user socket file path
568 : : * @param features
569 : : * A pointer to store the queried feature bits
570 : : * @return
571 : : * 0 on success, -1 on failure
572 : : */
573 : : int rte_vhost_driver_get_features(const char *path, uint64_t *features);
574 : :
575 : : /**
576 : : * Set the protocol feature bits before feature negotiation.
577 : : *
578 : : * @param path
579 : : * The vhost-user socket file path
580 : : * @param protocol_features
581 : : * Supported protocol features
582 : : * @return
583 : : * 0 on success, -1 on failure
584 : : */
585 : : int
586 : : rte_vhost_driver_set_protocol_features(const char *path,
587 : : uint64_t protocol_features);
588 : :
589 : : /**
590 : : * Get the protocol feature bits before feature negotiation.
591 : : *
592 : : * @param path
593 : : * The vhost-user socket file path
594 : : * @param protocol_features
595 : : * A pointer to store the queried protocol feature bits
596 : : * @return
597 : : * 0 on success, -1 on failure
598 : : */
599 : : int
600 : : rte_vhost_driver_get_protocol_features(const char *path,
601 : : uint64_t *protocol_features);
602 : :
603 : : /**
604 : : * Get the queue number bits before feature negotiation.
605 : : *
606 : : * @param path
607 : : * The vhost-user socket file path
608 : : * @param queue_num
609 : : * A pointer to store the queried queue number bits
610 : : * @return
611 : : * 0 on success, -1 on failure
612 : : */
613 : : int
614 : : rte_vhost_driver_get_queue_num(const char *path, uint32_t *queue_num);
615 : :
616 : : /**
617 : : * Set the maximum number of queue pairs supported by the device.
618 : : * The value set is ignored for Vhost-user backends. It is only taken into
619 : : * account with VDUSE backends.
620 : : *
621 : : * @param path
622 : : * The vhost-user socket file path
623 : : * @param max_queue_pairs
624 : : * The maximum number of queue pairs
625 : : * @return
626 : : * 0 on success, -1 on failure
627 : : */
628 : : int
629 : : rte_vhost_driver_set_max_queue_num(const char *path, uint32_t max_queue_pairs);
630 : :
631 : : /**
632 : : * Get the feature bits after negotiation
633 : : *
634 : : * @param vid
635 : : * Vhost device ID
636 : : * @param features
637 : : * A pointer to store the queried feature bits
638 : : * @return
639 : : * 0 on success, -1 on failure
640 : : */
641 : : int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
642 : :
643 : : /**
644 : : * Get the protocol feature bits after negotiation
645 : : *
646 : : * @param vid
647 : : * Vhost device ID
648 : : * @param protocol_features
649 : : * A pointer to store the queried protocol feature bits
650 : : * @return
651 : : * 0 on success, -1 on failure
652 : : */
653 : : int
654 : : rte_vhost_get_negotiated_protocol_features(int vid,
655 : : uint64_t *protocol_features);
656 : :
657 : : /* Register callbacks. */
658 : : int rte_vhost_driver_callback_register(const char *path,
659 : : struct rte_vhost_device_ops const * const ops);
660 : :
661 : : /**
662 : : *
663 : : * Start the vhost-user driver.
664 : : *
665 : : * This function triggers the vhost-user negotiation.
666 : : *
667 : : * @param path
668 : : * The vhost-user socket file path
669 : : * @return
670 : : * 0 on success, -1 on failure
671 : : */
672 : : int rte_vhost_driver_start(const char *path);
673 : :
674 : : /**
675 : : * Get the MTU value of the device if set in QEMU.
676 : : *
677 : : * @param vid
678 : : * virtio-net device ID
679 : : * @param mtu
680 : : * The variable to store the MTU value
681 : : *
682 : : * @return
683 : : * 0: success
684 : : * -EAGAIN: device not yet started
685 : : * -ENOTSUP: device does not support MTU feature
686 : : */
687 : : int rte_vhost_get_mtu(int vid, uint16_t *mtu);
688 : :
689 : : /**
690 : : * Get the numa node from which the virtio net device's memory
691 : : * is allocated.
692 : : *
693 : : * @param vid
694 : : * vhost device ID
695 : : *
696 : : * @return
697 : : * The numa node, -1 on failure
698 : : */
699 : : int rte_vhost_get_numa_node(int vid);
700 : :
701 : : /**
702 : : * Get the number of vrings the device supports.
703 : : *
704 : : * @param vid
705 : : * vhost device ID
706 : : *
707 : : * @return
708 : : * The number of vrings, 0 on failure
709 : : */
710 : : uint16_t rte_vhost_get_vring_num(int vid);
711 : :
712 : : /**
713 : : * Get the virtio net device's ifname, which is the vhost-user socket
714 : : * file path.
715 : : *
716 : : * @param vid
717 : : * vhost device ID
718 : : * @param buf
719 : : * The buffer to stored the queried ifname
720 : : * @param len
721 : : * The length of buf
722 : : *
723 : : * @return
724 : : * 0 on success, -1 on failure
725 : : */
726 : : int rte_vhost_get_ifname(int vid, char *buf, size_t len);
727 : :
728 : : /**
729 : : * Get how many avail entries are left in the queue
730 : : *
731 : : * @param vid
732 : : * vhost device ID
733 : : * @param queue_id
734 : : * virtio queue index
735 : : *
736 : : * @return
737 : : * num of avail entries left
738 : : */
739 : : uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id);
740 : :
741 : : struct rte_mbuf;
742 : : struct rte_mempool;
743 : : /**
744 : : * This function adds buffers to the virtio devices RX virtqueue. Buffers can
745 : : * be received from the physical port or from another virtual device. A packet
746 : : * count is returned to indicate the number of packets that were successfully
747 : : * added to the RX queue.
748 : : * @param vid
749 : : * vhost device ID
750 : : * @param queue_id
751 : : * virtio queue index in mq case
752 : : * @param pkts
753 : : * array to contain packets to be enqueued
754 : : * @param count
755 : : * packets num to be enqueued
756 : : * @return
757 : : * num of packets enqueued
758 : : */
759 : : uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id,
760 : : struct rte_mbuf **pkts, uint16_t count);
761 : :
762 : : /**
763 : : * This function gets guest buffers from the virtio device TX virtqueue,
764 : : * construct host mbufs, copies guest buffer content to host mbufs and
765 : : * store them in pkts to be processed.
766 : : * @param vid
767 : : * vhost device ID
768 : : * @param queue_id
769 : : * virtio queue index in mq case
770 : : * @param mbuf_pool
771 : : * mbuf_pool where host mbuf is allocated.
772 : : * @param pkts
773 : : * array to contain packets to be dequeued
774 : : * @param count
775 : : * packets num to be dequeued
776 : : * @return
777 : : * num of packets dequeued
778 : : */
779 : : uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id,
780 : : struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count);
781 : :
782 : : /**
783 : : * Get guest mem table: a list of memory regions.
784 : : *
785 : : * An rte_vhost_vhost_memory object will be allocated internally, to hold the
786 : : * guest memory regions. Application should free it at destroy_device()
787 : : * callback.
788 : : *
789 : : * @param vid
790 : : * vhost device ID
791 : : * @param mem
792 : : * To store the returned mem regions
793 : : * @return
794 : : * 0 on success, -1 on failure
795 : : */
796 : : int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem);
797 : :
798 : : /**
799 : : * Get guest vring info, including the vring address, vring size, etc.
800 : : *
801 : : * @param vid
802 : : * vhost device ID
803 : : * @param vring_idx
804 : : * vring index
805 : : * @param vring
806 : : * the structure to hold the requested vring info
807 : : * @return
808 : : * 0 on success, -1 on failure
809 : : */
810 : : int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx,
811 : : struct rte_vhost_vring *vring);
812 : :
813 : : /**
814 : : * Get guest inflight vring info, including inflight ring and resubmit list.
815 : : *
816 : : * @param vid
817 : : * vhost device ID
818 : : * @param vring_idx
819 : : * vring index
820 : : * @param vring
821 : : * the structure to hold the requested inflight vring info
822 : : * @return
823 : : * 0 on success, -1 on failure
824 : : */
825 : : int
826 : : rte_vhost_get_vhost_ring_inflight(int vid, uint16_t vring_idx,
827 : : struct rte_vhost_ring_inflight *vring);
828 : :
829 : : /**
830 : : * Set split inflight descriptor.
831 : : *
832 : : * This function save descriptors that has been consumed in available
833 : : * ring
834 : : *
835 : : * @param vid
836 : : * vhost device ID
837 : : * @param vring_idx
838 : : * vring index
839 : : * @param idx
840 : : * inflight entry index
841 : : * @return
842 : : * 0 on success, -1 on failure
843 : : */
844 : : int
845 : : rte_vhost_set_inflight_desc_split(int vid, uint16_t vring_idx,
846 : : uint16_t idx);
847 : :
848 : : /**
849 : : * Set packed inflight descriptor and get corresponding inflight entry
850 : : *
851 : : * This function save descriptors that has been consumed
852 : : *
853 : : * @param vid
854 : : * vhost device ID
855 : : * @param vring_idx
856 : : * vring index
857 : : * @param head
858 : : * head of descriptors
859 : : * @param last
860 : : * last of descriptors
861 : : * @param inflight_entry
862 : : * corresponding inflight entry
863 : : * @return
864 : : * 0 on success, -1 on failure
865 : : */
866 : : int
867 : : rte_vhost_set_inflight_desc_packed(int vid, uint16_t vring_idx,
868 : : uint16_t head, uint16_t last, uint16_t *inflight_entry);
869 : :
870 : : /**
871 : : * Save the head of list that the last batch of used descriptors.
872 : : *
873 : : * @param vid
874 : : * vhost device ID
875 : : * @param vring_idx
876 : : * vring index
877 : : * @param idx
878 : : * descriptor entry index
879 : : * @return
880 : : * 0 on success, -1 on failure
881 : : */
882 : : int
883 : : rte_vhost_set_last_inflight_io_split(int vid,
884 : : uint16_t vring_idx, uint16_t idx);
885 : :
886 : : /**
887 : : * Update the inflight free_head, used_idx and used_wrap_counter.
888 : : *
889 : : * This function will update status first before updating descriptors
890 : : * to used
891 : : *
892 : : * @param vid
893 : : * vhost device ID
894 : : * @param vring_idx
895 : : * vring index
896 : : * @param head
897 : : * head of descriptors
898 : : * @return
899 : : * 0 on success, -1 on failure
900 : : */
901 : : int
902 : : rte_vhost_set_last_inflight_io_packed(int vid,
903 : : uint16_t vring_idx, uint16_t head);
904 : :
905 : : /**
906 : : * Clear the split inflight status.
907 : : *
908 : : * @param vid
909 : : * vhost device ID
910 : : * @param vring_idx
911 : : * vring index
912 : : * @param last_used_idx
913 : : * last used idx of used ring
914 : : * @param idx
915 : : * inflight entry index
916 : : * @return
917 : : * 0 on success, -1 on failure
918 : : */
919 : : int
920 : : rte_vhost_clr_inflight_desc_split(int vid, uint16_t vring_idx,
921 : : uint16_t last_used_idx, uint16_t idx);
922 : :
923 : : /**
924 : : * Clear the packed inflight status.
925 : : *
926 : : * @param vid
927 : : * vhost device ID
928 : : * @param vring_idx
929 : : * vring index
930 : : * @param head
931 : : * inflight entry index
932 : : * @return
933 : : * 0 on success, -1 on failure
934 : : */
935 : : int
936 : : rte_vhost_clr_inflight_desc_packed(int vid, uint16_t vring_idx,
937 : : uint16_t head);
938 : :
939 : : /**
940 : : * Notify the guest that used descriptors have been added to the vring. This
941 : : * function acts as a memory barrier.
942 : : *
943 : : * @param vid
944 : : * vhost device ID
945 : : * @param vring_idx
946 : : * vring index
947 : : * @return
948 : : * 0 on success, -1 on failure
949 : : */
950 : : int rte_vhost_vring_call(int vid, uint16_t vring_idx);
951 : :
952 : : /**
953 : : * Notify the guest that used descriptors have been added to the vring. This
954 : : * function acts as a memory barrier. This function will return -EAGAIN when
955 : : * vq's access lock is held by other thread, user should try again later.
956 : : *
957 : : * @param vid
958 : : * vhost device ID
959 : : * @param vring_idx
960 : : * vring index
961 : : * @return
962 : : * 0 on success, -1 on failure, -EAGAIN for another retry
963 : : */
964 : : int rte_vhost_vring_call_nonblock(int vid, uint16_t vring_idx);
965 : :
966 : : /**
967 : : * Get vhost RX queue avail count.
968 : : *
969 : : * @param vid
970 : : * vhost device ID
971 : : * @param qid
972 : : * virtio queue index in mq case
973 : : * @return
974 : : * num of desc available
975 : : */
976 : : uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid);
977 : :
978 : : /**
979 : : * Get power monitor address of the vhost device
980 : : *
981 : : * @param vid
982 : : * vhost device ID
983 : : * @param queue_id
984 : : * vhost queue ID
985 : : * @param pmc
986 : : * power monitor condition
987 : : * @return
988 : : * 0 on success, -1 on failure
989 : : */
990 : : int
991 : : rte_vhost_get_monitor_addr(int vid, uint16_t queue_id,
992 : : struct rte_vhost_power_monitor_cond *pmc);
993 : :
994 : : /**
995 : : * Get log base and log size of the vhost device
996 : : *
997 : : * @param vid
998 : : * vhost device ID
999 : : * @param log_base
1000 : : * vhost log base
1001 : : * @param log_size
1002 : : * vhost log size
1003 : : * @return
1004 : : * 0 on success, -1 on failure
1005 : : */
1006 : : int
1007 : : rte_vhost_get_log_base(int vid, uint64_t *log_base, uint64_t *log_size);
1008 : :
1009 : : /**
1010 : : * Get last_avail/used_idx of the vhost virtqueue
1011 : : *
1012 : : * @param vid
1013 : : * vhost device ID
1014 : : * @param queue_id
1015 : : * vhost queue index
1016 : : * @param last_avail_idx
1017 : : * vhost last_avail_idx to get
1018 : : * @param last_used_idx
1019 : : * vhost last_used_idx to get
1020 : : * @return
1021 : : * 0 on success, -1 on failure
1022 : : */
1023 : : int
1024 : : rte_vhost_get_vring_base(int vid, uint16_t queue_id,
1025 : : uint16_t *last_avail_idx, uint16_t *last_used_idx);
1026 : :
1027 : : /**
1028 : : * Get last_avail/last_used of the vhost virtqueue
1029 : : *
1030 : : * This function is designed for the reconnection and it's specific for
1031 : : * the packed ring as we can get the two parameters from the inflight
1032 : : * queueregion
1033 : : *
1034 : : * @param vid
1035 : : * vhost device ID
1036 : : * @param queue_id
1037 : : * vhost queue index
1038 : : * @param last_avail_idx
1039 : : * vhost last_avail_idx to get
1040 : : * @param last_used_idx
1041 : : * vhost last_used_idx to get
1042 : : * @return
1043 : : * 0 on success, -1 on failure
1044 : : */
1045 : : int
1046 : : rte_vhost_get_vring_base_from_inflight(int vid,
1047 : : uint16_t queue_id, uint16_t *last_avail_idx, uint16_t *last_used_idx);
1048 : :
1049 : : /**
1050 : : * Set last_avail/used_idx of the vhost virtqueue
1051 : : *
1052 : : * @param vid
1053 : : * vhost device ID
1054 : : * @param queue_id
1055 : : * vhost queue index
1056 : : * @param last_avail_idx
1057 : : * last_avail_idx to set
1058 : : * @param last_used_idx
1059 : : * last_used_idx to set
1060 : : * @return
1061 : : * 0 on success, -1 on failure
1062 : : */
1063 : : int
1064 : : rte_vhost_set_vring_base(int vid, uint16_t queue_id,
1065 : : uint16_t last_avail_idx, uint16_t last_used_idx);
1066 : :
1067 : : /**
1068 : : * Register external message handling callbacks
1069 : : *
1070 : : * @param vid
1071 : : * vhost device ID
1072 : : * @param ops
1073 : : * virtio external callbacks to register
1074 : : * @param ctx
1075 : : * additional context passed to the callbacks
1076 : : * @return
1077 : : * 0 on success, -1 on failure
1078 : : */
1079 : : int
1080 : : rte_vhost_extern_callback_register(int vid,
1081 : : struct rte_vhost_user_extern_ops const * const ops, void *ctx);
1082 : :
1083 : : /**
1084 : : * Get vdpa device id for vhost device.
1085 : : *
1086 : : * @param vid
1087 : : * vhost device id
1088 : : * @return
1089 : : * vDPA device pointer on success, NULL on failure
1090 : : */
1091 : : struct rte_vdpa_device *
1092 : : rte_vhost_get_vdpa_device(int vid);
1093 : :
1094 : : /**
1095 : : * Notify the guest that should get virtio configuration space from backend.
1096 : : *
1097 : : * @param vid
1098 : : * vhost device ID
1099 : : * @param need_reply
1100 : : * wait for the frontend response the status of this operation
1101 : : * @return
1102 : : * 0 on success, < 0 on failure
1103 : : */
1104 : : int
1105 : : rte_vhost_backend_config_change(int vid, bool need_reply);
1106 : :
1107 : : /**
1108 : : * Retrieve names of statistics of a Vhost virtqueue.
1109 : : *
1110 : : * There is an assumption that 'stat_names' and 'stats' arrays are matched
1111 : : * by array index: stats_names[i].name => stats[i].value
1112 : : *
1113 : : * @param vid
1114 : : * vhost device ID
1115 : : * @param queue_id
1116 : : * vhost queue index
1117 : : * @param name
1118 : : * array of at least size elements to be filled.
1119 : : * If set to NULL, the function returns the required number of elements.
1120 : : * @param size
1121 : : * The number of elements in stats_names array.
1122 : : * @return
1123 : : * - Success if greater than 0 and lower or equal to *size*. The return value
1124 : : * indicates the number of elements filled in the *names* array.
1125 : : * - Failure if greater than *size*. The return value indicates the number of
1126 : : * elements the *names* array that should be given to succeed.
1127 : : * - Failure if lower than 0. The device ID or queue ID is invalid or
1128 : : + statistics collection is not enabled.
1129 : : */
1130 : : int
1131 : : rte_vhost_vring_stats_get_names(int vid, uint16_t queue_id,
1132 : : struct rte_vhost_stat_name *name, unsigned int size);
1133 : :
1134 : : /**
1135 : : * Retrieve statistics of a Vhost virtqueue.
1136 : : *
1137 : : * There is an assumption that 'stat_names' and 'stats' arrays are matched
1138 : : * by array index: stats_names[i].name => stats[i].value
1139 : : *
1140 : : * @param vid
1141 : : * vhost device ID
1142 : : * @param queue_id
1143 : : * vhost queue index
1144 : : * @param stats
1145 : : * A pointer to a table of structure of type rte_vhost_stat to be filled with
1146 : : * virtqueue statistics ids and values.
1147 : : * @param n
1148 : : * The number of elements in stats array.
1149 : : * @return
1150 : : * - Success if greater than 0 and lower or equal to *n*. The return value
1151 : : * indicates the number of elements filled in the *stats* array.
1152 : : * - Failure if greater than *n*. The return value indicates the number of
1153 : : * elements the *stats* array that should be given to succeed.
1154 : : * - Failure if lower than 0. The device ID or queue ID is invalid, or
1155 : : * statistics collection is not enabled.
1156 : : */
1157 : : int
1158 : : rte_vhost_vring_stats_get(int vid, uint16_t queue_id,
1159 : : struct rte_vhost_stat *stats, unsigned int n);
1160 : :
1161 : : /**
1162 : : * Reset statistics of a Vhost virtqueue.
1163 : : *
1164 : : * @param vid
1165 : : * vhost device ID
1166 : : * @param queue_id
1167 : : * vhost queue index
1168 : : * @return
1169 : : * - Success if 0. Statistics have been reset.
1170 : : * - Failure if lower than 0. The device ID or queue ID is invalid, or
1171 : : * statistics collection is not enabled.
1172 : : */
1173 : : int
1174 : : rte_vhost_vring_stats_reset(int vid, uint16_t queue_id);
1175 : :
1176 : : #ifdef __cplusplus
1177 : : }
1178 : : #endif
1179 : :
1180 : : #endif /* _RTE_VHOST_H_ */
|
