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