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, negative value means error 63 */ 64 int32_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, negative value means error 80 */ 81 int32_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 features; 107 uint32_t rsvd[2]; 108 }; 109 110 /** 111 * Register an async channel for a vhost queue 112 * 113 * @param vid 114 * vhost device id async channel to be attached to 115 * @param queue_id 116 * vhost queue id async channel to be attached to 117 * @param config 118 * Async channel configuration structure 119 * @param ops 120 * Async channel operation callbacks 121 * @return 122 * 0 on success, -1 on failures 123 */ 124 __rte_experimental 125 int rte_vhost_async_channel_register(int vid, uint16_t queue_id, 126 struct rte_vhost_async_config config, 127 struct rte_vhost_async_channel_ops *ops); 128 129 /** 130 * Unregister an async channel for a vhost queue 131 * 132 * @param vid 133 * vhost device id async channel to be detached from 134 * @param queue_id 135 * vhost queue id async channel to be detached from 136 * @return 137 * 0 on success, -1 on failures 138 */ 139 __rte_experimental 140 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id); 141 142 /** 143 * Register an async channel for a vhost queue without performing any 144 * locking 145 * 146 * @note This function does not perform any locking, and is only safe to 147 * call in vhost callback functions. 148 * 149 * @param vid 150 * vhost device id async channel to be attached to 151 * @param queue_id 152 * vhost queue id async channel to be attached to 153 * @param config 154 * Async channel configuration 155 * @param ops 156 * Async channel operation callbacks 157 * @return 158 * 0 on success, -1 on failures 159 */ 160 __rte_experimental 161 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id, 162 struct rte_vhost_async_config config, 163 struct rte_vhost_async_channel_ops *ops); 164 165 /** 166 * Unregister an async channel for a vhost queue without performing any 167 * locking 168 * 169 * @note This function does not perform any locking, and is only safe to 170 * call in vhost callback functions. 171 * 172 * @param vid 173 * vhost device id async channel to be detached from 174 * @param queue_id 175 * vhost queue id async channel to be detached from 176 * @return 177 * 0 on success, -1 on failures 178 */ 179 __rte_experimental 180 int rte_vhost_async_channel_unregister_thread_unsafe(int vid, 181 uint16_t queue_id); 182 183 /** 184 * This function submits enqueue packets to async copy engine. Users 185 * need to poll transfer status by rte_vhost_poll_enqueue_completed() 186 * for successfully enqueued packets. 187 * 188 * @param vid 189 * id of vhost device to enqueue data 190 * @param queue_id 191 * queue id to enqueue data 192 * @param pkts 193 * array of packets to be enqueued 194 * @param count 195 * packets num to be enqueued 196 * @return 197 * num of packets enqueued 198 */ 199 __rte_experimental 200 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id, 201 struct rte_mbuf **pkts, uint16_t count); 202 203 /** 204 * This function checks async completion status for a specific vhost 205 * device queue. Packets which finish copying (enqueue) operation 206 * will be returned in an array. 207 * 208 * @param vid 209 * id of vhost device to enqueue data 210 * @param queue_id 211 * queue id to enqueue data 212 * @param pkts 213 * blank array to get return packet pointer 214 * @param count 215 * size of the packet array 216 * @return 217 * num of packets returned 218 */ 219 __rte_experimental 220 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id, 221 struct rte_mbuf **pkts, uint16_t count); 222 223 /** 224 * This function returns the amount of in-flight packets for the vhost 225 * queue which uses async channel acceleration. 226 * 227 * @param vid 228 * id of vhost device to enqueue data 229 * @param queue_id 230 * queue id to enqueue data 231 * @return 232 * the amount of in-flight packets on success; -1 on failure 233 */ 234 __rte_experimental 235 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id); 236 237 /** 238 * This function checks async completion status and clear packets for 239 * a specific vhost device queue. Packets which are inflight will be 240 * returned in an array. 241 * 242 * @note This function does not perform any locking 243 * 244 * @param vid 245 * ID of vhost device to clear data 246 * @param queue_id 247 * Queue id to clear data 248 * @param pkts 249 * Blank array to get return packet pointer 250 * @param count 251 * Size of the packet array 252 * @return 253 * Number of packets returned 254 */ 255 __rte_experimental 256 uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id, 257 struct rte_mbuf **pkts, uint16_t count); 258 259 #endif /* _RTE_VHOST_ASYNC_H_ */ 260