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