1/* SPDX-License-Identifier: BSD-3-Clause */
2/* Copyright(c) 2007-2022 Intel Corporation */
3/**
4 ***************************************************************************
5 * @file icp_sal_poll.h
6 *
7 * @defgroup SalPoll
8 *
9 * @ingroup SalPoll
10 *
11 * @description
12 *    Polling APIs for instance polling.
13 *    These functions retrieve requests on appropriate response rings and
14 *    dispatch the associated callbacks. Callbacks are called in the
15 *    context of the polling function itself.
16 *
17 *
18 ***************************************************************************/
19
20#ifndef ICP_SAL_POLL_H
21#define ICP_SAL_POLL_H
22
23/*************************************************************************
24  * @ingroup SalPoll
25  * @description
26  *    Poll a Cy logical instance to retrieve requests that are on the
27  *    response rings associated with that instance and dispatch the
28  *    associated callbacks.
29  *
30  * @context
31  *      This functions is called from both the user and kernel context
32  *
33  * @assumptions
34  *      None
35  * @sideEffects
36  *      None
37  * @reentrant
38  *      No
39  * @threadSafe
40  *      Yes
41  *
42  * @param[in] instanceHandle     Instance handle.
43  * @param[in] response_quota     The maximum number of messages that
44  *                               will be read in one polling. Setting
45  *                               the response quota to zero means that
46  *                               all messages on the ring will be read.
47  *
48  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
49  * @retval CPA_STATUS_RETRY      There are no responses on the rings
50  *                               associated with this instance
51  * @retval CPA_STATUS_FAIL       Indicates a failure
52  *************************************************************************/
53CpaStatus icp_sal_CyPollInstance(CpaInstanceHandle instanceHandle,
54				 Cpa32U response_quota);
55
56/*************************************************************************
57  * @ingroup SalPoll
58  * @description
59  *    Poll a Sym Cy ring to retrieve requests that are on the
60  *    response rings associated with that instance and dispatch the
61  *    associated callbacks.
62  *
63  * @context
64  *      This functions is called from both the user and kernel context
65  *
66  * @assumptions
67  *      None
68  * @sideEffects
69  *      None
70  * @reentrant
71  *      No
72  * @threadSafe
73  *      Yes
74  *
75  * @param[in] instanceHandle     Instance handle.
76  * @param[in] response_quota     The maximum number of messages that
77  *                               will be read in one polling. Setting
78  *                               the response quota to zero means that
79  *                               all messages on the ring will be read.
80  *
81  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
82  * @retval CPA_STATUS_RETRY      There are no responses on the rings
83  *                               associated with this instance
84  * @retval CPA_STATUS_FAIL       Indicates a failure
85  *************************************************************************/
86CpaStatus icp_sal_CyPollSymRing(CpaInstanceHandle instanceHandle,
87				Cpa32U response_quota);
88
89/*************************************************************************
90  * @ingroup SalPoll
91  * @description
92  *    Poll an Asym Cy ring to retrieve requests that are on the
93  *    response rings associated with that instance and dispatch the
94  *    associated callbacks.
95  *
96  * @context
97  *      This functions is called from both the user and kernel context
98  *
99  * @assumptions
100  *      None
101  * @sideEffects
102  *      None
103  * @reentrant
104  *      No
105  * @threadSafe
106  *      Yes
107  *
108  * @param[in] instanceHandle     Instance handle.
109  * @param[in] response_quota     The maximum number of messages that
110  *                               will be read in one polling. Setting
111  *                               the response quota to zero means that
112  *                               all messages on the ring will be read.
113  *
114  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
115  * @retval CPA_STATUS_RETRY      There are no responses on the rings
116  *                               associated with this instance
117  * @retval CPA_STATUS_FAIL       Indicates a failure
118  *************************************************************************/
119CpaStatus icp_sal_CyPollAsymRing(CpaInstanceHandle instanceHandle,
120				 Cpa32U response_quota);
121
122/*************************************************************************
123  * @ingroup SalPoll
124  * @description
125  *    Poll a Cy NRBG ring to retrieve requests that are on the
126  *    response rings associated with that instance and dispatch the
127  *    associated callbacks.
128  *
129  * @context
130  *      This functions is called from both the user and kernel context
131  *
132  * @assumptions
133  *      None
134  * @sideEffects
135  *      None
136  * @reentrant
137  *      No
138  * @threadSafe
139  *      Yes
140  *
141  * @param[in] instanceHandle     Instance handle.
142  * @param[in] response_quota     The maximum number of messages that
143  *                               will be read in one polling. Setting
144  *                               the response quota to zero means that
145  *                               all messages on the ring will be read.
146  *
147  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
148  * @retval CPA_STATUS_RETRY      There are no responses on the rings
149  *                               associated with this instance
150  * @retval CPA_STATUS_FAIL       Indicates a failure
151  *************************************************************************/
152CpaStatus icp_sal_CyPollNRBGRing(CpaInstanceHandle instanceHandle,
153				 Cpa32U response_quota);
154
155/*************************************************************************
156  * @ingroup SalPoll
157  * @description
158  *    Poll the high priority symmetric response ring associated with a Cy
159  *    logical instance to retrieve requests and dispatch the
160  *    associated callbacks.
161  *
162  *    This API is recommended for data plane applications, in which the
163  *    cost of offload - that is, the cycles consumed by the driver in
164  *    sending requests to the hardware, and processing responses - needs
165  *    to be minimized.  In particular, use of this API is recommended
166  *    if the following constraints are acceptable to your application:
167  *
168  *    - Thread safety is not guaranteed.  Each software thread should
169  *      have access to its own unique instance (CpaInstanceHandle) to
170  *      avoid contention.
171  *    - The "default" instance (@ref CPA_INSTANCE_HANDLE_SINGLE) is not
172  *      supported on this API.  The specific handle should be obtained
173  *      using the instance discovery functions (@ref cpaCyGetNumInstances,
174  *      @ref cpaCyGetInstances).
175  *
176  *    This polling function should be used with the functions described
177  *    in cpa_cy_sym_dp.h
178  *
179  * @context
180  *      This functions is called from both the user and kernel context
181  *
182  * @assumptions
183  *      None
184  * @sideEffects
185  *      None
186  * @reentrant
187  *      No
188  * @threadSafe
189  *      No
190  *
191  * @param[in] instanceHandle     Instance handle.
192  * @param[in] response_quota     The maximum number of messages that
193  *                               will be read in one polling. Setting
194  *                               the response quota to zero means that
195  *                               all messages on the ring will be read.
196  *
197  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
198  * @retval CPA_STATUS_RETRY      There are no responses on the ring
199  *                               associated with this instance
200  * @retval CPA_STATUS_FAIL       Indicates a failure
201  *************************************************************************/
202CpaStatus icp_sal_CyPollDpInstance(const CpaInstanceHandle instanceHandle,
203				   const Cpa32U response_quota);
204
205/*************************************************************************
206  * @ingroup SalPoll
207  * @description
208  *    Poll a Dc logical instance to retrieve requests that are on the
209  *    response ring associated with that instance and dispatch the
210  *    associated callbacks.
211  *
212  * @context
213  *      This function is called from both the user and kernel context
214  *
215  * @assumptions
216  *      None
217  * @sideEffects
218  *      None
219  * @reentrant
220  *      No
221  * @threadSafe
222  *      Yes
223  *
224  * @param[in] instanceHandle     Instance handle.
225  * @param[in] response_quota     The maximum number of messages that
226  *                               will be read in one polling. Setting
227  *                               the response quota to zero means that
228  *                               all messages on the ring will be read.
229  *
230  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
231  * @retval CPA_STATUS_RETRY      There are no responses on the ring
232  *                               associated with this instance
233  * @retval CPA_STATUS_FAIL       Indicates a failure
234  *************************************************************************/
235CpaStatus icp_sal_DcPollInstance(CpaInstanceHandle instanceHandle,
236				 Cpa32U response_quota);
237
238/*************************************************************************
239  * @ingroup SalPoll
240  * @description
241  *    Poll the response ring associated with a Dc logical instance to
242  *    retrieve requests and dispatch the associated callbacks.
243  *
244  *    This API is recommended for data plane applications, in which the
245  *    cost of offload - that is, the cycles consumed by the driver in
246  *    sending requests to the hardware, and processing responses - needs
247  *    to be minimized.  In particular, use of this API is recommended
248  *    if the following constraints are acceptable to your application:
249  *
250  *    - Thread safety is not guaranteed.  Each software thread should
251  *      have access to its own unique instance (CpaInstanceHandle) to
252  *      avoid contention.
253  *    - The "default" instance (@ref CPA_INSTANCE_HANDLE_SINGLE) is not
254  *      supported on this API.  The specific handle should be obtained
255  *      using the instance discovery functions (@ref cpaDcGetNumInstances,
256  *      @ref cpaDcGetInstances).
257  *
258  *    This polling function should be used with the functions described
259  *    in cpa_dc_dp.h
260
261  *
262  * @context
263  *      This functions is called from both the user and kernel context
264  *
265  * @assumptions
266  *      None
267  * @sideEffects
268  *      None
269  * @reentrant
270  *      No
271  * @threadSafe
272  *      No
273  *
274  * @param[in] instanceHandle     Instance handle.
275  * @param[in] response_quota     The maximum number of messages that
276  *                               will be read in one polling. Setting
277  *                               the response quota to zero means that
278  *                               all messages on the ring will be read.
279  *
280  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
281  * @retval CPA_STATUS_RETRY      There are no responses on the ring
282  *                               associated with this instance
283  * @retval CPA_STATUS_FAIL       Indicates a failure
284  *************************************************************************/
285CpaStatus icp_sal_DcPollDpInstance(CpaInstanceHandle dcInstance,
286				   Cpa32U responseQuota);
287
288/*************************************************************************
289  * @ingroup SalPoll
290  * @description
291  *    This function polls the rings on the given bank to determine
292  *    if any of the rings contain messages to be read. The
293  *    response quota is per ring.
294  *
295  * @context
296  *      This functions is called from both the user and kernel context
297  *
298  * @assumptions
299  *      None
300  * @sideEffects
301  *      None
302  * @reentrant
303  *      No
304  * @threadSafe
305  *      Yes
306  *
307  * @param[in] accelId            Acceleration device Id, also known as
308  *                               packageId. This can be obtained using
309  *                               instance info functions (
310  *                               @ref cpaCyInstanceGetInfo2
311  *                               and @ref cpaDcInstanceGetInfo2)
312  *
313  * @param[in] bank_number        Bank number
314  *
315  * @param[in] response_quota     The maximum number of messages that
316  *                               will be read in one polling. Setting
317  *                               the response quota to zero means that
318  *                               all messages on the ring will be read.
319  *
320  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
321  * @retval CPA_STATUS_RETRY      There is no data on any ring on the bank
322  *                               or the bank is already being polled
323  * @retval CPA_STATUS_FAIL       Indicates a failure
324  *************************************************************************/
325CpaStatus
326icp_sal_pollBank(Cpa32U accelId, Cpa32U bank_number, Cpa32U response_quota);
327
328/*************************************************************************
329  * @ingroup SalPoll
330  * @description
331  *    This function polls the rings on all banks to determine
332  *    if any of the rings contain messages to be read. The
333  *    response quota is per ring.
334  *
335  * @context
336  *      This functions is called from both the user and kernel context
337  *
338  * @assumptions
339  *      None
340  * @sideEffects
341  *      None
342  * @reentrant
343  *      No
344  * @threadSafe
345  *      Yes
346  *
347  * @param[in] accelId            Acceleration device Id, also known as
348  *                               packageId. This can be obtained using
349  *                               instance info functions (
350  *                               @ref cpaCyInstanceGetInfo2
351  *                               and @ref cpaDcInstanceGetInfo2)
352  *
353  * @param[in] response_quota     The maximum number of messages that
354  *                               will be read in one polling. Setting
355  *                               the response quota to zero means that
356  *                               all messages on the ring will be read.
357  *
358  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
359  * @retval CPA_STATUS_RETRY      There is no data on any ring on any bank
360  *                               or the banks are already being polled
361  * @retval CPA_STATUS_FAIL       Indicates a failure
362  *************************************************************************/
363CpaStatus icp_sal_pollAllBanks(Cpa32U accelId, Cpa32U response_quota);
364
365#endif
366