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 	union {
91 		uint32_t info;
92 		struct {
93 			uint16_t descs; /* num of descs inflight */
94 			uint16_t segs; /* iov segs inflight */
95 		};
96 	};
97 };
98 
99 /**
100  *  dma channel feature bit definition
101  */
102 struct rte_vhost_async_features {
103 	union {
104 		uint32_t intval;
105 		struct {
106 			uint32_t async_inorder:1;
107 			uint32_t resvd_0:15;
108 			uint32_t async_threshold:12;
109 			uint32_t resvd_1:4;
110 		};
111 	};
112 };
113 
114 /**
115  * register a async channel for vhost
116  *
117  * @param vid
118  *  vhost device id async channel to be attached to
119  * @param queue_id
120  *  vhost queue id async channel to be attached to
121  * @param features
122  *  DMA channel feature bit
123  *    b0       : DMA supports inorder data transfer
124  *    b1  - b15: reserved
125  *    b16 - b27: Packet length threshold for DMA transfer
126  *    b28 - b31: reserved
127  * @param ops
128  *  DMA operation callbacks
129  * @return
130  *  0 on success, -1 on failures
131  */
132 __rte_experimental
133 int rte_vhost_async_channel_register(int vid, uint16_t queue_id,
134 	uint32_t features, struct rte_vhost_async_channel_ops *ops);
135 
136 /**
137  * unregister a dma channel for vhost
138  *
139  * @param vid
140  *  vhost device id DMA channel to be detached
141  * @param queue_id
142  *  vhost queue id DMA channel to be detached
143  * @return
144  *  0 on success, -1 on failures
145  */
146 __rte_experimental
147 int rte_vhost_async_channel_unregister(int vid, uint16_t queue_id);
148 
149 /**
150  * This function submit enqueue data to async engine. This function has
151  * no guranttee to the transfer completion upon return. Applications
152  * should poll transfer status by 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  * @return
163  *  num of packets enqueued
164  */
165 __rte_experimental
166 uint16_t rte_vhost_submit_enqueue_burst(int vid, uint16_t queue_id,
167 		struct rte_mbuf **pkts, uint16_t count);
168 
169 /**
170  * This function check async completion status for a specific vhost
171  * device queue. Packets which finish copying (enqueue) operation
172  * will be returned in an array.
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  *  blank array to get return packet pointer
180  * @param count
181  *  size of the packet array
182  * @return
183  *  num of packets returned
184  */
185 __rte_experimental
186 uint16_t rte_vhost_poll_enqueue_completed(int vid, uint16_t queue_id,
187 		struct rte_mbuf **pkts, uint16_t count);
188 
189 #endif /* _RTE_VHOST_ASYNC_H_ */
190