193139Sru/* SPDX-License-Identifier: BSD-3-Clause */
293139Sru/* Copyright(c) 2007-2022 Intel Corporation */
393139Sru/**
4146515Sru ***************************************************************************
5146515Sru * @file icp_sal_poll.h
6146515Sru *
793139Sru * @defgroup SalPoll
893139Sru *
993139Sru * @ingroup SalPoll
1093139Sru *
11146515Sru * @description
12146515Sru *    Polling APIs for instance polling.
1393139Sru *    These functions retrieve requests on appropriate response rings and
14146515Sru *    dispatch the associated callbacks. Callbacks are called in the
15146515Sru *    context of the polling function itself.
16146515Sru *
1793139Sru *
1893139Sru ***************************************************************************/
1993139Sru
2093139Sru#ifndef ICP_SAL_POLL_H
2193139Sru#define ICP_SAL_POLL_H
2293139Sru
2393139Sru/*************************************************************************
2493139Sru  * @ingroup SalPoll
2593139Sru  * @description
2693139Sru  *    Poll a Cy logical instance to retrieve requests that are on the
2793139Sru  *    response rings associated with that instance and dispatch the
2893139Sru  *    associated callbacks.
29114472Sru  *
30114472Sru  * @context
31114472Sru  *      This functions is called from both the user and kernel context
32114472Sru  *
33114472Sru  * @assumptions
34114472Sru  *      None
35114472Sru  * @sideEffects
36114472Sru  *      None
37114472Sru  * @reentrant
38114472Sru  *      No
3993139Sru  * @threadSafe
4093139Sru  *      Yes
4193139Sru  *
4293139Sru  * @param[in] instanceHandle     Instance handle.
4393139Sru  * @param[in] response_quota     The maximum number of messages that
4493139Sru  *                               will be read in one polling. Setting
4593139Sru  *                               the response quota to zero means that
4693139Sru  *                               all messages on the ring will be read.
4793139Sru  *
4893139Sru  * @retval CPA_STATUS_SUCCESS    Successfully polled a ring with data
4993139Sru  * @retval CPA_STATUS_RETRY      There are no responses on the rings
5093139Sru  *                               associated with this instance
5193139Sru  * @retval CPA_STATUS_FAIL       Indicates a failure
5293139Sru  *************************************************************************/
5393139SruCpaStatus icp_sal_CyPollInstance(CpaInstanceHandle instanceHandle,
5493139Sru				 Cpa32U response_quota);
5593139Sru
56114472Sru/*************************************************************************
5793139Sru  * @ingroup SalPoll
5893139Sru  * @description
5993139Sru  *    Poll a Sym Cy ring to retrieve requests that are on the
6093139Sru  *    response rings associated with that instance and dispatch the
6193139Sru  *    associated callbacks.
6293139Sru  *
6393139Sru  * @context
6493139Sru  *      This functions is called from both the user and kernel context
6593139Sru  *
6693139Sru  * @assumptions
6793139Sru  *      None
6893139Sru  * @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