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