1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2022 Intel Corporation */ 3 /* $FreeBSD$ */ 4 /** 5 ***************************************************************************** 6 * @file lac_sal.h 7 * 8 * @defgroup SalCtrl Service Access Layer Controller 9 * 10 * @ingroup SalCtrl 11 * 12 * @description 13 * These functions are the functions to be executed for each state 14 * of the state machine for each service. 15 * 16 *****************************************************************************/ 17 18 #ifndef LAC_SAL_H 19 #define LAC_SAL_H 20 21 #include "cpa_cy_im.h" 22 23 /** 24 ******************************************************************************* 25 * @ingroup SalCtrl 26 * @description 27 * This function allocates memory for a specific instance type. 28 * Zeros this memory and sets the generic service section of 29 * the instance memory. 30 * 31 * @context 32 * This function is called from the generic services init. 33 * 34 * @assumptions 35 * None 36 * @sideEffects 37 * None 38 * @reentrant 39 * No 40 * @threadSafe 41 * Yes 42 * 43 * @param[in] service The type of the service to be created 44 * (e.g. CRYPTO) 45 * @param[in] instance_num The logical instance number which will 46 * run the service 47 * @param[out] pObj Pointer to specific service instance memory 48 * @retVal CPA_STATUS_SUCCESS Instance memory successfully allocated 49 * @retVal CPA_STATUS_RESOURCE Instance memory not successfully allocated 50 * @retVal CPA_STATUS_FAIL Unsupported service type 51 * 52 *****************************************************************************/ 53 CpaStatus SalCtrl_ServiceCreate(sal_service_type_t service, 54 Cpa32U instance_num, 55 sal_service_t **pObj); 56 57 /** 58 ******************************************************************************* 59 * @ingroup SalCtl 60 * @description 61 * This macro goes through the 'list' passed in as a parameter. For each 62 * element found in the list, it peforms a cast to the type of the element 63 * given by the 'type' parameter. Finally, it calls the function given by 64 * the 'function' parameter, passing itself and the device as parameters. 65 * 66 * In case of error (i.e. 'function' does not return _SUCCESS or _RETRY) 67 * processing of the 'list' elements will stop and the status_ret will be 68 * updated. 69 * 70 * In case of _RETRY status_ret will be updated but the 'list' 71 * will continue to be processed. _RETRY is only expected when 72 * 'function' is stop. 73 * 74 * @context 75 * This macro is used by both the service and qat event handlers. 76 * 77 * @assumptions 78 * None 79 * @sideEffects 80 * None 81 * 82 * @param[in] list The list of services or qats as a type of list_t 83 * @param[in] type It identifies the type of the object inside the 84 * list: service or qat 85 * @param[in] device The ADF accelerator handle for the device 86 * @param[in] function The function pointer to call 87 * @param[in/out] status_ret If an error occurred (i.e. status returned from 88 * function is not _SUCCESS) then status_ret is 89 * overwritten with status returned from function. 90 * 91 *****************************************************************************/ 92 #define SAL_FOR_EACH(list, type, device, function, status_ret) \ 93 do { \ 94 sal_list_t *curr_element = list; \ 95 CpaStatus status_temp = CPA_STATUS_SUCCESS; \ 96 typeof(type) *process = NULL; \ 97 while (NULL != curr_element) { \ 98 process = \ 99 (typeof(type) *)SalList_getObject(curr_element); \ 100 status_temp = process->function(device, process); \ 101 if ((CPA_STATUS_SUCCESS != status_temp) && \ 102 (CPA_STATUS_RETRY != status_temp)) { \ 103 status_ret = status_temp; \ 104 break; \ 105 } else { \ 106 if (CPA_STATUS_RETRY == status_temp) { \ 107 status_ret = status_temp; \ 108 } \ 109 } \ 110 curr_element = SalList_next(curr_element); \ 111 } \ 112 } while (0) 113 114 /** 115 ******************************************************************************* 116 * @ingroup SalCtl 117 * @description 118 * This macro goes through the 'list' passed in as a parameter. For each 119 * element found in the list, it peforms a cast to the type of the element 120 * given by the 'type' parameter. Finally, it checks the state of the 121 * element and if it is in state 'state_check' then it calls the 122 * function given by the 'function' parameter, passing itself 123 * and the device as parameters. 124 * If the element is not in 'state_check' it returns from the macro. 125 * 126 * In case of error (i.e. 'function' does not return _SUCCESS) 127 * processing of the 'list' elements will continue. 128 * 129 * @context 130 * This macro is used by both the service and qat event handlers. 131 * 132 * @assumptions 133 * None 134 * @sideEffects 135 * None 136 * 137 * @param[in] list The list of services or qats as a type of list_t 138 * @param[in] type It identifies the type of the object 139 * inside the list: service or qat 140 * @param[in] device The ADF accelerator handle for the device 141 * @param[in] function The function pointer to call 142 * @param[in] state_check The state to check for 143 * 144 *****************************************************************************/ 145 #define SAL_FOR_EACH_STATE(list, type, device, function, state_check) \ 146 do { \ 147 sal_list_t *curr_element = list; \ 148 typeof(type) *process = NULL; \ 149 while (NULL != curr_element) { \ 150 process = \ 151 (typeof(type) *)SalList_getObject(curr_element); \ 152 if (process->state == state_check) { \ 153 process->function(device, process); \ 154 } else { \ 155 break; \ 156 } \ 157 curr_element = SalList_next(curr_element); \ 158 } \ 159 } while (0) 160 161 /************************************************************************* 162 * @ingroup SalCtrl 163 * @description 164 * This function is used to initialize an instance of crypto service. 165 * It creates a crypto instance's memory pools. It calls ADF to create 166 * its required transport handles. It calls the sub crypto service init 167 * functions. Resets the stats. 168 * 169 * @context 170 * This function is called from the SalCtrl_ServiceEventInit function. 171 * 172 * @assumptions 173 * None 174 * @sideEffects 175 * None 176 * @reentrant 177 * No 178 * @threadSafe 179 * No (ADF ensures that this function doesn't need to be thread safe) 180 * 181 * @param[in] device An icp_accel_dev_t* type 182 * @param[in] service A crypto instance 183 * 184 *************************************************************************/ 185 CpaStatus SalCtrl_CryptoInit(icp_accel_dev_t *device, sal_service_t *service); 186 187 /************************************************************************* 188 * @ingroup SalCtrl 189 * @description 190 * This function is used to start an instance of crypto service. 191 * It sends the first messages to FW on its crypto instance transport 192 * handles. For asymmetric crypto it verifies the header on the downloaded 193 * MMP library. 194 * 195 * @context 196 * This function is called from the SalCtrl_ServiceEventStart function. 197 * 198 * @assumptions 199 * None 200 * @sideEffects 201 * None 202 * @reentrant 203 * No 204 * @threadSafe 205 * No (ADF ensures that this function doesn't need to be thread safe) 206 * 207 * @param[in] device An icp_accel_dev_t* type 208 * @param[in] service A crypto instance 209 * 210 *************************************************************************/ 211 CpaStatus SalCtrl_CryptoStart(icp_accel_dev_t *device, sal_service_t *service); 212 213 /************************************************************************* 214 * @ingroup SalCtrl 215 * @description 216 * This function is used to stop an instance of crypto service. 217 * It checks for inflight messages to the FW. If no messages are pending 218 * it returns success. If messages are pending it returns retry. 219 * 220 * @context 221 * This function is called from the SalCtrl_ServiceEventStop function. 222 * 223 * @assumptions 224 * None 225 * @sideEffects 226 * None 227 * @reentrant 228 * No 229 * @threadSafe 230 * No (ADF ensures that this function doesn't need to be thread safe) 231 * 232 * @param[in] device An icp_accel_dev_t* type 233 * @param[in] service A crypto instance 234 * 235 *************************************************************************/ 236 CpaStatus SalCtrl_CryptoStop(icp_accel_dev_t *device, sal_service_t *service); 237 238 /************************************************************************* 239 * @ingroup SalCtrl 240 * @description 241 * This function is used to shutdown an instance of crypto service. 242 * It frees resources allocated at initialisation - e.g. frees the 243 * memory pools and ADF transport handles. 244 * 245 * @context 246 * This function is called from the SalCtrl_ServiceEventShutdown function. 247 * 248 * @assumptions 249 * None 250 * @sideEffects 251 * None 252 * @reentrant 253 * No 254 * @threadSafe 255 * No (ADF ensures that this function doesn't need to be thread safe) 256 * 257 * @param[in] device An icp_accel_dev_t* type 258 * @param[in] service A crypto instance 259 * 260 *************************************************************************/ 261 CpaStatus SalCtrl_CryptoShutdown(icp_accel_dev_t *device, 262 sal_service_t *service); 263 264 /************************************************************************* 265 * @ingroup SalCtrl 266 * @description 267 * This function sets the capability info of crypto instances. 268 * 269 * @context 270 * This function is called from the cpaCyQueryCapabilities and 271 * LacSymSession_ParamCheck function. 272 * 273 * @assumptions 274 * None 275 * @sideEffects 276 * None 277 * @reentrant 278 * No 279 * @threadSafe 280 * No (ADF ensures that this function doesn't need to be thread safe) 281 * 282 * @param[in] service A sal_service_t* type 283 * @param[in] cyCapabilityInfo A CpaCyCapabilitiesInfo* type 284 * 285 *************************************************************************/ 286 void SalCtrl_CyQueryCapabilities(sal_service_t *pGenericService, 287 CpaCyCapabilitiesInfo *pCapInfo); 288 289 /************************************************************************* 290 * @ingroup SalCtrl 291 * @description 292 * This function is used to initialize an instance of compression service. 293 * It creates a compression instance's memory pools. It calls ADF to create 294 * its required transport handles. It zeros an instances stats. 295 * 296 * @context 297 * This function is called from the SalCtrl_ServiceEventInit function. 298 * 299 * @assumptions 300 * None 301 * @sideEffects 302 * None 303 * @reentrant 304 * No 305 * @threadSafe 306 * No (ADF ensures that this function doesn't need to be thread safe) 307 * 308 * @param[in] device An icp_accel_dev_t* type 309 * @param[in] service A compression instance 310 * 311 *************************************************************************/ 312 313 CpaStatus SalCtrl_CompressionInit(icp_accel_dev_t *device, 314 sal_service_t *service); 315 316 /************************************************************************* 317 * @ingroup SalCtrl 318 * @description 319 * This function is used to start an instance of compression service. 320 * 321 * @context 322 * This function is called from the SalCtrl_ServiceEventStart function. 323 * 324 * @assumptions 325 * None 326 * @sideEffects 327 * None 328 * @reentrant 329 * No 330 * @threadSafe 331 * No (ADF ensures that this function doesn't need to be thread safe) 332 * 333 * @param[in] device An icp_accel_dev_t* type 334 * @param[in] service A compression instance 335 * 336 *************************************************************************/ 337 338 CpaStatus SalCtrl_CompressionStart(icp_accel_dev_t *device, 339 sal_service_t *service); 340 341 /************************************************************************* 342 * @ingroup SalCtrl 343 * @description 344 * This function is used to stop an instance of compression service. 345 * It checks for inflight messages to the FW. If no messages are pending 346 * it returns success. If messages are pending it returns retry. 347 * 348 * @context 349 * This function is called from the SalCtrl_ServiceEventStop function. 350 * 351 * @assumptions 352 * None 353 * @sideEffects 354 * None 355 * @reentrant 356 * No 357 * @threadSafe 358 * No (ADF ensures that this function doesn't need to be thread safe) 359 * 360 * @param[in] device An icp_accel_dev_t* type 361 * @param[in] service A compression instance 362 * 363 *************************************************************************/ 364 365 CpaStatus SalCtrl_CompressionStop(icp_accel_dev_t *device, 366 sal_service_t *service); 367 368 /************************************************************************* 369 * @ingroup SalCtrl 370 * @description 371 * This function is used to shutdown an instance of compression service. 372 * It frees resources allocated at initialisation - e.g. frees the 373 * memory pools and ADF transport handles. 374 * 375 * @context 376 * This function is called from the SalCtrl_ServiceEventShutdown function. 377 * 378 * @assumptions 379 * None 380 * @sideEffects 381 * None 382 * @reentrant 383 * No 384 * @threadSafe 385 * No (ADF ensures that this function doesn't need to be thread safe) 386 * 387 * @param[in] device An icp_accel_dev_t* type 388 * @param[in] service A compression instance 389 * 390 *************************************************************************/ 391 392 CpaStatus SalCtrl_CompressionShutdown(icp_accel_dev_t *device, 393 sal_service_t *service); 394 395 /************************************************************************* 396 * @ingroup SalCtrl 397 * @description 398 * This function is used to get the number of services enabled 399 * from the config table. 400 * 401 * @context 402 * This function is called from the SalCtrl_QatInit 403 * 404 * @assumptions 405 * None 406 * @sideEffects 407 * None 408 * @reentrant 409 * No 410 * @threadSafe 411 * No 412 * 413 * param[in] device An icp_accel_dev_t* type 414 * param[in] pEnabledServices pointer to a variable used to store 415 * the enabled services 416 * 417 *************************************************************************/ 418 419 CpaStatus SalCtrl_GetEnabledServices(icp_accel_dev_t *device, 420 Cpa32U *pEnabledServices); 421 422 /************************************************************************* 423 * @ingroup SalCtrl 424 * @description 425 * This function is used to check if a service is enabled 426 * 427 * @context 428 * This function is called from the SalCtrl_QatInit 429 * 430 * @assumptions 431 * None 432 * @sideEffects 433 * None 434 * @reentrant 435 * No 436 * @threadSafe 437 * Yes 438 * 439 * param[in] enabled_services 440 * param[in] service 441 * 442 *************************************************************************/ 443 444 CpaBoolean SalCtrl_IsServiceEnabled(Cpa32U enabled_services, 445 sal_service_type_t service); 446 447 /************************************************************************* 448 * @ingroup SalCtrl 449 * @description 450 * This function is used to check if a service is supported on the device 451 * The key difference between this and SalCtrl_GetSupportedServices() is 452 * that the latter treats it as an error if the service is unsupported. 453 * 454 * @context 455 * This can be called anywhere. 456 * 457 * @assumptions 458 * None 459 * @sideEffects 460 * None 461 * @reentrant 462 * No 463 * @threadSafe 464 * Yes 465 * 466 * param[in] device 467 * param[in] service service or services to check 468 * 469 *************************************************************************/ 470 CpaBoolean SalCtrl_IsServiceSupported(icp_accel_dev_t *device, 471 sal_service_type_t service); 472 473 /************************************************************************* 474 * @ingroup SalCtrl 475 * @description 476 * This function is used to check whether enabled services has associated 477 * hardware capability support 478 * 479 * @context 480 * This functions is called from the SalCtrl_ServiceEventInit function. 481 * 482 * @assumptions 483 * None 484 * @sideEffects 485 * None 486 * @reentrant 487 * No 488 * @threadSafe 489 * Yes 490 * 491 * param[in] device A pointer to an icp_accel_dev_t 492 * param[in] enabled_services It is the bitmask for the enabled services 493 *************************************************************************/ 494 495 CpaStatus SalCtrl_GetSupportedServices(icp_accel_dev_t *device, 496 Cpa32U enabled_services); 497 498 #endif 499