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 "rte_vhost.h" 9 10 /** 11 * iovec iterator 12 */ 13 struct rte_vhost_iov_iter { 14 /** offset to the first byte of interesting data */ 15 size_t offset; 16 /** total bytes of data in this iterator */ 17 size_t count; 18 /** pointer to the iovec array */ 19 struct iovec *iov; 20 /** number of iovec in this iterator */ 21 unsigned long nr_segs; 22 }; 23 24 /** 25 * dma transfer descriptor pair 26 */ 27 struct rte_vhost_async_desc { 28 /** source memory iov_iter */ 29 struct rte_vhost_iov_iter *src; 30 /** destination memory iov_iter */ 31 struct rte_vhost_iov_iter *dst; 32 }; 33 34 /** 35 * dma transfer status 36 */ 37 struct rte_vhost_async_status { 38 /** An array of application specific data for source memory */ 39 uintptr_t *src_opaque_data; 40 /** An array of application specific data for destination memory */ 41 uintptr_t *dst_opaque_data; 42 }; 43 44 /** 45 * dma operation callbacks to be implemented by applications 46 */ 47 struct rte_vhost_async_channel_ops { 48 /** 49 * instruct async engines to perform copies for a batch of packets 50 * 51 * @param vid 52 * id of vhost device to perform data copies 53 * @param queue_id 54 * queue id to perform data copies 55 * @param descs 56 * an array of DMA transfer memory descriptors 57 * @param opaque_data 58 * opaque data pair sending to DMA engine 59 * @param count 60 * number of elements in the "descs" array 61 * @return 62 * number of descs processed 63 */ 64 uint32_t (*transfer_data)(int vid, uint16_t queue_id, 65 struct rte_vhost_async_desc *descs, 66 struct rte_vhost_async_status *opaque_data, 67 uint16_t count); 68 /** 69 * check copy-completed packets from the async engine 70 * @param vid 71 * id of vhost device to check copy completion 72 * @param queue_id 73 * queue id to check copy completion 74 * @param opaque_data 75 * buffer to receive the opaque data pair from DMA engine 76 * @param max_packets 77 * max number of packets could be completed 78 * @return 79 * number of async descs completed 80 */ 81 uint32_t (*check_completed_copies)(int vid, uint16_t queue_id, 82 struct rte_vhost_async_status *opaque_data, 83 uint16_t max_packets); 84 }; 85 86 /** 87 * inflight async packet information 88 */ 89 struct async_inflight_info { 90 struct rte_mbuf *mbuf; 91 uint16_t descs; /* num of descs inflight */ 92 uint16_t nr_buffers; /* num of buffers inflight for packed ring */ 93 }; 94 95 /** 96 * async channel features 97 */ 98 enum { 99 RTE_VHOST_ASYNC_INORDER = 1U << 0, 100 }; 101 102 /** 103 * async channel configuration 104 */ 105 struct rte_vhost_async_config { 106 uint32_t async_threshold; 107 uint32_t features; 108 uint32_t rsvd[2]; 109 }; 110 111 /** 112 * Register an async channel for a vhost queue 113 * 114 * @param vid 115 * vhost device id async channel to be attached to 116 * @param queue_id 117 * vhost queue id async channel to be attached to 118 * @param config 119 * Async channel configuration structure 120 * @param ops 121 * Async channel operation callbacks 122 * @return 123 * 0 on success, -1 on failures 124 */ 125 __rte_experimental 126 int rte_vhost_async_channel_register(int vid, uint16_t queue_id, 127 struct rte_vhost_async_config config, 128 struct rte_vhost_async_channel_ops *ops); 129 130 /** 131 * Unregister an async channel for a vhost queue 132 * 133 * @param vid 134 * vhost device id async channel to be detached from 135 * @param queue_id 136 * vhost queue id async channel to be detached from 137 * @return 138 * 0 on success, -1 on failures 139 */ 140 __rte_experimental 141 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id); 142 143 /** 144 * Register an async channel for a vhost queue without performing any 145 * locking 146 * 147 * @note This function does not perform any locking, and is only safe to 148 * call in vhost callback functions. 149 * 150 * @param vid 151 * vhost device id async channel to be attached to 152 * @param queue_id 153 * vhost queue id async channel to be attached to 154 * @param config 155 * Async channel configuration 156 * @param ops 157 * Async channel operation callbacks 158 * @return 159 * 0 on success, -1 on failures 160 */ 161 __rte_experimental 162 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id, 163 struct rte_vhost_async_config config, 164 struct rte_vhost_async_channel_ops *ops); 165 166 /** 167 * Unregister an async channel for a vhost queue without performing any 168 * locking 169 * 170 * @note This function does not perform any locking, and is only safe to 171 * call in vhost callback functions. 172 * 173 * @param vid 174 * vhost device id async channel to be detached from 175 * @param queue_id 176 * vhost queue id async channel to be detached from 177 * @return 178 * 0 on success, -1 on failures 179 */ 180 __rte_experimental 181 int rte_vhost_async_channel_unregister_thread_unsafe(int vid, 182 uint16_t queue_id); 183 184 /** 185 * This function submits enqueue data to async engine. Successfully 186 * enqueued packets can be transfer completed or being occupied by DMA 187 * engines, when this API returns. Transfer completed packets are returned 188 * in comp_pkts, so users need to guarantee its size is greater than or 189 * equal to the size of pkts; for packets that are successfully enqueued 190 * but not transfer completed, users should poll transfer status by 191 * rte_vhost_poll_enqueue_completed(). 192 * 193 * @param vid 194 * id of vhost device to enqueue data 195 * @param queue_id 196 * queue id to enqueue data 197 * @param pkts 198 * array of packets to be enqueued 199 * @param count 200 * packets num to be enqueued 201 * @param comp_pkts 202 * empty array to get transfer completed packets. Users need to 203 * guarantee its size is greater than or equal to that of pkts 204 * @param comp_count 205 * num of packets that are transfer completed, when this API returns. 206 * If no packets are transfer completed, its value is set to 0. 207 * @return 208 * num of packets enqueued, including in-flight and transfer completed 209 */ 210 __rte_experimental 211 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id, 212 struct rte_mbuf **pkts, uint16_t count, 213 struct rte_mbuf **comp_pkts, uint32_t *comp_count); 214 215 /** 216 * This function checks async completion status for a specific vhost 217 * device queue. Packets which finish copying (enqueue) operation 218 * will be returned in an array. 219 * 220 * @param vid 221 * id of vhost device to enqueue data 222 * @param queue_id 223 * queue id to enqueue data 224 * @param pkts 225 * blank array to get return packet pointer 226 * @param count 227 * size of the packet array 228 * @return 229 * num of packets returned 230 */ 231 __rte_experimental 232 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id, 233 struct rte_mbuf **pkts, uint16_t count); 234 235 /** 236 * This function returns the amount of in-flight packets for the vhost 237 * queue which uses async channel acceleration. 238 * 239 * @param vid 240 * id of vhost device to enqueue data 241 * @param queue_id 242 * queue id to enqueue data 243 * @return 244 * the amount of in-flight packets on success; -1 on failure 245 */ 246 __rte_experimental 247 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id); 248 249 #endif /* _RTE_VHOST_ASYNC_H_ */ 250