1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2020 Intel Corporation
5 #ifndef _RTE_VHOST_ASYNC_H_
6 #define _RTE_VHOST_ASYNC_H_
14 #include <rte_compat.h>
18 * Register an async channel for a vhost queue
21 * vhost device id async channel to be attached to
23 * vhost queue id async channel to be attached to
25 * 0 on success, -1 on failures
28 int rte_vhost_async_channel_register(int vid, uint16_t queue_id);
31 * Unregister an async channel for a vhost queue
34 * vhost device id async channel to be detached from
36 * vhost queue id async channel to be detached from
38 * 0 on success, -1 on failures
41 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id);
44 * Register an async channel for a vhost queue without performing any
47 * @note This function does not perform any locking, and is only safe to
48 * call in vhost callback functions.
51 * vhost device id async channel to be attached to
53 * vhost queue id async channel to be attached to
55 * 0 on success, -1 on failures
58 int rte_vhost_async_channel_register_thread_unsafe(int vid, uint16_t queue_id);
61 * Unregister an async channel for a vhost queue without performing any
64 * @note This function does not perform any locking, and is only safe to
65 * call in vhost callback functions.
68 * vhost device id async channel to be detached from
70 * vhost queue id async channel to be detached from
72 * 0 on success, -1 on failures
75 int rte_vhost_async_channel_unregister_thread_unsafe(int vid,
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.
84 * id of vhost device to enqueue data
86 * queue id to enqueue data
88 * array of packets to be enqueued
90 * packets num to be enqueued
92 * the identifier of DMA device
94 * the identifier of virtual DMA channel
96 * num of packets enqueued
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,
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.
109 * id of vhost device to enqueue data
111 * queue id to enqueue data
113 * blank array to get return packet pointer
115 * size of the packet array
117 * the identifier of DMA device
119 * the identifier of virtual DMA channel
121 * num of packets returned
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,
129 * This function returns the amount of in-flight packets for the vhost
130 * queue which uses async channel acceleration.
133 * id of vhost device to enqueue data
135 * queue id to enqueue data
137 * the amount of in-flight packets on success; -1 on failure
140 int rte_vhost_async_get_inflight(int vid, uint16_t queue_id);
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.
146 * @note This function does not perform any locking, it should only be
147 * used within the vhost ops, which already holds the lock.
150 * id of vhost device to enqueue data
152 * queue id to enqueue data
154 * the amount of in-flight packets on success; -1 on failure
157 int rte_vhost_async_get_inflight_thread_unsafe(int vid, uint16_t queue_id);
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.
164 * @note This function does not perform any locking
167 * ID of vhost device to clear data
169 * Queue id to clear data
171 * Blank array to get return packet pointer
173 * Size of the packet array
175 * the identifier of DMA device
177 * the identifier of virtual DMA channel
179 * Number of packets returned
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,
187 * The DMA vChannels used in asynchronous data path must be configured
188 * first. So this function needs to be called before enabling DMA
189 * acceleration for vring. If this function fails, the given DMA vChannel
190 * cannot be used in asynchronous data path.
192 * DMA devices used in data-path must belong to DMA devices given in this
193 * function. Application is free to use DMA devices passed to this function
194 * for non-vhost scenarios, but will have to ensure the Vhost library is not
195 * using the channel at the same time.
198 * the identifier of DMA device
200 * the identifier of virtual DMA channel
202 * 0 on success, and -1 on failure
205 int rte_vhost_async_dma_configure(int16_t dma_id, uint16_t vchan_id);
209 * @b EXPERIMENTAL: this API may change, or be removed, without prior notice
211 * This function tries to receive packets from the guest with offloading
212 * copies to the DMA vChannels. Successfully dequeued packets are returned
213 * in "pkts". The other packets that their copies are submitted to
214 * the DMA vChannels but not completed are called "in-flight packets".
215 * This function will not return in-flight packets until their copies are
216 * completed by the DMA vChannels.
219 * ID of vhost device to dequeue data
221 * ID of virtqueue to dequeue data
223 * Mbuf_pool where host mbuf is allocated
225 * Blank array to keep successfully dequeued packets
227 * Size of the packet array
229 * >= 0: The amount of in-flight packets
230 * -1: Meaningless, indicates failed lock acquisition or invalid queue_id/dma_id
232 * The identifier of DMA device
234 * The identifier of virtual DMA channel
236 * Number of successfully dequeued packets
240 rte_vhost_async_try_dequeue_burst(int vid, uint16_t queue_id,
241 struct rte_mempool *mbuf_pool, struct rte_mbuf **pkts, uint16_t count,
242 int *nr_inflight, int16_t dma_id, uint16_t vchan_id);
248 #endif /* _RTE_VHOST_ASYNC_H_ */