1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2022 Intel Corporation */ 3 /* $FreeBSD$ */ 4 /** 5 *************************************************************************** 6 * @file icp_sal_user.h 7 * 8 * @ingroup SalUser 9 * 10 * User space process init and shutdown functions. 11 * 12 ***************************************************************************/ 13 14 #ifndef ICP_SAL_USER_H 15 #define ICP_SAL_USER_H 16 17 /************************************************************************* 18 * @ingroup SalUser 19 * @description 20 * This function initialises and starts user space service access layer 21 * (SAL) - it registers SAL with ADF and initialises the ADF proxy. 22 * This function must only be called once per user space process. 23 * 24 * @context 25 * This function is called from the user process context 26 * 27 * @assumptions 28 * None 29 * @sideEffects 30 * None 31 * @reentrant 32 * No 33 * @threadSafe 34 * Yes 35 * 36 * @param[in] pProcessName Process address space name described in 37 * the config file for this device 38 * 39 * @retval CPA_STATUS_SUCCESS No error 40 * @retval CPA_STATUS_FAIL Operation failed 41 * 42 *************************************************************************/ 43 CpaStatus icp_sal_userStart(const char *pProcessName); 44 45 /************************************************************************* 46 * @ingroup SalUser 47 * @description 48 * This function is to be used with simplified config file, where user 49 * defines many user space processes. The driver generates unique 50 * process names based on the pProcessName provided. 51 * For example: 52 * If a config file in simplified format contains: 53 * [SSL] 54 * NumProcesses = 3 55 * 56 * Then three internal sections will be generated and the three 57 * applications can be started at a given time. Each application can call 58 * icp_sal_userStartMultiProcess("SSL"). In this case the driver will 59 * figure out the unique name to use for each process. 60 * 61 * @context 62 * This function is called from the user process context 63 * 64 * @assumptions 65 * None 66 * @sideEffects 67 * None 68 * @reentrant 69 * No 70 * @threadSafe 71 * Yes 72 * 73 * @param[in] pProcessName Process address space name described in 74 * the new format of the config file 75 * for this device. 76 * 77 * @param[in] limitDevAccess Specifies if the address space is limited 78 * to one device (true) or if it spans 79 * accross multiple devices. 80 * 81 * @retval CPA_STATUS_SUCCESS No error 82 * @retval CPA_STATUS_FAIL Operation failed. In this case user 83 * can wait and retry. 84 * 85 *************************************************************************/ 86 CpaStatus icp_sal_userStartMultiProcess(const char *pProcessName, 87 CpaBoolean limitDevAccess); 88 89 /************************************************************************* 90 * @ingroup SalUser 91 * @description 92 * This function stops and shuts down user space SAL 93 * - it deregisters SAL with ADF and shuts down ADF proxy 94 * 95 * @context 96 * This function is called from the user process context 97 * 98 * @assumptions 99 * None 100 * @sideEffects 101 * None 102 * @reentrant 103 * No 104 * @threadSafe 105 * Yes 106 * 107 * @retval CPA_STATUS_SUCCESS No error 108 * @retval CPA_STATUS_FAIL Operation failed 109 * 110 ************************************************************************/ 111 CpaStatus icp_sal_userStop(void); 112 113 /************************************************************************* 114 * @ingroup SalUser 115 * @description 116 * This function gets the number of the available dynamic allocated 117 * crypto instances 118 * 119 * @context 120 * This function is called from the user process context 121 * 122 * @assumptions 123 * None 124 * @sideEffects 125 * None 126 * @reentrant 127 * No 128 * @threadSafe 129 * Yes 130 * 131 * @retval CPA_STATUS_SUCCESS No error 132 * @retval CPA_STATUS_FAIL Operation failed 133 * 134 ************************************************************************/ 135 CpaStatus icp_sal_userCyGetAvailableNumDynInstances(Cpa32U *pNumCyInstances); 136 137 /************************************************************************* 138 * @ingroup SalUser 139 * @description 140 * This function gets the number of the available dynamic allocated 141 * compression instances 142 * 143 * @context 144 * This function is called from the user process context 145 * 146 * @assumptions 147 * None 148 * @sideEffects 149 * None 150 * @reentrant 151 * No 152 * @threadSafe 153 * Yes 154 * 155 * @retval CPA_STATUS_SUCCESS No error 156 * @retval CPA_STATUS_FAIL Operation failed 157 * 158 ************************************************************************/ 159 CpaStatus icp_sal_userDcGetAvailableNumDynInstances(Cpa32U *pNumDcInstances); 160 161 /************************************************************************* 162 * @ingroup SalUser 163 * @description 164 * This function gets the number of the available dynamic allocated 165 * crypto instances which are from the specific device package. 166 * 167 * @context 168 * This function is called from the user process context 169 * 170 * @assumptions 171 * None 172 * @sideEffects 173 * None 174 * @reentrant 175 * No 176 * @threadSafe 177 * Yes 178 * 179 * @retval CPA_STATUS_SUCCESS No error 180 * @retval CPA_STATUS_FAIL Operation failed 181 * 182 ************************************************************************/ 183 CpaStatus 184 icp_sal_userCyGetAvailableNumDynInstancesByDevPkg(Cpa32U *pNumCyInstances, 185 Cpa32U devPkgID); 186 187 /************************************************************************* 188 * @ingroup SalUser 189 * @description 190 * This function gets the number of the available dynamic allocated 191 * crypto instances which are from the specific device package and specific 192 * accelerator. 193 * 194 * @context 195 * This function is called from the user process context 196 * 197 * @assumptions 198 * None 199 * @sideEffects 200 * None 201 * @reentrant 202 * No 203 * @threadSafe 204 * Yes 205 * 206 * @retval CPA_STATUS_SUCCESS No error 207 * @retval CPA_STATUS_FAIL Operation failed 208 * 209 ************************************************************************/ 210 CpaStatus 211 icp_sal_userCyGetAvailableNumDynInstancesByPkgAccel(Cpa32U *pNumCyInstances, 212 Cpa32U devPkgID, 213 Cpa32U accelerator_number); 214 215 /************************************************************************* 216 * @ingroup SalUser 217 * @description 218 * This function gets the number of the available dynamic allocated 219 * compression instances which are from the specific device package. 220 * 221 * @context 222 * This function is called from the user process context 223 * 224 * @assumptions 225 * None 226 * @sideEffects 227 * None 228 * @reentrant 229 * No 230 * @threadSafe 231 * Yes 232 * 233 * @retval CPA_STATUS_SUCCESS No error 234 * @retval CPA_STATUS_FAIL Operation failed 235 * 236 ************************************************************************/ 237 CpaStatus 238 icp_sal_userDcGetAvailableNumDynInstancesByDevPkg(Cpa32U *pNumDcInstances, 239 Cpa32U devPkgID); 240 241 /************************************************************************* 242 * @ingroup SalUser 243 * @description 244 * This function allocates crypto instances 245 * from dynamic crypto instance pool 246 * - it adds new allocated instances into crypto_services 247 * - it initializes new allocated instances 248 * - it starts new allocated instances 249 * 250 * @context 251 * This function is called from the user process context 252 * 253 * @assumptions 254 * None 255 * @sideEffects 256 * None 257 * @reentrant 258 * No 259 * @threadSafe 260 * Yes 261 * 262 * @retval CPA_STATUS_SUCCESS No error 263 * @retval CPA_STATUS_FAIL Operation failed 264 * 265 ************************************************************************/ 266 CpaStatus icp_sal_userCyInstancesAlloc(Cpa32U numCyInstances, 267 CpaInstanceHandle *pCyInstances); 268 269 /************************************************************************* 270 * @ingroup SalUser 271 * @description 272 * This function allocates crypto instances 273 * from dynamic crypto instance pool 274 * which are from the specific device package. 275 * - it adds new allocated instances into crypto_services 276 * - it initializes new allocated instances 277 * - it starts new allocated instances 278 * 279 * @context 280 * This function is called from the user process context 281 * 282 * @assumptions 283 * None 284 * @sideEffects 285 * None 286 * @reentrant 287 * No 288 * @threadSafe 289 * Yes 290 * 291 * @retval CPA_STATUS_SUCCESS No error 292 * @retval CPA_STATUS_FAIL Operation failed 293 * 294 ************************************************************************/ 295 CpaStatus icp_sal_userCyInstancesAllocByDevPkg(Cpa32U numCyInstances, 296 CpaInstanceHandle *pCyInstances, 297 Cpa32U devPkgID); 298 299 /************************************************************************* 300 * @ingroup SalUser 301 * @description 302 * This function allocates crypto instances 303 * from dynamic crypto instance pool 304 * which are from the specific device package and specific accelerator 305 * - it adds new allocated instances into crypto_services 306 * - it initializes new allocated instances 307 * - it starts new allocated instances 308 * 309 * @context 310 * This function is called from the user process context 311 * 312 * @assumptions 313 * None 314 * @sideEffects 315 * None 316 * @reentrant 317 * No 318 * @threadSafe 319 * Yes 320 * 321 * @retval CPA_STATUS_SUCCESS No error 322 * @retval CPA_STATUS_FAIL Operation failed 323 * 324 ************************************************************************/ 325 CpaStatus 326 icp_sal_userCyInstancesAllocByPkgAccel(Cpa32U numCyInstances, 327 CpaInstanceHandle *pCyInstances, 328 Cpa32U devPkgID, 329 Cpa32U accelerator_number); 330 331 /************************************************************************* 332 * @ingroup SalUser 333 * @description 334 * This function frees crypto instances allocated 335 * from dynamic crypto instance pool 336 * - it stops the instances 337 * - it shutdowns the instances 338 * - it removes the instances from crypto_services 339 * 340 * @context 341 * This function is called from the user process context 342 * 343 * @assumptions 344 * None 345 * @sideEffects 346 * None 347 * @reentrant 348 * No 349 * @threadSafe 350 * Yes 351 * 352 * @retval CPA_STATUS_SUCCESS No error 353 * @retval CPA_STATUS_FAIL Operation failed 354 * 355 ************************************************************************/ 356 CpaStatus icp_sal_userCyFreeInstances(Cpa32U numCyInstances, 357 CpaInstanceHandle *pCyInstances); 358 359 /************************************************************************* 360 * @ingroup SalUser 361 * @description 362 * This function allocates compression instances 363 * from dynamic compression instance pool 364 * - it adds new allocated instances into compression_services 365 * - it initializes new allocated instances 366 * - it starts new allocated instances 367 * 368 * @context 369 * This function is called from the user process context 370 * 371 * @assumptions 372 * None 373 * @sideEffects 374 * None 375 * @reentrant 376 * No 377 * @threadSafe 378 * Yes 379 * 380 * @retval CPA_STATUS_SUCCESS No error 381 * @retval CPA_STATUS_FAIL Operation failed 382 * 383 ************************************************************************/ 384 CpaStatus icp_sal_userDcInstancesAlloc(Cpa32U numDcInstances, 385 CpaInstanceHandle *pDcInstances); 386 387 /************************************************************************* 388 * @ingroup SalUser 389 * @description 390 * This function allocates compression instances 391 * from dynamic compression instance pool 392 * which are from the specific device package. 393 * - it adds new allocated instances into compression_services 394 * - it initializes new allocated instances 395 * - it starts new allocated instances 396 * 397 * @context 398 * This function is called from the user process context 399 * 400 * @assumptions 401 * None 402 * @sideEffects 403 * None 404 * @reentrant 405 * No 406 * @threadSafe 407 * Yes 408 * 409 * @retval CPA_STATUS_SUCCESS No error 410 * @retval CPA_STATUS_FAIL Operation failed 411 * 412 ************************************************************************/ 413 CpaStatus icp_sal_userDcInstancesAllocByDevPkg(Cpa32U numDcInstances, 414 CpaInstanceHandle *pDcInstances, 415 Cpa32U devPkgID); 416 417 /************************************************************************* 418 * @ingroup SalUser 419 * @description 420 * This function frees compression instances allocated 421 * from dynamic compression instance pool 422 * - it stops the instances 423 * - it shutdowns the instances 424 * - it removes the instances from compression_services 425 * 426 * @context 427 * This function is called from the user process context 428 * 429 * @assumptions 430 * None 431 * @sideEffects 432 * None 433 * @reentrant 434 * No 435 * @threadSafe 436 * Yes 437 * 438 * @retval CPA_STATUS_SUCCESS No error 439 * @retval CPA_STATUS_FAIL Operation failed 440 * 441 ************************************************************************/ 442 CpaStatus icp_sal_userDcFreeInstances(Cpa32U numDcInstances, 443 CpaInstanceHandle *pDcInstances); 444 445 /************************************************************************* 446 * @ingroup SalUser 447 * @description 448 * This function checks if new devices have been started and if so 449 * starts to use them. 450 * 451 * @context 452 * This function is called from the user process context 453 * in threadless mode 454 * 455 * @assumptions 456 * None 457 * @sideEffects 458 * None 459 * @reentrant 460 * No 461 * @threadSafe 462 * No 463 * 464 * @retval CPA_STATUS_SUCCESS No error 465 * @retval CPA_STATUS_FAIL Operation failed 466 * 467 ************************************************************************/ 468 CpaStatus icp_sal_find_new_devices(void); 469 470 /************************************************************************* 471 * @ingroup SalUser 472 * @description 473 * This function polls device events. 474 * 475 * @context 476 * This function is called from the user process context 477 * in threadless mode 478 * 479 * @assumptions 480 * None 481 * @sideEffects 482 * In case a device has beed stoped or restarted the application 483 * will get restarting/stop/shutdown events 484 * @reentrant 485 * No 486 * @threadSafe 487 * No 488 * 489 * @retval CPA_STATUS_SUCCESS No error 490 * @retval CPA_STATUS_FAIL Operation failed 491 * 492 ************************************************************************/ 493 CpaStatus icp_sal_poll_device_events(void); 494 495 /* 496 * icp_adf_check_device 497 * 498 * @description: 499 * This function checks the status of the firmware/hardware for a given device. 500 * This function is used as part of the heartbeat functionality. 501 * 502 * @context 503 * This function is called from the user process context 504 * @assumptions 505 * None 506 * @sideEffects 507 * In case a device is unresponsive the device will 508 * be restarted. 509 * @reentrant 510 * No 511 * @threadSafe 512 * Yes 513 * 514 * @param[in] accelId Device Id. 515 * @retval CPA_STATUS_SUCCESS No error 516 * @retval CPA_STATUS_FAIL Operation failed 517 */ 518 CpaStatus icp_sal_check_device(Cpa32U accelId); 519 520 /* 521 * icp_adf_check_all_devices 522 * 523 * @description: 524 * This function checks the status of the firmware/hardware for all devices. 525 * This function is used as part of the heartbeat functionality. 526 * 527 * @context 528 * This function is called from the user process context 529 * @assumptions 530 * None 531 * @sideEffects 532 * In case a device is unresponsive the device will 533 * be restarted. 534 * @reentrant 535 * No 536 * @threadSafe 537 * Yes 538 * 539 * @retval CPA_STATUS_SUCCESS No error 540 * @retval CPA_STATUS_FAIL Operation failed 541 */ 542 CpaStatus icp_sal_check_all_devices(void); 543 544 /* 545 * @ingroup icp_sal_user 546 * @description 547 * This is a stub function to send messages to VF 548 * 549 * @context 550 * None 551 * 552 * @assumptions 553 * None 554 * @sideEffects 555 * None 556 * @reentrant 557 * Yes 558 * @threadSafe 559 * Yes 560 * 561 */ 562 CpaStatus icp_sal_userSendMsgToVf(Cpa32U accelId, Cpa32U vfNum, Cpa32U message); 563 564 /* 565 * @ingroup icp_sal_user 566 * @description 567 * This is a stub function to send messages to PF 568 * 569 * @context 570 * None 571 * 572 * @assumptions 573 * None 574 * @sideEffects 575 * None 576 * @reentrant 577 * Yes 578 * @threadSafe 579 * Yes 580 * 581 */ 582 CpaStatus icp_sal_userSendMsgToPf(Cpa32U accelId, Cpa32U message); 583 584 /* 585 * @ingroup icp_sal_user 586 * @description 587 * This is a stub function to get messages from VF 588 * 589 * @context 590 * None 591 * 592 * @assumptions 593 * None 594 * @sideEffects 595 * None 596 * @reentrant 597 * Yes 598 * @threadSafe 599 * Yes 600 * 601 */ 602 CpaStatus icp_sal_userGetMsgFromVf(Cpa32U accelId, 603 Cpa32U vfNum, 604 Cpa32U *message, 605 Cpa32U *messageCounter); 606 607 /* 608 * @ingroup icp_sal_user 609 * @description 610 * This is a stub function to get messages from PF 611 * 612 * @context 613 * None 614 * 615 * @assumptions 616 * None 617 * @sideEffects 618 * None 619 * @reentrant 620 * Yes 621 * @threadSafe 622 * Yes 623 * 624 */ 625 CpaStatus icp_sal_userGetMsgFromPf(Cpa32U accelId, 626 Cpa32U *message, 627 Cpa32U *messageCounter); 628 629 /* 630 * @ingroup icp_sal_user 631 * @description 632 * This is a stub function to get pfvf comms status 633 * 634 * @context 635 * None 636 * 637 * @assumptions 638 * None 639 * @sideEffects 640 * None 641 * @reentrant 642 * Yes 643 * @threadSafe 644 * Yes 645 * 646 */ 647 CpaStatus icp_sal_userGetPfVfcommsStatus(CpaBoolean *unreadMessage); 648 649 /* 650 * @ingroup icp_sal_user 651 * @description 652 * This is a stub function to reset the device 653 * 654 * @context 655 * None 656 * 657 * @assumptions 658 * None 659 * @sideEffects 660 * None 661 * @reentrant 662 * Yes 663 * @threadSafe 664 * Yes 665 * 666 */ 667 CpaStatus icp_sal_reset_device(Cpa32U accelId); 668 669 /** 670 ***************************************************************************** 671 * @ingroup icp_sal_user 672 * Retrieve number of in flight requests for a nrbg tx ring 673 * from a crypto instance (Traditional API). 674 * 675 * @description 676 * This function is a part of back-pressure mechanism. 677 * Applications can query for inflight requests in 678 * the appropriate service/ring on each instance 679 * and select any instance with sufficient space or 680 * the instance with the lowest number. 681 * 682 * @assumptions 683 * None 684 * @sideEffects 685 * None 686 * @blocking 687 * None 688 * @reentrant 689 * No 690 * @threadSafe 691 * Yes 692 * 693 * @param[in] instanceHandle Crypto API instance handle. 694 * @param[out] maxInflightRequests Maximal number of in flight requests. 695 * @param[out] numInflightRequests Current number of in flight requests. 696 * 697 * @retval CPA_STATUS_SUCCESS Function executed successfully. 698 * @retval CPA_STATUS_FAIL Function failed. 699 * @pre 700 * None 701 * @post 702 * None 703 * @see 704 * None 705 * 706 *****************************************************************************/ 707 CpaStatus icp_sal_NrbgGetInflightRequests(CpaInstanceHandle instanceHandle, 708 Cpa32U *maxInflightRequests, 709 Cpa32U *numInflightRequests); 710 711 /** 712 ***************************************************************************** 713 * @ingroup icp_sal_user 714 * Retrieve number of in flight requests for a symmetric tx ring 715 * from a crypto instance (Traditional API). 716 * 717 * @description 718 * This function is a part of back-pressure mechanism. 719 * Applications can query for inflight requests in 720 * the appropriate service/ring on each instance 721 * and select any instance with sufficient space or 722 * the instance with the lowest number. 723 * 724 * @assumptions 725 * None 726 * @sideEffects 727 * None 728 * @blocking 729 * None 730 * @reentrant 731 * No 732 * @threadSafe 733 * Yes 734 * 735 * @param[in] instanceHandle Crypto API instance handle. 736 * @param[out] maxInflightRequests Maximal number of in flight requests. 737 * @param[out] numInflightRequests Current number of in flight requests. 738 * 739 * @retval CPA_STATUS_SUCCESS Function executed successfully. 740 * @retval CPA_STATUS_FAIL Function failed. 741 * @pre 742 * None 743 * @post 744 * None 745 * @see 746 * None 747 * 748 *****************************************************************************/ 749 CpaStatus icp_sal_SymGetInflightRequests(CpaInstanceHandle instanceHandle, 750 Cpa32U *maxInflightRequests, 751 Cpa32U *numInflightRequests); 752 753 /** 754 ***************************************************************************** 755 * @ingroup icp_sal_user 756 * Retrieve number of in flight requests for an asymmetric tx ring 757 * from a crypto instance (Traditional API). 758 * 759 * @description 760 * This function is a part of back-pressure mechanism. 761 * Applications can query the appropriate service/ring on each instance 762 * and select any instance with sufficient space or 763 * the instance with the lowest number. 764 * 765 * @assumptions 766 * None 767 * @sideEffects 768 * None 769 * @blocking 770 * None 771 * @reentrant 772 * No 773 * @threadSafe 774 * Yes 775 * 776 * @param[in] instanceHandle Crypto API instance handle. 777 * @param[out] maxInflightRequests Maximal number of in flight requests. 778 * @param[out] numInflightRequests Current number of in flight requests. 779 * 780 * @retval CPA_STATUS_SUCCESS Function executed successfully. 781 * @retval CPA_STATUS_FAIL Function failed. 782 * @pre 783 * None 784 * @post 785 * None 786 * @see 787 * None 788 * 789 *****************************************************************************/ 790 CpaStatus icp_sal_AsymGetInflightRequests(CpaInstanceHandle instanceHandle, 791 Cpa32U *maxInflightRequests, 792 Cpa32U *numInflightRequests); 793 794 /** 795 ***************************************************************************** 796 * @ingroup icp_sal_user 797 * Retrieve number of in flight requests for a symmetric tx ring 798 * from a crypto instancei (Data Plane API). 799 * 800 * @description 801 * This function is a part of back-pressure mechanism. 802 * Applications can query the appropriate service/ring on each instance 803 * and select any instance with sufficient space or 804 * the instance with the lowest number. 805 * 806 * @assumptions 807 * None 808 * @sideEffects 809 * None 810 * @blocking 811 * None 812 * @reentrant 813 * No 814 * @threadSafe 815 * Yes 816 * 817 * @param[in] instanceHandle Crypto API instance handle. 818 * @param[out] maxInflightRequests Maximal number of in flight requests. 819 * @param[out] numInflightRequests Current number of in flight requests. 820 * 821 * @retval CPA_STATUS_SUCCESS Function executed successfully. 822 * @retval CPA_STATUS_FAIL Function failed. 823 * @pre 824 * None 825 * @post 826 * None 827 * @see 828 * None 829 * 830 *****************************************************************************/ 831 CpaStatus icp_sal_dp_SymGetInflightRequests(CpaInstanceHandle instanceHandle, 832 Cpa32U *maxInflightRequests, 833 Cpa32U *numInflightRequests); 834 835 /** 836 ***************************************************************************** 837 * @ingroup icp_sal_user 838 * Updates the CSR with queued requests in the asymmetric tx ring. 839 * 840 * @description 841 * The function writes current shadow tail pointer of the asymmetric 842 * TX ring into ring's CSR. Updating the CSR will notify the HW that 843 * there are request(s) queued to be processed. The CSR is updated 844 * always, disregarding the current value of shadow tail pointer and 845 * the current CSR's tail value. 846 * 847 * @assumptions 848 * None 849 * @sideEffects 850 * None 851 * @blocking 852 * None 853 * @reentrant 854 * No 855 * @threadSafe 856 * Yes 857 * 858 * @param[in] instanceHandle Crypto API instance handle. 859 * 860 * @retval CPA_STATUS_SUCCESS Function executed successfully. 861 * @retval CPA_STATUS_FAIL Function failed. 862 * @pre 863 * None 864 * @post 865 * None 866 * @see 867 * None 868 * 869 *****************************************************************************/ 870 CpaStatus icp_sal_AsymPerformOpNow(CpaInstanceHandle instanceHandle); 871 #endif 872