1 /* SPDX-License-Identifier: BSD-3-Clause */ 2 /* Copyright(c) 2007-2025 Intel Corporation */ 3 4 /* 5 ***************************************************************************** 6 * Doxygen group definitions 7 ****************************************************************************/ 8 9 /** 10 ***************************************************************************** 11 * @file cpa.h 12 * 13 * @defgroup cpa CPA API 14 * 15 * @description 16 * This is the top level API definition for Intel(R) QuickAssist Technology. 17 * It contains structures, data types and definitions that are common 18 * across the interface. 19 * 20 *****************************************************************************/ 21 22 /** 23 ***************************************************************************** 24 * @defgroup cpa_BaseDataTypes Base Data Types 25 * @file cpa.h 26 * 27 * @ingroup cpa 28 * 29 * @description 30 * The base data types for the Intel CPA API. 31 * 32 *****************************************************************************/ 33 34 #ifndef CPA_H 35 #define CPA_H 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 #include "cpa_types.h" 42 43 /** 44 ***************************************************************************** 45 * @ingroup cpa_BaseDataTypes 46 * Instance handle type. 47 * 48 * @description 49 * Handle used to uniquely identify an instance. 50 * 51 * @note 52 * Where only a single instantiation exists this field may be set to 53 * @ref CPA_INSTANCE_HANDLE_SINGLE. 54 * 55 *****************************************************************************/ 56 typedef void * CpaInstanceHandle; 57 58 /** 59 ***************************************************************************** 60 * @ingroup cpa_BaseDataTypes 61 * Default instantiation handle value where there is only a single instance 62 * 63 * @description 64 * Used as an instance handle value where only one instance exists. 65 * 66 *****************************************************************************/ 67 #define CPA_INSTANCE_HANDLE_SINGLE ((CpaInstanceHandle)0) 68 69 /** 70 ***************************************************************************** 71 * @ingroup cpa_BaseDataTypes 72 * Physical memory address. 73 * @description 74 * Type for physical memory addresses. 75 *****************************************************************************/ 76 typedef Cpa64U CpaPhysicalAddr; 77 78 /** 79 ***************************************************************************** 80 * @ingroup cpa_BaseDataTypes 81 * Virtual to physical address conversion routine. 82 * 83 * @description 84 * This function is used to convert virtual addresses to physical 85 * addresses. 86 * 87 * @context 88 * The function shall not be called in an interrupt context. 89 * @assumptions 90 * None 91 * @sideEffects 92 * None 93 * @blocking 94 * This function is synchronous and blocking. 95 * @reentrant 96 * No 97 * @threadSafe 98 * Yes 99 * 100 * @param[in] pVirtualAddr Virtual address to be converted. 101 * 102 * @return 103 * Returns the corresponding physical address. 104 * On error, the value NULL is returned. 105 * 106 * @post 107 * None 108 * @see 109 * None 110 * 111 *****************************************************************************/ 112 typedef CpaPhysicalAddr (*CpaVirtualToPhysical)(void * pVirtualAddr); 113 114 115 /** 116 ***************************************************************************** 117 * @ingroup cpa_BaseDataTypes 118 * Flat buffer structure containing a pointer and length member. 119 * 120 * @description 121 * A flat buffer structure. The data pointer, pData, is a virtual address. 122 * An API instance may require the actual data to be in contiguous 123 * physical memory as determined by @ref CpaInstanceInfo2. 124 * 125 *****************************************************************************/ 126 typedef struct _CpaFlatBuffer { 127 Cpa32U dataLenInBytes; 128 /**< Data length specified in bytes. 129 * When used as an input parameter to a function, the length specifies 130 * the current length of the buffer. 131 * When used as an output parameter to a function, the length passed in 132 * specifies the maximum length of the buffer on return (i.e. the allocated 133 * length). The implementation will not write past this length. On return, 134 * the length is always unchanged. */ 135 Cpa8U *pData; 136 /**< The data pointer is a virtual address, however the actual data pointed 137 * to is required to be in contiguous physical memory unless the field 138 requiresPhysicallyContiguousMemory in CpaInstanceInfo2 is false. */ 139 } CpaFlatBuffer; 140 141 /** 142 ***************************************************************************** 143 * @ingroup cpa_BaseDataTypes 144 * Scatter/Gather buffer list containing an array of flat buffers. 145 * 146 * @description 147 * A scatter/gather buffer list structure. This buffer structure is 148 * typically used to represent a region of memory which is not 149 * physically contiguous, by describing it as a collection of 150 * buffers, each of which is physically contiguous. 151 * 152 * @note 153 * The memory for the pPrivateMetaData member must be allocated 154 * by the client as physically contiguous memory. When allocating 155 * memory for pPrivateMetaData, a call to the corresponding 156 * BufferListGetMetaSize function (e.g. cpaCyBufferListGetMetaSize) 157 * MUST be made to determine the size of the Meta Data Buffer. The 158 * returned size (in bytes) may then be passed in a memory allocation 159 * routine to allocate the pPrivateMetaData memory. 160 *****************************************************************************/ 161 typedef struct _CpaBufferList { 162 Cpa32U numBuffers; 163 /**< Number of buffers in the list */ 164 CpaFlatBuffer *pBuffers; 165 /**< Pointer to an unbounded array containing the number of CpaFlatBuffers 166 * defined by numBuffers 167 */ 168 void *pUserData; 169 /**< This is an opaque field that is not read or modified internally. */ 170 void *pPrivateMetaData; 171 /**< Private representation of this buffer list. The memory for this 172 * buffer needs to be allocated by the client as contiguous data. 173 * The amount of memory required is returned with a call to 174 * the corresponding BufferListGetMetaSize function. If that function 175 * returns a size of zero then no memory needs to be allocated, and this 176 * parameter can be NULL. 177 */ 178 } CpaBufferList; 179 180 /** 181 ***************************************************************************** 182 * @ingroup cpa_BaseDataTypes 183 * Flat buffer structure with physical address. 184 * 185 * @description 186 * Functions taking this structure do not need to do any virtual to 187 * physical address translation before writing the buffer to hardware. 188 *****************************************************************************/ 189 typedef struct _CpaPhysFlatBuffer { 190 Cpa32U dataLenInBytes; 191 /**< Data length specified in bytes. 192 * When used as an input parameter to a function, the length specifies 193 * the current length of the buffer. 194 * When used as an output parameter to a function, the length passed in 195 * specifies the maximum length of the buffer on return (i.e. the allocated 196 * length). The implementation will not write past this length. On return, 197 * the length is always unchanged. 198 */ 199 Cpa32U reserved; 200 /**< Reserved for alignment */ 201 CpaPhysicalAddr bufferPhysAddr; 202 /**< The physical address at which the data resides. The data pointed 203 * to is required to be in contiguous physical memory. 204 */ 205 } CpaPhysFlatBuffer; 206 207 /** 208 ***************************************************************************** 209 * @ingroup cpa_BaseDataTypes 210 * Scatter/gather list containing an array of flat buffers with 211 * physical addresses. 212 * 213 * @description 214 * Similar to @ref CpaBufferList, this buffer structure is typically 215 * used to represent a region of memory which is not physically 216 * contiguous, by describing it as a collection of buffers, each of 217 * which is physically contiguous. The difference is that, in this 218 * case, the individual "flat" buffers are represented using 219 * physical, rather than virtual, addresses. 220 *****************************************************************************/ 221 typedef struct _CpaPhysBufferList { 222 Cpa64U reserved0; 223 /**< Reserved for internal usage */ 224 Cpa32U numBuffers; 225 /**< Number of buffers in the list */ 226 Cpa32U reserved1; 227 /**< Reserved for alignment */ 228 CpaPhysFlatBuffer flatBuffers[]; 229 /**< Array of flat buffer structures, of size numBuffers */ 230 } CpaPhysBufferList; 231 232 233 /** 234 ***************************************************************************** 235 * @ingroup cpa_BaseDataTypes 236 * Special value which can be taken by length fields on some of the 237 * "data plane" APIs to indicate that the buffer in question is of 238 * type CpaPhysBufferList, rather than simply an array of bytes. 239 ****************************************************************************/ 240 #define CPA_DP_BUFLIST ((Cpa32U)0xFFFFFFFF) 241 242 243 /** 244 ***************************************************************************** 245 * @ingroup cpa_BaseDataTypes 246 * API status value type definition 247 * 248 * @description 249 * This type definition is used for the return values used in all the 250 * API functions. Common values are defined, for example see 251 * @ref CPA_STATUS_SUCCESS, @ref CPA_STATUS_FAIL, etc. 252 *****************************************************************************/ 253 typedef Cpa32S CpaStatus; 254 255 #define CPA_STATUS_SUCCESS (0) 256 /**< 257 * @ingroup cpa_BaseDataTypes 258 * Success status value. */ 259 #define CPA_STATUS_FAIL (-1) 260 /**< 261 * @ingroup cpa_BaseDataTypes 262 * Fail status value. */ 263 #define CPA_STATUS_RETRY (-2) 264 /**< 265 * @ingroup cpa_BaseDataTypes 266 * Retry status value. */ 267 #define CPA_STATUS_RESOURCE (-3) 268 /**< 269 * @ingroup cpa_BaseDataTypes 270 * The resource that has been requested is unavailable. Refer 271 * to relevant sections of the API for specifics on what the suggested 272 * course of action is. */ 273 #define CPA_STATUS_INVALID_PARAM (-4) 274 /**< 275 * @ingroup cpa_BaseDataTypes 276 * Invalid parameter has been passed in. */ 277 #define CPA_STATUS_FATAL (-5) 278 /**< 279 * @ingroup cpa_BaseDataTypes 280 * A serious error has occurred. Recommended course of action 281 * is to shutdown and restart the component. */ 282 #define CPA_STATUS_UNSUPPORTED (-6) 283 /**< 284 * @ingroup cpa_BaseDataTypes 285 * The function is not supported, at least not with the specific 286 * parameters supplied. This may be because a particular 287 * capability is not supported by the current implementation. */ 288 #define CPA_STATUS_RESTARTING (-7) 289 /**< 290 * @ingroup cpa_BaseDataTypes 291 * The API implementation is restarting. This may be reported if, for example, 292 * a hardware implementation is undergoing a reset. Recommended course of 293 * action is to retry the request. */ 294 295 /** 296 ***************************************************************************** 297 * @ingroup cpa_BaseDataTypes 298 * API status string type definition 299 * @description 300 * This type definition is used for the generic status text strings 301 * provided by cpaXxGetStatusText API functions. Common values are 302 * defined, for example see @ref CPA_STATUS_STR_SUCCESS, 303 * @ref CPA_STATUS_FAIL, etc., as well as the maximum size 304 * @ref CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. 305 *****************************************************************************/ 306 #define CPA_STATUS_MAX_STR_LENGTH_IN_BYTES (255) 307 /**< 308 * @ingroup cpa_BaseDataTypes 309 * Maximum length of the Overall Status String (including generic and specific 310 * strings returned by calls to cpaXxGetStatusText) */ 311 312 #define CPA_STATUS_STR_SUCCESS ("Operation was successful:") 313 /**< 314 * @ingroup cpa_BaseDataTypes 315 * Status string for @ref CPA_STATUS_SUCCESS. */ 316 #define CPA_STATUS_STR_FAIL ("General or unspecified error occurred:") 317 /**< 318 * @ingroup cpa_BaseDataTypes 319 * Status string for @ref CPA_STATUS_FAIL. */ 320 #define CPA_STATUS_STR_RETRY ("Recoverable error occurred:") 321 /**< 322 * @ingroup cpa_BaseDataTypes 323 * Status string for @ref CPA_STATUS_RETRY. */ 324 #define CPA_STATUS_STR_RESOURCE ("Required resource unavailable:") 325 /**< 326 * @ingroup cpa_BaseDataTypes 327 * Status string for @ref CPA_STATUS_RESOURCE. */ 328 #define CPA_STATUS_STR_INVALID_PARAM ("Invalid parameter supplied:") 329 /**< 330 * @ingroup cpa_BaseDataTypes 331 * Status string for @ref CPA_STATUS_INVALID_PARAM. */ 332 #define CPA_STATUS_STR_FATAL ("Fatal error has occurred:") 333 /**< 334 * @ingroup cpa_BaseDataTypes 335 * Status string for @ref CPA_STATUS_FATAL. */ 336 #define CPA_STATUS_STR_UNSUPPORTED ("Operation not supported:") 337 /**< 338 * @ingroup cpa_BaseDataTypes 339 * Status string for @ref CPA_STATUS_UNSUPPORTED. */ 340 341 /** 342 ***************************************************************************** 343 * @ingroup cpa_BaseDataTypes 344 * Instance Types 345 * 346 * @deprecated 347 * As of v1.3 of the Crypto API, this enum has been deprecated, 348 * replaced by @ref CpaAccelerationServiceType. 349 * 350 * @description 351 * Enumeration of the different instance types. 352 * 353 *****************************************************************************/ 354 typedef enum _CpaInstanceType 355 { 356 CPA_INSTANCE_TYPE_CRYPTO = 0, 357 /**< Cryptographic instance type */ 358 CPA_INSTANCE_TYPE_DATA_COMPRESSION, 359 /**< Data compression instance type */ 360 CPA_INSTANCE_TYPE_RAID, 361 /**< RAID instance type */ 362 CPA_INSTANCE_TYPE_XML, 363 /**< XML instance type */ 364 CPA_INSTANCE_TYPE_REGEX 365 /**< Regular Expression instance type */ 366 } CpaInstanceType CPA_DEPRECATED; 367 368 /** 369 ***************************************************************************** 370 * @ingroup cpa_BaseDataTypes 371 * Service Type 372 * @description 373 * Enumeration of the different service types. 374 * 375 *****************************************************************************/ 376 typedef enum _CpaAccelerationServiceType 377 { 378 CPA_ACC_SVC_TYPE_CRYPTO = CPA_INSTANCE_TYPE_CRYPTO, 379 /**< Cryptography */ 380 CPA_ACC_SVC_TYPE_DATA_COMPRESSION = CPA_INSTANCE_TYPE_DATA_COMPRESSION, 381 /**< Data Compression */ 382 CPA_ACC_SVC_TYPE_PATTERN_MATCH = CPA_INSTANCE_TYPE_REGEX, 383 /**< Pattern Match */ 384 CPA_ACC_SVC_TYPE_RAID = CPA_INSTANCE_TYPE_RAID, 385 /**< RAID */ 386 CPA_ACC_SVC_TYPE_XML = CPA_INSTANCE_TYPE_XML, 387 /**< XML */ 388 CPA_ACC_SVC_TYPE_VIDEO_ANALYTICS, 389 /**< Video Analytics */ 390 CPA_ACC_SVC_TYPE_CRYPTO_ASYM, 391 /**< Cryptography - Asymmetric service */ 392 CPA_ACC_SVC_TYPE_CRYPTO_SYM 393 /**< Cryptography - Symmetric service */ 394 } CpaAccelerationServiceType; 395 396 /** 397 ***************************************************************************** 398 * @ingroup cpa_BaseDataTypes 399 * Instance State 400 * 401 * @deprecated 402 * As of v1.3 of the Crypto API, this enum has been deprecated, 403 * replaced by @ref CpaOperationalState. 404 * 405 * @description 406 * Enumeration of the different instance states that are possible. 407 * 408 *****************************************************************************/ 409 typedef enum _CpaInstanceState 410 { 411 CPA_INSTANCE_STATE_INITIALISED = 0, 412 /**< Instance is in the initialized state and ready for use. */ 413 CPA_INSTANCE_STATE_SHUTDOWN 414 /**< Instance is in the shutdown state and not available for use. */ 415 } CpaInstanceState CPA_DEPRECATED; 416 417 /** 418 ***************************************************************************** 419 * @ingroup cpa_BaseDataTypes 420 * Instance operational state 421 * @description 422 * Enumeration of the different operational states that are possible. 423 * 424 *****************************************************************************/ 425 typedef enum _CpaOperationalState 426 { 427 CPA_OPER_STATE_DOWN= 0, 428 /**< Instance is not available for use. May not yet be initialized, 429 * or stopped. */ 430 CPA_OPER_STATE_UP 431 /**< Instance is available for use. Has been initialized and started. */ 432 } CpaOperationalState; 433 434 #define CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES 64 435 /**< 436 * @ingroup cpa_BaseDataTypes 437 * Maximum instance info name string length in bytes */ 438 #define CPA_INSTANCE_MAX_ID_SIZE_IN_BYTES 128 439 /**< 440 * @ingroup cpa_BaseDataTypes 441 * Maximum instance info id string length in bytes */ 442 #define CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES 64 443 /**< 444 * @ingroup cpa_BaseDataTypes 445 * Maximum instance info version string length in bytes */ 446 447 /** 448 ***************************************************************************** 449 * @ingroup cpa_BaseDataTypes 450 * Instance Info Structure 451 * 452 * @deprecated 453 * As of v1.3 of the Crypto API, this structure has been deprecated, 454 * replaced by CpaInstanceInfo2. 455 * 456 * @description 457 * Structure that contains the information to describe the instance. 458 * 459 *****************************************************************************/ 460 typedef struct _CpaInstanceInfo { 461 enum _CpaInstanceType type; 462 /**< Type definition for this instance. */ 463 enum _CpaInstanceState state; 464 /**< Operational state of the instance. */ 465 Cpa8U name[CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES]; 466 /**< Simple text string identifier for the instance. */ 467 Cpa8U version[CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES]; 468 /**< Version string. There may be multiple versions of the same type of 469 * instance accessible through a particular library. */ 470 } CpaInstanceInfo CPA_DEPRECATED; 471 472 /** 473 ***************************************************************************** 474 * @ingroup cpa_BaseDataTypes 475 * Physical Instance ID 476 * @description 477 * Identifies the physical instance of an accelerator execution 478 * engine. 479 * 480 * Accelerators grouped into "packages". Each accelerator can in 481 * turn contain one or more execution engines. Implementations of 482 * this API will define the packageId, acceleratorId, 483 * executionEngineId and busAddress as appropriate for the 484 * implementation. For example, for hardware-based accelerators, 485 * the packageId might identify the chip, which might contain 486 * multiple accelerators, each of which might contain multiple 487 * execution engines. The combination of packageId, acceleratorId 488 * and executionEngineId uniquely identifies the instance. 489 * 490 * Hardware based accelerators implementing this API may also provide 491 * information on the location of the accelerator in the busAddress 492 * field. This field will be defined as appropriate for the 493 * implementation. For example, for PCIe attached accelerators, 494 * the busAddress may contain the PCIe bus, device and function 495 * number of the accelerators. 496 * 497 *****************************************************************************/ 498 typedef struct _CpaPhysicalInstanceId { 499 Cpa16U packageId; 500 /**< Identifies the package within which the accelerator is 501 * contained. */ 502 Cpa16U acceleratorId; 503 /**< Identifies the specific accelerator within the package. */ 504 Cpa16U executionEngineId; 505 /**< Identifies the specific execution engine within the 506 * accelerator. */ 507 Cpa16U busAddress; 508 /**< Identifies the bus address associated with the accelerator 509 * execution engine. */ 510 Cpa32U kptAcHandle; 511 /**< Identifies the achandle of the accelerator. */ 512 } CpaPhysicalInstanceId; 513 514 /** 515 ***************************************************************************** 516 * @ingroup cpa_BaseDataTypes 517 * Instance Info Structure, version 2 518 * @description 519 * Structure that contains the information to describe the instance. 520 * 521 *****************************************************************************/ 522 typedef struct _CpaInstanceInfo2 { 523 CpaAccelerationServiceType accelerationServiceType; 524 /**< Type of service provided by this instance. */ 525 #define CPA_INST_VENDOR_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES 526 /**< Maximum length of the vendor name. */ 527 Cpa8U vendorName[CPA_INST_VENDOR_NAME_SIZE]; 528 /**< String identifying the vendor of the accelerator. */ 529 530 #define CPA_INST_PART_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES 531 /**< Maximum length of the part name. */ 532 Cpa8U partName[CPA_INST_PART_NAME_SIZE]; 533 /**< String identifying the part (name and/or number). */ 534 535 #define CPA_INST_SW_VERSION_SIZE CPA_INSTANCE_MAX_VERSION_SIZE_IN_BYTES 536 /**< Maximum length of the software version string. */ 537 Cpa8U swVersion[CPA_INST_SW_VERSION_SIZE]; 538 /**< String identifying the version of the software associated with 539 * the instance. For hardware-based implementations of the API, 540 * this should be the driver version. For software-based 541 * implementations of the API, this should be the version of the 542 * library. 543 * 544 * Note that this should NOT be used to store the version of the 545 * API, nor should it be used to report the hardware revision 546 * (which can be captured as part of the @ref partName, if required). */ 547 548 #define CPA_INST_NAME_SIZE CPA_INSTANCE_MAX_NAME_SIZE_IN_BYTES 549 /**< Maximum length of the instance name. */ 550 Cpa8U instName[CPA_INST_NAME_SIZE]; 551 /**< String identifying the name of the instance. */ 552 553 #define CPA_INST_ID_SIZE CPA_INSTANCE_MAX_ID_SIZE_IN_BYTES 554 Cpa8U instID[CPA_INST_ID_SIZE]; 555 /**< String containing a unique identifier for the instance */ 556 557 CpaPhysicalInstanceId physInstId; 558 /**< Identifies the "physical instance" of the accelerator. */ 559 560 #define CPA_MAX_CORES 4096 561 /**< Maximum number of cores to support in the coreAffinity bitmap. */ 562 CPA_BITMAP(coreAffinity, CPA_MAX_CORES); 563 /**< A bitmap identifying the core or cores to which the instance 564 * is affinitized in an SMP operating system. 565 * 566 * The term core here is used to mean a "logical" core - for example, 567 * in a dual-processor, quad-core system with hyperthreading (two 568 * threads per core), there would be 16 such cores (2 processors x 569 * 4 cores/processor x 2 threads/core). The numbering of these cores 570 * and the corresponding bit positions is OS-specific. Note that Linux 571 * refers to this as "processor affinity" or "CPU affinity", and refers 572 * to the bitmap as a "cpumask". 573 * 574 * The term "affinity" is used to mean that this is the core on which 575 * the callback function will be invoked when using the asynchronous 576 * mode of the API. In a hardware-based implementation of the API, 577 * this might be the core to which the interrupt is affinitized. 578 * In a software-based implementation, this might be the core to which 579 * the process running the algorithm is affinitized. Where there is 580 * no affinity, the bitmap can be set to all zeroes. 581 * 582 * This bitmap should be manipulated using the macros @ref 583 * CPA_BITMAP_BIT_SET, @ref CPA_BITMAP_BIT_CLEAR and @ref 584 * CPA_BITMAP_BIT_TEST. */ 585 586 Cpa32U nodeAffinity; 587 /**< Identifies the processor complex, or node, to which the accelerator 588 * is physically connected, to help identify locality in NUMA systems. 589 * 590 * The values taken by this attribute will typically be in the range 591 * 0..n-1, where n is the number of nodes (processor complexes) in the 592 * system. For example, in a dual-processor configuration, n=2. The 593 * precise values and their interpretation are OS-specific. */ 594 595 CpaOperationalState operState; 596 /**< Operational state of the instance. */ 597 CpaBoolean requiresPhysicallyContiguousMemory; 598 /**< Specifies whether the data pointed to by flat buffers 599 * (CpaFlatBuffer::pData) supplied to this instance must be in 600 * physically contiguous memory. */ 601 CpaBoolean isPolled; 602 /**< Specifies whether the instance must be polled, or is event driven. 603 * For hardware accelerators, the alternative to polling would be 604 * interrupts. */ 605 CpaBoolean isOffloaded; 606 /**< Identifies whether the instance uses hardware offload, or is a 607 * software-only implementation. */ 608 } CpaInstanceInfo2; 609 610 /** 611 ***************************************************************************** 612 * @ingroup cpa_BaseDataTypes 613 * Instance Events 614 * @description 615 * Enumeration of the different events that will cause the registered 616 * Instance notification callback function to be invoked. 617 * 618 *****************************************************************************/ 619 typedef enum _CpaInstanceEvent 620 { 621 CPA_INSTANCE_EVENT_RESTARTING = 0, 622 /**< Event type that triggers the registered instance notification callback 623 * function when and instance is restarting. The reason why an instance is 624 * restarting is implementation specific. For example a hardware 625 * implementation may send this event if the hardware device is about to 626 * be reset. 627 */ 628 CPA_INSTANCE_EVENT_RESTARTED, 629 /**< Event type that triggers the registered instance notification callback 630 * function when and instance has restarted. The reason why an instance has 631 * restarted is implementation specific. For example a hardware 632 * implementation may send this event after the hardware device has 633 * been reset. 634 */ 635 CPA_INSTANCE_EVENT_FATAL_ERROR 636 /**< Event type that triggers the registered instance notification callback 637 * function when an error has been detected that requires the device 638 * to be reset. 639 * This event will be sent by all instances using the device, both on the 640 * host and guests. 641 */ 642 } CpaInstanceEvent; 643 644 /*****************************************************************************/ 645 /* CPA Instance Management Functions */ 646 /*****************************************************************************/ 647 /** 648 ***************************************************************************** 649 * @file cpa.h 650 * @ingroup cpa 651 * Get the number of Acceleration Service instances that are supported by 652 * the API implementation. 653 * 654 * @description 655 * This function will get the number of instances that are supported 656 * for the required Acceleration Service by an implementation of the CPA 657 * API. This number is then used to determine the size of the array that 658 * must be passed to @ref cpaGetInstances(). 659 * 660 * @context 661 * This function MUST NOT be called from an interrupt context as it MAY 662 * sleep. 663 * @assumptions 664 * None 665 * @sideEffects 666 * None 667 * @blocking 668 * This function is synchronous and blocking. 669 * @reentrant 670 * No 671 * @threadSafe 672 * Yes 673 * 674 * @param[in] accelerationServiceType Acceleration Service required 675 * @param[out] pNumInstances Pointer to where the number of 676 * instances will be written. 677 * 678 * @retval CPA_STATUS_SUCCESS Function executed successfully. 679 * @retval CPA_STATUS_FAIL Function failed. 680 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 681 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 682 * 683 * @pre 684 * None 685 * @post 686 * None 687 * @note 688 * This function operates in a synchronous manner and no asynchronous 689 * callback will be generated 690 * 691 * @see 692 * cpaGetInstances 693 * 694 *****************************************************************************/ 695 CpaStatus 696 cpaGetNumInstances( 697 const CpaAccelerationServiceType accelerationServiceType, 698 Cpa16U *pNumInstances); 699 700 /** 701 ***************************************************************************** 702 * @file cpa.h 703 * @ingroup cpa 704 * Get the handles to the required Acceleration Service instances that are 705 * supported by the API implementation. 706 * 707 * @description 708 * This function will return handles to the required Acceleration Service 709 * instances that are supported by an implementation of the CPA API. These 710 * instance handles can then be used as input parameters with other 711 * API functions. 712 * 713 * This function will populate an array that has been allocated by the 714 * caller. The size of this array will have been determined by the 715 * cpaGetNumInstances() function. 716 * 717 * @context 718 * This function MUST NOT be called from an interrupt context as it MAY 719 * sleep. 720 * @assumptions 721 * None 722 * @sideEffects 723 * None 724 * @blocking 725 * This function is synchronous and blocking. 726 * @reentrant 727 * No 728 * @threadSafe 729 * Yes 730 * 731 * @param[in] accelerationServiceType Acceleration Service requested 732 * @param[in] numInstances Size of the array. If the value is 733 * greater than the number of instances 734 * supported, then an error (@ref 735 * CPA_STATUS_INVALID_PARAM) is returned. 736 * @param[in,out] cpaInstances Pointer to where the instance 737 * handles will be written. 738 * 739 * @retval CPA_STATUS_SUCCESS Function executed successfully. 740 * @retval CPA_STATUS_FAIL Function failed. 741 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 742 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 743 * 744 * @pre 745 * None 746 * @post 747 * None 748 * @note 749 * This function operates in a synchronous manner and no asynchronous 750 * callback will be generated 751 * 752 * @see 753 * cpaGetNumInstances 754 * 755 *****************************************************************************/ 756 CpaStatus 757 cpaGetInstances( 758 const CpaAccelerationServiceType accelerationServiceType, 759 Cpa16U numInstances, 760 CpaInstanceHandle *cpaInstances); 761 762 #ifdef __cplusplus 763 } /* close the extern "C" { */ 764 #endif 765 766 #endif /* CPA_H */ 767