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 #ifdef __cplusplus 14 extern "C" { 15 #endif 16 17 /** 18 * Register an async channel for a vhost queue 19 * 20 * @param vid 21 * vhost device id async channel to be attached to 22 * @param queue_id 23 * vhost queue id async channel to be attached to 24 * @return 25 * 0 on success, -1 on failures 26 */ 27 __rte_experimental 28 int rte_vhost_async_channel_register(int vid, uint16_t queue_id); 29 30 /** 31 * Unregister an async channel for a vhost queue 32 * 33 * @param vid 34 * vhost device id async channel to be detached from 35 * @param queue_id 36 * vhost queue id async channel to be detached from 37 * @return 38 * 0 on success, -1 on failures 39 */ 40 __rte_experimental 41 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id); 42 43 /** 44 * Register an async channel for a vhost queue without performing any 45 * locking 46 * 47 * @note This function does not perform any locking, and is only safe to 48 * call in vhost callback functions. 49 * 50 * @param vid 51 * vhost device id async channel to be attached to 52 * @param queue_id 53 * vhost queue id async channel to be attached to 54 * @return 55 * 0 on success, -1 on failures 56 */ 57 __rte_experimental 58 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id); 59 60 /** 61 * Unregister an async channel for a vhost queue without performing any 62 * locking 63 * 64 * @note This function does not perform any locking, and is only safe to 65 * call in vhost callback functions. 66 * 67 * @param vid 68 * vhost device id async channel to be detached from 69 * @param queue_id 70 * vhost queue id async channel to be detached from 71 * @return 72 * 0 on success, -1 on failures 73 */ 74 __rte_experimental 75 int rte_vhost_async_channel_unregister_thread_unsafe(int vid, 76 uint16_t queue_id); 77 78 /** 79 * This function submits enqueue packets to async copy engine. Users 80 * need to poll transfer status by rte_vhost_poll_enqueue_completed() 81 * for successfully enqueued packets. 82 * 83 * @param vid 84 * id of vhost device to enqueue data 85 * @param queue_id 86 * queue id to enqueue data 87 * @param pkts 88 * array of packets to be enqueued 89 * @param count 90 * packets num to be enqueued 91 * @param dma_id 92 * the identifier of DMA device 93 * @param vchan_id 94 * the identifier of virtual DMA channel 95 * @return 96 * num of packets enqueued 97 */ 98 __rte_experimental 99 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id, 100 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 101 uint16_t vchan_id); 102 103 /** 104 * This function checks async completion status for a specific vhost 105 * device queue. Packets which finish copying (enqueue) operation 106 * will be returned in an array. 107 * 108 * @param vid 109 * id of vhost device to enqueue data 110 * @param queue_id 111 * queue id to enqueue data 112 * @param pkts 113 * blank array to get return packet pointer 114 * @param count 115 * size of the packet array 116 * @param dma_id 117 * the identifier of DMA device 118 * @param vchan_id 119 * the identifier of virtual DMA channel 120 * @return 121 * num of packets returned 122 */ 123 __rte_experimental 124 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id, 125 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 126 uint16_t vchan_id); 127 128 /** 129 * This function returns the amount of in-flight packets for the vhost 130 * queue which uses async channel acceleration. 131 * 132 * @param vid 133 * id of vhost device to enqueue data 134 * @param queue_id 135 * queue id to enqueue data 136 * @return 137 * the amount of in-flight packets on success; -1 on failure 138 */ 139 __rte_experimental 140 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id); 141 142 /** 143 * This function is lock-free version to return the amount of in-flight 144 * packets for the vhost queue which uses async channel acceleration. 145 * 146 * @note This function does not perform any locking, it should only be 147 * used within the vhost ops, which already holds the lock. 148 * 149 * @param vid 150 * id of vhost device to enqueue data 151 * @param queue_id 152 * queue id to enqueue data 153 * @return 154 * the amount of in-flight packets on success; -1 on failure 155 */ 156 __rte_experimental 157 int rte_vhost_async_get_inflight_thread_unsafe(int vid, uint16_t queue_id); 158 159 /** 160 * This function checks async completion status and clear packets for 161 * a specific vhost device queue. Packets which are inflight will be 162 * returned in an array. 163 * 164 * @note This function does not perform any locking 165 * 166 * @param vid 167 * ID of vhost device to clear data 168 * @param queue_id 169 * Queue id to clear data 170 * @param pkts 171 * Blank array to get return packet pointer 172 * @param count 173 * Size of the packet array 174 * @param dma_id 175 * the identifier of DMA device 176 * @param vchan_id 177 * the identifier of virtual DMA channel 178 * @return 179 * Number of packets returned 180 */ 181 __rte_experimental 182 uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id, 183 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 184 uint16_t vchan_id); 185 186 /** 187 * This function checks async completion status and clear packets for 188 * a specific vhost device queue. Packets which are inflight will be 189 * returned in an array. 190 * 191 * @param vid 192 * ID of vhost device to clear data 193 * @param queue_id 194 * Queue id to clear data 195 * @param pkts 196 * Blank array to get return packet pointer 197 * @param count 198 * Size of the packet array 199 * @param dma_id 200 * The identifier of the DMA device 201 * @param vchan_id 202 * The identifier of virtual DMA channel 203 * @return 204 * Number of packets returned 205 */ 206 __rte_experimental 207 uint16_t rte_vhost_clear_queue(int vid, uint16_t queue_id, 208 struct rte_mbuf **pkts, uint16_t count, int16_t dma_id, 209 uint16_t vchan_id); 210 211 /** 212 * The DMA vChannels used in asynchronous data path must be configured 213 * first. So this function needs to be called before enabling DMA 214 * acceleration for vring. If this function fails, the given DMA vChannel 215 * cannot be used in asynchronous data path. 216 * 217 * DMA devices used in data-path must belong to DMA devices given in this 218 * function. Application is free to use DMA devices passed to this function 219 * for non-vhost scenarios, but will have to ensure the Vhost library is not 220 * using the channel at the same time. 221 * 222 * @param dma_id 223 * the identifier of DMA device 224 * @param vchan_id 225 * the identifier of virtual DMA channel 226 * @return 227 * 0 on success, and -1 on failure 228 */ 229 __rte_experimental 230 int rte_vhost_async_dma_configure(int16_t dma_id, uint16_t vchan_id); 231 232 /** 233 * @warning 234 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice 235 * 236 * This function tries to receive packets from the guest with offloading 237 * copies to the DMA vChannels. Successfully dequeued packets are returned 238 * in "pkts". The other packets that their copies are submitted to 239 * the DMA vChannels but not completed are called "in-flight packets". 240 * This function will not return in-flight packets until their copies are 241 * completed by the DMA vChannels. 242 * 243 * @param vid 244 * ID of vhost device to dequeue data 245 * @param queue_id 246 * ID of virtqueue to dequeue data 247 * @param mbuf_pool 248 * Mbuf_pool where host mbuf is allocated 249 * @param pkts 250 * Blank array to keep successfully dequeued packets 251 * @param count 252 * Size of the packet array 253 * @param nr_inflight 254 * >= 0: The amount of in-flight packets 255 * -1: Meaningless, indicates failed lock acquisition or invalid queue_id/dma_id 256 * @param dma_id 257 * The identifier of DMA device 258 * @param vchan_id 259 * The identifier of virtual DMA channel 260 * @return 261 * Number of successfully dequeued packets 262 */ 263 __rte_experimental 264 uint16_t 265 rte_vhost_async_try_dequeue_burst(int vid, uint16_t queue_id, 266 struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count, 267 int *nr_inflight, int16_t dma_id, uint16_t vchan_id); 268 269 /** 270 * @warning 271 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice. 272 * 273 * Unconfigure DMA vChannel in Vhost asynchronous data path. 274 * This function should be called when the specified DMA vChannel is no longer 275 * used by the Vhost library. Before this function is called, make sure there 276 * does not exist in-flight packets in DMA vChannel. 277 * 278 * @param dma_id 279 * the identifier of DMA device 280 * @param vchan_id 281 * the identifier of virtual DMA channel 282 * @return 283 * 0 on success, and -1 on failure 284 */ 285 __rte_experimental 286 int 287 rte_vhost_async_dma_unconfigure(int16_t dma_id, uint16_t vchan_id); 288 289 #ifdef __cplusplus 290 } 291 #endif 292 293 #endif /* _RTE_VHOST_ASYNC_H_ */ 294