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