1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2020 Intel Corporation 3 */ 4 5 #ifndef _RTE_VHOST_ASYNC_H_ 6 #define _RTE_VHOST_ASYNC_H_ 7 8 #include <stdint.h> 9 10 #include <rte_compat.h> 11 #include <rte_mbuf.h> 12 13 /** 14 * Register an async channel for a vhost queue 15 * 16 * @param vid 17 * vhost device id async channel to be attached to 18 * @param queue_id 19 * vhost queue id async channel to be attached to 20 * @return 21 * 0 on success, -1 on failures 22 */ 23 __rte_experimental 24 int rte_vhost_async_channel_register(int vid, uint16_t queue_id); 25 26 /** 27 * Unregister an async channel for a vhost queue 28 * 29 * @param vid 30 * vhost device id async channel to be detached from 31 * @param queue_id 32 * vhost queue id async channel to be detached from 33 * @return 34 * 0 on success, -1 on failures 35 */ 36 __rte_experimental 37 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id); 38 39 /** 40 * Register an async channel for a vhost queue without performing any 41 * locking 42 * 43 * @note This function does not perform any locking, and is only safe to 44 * call in vhost callback functions. 45 * 46 * @param vid 47 * vhost device id async channel to be attached to 48 * @param queue_id 49 * vhost queue id async channel to be attached to 50 * @return 51 * 0 on success, -1 on failures 52 */ 53 __rte_experimental 54 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id); 55 56 /** 57 * Unregister an async channel for a vhost queue without performing any 58 * locking 59 * 60 * @note This function does not perform any locking, and is only safe to 61 * call in vhost callback functions. 62 * 63 * @param vid 64 * vhost device id async channel to be detached from 65 * @param queue_id 66 * vhost queue id async channel to be detached from 67 * @return 68 * 0 on success, -1 on failures 69 */ 70 __rte_experimental 71 int rte_vhost_async_channel_unregister_thread_unsafe(int vid, 72 uint16_t queue_id); 73 74 /** 75 * This function submits enqueue packets to async copy engine. Users 76 * need to poll transfer status by rte_vhost_poll_enqueue_completed() 77 * for successfully enqueued packets. 78 * 79 * @param vid 80 * id of vhost device to enqueue data 81 * @param queue_id 82 * queue id to enqueue data 83 * @param pkts 84 * array of packets to be enqueued 85 * @param count 86 * packets num to be enqueued 87 * @param dma_id 88 * the identifier of DMA device 89 * @param vchan_id 90 * the identifier of virtual DMA channel 91 * @return 92 * num of packets enqueued 93 */ 94 __rte_experimental 95 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id, 96 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 97 uint16_t vchan_id); 98 99 /** 100 * This function checks async completion status for a specific vhost 101 * device queue. Packets which finish copying (enqueue) operation 102 * will be returned in an array. 103 * 104 * @param vid 105 * id of vhost device to enqueue data 106 * @param queue_id 107 * queue id to enqueue data 108 * @param pkts 109 * blank array to get return packet pointer 110 * @param count 111 * size of the packet array 112 * @param dma_id 113 * the identifier of DMA device 114 * @param vchan_id 115 * the identifier of virtual DMA channel 116 * @return 117 * num of packets returned 118 */ 119 __rte_experimental 120 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id, 121 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 122 uint16_t vchan_id); 123 124 /** 125 * This function returns the amount of in-flight packets for the vhost 126 * queue which uses async channel acceleration. 127 * 128 * @param vid 129 * id of vhost device to enqueue data 130 * @param queue_id 131 * queue id to enqueue data 132 * @return 133 * the amount of in-flight packets on success; -1 on failure 134 */ 135 __rte_experimental 136 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id); 137 138 /** 139 * This function checks async completion status and clear packets for 140 * a specific vhost device queue. Packets which are inflight will be 141 * returned in an array. 142 * 143 * @note This function does not perform any locking 144 * 145 * @param vid 146 * ID of vhost device to clear data 147 * @param queue_id 148 * Queue id to clear data 149 * @param pkts 150 * Blank array to get return packet pointer 151 * @param count 152 * Size of the packet array 153 * @param dma_id 154 * the identifier of DMA device 155 * @param vchan_id 156 * the identifier of virtual DMA channel 157 * @return 158 * Number of packets returned 159 */ 160 __rte_experimental 161 uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id, 162 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 163 uint16_t vchan_id); 164 165 /** 166 * The DMA vChannels used in asynchronous data path must be configured 167 * first. So this function needs to be called before enabling DMA 168 * acceleration for vring. If this function fails, the given DMA vChannel 169 * cannot be used in asynchronous data path. 170 * 171 * DMA devices used in data-path must belong to DMA devices given in this 172 * function. Application is free to use DMA devices passed to this function 173 * for non-vhost scenarios, but will have to ensure the Vhost library is not 174 * using the channel at the same time. 175 * 176 * @param dma_id 177 * the identifier of DMA device 178 * @param vchan_id 179 * the identifier of virtual DMA channel 180 * @return 181 * 0 on success, and -1 on failure 182 */ 183 __rte_experimental 184 int rte_vhost_async_dma_configure(int16_t dma_id, uint16_t vchan_id); 185 186 #endif /* _RTE_VHOST_ASYNC_H_ */ 187