net/virtio: fix incorrect cast of void *
[dpdk.git] / vhost / rte_vhost_async.h
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 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 /**
250  * This function checks async completion status and clear packets for
251  * a specific vhost device queue. Packets which are inflight will be
252  * returned in an array.
253  *
254  * @note This function does not perform any locking
255  *
256  * @param vid
257  *  ID of vhost device to clear data
258  * @param queue_id
259  *  Queue id to clear data
260  * @param pkts
261  *  Blank array to get return packet pointer
262  * @param count
263  *  Size of the packet array
264  * @return
265  *  Number of packets returned
266  */
267 __rte_experimental
268 uint16_t rte_vhost_clear_queue_thread_unsafe(int vid, uint16_t queue_id,
269                 struct rte_mbuf **pkts, uint16_t count);
270
271 #endif /* _RTE_VHOST_ASYNC_H_ */