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 * dma channel feature bit definition 97 */ 98 struct rte_vhost_async_features { 99 union { 100 uint32_t intval; 101 struct { 102 uint32_t async_inorder:1; 103 uint32_t resvd_0:15; 104 uint32_t async_threshold:12; 105 uint32_t resvd_1:4; 106 }; 107 }; 108 }; 109 110 /** 111 * register an async channel for vhost 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 features 118 * DMA channel feature bit 119 * b0 : DMA supports inorder data transfer 120 * b1 - b15: reserved 121 * b16 - b27: Packet length threshold for DMA transfer 122 * b28 - b31: reserved 123 * @param ops 124 * DMA operation callbacks 125 * @return 126 * 0 on success, -1 on failures 127 */ 128 __rte_experimental 129 int rte_vhost_async_channel_register(int vid, uint16_t queue_id, 130 uint32_t features, struct rte_vhost_async_channel_ops *ops); 131 132 /** 133 * unregister a dma channel for vhost 134 * 135 * @param vid 136 * vhost device id DMA channel to be detached 137 * @param queue_id 138 * vhost queue id DMA channel to be detached 139 * @return 140 * 0 on success, -1 on failures 141 */ 142 __rte_experimental 143 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id); 144 145 /** 146 * This function submits enqueue data to async engine. Successfully 147 * enqueued packets can be transfer completed or being occupied by DMA 148 * engines, when this API returns. Transfer completed packets are returned 149 * in comp_pkts, so users need to guarantee its size is greater than or 150 * equal to the size of pkts; for packets that are successfully enqueued 151 * but not transfer completed, users should poll transfer status by 152 * rte_vhost_poll_enqueue_completed(). 153 * 154 * @param vid 155 * id of vhost device to enqueue data 156 * @param queue_id 157 * queue id to enqueue data 158 * @param pkts 159 * array of packets to be enqueued 160 * @param count 161 * packets num to be enqueued 162 * @param comp_pkts 163 * empty array to get transfer completed packets. Users need to 164 * guarantee its size is greater than or equal to that of pkts 165 * @param comp_count 166 * num of packets that are transfer completed, when this API returns. 167 * If no packets are transfer completed, its value is set to 0. 168 * @return 169 * num of packets enqueued, including in-flight and transfer completed 170 */ 171 __rte_experimental 172 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id, 173 struct rte_mbuf **pkts, uint16_t count, 174 struct rte_mbuf **comp_pkts, uint32_t *comp_count); 175 176 /** 177 * This function checks async completion status for a specific vhost 178 * device queue. Packets which finish copying (enqueue) operation 179 * will be returned in an array. 180 * 181 * @param vid 182 * id of vhost device to enqueue data 183 * @param queue_id 184 * queue id to enqueue data 185 * @param pkts 186 * blank array to get return packet pointer 187 * @param count 188 * size of the packet array 189 * @return 190 * num of packets returned 191 */ 192 __rte_experimental 193 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id, 194 struct rte_mbuf **pkts, uint16_t count); 195 196 #endif /* _RTE_VHOST_ASYNC_H_ */ 197