vhost: add packed ring into vring struct
[dpdk.git] / lib / librte_vhost / rte_vhost.h
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 <stdint.h>
14 #include <sys/eventfd.h>
15
16 #include <rte_memory.h>
17 #include <rte_mempool.h>
18
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22
23 /* These are not C++-aware. */
24 #include <linux/vhost.h>
25 #include <linux/virtio_ring.h>
26 #include <linux/virtio_net.h>
27
28 #define RTE_VHOST_USER_CLIENT           (1ULL << 0)
29 #define RTE_VHOST_USER_NO_RECONNECT     (1ULL << 1)
30 #define RTE_VHOST_USER_DEQUEUE_ZERO_COPY        (1ULL << 2)
31 #define RTE_VHOST_USER_IOMMU_SUPPORT    (1ULL << 3)
32 #define RTE_VHOST_USER_POSTCOPY_SUPPORT         (1ULL << 4)
33
34 /** Protocol features. */
35 #ifndef VHOST_USER_PROTOCOL_F_MQ
36 #define VHOST_USER_PROTOCOL_F_MQ        0
37 #endif
38
39 #ifndef VHOST_USER_PROTOCOL_F_LOG_SHMFD
40 #define VHOST_USER_PROTOCOL_F_LOG_SHMFD 1
41 #endif
42
43 #ifndef VHOST_USER_PROTOCOL_F_RARP
44 #define VHOST_USER_PROTOCOL_F_RARP      2
45 #endif
46
47 #ifndef VHOST_USER_PROTOCOL_F_REPLY_ACK
48 #define VHOST_USER_PROTOCOL_F_REPLY_ACK 3
49 #endif
50
51 #ifndef VHOST_USER_PROTOCOL_F_NET_MTU
52 #define VHOST_USER_PROTOCOL_F_NET_MTU   4
53 #endif
54
55 #ifndef VHOST_USER_PROTOCOL_F_SLAVE_REQ
56 #define VHOST_USER_PROTOCOL_F_SLAVE_REQ 5
57 #endif
58
59 #ifndef VHOST_USER_PROTOCOL_F_CRYPTO_SESSION
60 #define VHOST_USER_PROTOCOL_F_CRYPTO_SESSION 7
61 #endif
62
63 #ifndef VHOST_USER_PROTOCOL_F_PAGEFAULT
64 #define VHOST_USER_PROTOCOL_F_PAGEFAULT 8
65 #endif
66
67 #ifndef VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD
68 #define VHOST_USER_PROTOCOL_F_SLAVE_SEND_FD 10
69 #endif
70
71 #ifndef VHOST_USER_PROTOCOL_F_HOST_NOTIFIER
72 #define VHOST_USER_PROTOCOL_F_HOST_NOTIFIER 11
73 #endif
74
75 #ifndef VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD
76 #define VHOST_USER_PROTOCOL_F_INFLIGHT_SHMFD 12
77 #endif
78
79 /** Indicate whether protocol features negotiation is supported. */
80 #ifndef VHOST_USER_F_PROTOCOL_FEATURES
81 #define VHOST_USER_F_PROTOCOL_FEATURES  30
82 #endif
83
84 /**
85  * Information relating to memory regions including offsets to
86  * addresses in QEMUs memory file.
87  */
88 struct rte_vhost_mem_region {
89         uint64_t guest_phys_addr;
90         uint64_t guest_user_addr;
91         uint64_t host_user_addr;
92         uint64_t size;
93         void     *mmap_addr;
94         uint64_t mmap_size;
95         int fd;
96 };
97
98 /**
99  * Memory structure includes region and mapping information.
100  */
101 struct rte_vhost_memory {
102         uint32_t nregions;
103         struct rte_vhost_mem_region regions[];
104 };
105
106 struct rte_vhost_vring {
107         union {
108                 struct vring_desc *desc;
109                 struct vring_packed_desc *desc_packed;
110         };
111         union {
112                 struct vring_avail *avail;
113                 struct vring_packed_desc_event *driver_event;
114         };
115         union {
116                 struct vring_used *used;
117                 struct vring_packed_desc_event *device_event;
118         };
119         uint64_t                log_guest_addr;
120
121         /** Deprecated, use rte_vhost_vring_call() instead. */
122         int                     callfd;
123
124         int                     kickfd;
125         uint16_t                size;
126 };
127
128 /**
129  * Possible results of the vhost user message handling callbacks
130  */
131 enum rte_vhost_msg_result {
132         /* Message handling failed */
133         RTE_VHOST_MSG_RESULT_ERR = -1,
134         /* Message handling successful */
135         RTE_VHOST_MSG_RESULT_OK =  0,
136         /* Message handling successful and reply prepared */
137         RTE_VHOST_MSG_RESULT_REPLY =  1,
138         /* Message not handled */
139         RTE_VHOST_MSG_RESULT_NOT_HANDLED,
140 };
141
142 /**
143  * Function prototype for the vhost backend to handle specific vhost user
144  * messages.
145  *
146  * @param vid
147  *  vhost device id
148  * @param msg
149  *  Message pointer.
150  * @return
151  *  RTE_VHOST_MSG_RESULT_OK on success,
152  *  RTE_VHOST_MSG_RESULT_REPLY on success with reply,
153  *  RTE_VHOST_MSG_RESULT_ERR on failure,
154  *  RTE_VHOST_MSG_RESULT_NOT_HANDLED if message was not handled.
155  */
156 typedef enum rte_vhost_msg_result (*rte_vhost_msg_handle)(int vid, void *msg);
157
158 /**
159  * Optional vhost user message handlers.
160  */
161 struct rte_vhost_user_extern_ops {
162         /* Called prior to the master message handling. */
163         rte_vhost_msg_handle pre_msg_handle;
164         /* Called after the master message handling. */
165         rte_vhost_msg_handle post_msg_handle;
166 };
167
168 /**
169  * Device and vring operations.
170  */
171 struct vhost_device_ops {
172         int (*new_device)(int vid);             /**< Add device. */
173         void (*destroy_device)(int vid);        /**< Remove device. */
174
175         int (*vring_state_changed)(int vid, uint16_t queue_id, int enable);     /**< triggered when a vring is enabled or disabled */
176
177         /**
178          * Features could be changed after the feature negotiation.
179          * For example, VHOST_F_LOG_ALL will be set/cleared at the
180          * start/end of live migration, respectively. This callback
181          * is used to inform the application on such change.
182          */
183         int (*features_changed)(int vid, uint64_t features);
184
185         int (*new_connection)(int vid);
186         void (*destroy_connection)(int vid);
187
188         /**
189          * This callback gets called each time a guest gets notified
190          * about waiting packets. This is the interrupt handling trough
191          * the eventfd_write(callfd), which can be used for counting these
192          * "slow" syscalls.
193          */
194         void (*guest_notified)(int vid);
195
196         void *reserved[1]; /**< Reserved for future extension */
197 };
198
199 /**
200  * Convert guest physical address to host virtual address
201  *
202  * This function is deprecated because unsafe.
203  * New rte_vhost_va_from_guest_pa() should be used instead to ensure
204  * guest physical ranges are fully and contiguously mapped into
205  * process virtual address space.
206  *
207  * @param mem
208  *  the guest memory regions
209  * @param gpa
210  *  the guest physical address for querying
211  * @return
212  *  the host virtual address on success, 0 on failure
213  */
214 __rte_deprecated
215 static __rte_always_inline uint64_t
216 rte_vhost_gpa_to_vva(struct rte_vhost_memory *mem, uint64_t gpa)
217 {
218         struct rte_vhost_mem_region *reg;
219         uint32_t i;
220
221         for (i = 0; i < mem->nregions; i++) {
222                 reg = &mem->regions[i];
223                 if (gpa >= reg->guest_phys_addr &&
224                     gpa <  reg->guest_phys_addr + reg->size) {
225                         return gpa - reg->guest_phys_addr +
226                                reg->host_user_addr;
227                 }
228         }
229
230         return 0;
231 }
232
233 /**
234  * Convert guest physical address to host virtual address safely
235  *
236  * This variant of rte_vhost_gpa_to_vva() takes care all the
237  * requested length is mapped and contiguous in process address
238  * space.
239  *
240  * @param mem
241  *  the guest memory regions
242  * @param gpa
243  *  the guest physical address for querying
244  * @param len
245  *  the size of the requested area to map, updated with actual size mapped
246  * @return
247  *  the host virtual address on success, 0 on failure
248  */
249 __rte_experimental
250 static __rte_always_inline uint64_t
251 rte_vhost_va_from_guest_pa(struct rte_vhost_memory *mem,
252                                                    uint64_t gpa, uint64_t *len)
253 {
254         struct rte_vhost_mem_region *r;
255         uint32_t i;
256
257         for (i = 0; i < mem->nregions; i++) {
258                 r = &mem->regions[i];
259                 if (gpa >= r->guest_phys_addr &&
260                     gpa <  r->guest_phys_addr + r->size) {
261
262                         if (unlikely(*len > r->guest_phys_addr + r->size - gpa))
263                                 *len = r->guest_phys_addr + r->size - gpa;
264
265                         return gpa - r->guest_phys_addr +
266                                r->host_user_addr;
267                 }
268         }
269         *len = 0;
270
271         return 0;
272 }
273
274 #define RTE_VHOST_NEED_LOG(features)    ((features) & (1ULL << VHOST_F_LOG_ALL))
275
276 /**
277  * Log the memory write start with given address.
278  *
279  * This function only need be invoked when the live migration starts.
280  * Therefore, we won't need call it at all in the most of time. For
281  * making the performance impact be minimum, it's suggested to do a
282  * check before calling it:
283  *
284  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
285  *                rte_vhost_log_write(vid, addr, len);
286  *
287  * @param vid
288  *  vhost device ID
289  * @param addr
290  *  the starting address for write (in guest physical address space)
291  * @param len
292  *  the length to write
293  */
294 void rte_vhost_log_write(int vid, uint64_t addr, uint64_t len);
295
296 /**
297  * Log the used ring update start at given offset.
298  *
299  * Same as rte_vhost_log_write, it's suggested to do a check before
300  * calling it:
301  *
302  *        if (unlikely(RTE_VHOST_NEED_LOG(features)))
303  *                rte_vhost_log_used_vring(vid, vring_idx, offset, len);
304  *
305  * @param vid
306  *  vhost device ID
307  * @param vring_idx
308  *  the vring index
309  * @param offset
310  *  the offset inside the used ring
311  * @param len
312  *  the length to write
313  */
314 void rte_vhost_log_used_vring(int vid, uint16_t vring_idx,
315                               uint64_t offset, uint64_t len);
316
317 int rte_vhost_enable_guest_notification(int vid, uint16_t queue_id, int enable);
318
319 /**
320  * Register vhost driver. path could be different for multiple
321  * instance support.
322  */
323 int rte_vhost_driver_register(const char *path, uint64_t flags);
324
325 /* Unregister vhost driver. This is only meaningful to vhost user. */
326 int rte_vhost_driver_unregister(const char *path);
327
328 /**
329  * Set the vdpa device id, enforce single connection per socket
330  *
331  * @param path
332  *  The vhost-user socket file path
333  * @param did
334  *  Device id
335  * @return
336  *  0 on success, -1 on failure
337  */
338 __rte_experimental
339 int
340 rte_vhost_driver_attach_vdpa_device(const char *path, int did);
341
342 /**
343  * Unset the vdpa device id
344  *
345  * @param path
346  *  The vhost-user socket file path
347  * @return
348  *  0 on success, -1 on failure
349  */
350 __rte_experimental
351 int
352 rte_vhost_driver_detach_vdpa_device(const char *path);
353
354 /**
355  * Get the device id
356  *
357  * @param path
358  *  The vhost-user socket file path
359  * @return
360  *  Device id, -1 on failure
361  */
362 __rte_experimental
363 int
364 rte_vhost_driver_get_vdpa_device_id(const char *path);
365
366 /**
367  * Set the feature bits the vhost-user driver supports.
368  *
369  * @param path
370  *  The vhost-user socket file path
371  * @param features
372  *  Supported features
373  * @return
374  *  0 on success, -1 on failure
375  */
376 int rte_vhost_driver_set_features(const char *path, uint64_t features);
377
378 /**
379  * Enable vhost-user driver features.
380  *
381  * Note that
382  * - the param features should be a subset of the feature bits provided
383  *   by rte_vhost_driver_set_features().
384  * - it must be invoked before vhost-user negotiation starts.
385  *
386  * @param path
387  *  The vhost-user socket file path
388  * @param features
389  *  Features to enable
390  * @return
391  *  0 on success, -1 on failure
392  */
393 int rte_vhost_driver_enable_features(const char *path, uint64_t features);
394
395 /**
396  * Disable vhost-user driver features.
397  *
398  * The two notes at rte_vhost_driver_enable_features() also apply here.
399  *
400  * @param path
401  *  The vhost-user socket file path
402  * @param features
403  *  Features to disable
404  * @return
405  *  0 on success, -1 on failure
406  */
407 int rte_vhost_driver_disable_features(const char *path, uint64_t features);
408
409 /**
410  * Get the feature bits before feature negotiation.
411  *
412  * @param path
413  *  The vhost-user socket file path
414  * @param features
415  *  A pointer to store the queried feature bits
416  * @return
417  *  0 on success, -1 on failure
418  */
419 int rte_vhost_driver_get_features(const char *path, uint64_t *features);
420
421 /**
422  * Set the protocol feature bits before feature negotiation.
423  *
424  * @param path
425  *  The vhost-user socket file path
426  * @param protocol_features
427  *  Supported protocol features
428  * @return
429  *  0 on success, -1 on failure
430  */
431 __rte_experimental
432 int
433 rte_vhost_driver_set_protocol_features(const char *path,
434                 uint64_t protocol_features);
435
436 /**
437  * Get the protocol feature bits before feature negotiation.
438  *
439  * @param path
440  *  The vhost-user socket file path
441  * @param protocol_features
442  *  A pointer to store the queried protocol feature bits
443  * @return
444  *  0 on success, -1 on failure
445  */
446 __rte_experimental
447 int
448 rte_vhost_driver_get_protocol_features(const char *path,
449                 uint64_t *protocol_features);
450
451 /**
452  * Get the queue number bits before feature negotiation.
453  *
454  * @param path
455  *  The vhost-user socket file path
456  * @param queue_num
457  *  A pointer to store the queried queue number bits
458  * @return
459  *  0 on success, -1 on failure
460  */
461 __rte_experimental
462 int
463 rte_vhost_driver_get_queue_num(const char *path, uint32_t *queue_num);
464
465 /**
466  * Get the feature bits after negotiation
467  *
468  * @param vid
469  *  Vhost device ID
470  * @param features
471  *  A pointer to store the queried feature bits
472  * @return
473  *  0 on success, -1 on failure
474  */
475 int rte_vhost_get_negotiated_features(int vid, uint64_t *features);
476
477 /* Register callbacks. */
478 int rte_vhost_driver_callback_register(const char *path,
479         struct vhost_device_ops const * const ops);
480
481 /**
482  *
483  * Start the vhost-user driver.
484  *
485  * This function triggers the vhost-user negotiation.
486  *
487  * @param path
488  *  The vhost-user socket file path
489  * @return
490  *  0 on success, -1 on failure
491  */
492 int rte_vhost_driver_start(const char *path);
493
494 /**
495  * Get the MTU value of the device if set in QEMU.
496  *
497  * @param vid
498  *  virtio-net device ID
499  * @param mtu
500  *  The variable to store the MTU value
501  *
502  * @return
503  *  0: success
504  *  -EAGAIN: device not yet started
505  *  -ENOTSUP: device does not support MTU feature
506  */
507 int rte_vhost_get_mtu(int vid, uint16_t *mtu);
508
509 /**
510  * Get the numa node from which the virtio net device's memory
511  * is allocated.
512  *
513  * @param vid
514  *  vhost device ID
515  *
516  * @return
517  *  The numa node, -1 on failure
518  */
519 int rte_vhost_get_numa_node(int vid);
520
521 /**
522  * @deprecated
523  * Get the number of queues the device supports.
524  *
525  * Note this function is deprecated, as it returns a queue pair number,
526  * which is vhost specific. Instead, rte_vhost_get_vring_num should
527  * be used.
528  *
529  * @param vid
530  *  vhost device ID
531  *
532  * @return
533  *  The number of queues, 0 on failure
534  */
535 __rte_deprecated
536 uint32_t rte_vhost_get_queue_num(int vid);
537
538 /**
539  * Get the number of vrings the device supports.
540  *
541  * @param vid
542  *  vhost device ID
543  *
544  * @return
545  *  The number of vrings, 0 on failure
546  */
547 uint16_t rte_vhost_get_vring_num(int vid);
548
549 /**
550  * Get the virtio net device's ifname, which is the vhost-user socket
551  * file path.
552  *
553  * @param vid
554  *  vhost device ID
555  * @param buf
556  *  The buffer to stored the queried ifname
557  * @param len
558  *  The length of buf
559  *
560  * @return
561  *  0 on success, -1 on failure
562  */
563 int rte_vhost_get_ifname(int vid, char *buf, size_t len);
564
565 /**
566  * Get how many avail entries are left in the queue
567  *
568  * @param vid
569  *  vhost device ID
570  * @param queue_id
571  *  virtio queue index
572  *
573  * @return
574  *  num of avail entries left
575  */
576 uint16_t rte_vhost_avail_entries(int vid, uint16_t queue_id);
577
578 struct rte_mbuf;
579 struct rte_mempool;
580 /**
581  * This function adds buffers to the virtio devices RX virtqueue. Buffers can
582  * be received from the physical port or from another virtual device. A packet
583  * count is returned to indicate the number of packets that were successfully
584  * added to the RX queue.
585  * @param vid
586  *  vhost device ID
587  * @param queue_id
588  *  virtio queue index in mq case
589  * @param pkts
590  *  array to contain packets to be enqueued
591  * @param count
592  *  packets num to be enqueued
593  * @return
594  *  num of packets enqueued
595  */
596 uint16_t rte_vhost_enqueue_burst(int vid, uint16_t queue_id,
597         struct rte_mbuf **pkts, uint16_t count);
598
599 /**
600  * This function gets guest buffers from the virtio device TX virtqueue,
601  * construct host mbufs, copies guest buffer content to host mbufs and
602  * store them in pkts to be processed.
603  * @param vid
604  *  vhost device ID
605  * @param queue_id
606  *  virtio queue index in mq case
607  * @param mbuf_pool
608  *  mbuf_pool where host mbuf is allocated.
609  * @param pkts
610  *  array to contain packets to be dequeued
611  * @param count
612  *  packets num to be dequeued
613  * @return
614  *  num of packets dequeued
615  */
616 uint16_t rte_vhost_dequeue_burst(int vid, uint16_t queue_id,
617         struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count);
618
619 /**
620  * Get guest mem table: a list of memory regions.
621  *
622  * An rte_vhost_vhost_memory object will be allocated internally, to hold the
623  * guest memory regions. Application should free it at destroy_device()
624  * callback.
625  *
626  * @param vid
627  *  vhost device ID
628  * @param mem
629  *  To store the returned mem regions
630  * @return
631  *  0 on success, -1 on failure
632  */
633 int rte_vhost_get_mem_table(int vid, struct rte_vhost_memory **mem);
634
635 /**
636  * Get guest vring info, including the vring address, vring size, etc.
637  *
638  * @param vid
639  *  vhost device ID
640  * @param vring_idx
641  *  vring index
642  * @param vring
643  *  the structure to hold the requested vring info
644  * @return
645  *  0 on success, -1 on failure
646  */
647 int rte_vhost_get_vhost_vring(int vid, uint16_t vring_idx,
648                               struct rte_vhost_vring *vring);
649
650 /**
651  * Notify the guest that used descriptors have been added to the vring.  This
652  * function acts as a memory barrier.
653  *
654  * @param vid
655  *  vhost device ID
656  * @param vring_idx
657  *  vring index
658  * @return
659  *  0 on success, -1 on failure
660  */
661 int rte_vhost_vring_call(int vid, uint16_t vring_idx);
662
663 /**
664  * Get vhost RX queue avail count.
665  *
666  * @param vid
667  *  vhost device ID
668  * @param qid
669  *  virtio queue index in mq case
670  * @return
671  *  num of desc available
672  */
673 uint32_t rte_vhost_rx_queue_count(int vid, uint16_t qid);
674
675 /**
676  * Get log base and log size of the vhost device
677  *
678  * @param vid
679  *  vhost device ID
680  * @param log_base
681  *  vhost log base
682  * @param log_size
683  *  vhost log size
684  * @return
685  *  0 on success, -1 on failure
686  */
687 __rte_experimental
688 int
689 rte_vhost_get_log_base(int vid, uint64_t *log_base, uint64_t *log_size);
690
691 /**
692  * Get last_avail/used_idx of the vhost virtqueue
693  *
694  * @param vid
695  *  vhost device ID
696  * @param queue_id
697  *  vhost queue index
698  * @param last_avail_idx
699  *  vhost last_avail_idx to get
700  * @param last_used_idx
701  *  vhost last_used_idx to get
702  * @return
703  *  0 on success, -1 on failure
704  */
705 __rte_experimental
706 int
707 rte_vhost_get_vring_base(int vid, uint16_t queue_id,
708                 uint16_t *last_avail_idx, uint16_t *last_used_idx);
709
710 /**
711  * Set last_avail/used_idx of the vhost virtqueue
712  *
713  * @param vid
714  *  vhost device ID
715  * @param queue_id
716  *  vhost queue index
717  * @param last_avail_idx
718  *  last_avail_idx to set
719  * @param last_used_idx
720  *  last_used_idx to set
721  * @return
722  *  0 on success, -1 on failure
723  */
724 __rte_experimental
725 int
726 rte_vhost_set_vring_base(int vid, uint16_t queue_id,
727                 uint16_t last_avail_idx, uint16_t last_used_idx);
728
729 /**
730  * Register external message handling callbacks
731  *
732  * @param vid
733  *  vhost device ID
734  * @param ops
735  *  virtio external callbacks to register
736  * @param ctx
737  *  additional context passed to the callbacks
738  * @return
739  *  0 on success, -1 on failure
740  */
741 __rte_experimental
742 int
743 rte_vhost_extern_callback_register(int vid,
744                 struct rte_vhost_user_extern_ops const * const ops, void *ctx);
745
746 /**
747  * Get vdpa device id for vhost device.
748  *
749  * @param vid
750  *  vhost device id
751  * @return
752  *  device id
753  */
754 __rte_experimental
755 int
756 rte_vhost_get_vdpa_device_id(int vid);
757
758 #ifdef __cplusplus
759 }
760 #endif
761
762 #endif /* _RTE_VHOST_H_ */