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