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 *************************************************************************/ 53 CpaStatus 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 *************************************************************************/ 86 CpaStatus 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 *************************************************************************/ 119 CpaStatus 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 *************************************************************************/ 152 CpaStatus 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 *************************************************************************/ 202 CpaStatus 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 *************************************************************************/ 235 CpaStatus 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 *************************************************************************/ 285 CpaStatus 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 *************************************************************************/ 325 CpaStatus 326 icp_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 *************************************************************************/ 363 CpaStatus icp_sal_pollAllBanks(Cpa32U accelId, Cpa32U response_quota); 364 365 #endif 366