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_dc.h 45 * 46 * @defgroup cpaDc Data Compression API 47 * 48 * @ingroup cpa 49 * 50 * @description 51 * These functions specify the API for Data Compression operations. 52 * 53 * The Data Compression API has the following: 54 * 1) Session based API functions 55 * These functions require a session to be created before performing any 56 * DC operations. Subsequent DC API functions make use of the returned 57 * Session Handle within their structures or function prototypes. 58 * 2) Session-less or No-Session (Ns) based API functions. 59 * These functions do not require a session to be initialized before 60 * performing DC operations. They are "one-shot" API function calls 61 * that submit DC requests directly using the supplied parameters. 62 * 63 * @remarks 64 * 65 * 66 *****************************************************************************/ 67 68 #ifndef CPA_DC_H 69 #define CPA_DC_H 70 71 #ifdef __cplusplus 72 extern"C" { 73 #endif 74 75 76 #ifndef CPA_H 77 #include "cpa.h" 78 #endif 79 80 /** 81 ***************************************************************************** 82 * @ingroup cpaDc 83 * CPA Dc Major Version Number 84 * @description 85 * The CPA_DC API major version number. This number will be incremented 86 * when significant churn to the API has occurred. The combination of the 87 * major and minor number definitions represent the complete version number 88 * for this interface. 89 * 90 *****************************************************************************/ 91 #define CPA_DC_API_VERSION_NUM_MAJOR (3) 92 93 /** 94 ***************************************************************************** 95 * @ingroup cpaDc 96 * CPA DC Minor Version Number 97 * @description 98 * The CPA_DC API minor version number. This number will be incremented 99 * when minor changes to the API has occurred. The combination of the major 100 * and minor number definitions represent the complete version number for 101 * this interface. 102 * 103 *****************************************************************************/ 104 #define CPA_DC_API_VERSION_NUM_MINOR (2) 105 106 /** 107 ***************************************************************************** 108 * @file cpa_dc.h 109 * @ingroup cpaDc 110 * CPA DC API version at least 111 * @description 112 * The minimal supported CPA_DC API version. Allow to check if the API 113 * version is equal or above some version to avoid compilation issues 114 * with an older API version. 115 * 116 *****************************************************************************/ 117 #define CPA_DC_API_VERSION_AT_LEAST(major, minor) \ 118 (CPA_DC_API_VERSION_NUM_MAJOR > major || \ 119 (CPA_DC_API_VERSION_NUM_MAJOR == major && \ 120 CPA_DC_API_VERSION_NUM_MINOR >= minor)) 121 122 /** 123 ***************************************************************************** 124 * @file cpa_dc.h 125 * @ingroup cpaDc 126 * CPA DC API version less than 127 * @description 128 * The maximum supported CPA_DC API version. Allow to check if the API 129 * version is below some version to avoid compilation issues with a newer 130 * API version. 131 * 132 *****************************************************************************/ 133 #define CPA_DC_API_VERSION_LESS_THAN(major, minor) \ 134 (CPA_DC_API_VERSION_NUM_MAJOR < major || \ 135 (CPA_DC_API_VERSION_NUM_MAJOR == major && \ 136 CPA_DC_API_VERSION_NUM_MINOR < minor)) 137 138 /** 139 ***************************************************************************** 140 * @ingroup cpaDc 141 * Size of bitmap needed for compression chaining capabilities. 142 * 143 * @description 144 * Defines the number of bits in the bitmap to represent supported 145 * chaining capabilities @ref dcChainCapInfo. Should be set to 146 * at least one greater than the largest value in the enumerated type 147 * @ref CpaDcChainOperations, so that the value of the enum constant 148 * can also be used as the bit position in the bitmap. 149 * 150 * A larger value was chosen to allow for extensibility without the need 151 * to change the size of the bitmap (to ease backwards compatibility in 152 * future versions of the API). 153 * 154 *****************************************************************************/ 155 #define CPA_DC_CHAIN_CAP_BITMAP_SIZE (32) 156 157 /** 158 ***************************************************************************** 159 * @ingroup cpaDc 160 * Compression API session handle type 161 * 162 * @description 163 * Handle used to uniquely identify a Compression API session handle. This 164 * handle is established upon registration with the API using 165 * cpaDcInitSession(). 166 * 167 * 168 * 169 *****************************************************************************/ 170 typedef void * CpaDcSessionHandle; 171 172 173 /** 174 ***************************************************************************** 175 * @ingroup cpaDc 176 * Supported flush flags 177 * 178 * @description 179 * This enumerated list identifies the types of flush that can be 180 * specified for stateful and stateless cpaDcCompressData and 181 * cpaDcDecompressData functions. 182 * 183 *****************************************************************************/ 184 typedef enum _CpaDcFlush 185 { 186 CPA_DC_FLUSH_NONE = 0, 187 /**< No flush request. */ 188 CPA_DC_FLUSH_FINAL, 189 /**< Indicates that the input buffer contains all of the data for 190 the compression session allowing any buffered data to be released. 191 For Deflate, BFINAL is set in the compression header.*/ 192 CPA_DC_FLUSH_SYNC, 193 /**< Used for stateful deflate compression to indicate that all pending 194 output is flushed, byte aligned, to the output buffer. The session state 195 is not reset.*/ 196 CPA_DC_FLUSH_FULL 197 /**< Used for deflate compression to indicate that all pending output is 198 flushed to the output buffer and the session state is reset.*/ 199 } CpaDcFlush; 200 /** 201 ***************************************************************************** 202 * @ingroup cpaDc 203 * Supported Huffman Tree types 204 * 205 * @description 206 * This enumeration lists support for Huffman Tree types. 207 * Selecting Static Huffman trees generates compressed blocks with an RFC 208 * 1951 header specifying "compressed with fixed Huffman trees". 209 * 210 * Selecting Full Dynamic Huffman trees generates compressed blocks with 211 * an RFC 1951 header specifying "compressed with dynamic Huffman codes". 212 * The headers are calculated on the data being compressed, requiring two 213 * passes. 214 * 215 * Selecting Precompiled Huffman Trees generates blocks with RFC 1951 216 * dynamic headers. The headers are pre-calculated and are specified by 217 * the file type. 218 * 219 *****************************************************************************/ 220 typedef enum _CpaDcHuffType 221 { 222 CPA_DC_HT_STATIC = 0, 223 /**< Static Huffman Trees */ 224 CPA_DC_HT_PRECOMP, 225 /**< Precompiled Huffman Trees */ 226 CPA_DC_HT_FULL_DYNAMIC 227 /**< Full Dynamic Huffman Trees */ 228 } CpaDcHuffType; 229 230 /** 231 ***************************************************************************** 232 * @ingroup cpaDc 233 * Supported compression types 234 * 235 * @description 236 * This enumeration lists the supported data compression algorithms. 237 * In combination with CpaDcChecksum it is used to decide on the file 238 * header and footer format. 239 * 240 *****************************************************************************/ 241 typedef enum _CpaDcCompType 242 { 243 CPA_DC_DEFLATE = 3, 244 /**< Deflate Compression */ 245 CPA_DC_LZ4, 246 /**< LZ4 Compression */ 247 CPA_DC_LZ4S 248 /**< LZ4S Compression */ 249 } CpaDcCompType; 250 251 /** 252 ***************************************************************************** 253 * @ingroup cpaDc 254 * Support for defined algorithm window sizes 255 * 256 * @description 257 * This enumerated list defines the valid window sizes that can be 258 * used with the supported algorithms 259 *****************************************************************************/ 260 typedef enum _CpaDcCompWindowSize 261 { 262 CPA_DC_WINSIZE_4K = 0, 263 /**< Window size of 4KB */ 264 CPA_DC_WINSIZE_8K, 265 /**< Window size of 8KB */ 266 CPA_DC_WINSIZE_16K, 267 /**< Window size of 16KB */ 268 CPA_DC_WINSIZE_32K 269 /**< Window size of 32KB */ 270 } CpaDcCompWindowSize; 271 272 /** 273 ***************************************************************************** 274 * @ingroup cpaDc 275 * Min match size in bytes 276 * @description 277 * This is the min match size that will be used for the search algorithm. 278 * It is only configurable for LZ4S. 279 *****************************************************************************/ 280 typedef enum _CpaDcCompMinMatch 281 { 282 CPA_DC_MIN_3_BYTE_MATCH = 0, 283 /**< Min Match of 3 bytes */ 284 CPA_DC_MIN_4_BYTE_MATCH 285 /**< Min Match of 4 bytes */ 286 } CpaDcCompMinMatch; 287 288 /** 289 ***************************************************************************** 290 * @ingroup cpaDc 291 * Maximum LZ4 output block size 292 * @description 293 * Maximum LZ4 output block size 294 *****************************************************************************/ 295 typedef enum _CpaDcCompLZ4BlockMaxSize 296 { 297 CPA_DC_LZ4_MAX_BLOCK_SIZE_64K = 0, 298 /**< Maximum block size 64K */ 299 CPA_DC_LZ4_MAX_BLOCK_SIZE_256K, 300 /**< Maximum block size 256K */ 301 CPA_DC_LZ4_MAX_BLOCK_SIZE_1M, 302 /**< Maximum block size 1M */ 303 CPA_DC_LZ4_MAX_BLOCK_SIZE_4M, 304 /**< Maximum block size 4M */ 305 } CpaDcCompLZ4BlockMaxSize; 306 307 /** 308 ***************************************************************************** 309 * @ingroup cpaDc 310 * Supported checksum algorithms 311 * 312 * @description 313 * This enumeration lists the supported checksum algorithms 314 * Used to decide on file header and footer specifics. 315 * 316 *****************************************************************************/ 317 typedef enum _CpaDcChecksum 318 { 319 CPA_DC_NONE = 0, 320 /**< No checksum required */ 321 CPA_DC_CRC32, 322 /**< Application requires a CRC32 checksum */ 323 CPA_DC_ADLER32, 324 /**< Application requires Adler-32 checksum */ 325 CPA_DC_CRC32_ADLER32, 326 /**< Application requires both CRC32 and Adler-32 checksums */ 327 CPA_DC_XXHASH32, 328 /**< Application requires xxHash-32 checksum */ 329 } CpaDcChecksum; 330 331 332 /** 333 ***************************************************************************** 334 * @ingroup cpaDc 335 * Supported session directions 336 * 337 * @description 338 * This enumerated list identifies the direction of a session. 339 * A session can be compress, decompress or both. 340 * 341 *****************************************************************************/ 342 typedef enum _CpaDcSessionDir 343 { 344 CPA_DC_DIR_COMPRESS = 0, 345 /**< Session will be used for compression */ 346 CPA_DC_DIR_DECOMPRESS, 347 /**< Session will be used for decompression */ 348 CPA_DC_DIR_COMBINED 349 /**< Session will be used for both compression and decompression */ 350 } CpaDcSessionDir; 351 352 typedef CpaDcSessionDir CpaDcDir; 353 354 /** 355 ***************************************************************************** 356 * @ingroup cpaDc 357 * Supported session state settings 358 * 359 * @description 360 * This enumerated list identifies the stateful setting of a session. 361 * A session can be either stateful or stateless. 362 * 363 * Stateful sessions are limited to have only one in-flight message per 364 * session. This means a compress or decompress request must be complete 365 * before a new request can be started. This applies equally to sessions 366 * that are uni-directional in nature and sessions that are combined 367 * compress and decompress. Completion occurs when the synchronous function 368 * returns, or when the asynchronous callback function has completed. 369 * 370 *****************************************************************************/ 371 typedef enum _CpaDcSessionState 372 { 373 CPA_DC_STATEFUL = 0, 374 /**< Session will be stateful, implying that state may need to be 375 saved in some situations */ 376 CPA_DC_STATELESS 377 /**< Session will be stateless, implying no state will be stored*/ 378 } CpaDcSessionState; 379 380 typedef CpaDcSessionState CpaDcState; 381 382 /** 383 ***************************************************************************** 384 * @ingroup cpaDc 385 * Supported compression levels 386 * 387 * @description 388 * This enumerated lists the supported compressed levels. 389 * Lower values will result in less compressibility in less time. 390 * 391 * 392 *****************************************************************************/ 393 typedef enum _CpaDcCompLvl 394 { 395 CPA_DC_L1 = 1, 396 /**< Compression level 1 */ 397 CPA_DC_L2, 398 /**< Compression level 2 */ 399 CPA_DC_L3, 400 /**< Compression level 3 */ 401 CPA_DC_L4, 402 /**< Compression level 4 */ 403 CPA_DC_L5, 404 /**< Compression level 5 */ 405 CPA_DC_L6, 406 /**< Compression level 6 */ 407 CPA_DC_L7, 408 /**< Compression level 7 */ 409 CPA_DC_L8, 410 /**< Compression level 8 */ 411 CPA_DC_L9, 412 /**< Compression level 9 */ 413 CPA_DC_L10, 414 /**< Compression level 10 */ 415 CPA_DC_L11, 416 /**< Compression level 11 */ 417 CPA_DC_L12 418 /**< Compression level 12 */ 419 } CpaDcCompLvl; 420 421 /** 422 ***************************************************************************** 423 * @ingroup cpaDc 424 * Supported additional details from accelerator 425 * 426 * @description 427 * This enumeration lists the supported additional details from the 428 * accelerator. These may be useful in determining the best way to 429 * recover from a failure. 430 * 431 * 432 *****************************************************************************/ 433 typedef enum _CpaDcReqStatus 434 { 435 CPA_DC_OK = 0, 436 /**< No error detected by compression slice */ 437 CPA_DC_INVALID_BLOCK_TYPE = -1, 438 /**< Invalid block type (type == 3) */ 439 CPA_DC_BAD_STORED_BLOCK_LEN = -2, 440 /**< Stored block length did not match one's complement */ 441 CPA_DC_TOO_MANY_CODES = -3, 442 /**< Too many length or distance codes */ 443 CPA_DC_INCOMPLETE_CODE_LENS = -4, 444 /**< Code length codes incomplete */ 445 CPA_DC_REPEATED_LENS = -5, 446 /**< Repeated lengths with no first length */ 447 CPA_DC_MORE_REPEAT = -6, 448 /**< Repeat more than specified lengths */ 449 CPA_DC_BAD_LITLEN_CODES = -7, 450 /**< Invalid literal/length code lengths */ 451 CPA_DC_BAD_DIST_CODES = -8, 452 /**< Invalid distance code lengths */ 453 CPA_DC_INVALID_CODE = -9, 454 /**< Invalid literal/length or distance code in fixed or dynamic block */ 455 CPA_DC_INVALID_DIST = -10, 456 /**< Distance is too far back in fixed or dynamic block */ 457 CPA_DC_OVERFLOW = -11, 458 /**< Overflow detected. This is an indication that output buffer has overflowed. 459 * For stateful sessions, this is a warning (the input can be adjusted and 460 * resubmitted). 461 * For stateless sessions this is an error condition */ 462 CPA_DC_SOFTERR = -12, 463 /**< Other non-fatal detected */ 464 CPA_DC_FATALERR = -13, 465 /**< Fatal error detected */ 466 CPA_DC_MAX_RESUBITERR = -14, 467 /**< On an error being detected, the firmware attempted to correct and resubmitted the 468 * request, however, the maximum resubmit value was exceeded */ 469 CPA_DC_INCOMPLETE_FILE_ERR = -15, 470 /**< The input file is incomplete. Note this is an indication that the request was 471 * submitted with a CPA_DC_FLUSH_FINAL, however, a BFINAL bit was not found in the 472 * request */ 473 CPA_DC_WDOG_TIMER_ERR = -16, 474 /**< The request was not completed as a watchdog timer hardware event occurred */ 475 CPA_DC_EP_HARDWARE_ERR = -17, 476 /**< Request was not completed as an end point hardware error occurred (for 477 * example, a parity error) */ 478 CPA_DC_VERIFY_ERROR = -18, 479 /**< Error detected during "compress and verify" operation */ 480 CPA_DC_EMPTY_DYM_BLK = -19, 481 /**< Decompression request contained an empty dynamic stored block 482 * (not supported) */ 483 CPA_DC_CRC_INTEG_ERR = -20, 484 /**< A data integrity CRC error was detected */ 485 CPA_DC_LZ4_MAX_BLOCK_SIZE_EXCEEDED = -93, 486 /**< LZ4 max block size exceeded */ 487 CPA_DC_LZ4_BLOCK_OVERFLOW_ERR = -95, 488 /**< LZ4 Block Overflow Error */ 489 CPA_DC_LZ4_TOKEN_IS_ZERO_ERR = -98, 490 /**< LZ4 Decoded token offset or token length is zero */ 491 CPA_DC_LZ4_DISTANCE_OUT_OF_RANGE_ERR = -100, 492 /**< LZ4 Distance out of range for len/distance pair */ 493 } CpaDcReqStatus; 494 495 /** 496 ***************************************************************************** 497 * @ingroup cpaDc 498 * Supported modes for automatically selecting the best compression type. 499 * 500 * @description 501 * This enumeration lists the supported modes for automatically selecting 502 * the best encoding which would lead to the best compression results. 503 * 504 * When CPA_DC_ASB_ENABLED is used the output will be a format compliant 505 * block, whether the data is compressed or not. 506 * 507 * The following values are deprecated and should not be used. They 508 * will be removed in a future version of this file. 509 * - CPA_DC_ASB_STATIC_DYNAMIC 510 * - CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_STORED_HDRS 511 * - CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_NO_HDRS 512 * 513 *****************************************************************************/ 514 typedef enum _CpaDcAutoSelectBest 515 { 516 CPA_DC_ASB_DISABLED = 0, 517 /**< Auto select best mode is disabled */ 518 CPA_DC_ASB_STATIC_DYNAMIC = 1, 519 /**< Auto select between static and dynamic compression */ 520 CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_STORED_HDRS = 2, 521 /**< Auto select between uncompressed, static and dynamic compression, 522 * using stored block deflate headers if uncompressed is selected */ 523 CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_NO_HDRS = 3, 524 /**< Auto select between uncompressed, static and dynamic compression, 525 * using no deflate headers if uncompressed is selected */ 526 CPA_DC_ASB_ENABLED = 4, 527 /**< Auto select best mode is enabled */ 528 } CpaDcAutoSelectBest; 529 530 /** 531 ***************************************************************************** 532 * @ingroup cpaDc 533 * Supported modes for skipping regions of input or output buffers. 534 * 535 * @description 536 * This enumeration lists the supported modes for skipping regions of 537 * input or output buffers. 538 * 539 *****************************************************************************/ 540 typedef enum _CpaDcSkipMode 541 { 542 CPA_DC_SKIP_DISABLED = 0, 543 /**< Skip mode is disabled */ 544 CPA_DC_SKIP_AT_START = 1, 545 /**< Skip region is at the start of the buffer. */ 546 CPA_DC_SKIP_AT_END = 2, 547 /**< Skip region is at the end of the buffer. */ 548 CPA_DC_SKIP_STRIDE = 3 549 /**< Skip region occurs at regular intervals within the buffer. 550 CpaDcSkipData.strideLength specifies the number of bytes between each 551 skip region. */ 552 } CpaDcSkipMode; 553 554 /** 555 ***************************************************************************** 556 * @ingroup cpaDc 557 * Service specific return codes 558 * 559 * @description 560 * Compression specific return codes 561 * 562 * 563 *****************************************************************************/ 564 565 #define CPA_DC_BAD_DATA (-100) 566 /**<Input data in invalid */ 567 568 /** 569 ***************************************************************************** 570 * @ingroup cpaDc 571 * Definition of callback function invoked for asynchronous cpaDc 572 * requests. 573 * 574 * @description 575 * This is the prototype for the cpaDc compression callback functions. 576 * The callback function is registered by the application using the 577 * cpaDcInitSession() function call. 578 * 579 * @context 580 * This callback function can be executed in a context that DOES NOT 581 * permit sleeping to occur. 582 * @assumptions 583 * None 584 * @sideEffects 585 * None 586 * @reentrant 587 * No 588 * @threadSafe 589 * Yes 590 * 591 * @param callbackTag User-supplied value to help identify request. 592 * @param status Status of the operation. Valid values are 593 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 594 * CPA_STATUS_UNSUPPORTED. 595 * 596 * @retval 597 * None 598 * @pre 599 * Component has been initialized. 600 * @post 601 * None 602 * @note 603 * None 604 * @see 605 * None 606 * 607 *****************************************************************************/ 608 typedef void (*CpaDcCallbackFn)( 609 void *callbackTag, 610 CpaStatus status); 611 612 613 /** 614 ***************************************************************************** 615 * @ingroup cpaDc 616 * Implementation Capabilities Structure 617 * @description 618 * This structure contains data relating to the capabilities of an 619 * implementation. The capabilities include supported compression 620 * algorithms, RFC 1951 options and whether the implementation supports 621 * both stateful and stateless compress and decompress sessions. 622 * 623 ****************************************************************************/ 624 typedef struct _CpaDcInstanceCapabilities { 625 CpaBoolean statefulLZSCompression; 626 /**<True if the Instance supports Stateful LZS compression */ 627 CpaBoolean statefulLZSDecompression; 628 /**<True if the Instance supports Stateful LZS decompression */ 629 CpaBoolean statelessLZSCompression; 630 /**<True if the Instance supports Stateless LZS compression */ 631 CpaBoolean statelessLZSDecompression; 632 /**<True if the Instance supports Stateless LZS decompression */ 633 CpaBoolean statefulLZSSCompression; 634 /**<True if the Instance supports Stateful LZSS compression */ 635 CpaBoolean statefulLZSSDecompression; 636 /**<True if the Instance supports Stateful LZSS decompression */ 637 CpaBoolean statelessLZSSCompression; 638 /**<True if the Instance supports Stateless LZSS compression */ 639 CpaBoolean statelessLZSSDecompression; 640 /**<True if the Instance supports Stateless LZSS decompression */ 641 CpaBoolean statefulELZSCompression; 642 /**<True if the Instance supports Stateful Extended LZS 643 compression */ 644 CpaBoolean statefulELZSDecompression; 645 /**<True if the Instance supports Stateful Extended LZS 646 decompression */ 647 CpaBoolean statelessELZSCompression; 648 /**<True if the Instance supports Stateless Extended LZS 649 compression */ 650 CpaBoolean statelessELZSDecompression; 651 /**<True if the Instance supports Stateless Extended LZS 652 decompression */ 653 CpaBoolean statefulDeflateCompression; 654 /**<True if the Instance supports Stateful Deflate compression */ 655 CpaBoolean statefulDeflateDecompression; 656 /**<True if the Instance supports Stateful Deflate 657 decompression */ 658 CpaBoolean statelessDeflateCompression; 659 /**<True if the Instance supports Stateless Deflate compression */ 660 CpaBoolean statelessDeflateDecompression; 661 /**<True if the Instance supports Stateless Deflate 662 decompression */ 663 CpaBoolean statelessLZ4Compression; 664 /**<True if the Instance supports Stateless LZ4 compression */ 665 CpaBoolean statelessLZ4Decompression; 666 /**<True if the Instance supports Stateless LZ4 decompression */ 667 CpaBoolean statefulLZ4Decompression; 668 /**<True if the Instance supports Stateful LZ4 decompression */ 669 CpaBoolean statelessLZ4SCompression; 670 /**<True if the Instance supports Stateless LZ4S compression */ 671 CpaBoolean checksumCRC32; 672 /**<True if the Instance can calculate a CRC32 checksum over 673 the uncompressed data. This value is only calculated when 674 CPA_DC_DEFLATE is configured as the algorithm for 675 CpaDcCompType */ 676 CpaBoolean checksumAdler32; 677 /**<True if the Instance can calculate an Adler-32 checksum over 678 the uncompressed data. This value is only calculated when 679 CPA_DC_DEFLATE is configured as the algorithm for 680 CpaDcCompType */ 681 CpaBoolean checksumXXHash32; 682 /**<True if the Instance can calculate an xxHash-32 hash over 683 the uncompressed data. This value is only calculated when 684 CPA_DC_LZ4 or CPA_DC_LZ4S is configured as the algorithm for 685 CpaDcCompType */ 686 CpaBoolean dynamicHuffman; 687 /**<True if the Instance supports dynamic Huffman trees in deflate 688 blocks */ 689 CpaBoolean dynamicHuffmanBufferReq; 690 /**<True if an Instance specific buffer is required to perform 691 a dynamic Huffman tree deflate request */ 692 CpaBoolean precompiledHuffman; 693 /**<True if the Instance supports precompiled Huffman trees in 694 deflate blocks */ 695 CpaBoolean autoSelectBestHuffmanTree; 696 /**<True if the Instance has the ability to automatically select 697 between different Huffman encoding schemes for better 698 compression ratios */ 699 Cpa8U validWindowSizeMaskCompression; 700 /**<Bits set to '1' for each valid window size supported by 701 the compression implementation */ 702 Cpa8U validWindowSizeMaskDecompression; 703 /**<Bits set to '1' for each valid window size supported by 704 the decompression implementation */ 705 Cpa32U internalHuffmanMem; 706 /**<Number of bytes internally available to be used when 707 constructing dynamic Huffman trees. */ 708 CpaBoolean endOfLastBlock; 709 /**< True if the Instance supports stopping at the end of the last 710 * block in a deflate stream during a decompression operation and 711 * reporting that the end of the last block has been reached as 712 * part of the CpaDcReqStatus data. */ 713 CpaBoolean reportParityError; 714 /**<True if the instance supports parity error reporting. */ 715 CpaBoolean batchAndPack; 716 /**< True if the instance supports 'batch and pack' compression */ 717 CpaBoolean compressAndVerify; 718 /**<True if the instance supports checking that compressed data, 719 * generated as part of a compression operation, can be 720 * successfully decompressed. */ 721 CpaBoolean compressAndVerifyStrict; 722 /**< True if compressAndVerify is 'strictly' enabled for the 723 * instance. If strictly enabled, compressAndVerify will be enabled 724 * by default for compression operations and cannot be disabled by 725 * setting opData.compressAndVerify=0 with cpaDcCompressData2(). 726 * Compression operations with opData.compressAndVerify=0 will 727 * return a CPA_STATUS_INVALID_PARAM error status when in 728 * compressAndVerify strict mode. 729 */ 730 CpaBoolean compressAndVerifyAndRecover; 731 /**<True if the instance supports recovering from errors detected 732 * by compressAndVerify by generating a stored block in the 733 * compressed output data buffer. This stored block replaces any 734 * compressed content that resulted in a compressAndVerify error. 735 */ 736 CpaBoolean integrityCrcs; 737 /**<True if the instance supports 32 bit integrity CRC checking in 738 * the compression/decompression datapath. Refer to 739 * @ref CpaDcOpData for more details on integrity checking. */ 740 CPA_BITMAP(dcChainCapInfo, CPA_DC_CHAIN_CAP_BITMAP_SIZE); 741 /**< Bitmap representing which chaining capabilities are supported 742 * by the instance. 743 * Bits can be tested using the macro @ref CPA_BITMAP_BIT_TEST. 744 * The bit positions are those specified in the enumerated type 745 * @ref CpaDcChainOperations in cpa_dc_chain.h. */ 746 CpaBoolean integrityCrcs64b; 747 /**<True if the instance supports 64 bit integrity CRC checking in 748 * the compression / decompression datapath. Refer to 749 * @ref CpaDcOpData for more details on integrity checking. */ 750 } CpaDcInstanceCapabilities; 751 752 /** 753 ***************************************************************************** 754 * @ingroup cpaDc 755 * Session Setup Data. 756 * @description 757 * This structure contains data relating to setting up a session. The 758 * client needs to complete the information in this structure in order to 759 * setup a session. 760 * 761 ****************************************************************************/ 762 typedef struct _CpaDcSessionSetupData { 763 CpaDcCompLvl compLevel; 764 /**<Compression Level from CpaDcCompLvl */ 765 CpaDcCompType compType; 766 /**<Compression type from CpaDcCompType */ 767 CpaDcHuffType huffType; 768 /**<Huffman type from CpaDcHuffType */ 769 CpaDcAutoSelectBest autoSelectBestHuffmanTree; 770 /**<Indicates if and how the implementation should select the best 771 * Huffman encoding. */ 772 CpaDcSessionDir sessDirection; 773 /**<Session direction indicating whether session is used for 774 compression, decompression or both */ 775 CpaDcSessionState sessState; 776 /**<Session state indicating whether the session should be configured 777 as stateless or stateful */ 778 CpaDcCompWindowSize windowSize; 779 /**<Window size from CpaDcCompWindowSize */ 780 CpaDcCompMinMatch minMatch; 781 /**<Min Match size from CpaDcCompMinMatch */ 782 CpaDcCompLZ4BlockMaxSize lz4BlockMaxSize; 783 /**<Window size from CpaDcCompLZ4BlockMaxSize */ 784 CpaBoolean lz4BlockChecksum; 785 /**<LZ4 Block Checksum setting for the LZ4 request. 786 For LZ4 decompression operations, this setting must be set based 787 on the B.Checksum flag originating from the LZ4 frame header. 788 For LZ4 compression operations, this setting will be ignored as 789 the implementation does not support generation of Data Block 790 checksums. */ 791 CpaBoolean lz4BlockIndependence; 792 /**<LZ4 Block Independence Flag setting. 793 For LZ4 compression operations, this setting must be set based on 794 the Block Independence Flag originating from the LZ4 frame header. 795 For LZ4 decompression operations, this setting is ignored. 796 For data compressed with lz4BlockIndependence set to CPA_FALSE, 797 it is not possible to perform parallel decompression on the 798 compressed blocks. It is also not possible to access the produced 799 LZ4 blocks randomly. 800 */ 801 CpaDcChecksum checksum; 802 /**<Desired checksum required for the session */ 803 CpaBoolean accumulateXXHash; 804 /**<If TRUE the xxHash calculation for LZ4 requests using the session 805 based API, cpaDcCompressData2 and cpaDcCompressData, will be 806 accumulated across requests, with a valid xxHash being written to 807 CpaDcRqResults.checksum for the request which specifies 808 CPA_DC_FLUSH_FINAL in CpaDcOpData.flushFlag. When the 809 CPA_DC_FLUSH_FINAL is received, the internal XXHash state will be 810 reset for this session. 811 One exception is if a CPA_DC_OVERFLOW error is returned, the xxHash 812 value in the checksum field will be valid for requests up to that 813 point and the internal XXHash state will not be reset. This will 814 allow a user to either create an LZ4 frame based off the data at the 815 time of overflow, or correct the overflow condition and continue 816 submitting requests until specifying CPA_DC_FLUSH_FINAL. 817 Additionally the user can force the internal XXHash state to reset 818 (even on overflow) by calling cpaDcResetXXHashState on this session. 819 For the sessionless API, cpaDcNsCompressData, this flag will have 820 no effect */ 821 } CpaDcSessionSetupData; 822 823 typedef CpaDcSessionSetupData CpaDcNsSetupData; 824 825 /** 826 ***************************************************************************** 827 * @ingroup cpaDc 828 * Session Update Data. 829 * @description 830 * This structure contains data relating to updating up a session. The 831 * client needs to complete the information in this structure in order to 832 * update a session. 833 * 834 ****************************************************************************/ 835 typedef struct _CpaDcSessionUpdateData { 836 CpaDcCompLvl compLevel; 837 /**<Compression Level from CpaDcCompLvl */ 838 CpaDcHuffType huffType; 839 /**<Huffman type from CpaDcHuffType */ 840 CpaBoolean enableDmm; 841 /**<Desired DMM required for the session */ 842 } CpaDcSessionUpdateData ; 843 844 /** 845 ***************************************************************************** 846 * @ingroup cpaDc 847 * Compression Statistics Data. 848 * @description 849 * This structure contains data elements corresponding to statistics. 850 * Statistics are collected on a per instance basis and include: 851 * jobs submitted and completed for both compression and decompression. 852 * 853 ****************************************************************************/ 854 typedef struct _CpaDcStats { 855 Cpa64U numCompRequests; 856 /**< Number of successful compression requests */ 857 Cpa64U numCompRequestsErrors; 858 /**< Number of compression requests that had errors and 859 could not be processed */ 860 Cpa64U numCompCompleted; 861 /**< Compression requests completed */ 862 Cpa64U numCompCompletedErrors; 863 /**< Compression requests not completed due to errors */ 864 Cpa64U numCompCnvErrorsRecovered; 865 /**< Compression CNV errors that have been recovered */ 866 867 Cpa64U numDecompRequests; 868 /**< Number of successful decompression requests */ 869 Cpa64U numDecompRequestsErrors; 870 /**< Number of decompression requests that had errors and 871 could not be processed */ 872 Cpa64U numDecompCompleted; 873 /**< Decompression requests completed */ 874 Cpa64U numDecompCompletedErrors; 875 /**< Decompression requests not completed due to errors */ 876 877 } CpaDcStats; 878 879 /** 880 ***************************************************************************** 881 * @ingroup cpaDc 882 * Request results data 883 * @description 884 * This structure contains the request results. 885 * 886 * For stateful sessions the status, produced, consumed and 887 * endOfLastBlock results are per request values while the checksum 888 * value is cumulative across all requests on the session so far. 889 * In this case the checksum value is not guaranteed to be correct 890 * until the final compressed data has been processed. 891 * 892 * For stateless sessions, an initial checksum value is passed into 893 * the stateless operation. Once the stateless operation completes, 894 * the checksum value will contain checksum produced by the operation. 895 * 896 ****************************************************************************/ 897 typedef struct _CpaDcRqResults { 898 CpaDcReqStatus status; 899 /**< Additional status details from accelerator */ 900 Cpa32U produced; 901 /**< Octets produced by the operation */ 902 Cpa32U consumed; 903 /**< Octets consumed by the operation */ 904 Cpa32U checksum; 905 /**< The checksum produced by the operation. For some checksum 906 * algorithms, setting this field on the input to a stateless 907 * compression/decompression request can be used to pass in an initial 908 * checksum value that will be used to seed the checksums produced by 909 * the stateless operation. 910 * 911 * The checksum algorithm CPA_DC_XXHASH32 does not support passing an 912 * input value in this parameter. Any initial value passed will be 913 * ignored by the compression/decompression operation when this 914 * checksum algorithm is used. */ 915 CpaBoolean endOfLastBlock; 916 /**< Decompression operation has stopped at the end of the last 917 * block in a deflate stream. */ 918 CpaBoolean dataUncompressed; 919 /**< If TRUE the output data for this request is uncompressed and 920 * in the format setup for the request. This value is only valid 921 * for CPA_DC_ASB_ENABLED or if compressAndVerifyAndRecover is set to 922 * TRUE in the CpaDcOpData structure for a request. */ 923 } CpaDcRqResults; 924 925 /** 926 ***************************************************************************** 927 * @ingroup cpaDc 928 * Integrity CRC Size 929 * @description 930 * Enum of possible integrity CRC sizes. 931 * 932 ****************************************************************************/ 933 typedef enum _CpaDcIntegrityCrcSize 934 { 935 CPA_DC_INTEGRITY_CRC32 = 0, 936 /**< 32-bit Integrity CRCs */ 937 CPA_DC_INTEGRITY_CRC64, 938 /**< 64-bit integrity CRCs */ 939 } CpaDcIntegrityCrcSize; 940 941 /** 942 ***************************************************************************** 943 * @ingroup cpaDc 944 * Integrity CRC calculation details 945 * @description 946 * This structure contains information about resulting integrity CRC 947 * calculations performed for a single request. 948 * 949 ****************************************************************************/ 950 typedef struct _CpaIntegrityCrc { 951 Cpa32U iCrc; /**< CRC calculated on request's input buffer */ 952 Cpa32U oCrc; /**< CRC calculated on request's output buffer */ 953 } CpaIntegrityCrc; 954 955 /** 956 ***************************************************************************** 957 * @ingroup cpaDc 958 * Integrity CRC64 calculation details 959 * @description 960 * This structure contains information about resulting integrity CRC64 961 * calculations performed for a single request. 962 * 963 ****************************************************************************/ 964 typedef struct _CpaIntegrityCrc64b { 965 Cpa64U iCrc; /**< CRC calculated on request's input buffer */ 966 Cpa64U oCrc; /**< CRC calculated on request's output buffer */ 967 } CpaIntegrityCrc64b; 968 969 /** 970 ***************************************************************************** 971 * @ingroup cpaDc 972 * Collection of CRC related data 973 * @description 974 * This structure contains data facilitating CRC calculations. 975 * After successful request, this structure will contain 976 * all resulting CRCs. 977 * Integrity specific CRCs (when enabled/supported) are located in 978 * 'CpaIntegrityCrc integrityCrc' field for 32bit values and in 979 * 'CpaIntegrityCrc64b integrityCrC64b' field for 64 bit values. 980 * Integrity CRCs cannot be accumulated across multiple requests and 981 * do not provide seeding capabilities. 982 * @note 983 * this structure must be allocated in physical contiguous memory 984 * 985 ****************************************************************************/ 986 typedef struct _CpaCrcData { 987 Cpa32U crc32; 988 /**< CRC32 calculated on the input buffer during compression 989 * requests and on the output buffer during decompression requests. */ 990 Cpa32U adler32; 991 /**< ADLER32 calculated on the input buffer during compression 992 * requests and on the output buffer during decompression requests. */ 993 CpaIntegrityCrc integrityCrc; 994 /**< 32bit Integrity CRCs */ 995 CpaIntegrityCrc64b integrityCrc64b; 996 /**< 64bit Integrity CRCs */ 997 } CpaCrcData; 998 999 /** 1000 ***************************************************************************** 1001 * @ingroup cpaDc 1002 * Skip Region Data. 1003 * @description 1004 * This structure contains data relating to configuring skip region 1005 * behaviour. A skip region is a region of an input buffer that 1006 * should be omitted from processing or a region that should be inserted 1007 * into the output buffer. 1008 * 1009 ****************************************************************************/ 1010 typedef struct _CpaDcSkipData { 1011 CpaDcSkipMode skipMode; 1012 /**<Skip mode from CpaDcSkipMode for buffer processing */ 1013 Cpa32U skipLength; 1014 /**<Number of bytes to skip when skip mode is enabled */ 1015 Cpa32U strideLength; 1016 /**<Size of the stride between skip regions when skip mode is 1017 * set to CPA_DC_SKIP_STRIDE. */ 1018 Cpa32U firstSkipOffset; 1019 /**< Number of bytes to skip in a buffer before reading/writing the 1020 * input/output data. */ 1021 } CpaDcSkipData; 1022 1023 /** 1024 ***************************************************************************** 1025 * @ingroup cpaDc 1026 * (De)Compression request input parameters. 1027 * @description 1028 * This structure contains the request information for use with 1029 * compression operations. 1030 * 1031 ****************************************************************************/ 1032 typedef struct _CpaDcOpData { 1033 CpaDcFlush flushFlag; 1034 /**< Indicates the type of flush to be performed. */ 1035 CpaBoolean compressAndVerify; 1036 /**< If set to true, for compression operations, the implementation 1037 * will verify that compressed data, generated by the compression 1038 * operation, can be successfully decompressed. 1039 * This behavior is only supported for stateless compression. 1040 * This behavior is only supported on instances that support the 1041 * compressAndVerify capability. */ 1042 CpaBoolean compressAndVerifyAndRecover; 1043 /**< If set to true, for compression operations, the implementation 1044 * will automatically recover from a compressAndVerify error. 1045 * This behavior is only supported for stateless compression. 1046 * This behavior is only supported on instances that support the 1047 * compressAndVerifyAndRecover capability. 1048 * The compressAndVerify field in CpaDcOpData MUST be set to CPA_TRUE 1049 * if compressAndVerifyAndRecover is set to CPA_TRUE. */ 1050 CpaBoolean integrityCrcCheck; 1051 /**< If set to true, the implementation will verify that data 1052 * integrity is preserved through the processing pipeline. 1053 * 1054 * Integrity CRC checking is not supported for decompression operations 1055 * over data that contains multiple gzip headers. */ 1056 CpaBoolean verifyHwIntegrityCrcs; 1057 /**< If set to true, software calculated CRCs will be compared 1058 * against hardware generated integrity CRCs to ensure that data 1059 * integrity is maintained when transferring data to and from the 1060 * hardware accelerator. */ 1061 CpaDcIntegrityCrcSize integrityCrcSize; 1062 /**< This option specifies the size of the CRC to be used for data 1063 * integrity checking. As such it is only valid if this request is 1064 * configured for data integrity checks. */ 1065 CpaDcSkipData inputSkipData; 1066 /**< Optional skip regions in the input buffers */ 1067 CpaDcSkipData outputSkipData; 1068 /**< Optional skip regions in the output buffers */ 1069 CpaCrcData *pCrcData; 1070 /**< Pointer to CRCs for this operation, when integrity checks 1071 * are enabled. */ 1072 } CpaDcOpData; 1073 1074 /** 1075 ***************************************************************************** 1076 * @ingroup cpaDc 1077 * Retrieve Instance Capabilities 1078 * 1079 * @description 1080 * This function is used to retrieve the capabilities matrix of 1081 * an instance. 1082 * 1083 * @context 1084 * This function shall not be called in an interrupt context. 1085 * @assumptions 1086 * None 1087 * @sideEffects 1088 * None 1089 * @blocking 1090 * Yes 1091 * @reentrant 1092 * No 1093 * @threadSafe 1094 * Yes 1095 * 1096 * @param[in] dcInstance Instance handle derived from discovery 1097 * functions 1098 * @param[in,out] pInstanceCapabilities Pointer to a capabilities struct 1099 * 1100 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1101 * @retval CPA_STATUS_FAIL Function failed. 1102 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1103 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1104 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1105 * the request. 1106 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1107 * 1108 * @pre 1109 * None 1110 * @post 1111 * None 1112 * @note 1113 * Only a synchronous version of this function is provided. 1114 * 1115 * @see 1116 * None 1117 * 1118 *****************************************************************************/ 1119 CpaStatus 1120 cpaDcQueryCapabilities( CpaInstanceHandle dcInstance, 1121 CpaDcInstanceCapabilities *pInstanceCapabilities ); 1122 1123 /** 1124 ***************************************************************************** 1125 * @ingroup cpaDc 1126 * Initialize compression decompression session 1127 * 1128 * @description 1129 * This function is used to initialize a compression/decompression 1130 * session. 1131 * This function specifies a BufferList for context data. 1132 * A single session can be used for both compression and decompression 1133 * requests. Clients MAY register a callback 1134 * function for the compression service using this function. 1135 * This function returns a unique session handle each time this function 1136 * is invoked. 1137 * If the session has been configured with a callback function, then 1138 * the order of the callbacks are guaranteed to be in the same order the 1139 * compression or decompression requests were submitted for each session, 1140 * so long as a single thread of execution is used for job submission. 1141 * 1142 * @context 1143 * This is a synchronous function and it cannot sleep. It can be executed in 1144 * a context that does not permit sleeping. 1145 * @assumptions 1146 * None 1147 * @sideEffects 1148 * None 1149 * @blocking 1150 * No 1151 * @reentrant 1152 * No 1153 * @threadSafe 1154 * Yes 1155 * 1156 * @param[in] dcInstance Instance handle derived from discovery 1157 * functions. 1158 * @param[in,out] pSessionHandle Pointer to a session handle. 1159 * @param[in,out] pSessionData Pointer to a user instantiated structure 1160 * containing session data. 1161 * @param[in] pContextBuffer pointer to context buffer. This is not 1162 * required for stateless operations. 1163 * The total size of the buffer list must 1164 * be equal to or larger than the specified 1165 * contextSize retrieved from the 1166 * cpaDcGetSessionSize() function. 1167 * @param[in] callbackFn For synchronous operation this callback 1168 * shall be a null pointer. 1169 * 1170 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1171 * @retval CPA_STATUS_FAIL Function failed. 1172 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1173 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1174 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1175 * the request. 1176 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1177 * 1178 * @pre 1179 * dcInstance has been started using cpaDcStartInstance. 1180 * @post 1181 * None 1182 * @note 1183 * Only a synchronous version of this function is provided. 1184 * 1185 * This initializes opaque data structures in the session handle. Data 1186 * compressed under this session will be compressed to the level 1187 * specified in the pSessionData structure. Lower compression level 1188 * numbers indicate a request for faster compression at the 1189 * expense of compression ratio. Higher compression level numbers 1190 * indicate a request for higher compression ratios at the expense of 1191 * execution time. 1192 * 1193 * The session is opaque to the user application and the session handle 1194 * contains job specific data. 1195 * 1196 * The pointer to the ContextBuffer will be stored in session specific 1197 * data if required by the implementation. 1198 * 1199 * It is not permitted to have multiple 1200 * outstanding asynchronous compression requests for stateful sessions. 1201 * It is possible to add 1202 * parallelization to compression by using multiple sessions. 1203 * 1204 * The window size specified in the pSessionData must be match exactly 1205 * one of the supported window sizes specified in the capabilities 1206 * structure. If a bi-directional session is being initialized, then 1207 * the window size must be valid for both compress and decompress. 1208 * 1209 * @see 1210 * None 1211 * 1212 *****************************************************************************/ 1213 CpaStatus 1214 cpaDcInitSession( CpaInstanceHandle dcInstance, 1215 CpaDcSessionHandle pSessionHandle, 1216 CpaDcSessionSetupData *pSessionData, 1217 CpaBufferList *pContextBuffer, 1218 CpaDcCallbackFn callbackFn ); 1219 1220 1221 /** 1222 ***************************************************************************** 1223 * @ingroup cpaDc 1224 * Compression Session Reset Function. 1225 * 1226 * @description 1227 * This function will reset a previously initialized session handle 1228 * Reset will fail if outstanding calls still exist for the initialized 1229 * session handle. 1230 * The client needs to retry the reset function at a later time. 1231 * 1232 * @context 1233 * This is a synchronous function that cannot sleep. It can be 1234 * executed in a context that does not permit sleeping. 1235 * @assumptions 1236 * None 1237 * @sideEffects 1238 * None 1239 * @blocking 1240 * No. 1241 * @reentrant 1242 * No 1243 * @threadSafe 1244 * Yes 1245 * 1246 * @param[in] dcInstance Instance handle. 1247 * @param[in,out] pSessionHandle Session handle. 1248 * 1249 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1250 * @retval CPA_STATUS_FAIL Function failed. 1251 * @retval CPA_STATUS_RETRY Resubmit the request. 1252 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1253 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1254 * 1255 * @pre 1256 * The component has been initialized via cpaDcStartInstance function. 1257 * The session has been initialized via cpaDcInitSession function. 1258 * @post 1259 * None 1260 * @note 1261 * This is a synchronous function and has no completion callback 1262 * associated with it. 1263 * 1264 * @see 1265 * cpaDcInitSession() 1266 * 1267 *****************************************************************************/ 1268 CpaStatus 1269 cpaDcResetSession(const CpaInstanceHandle dcInstance, 1270 CpaDcSessionHandle pSessionHandle ); 1271 1272 /** 1273 ***************************************************************************** 1274 * @ingroup cpaDc 1275 * Reset of the xxHash internal state on a session. 1276 * 1277 * @description 1278 * This function will reset the internal xxHash state maintained within a 1279 * session. This would be used in conjunction with the 1280 * CpaDcSessionSetupData.accumulateXXHash flag being set to TRUE for this 1281 * session. It will enable reseting (reinitialising) just the xxHash 1282 * calculation back to the state when the session was first initialised. 1283 * 1284 * @context 1285 * This is a synchronous function that cannot sleep. It can be 1286 * executed in a context that does not permit sleeping. 1287 * @assumptions 1288 * None 1289 * @sideEffects 1290 * None 1291 * @blocking 1292 * No. 1293 * @reentrant 1294 * No 1295 * @threadSafe 1296 * Yes 1297 * 1298 * @param[in] dcInstance Instance handle. 1299 * @param[in,out] pSessionHandle Session handle. 1300 * 1301 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1302 * @retval CPA_STATUS_FAIL Function failed. 1303 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1304 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1305 * 1306 * @pre 1307 * The component has been initialized via cpaDcStartInstance function. 1308 * The session has been initialized via cpaDcInitSession function. 1309 * @post 1310 * None 1311 * @note 1312 * This is a synchronous function and has no completion callback 1313 * associated with it. 1314 * 1315 * @see 1316 * 1317 *****************************************************************************/ 1318 CpaStatus 1319 cpaDcResetXXHashState(const CpaInstanceHandle dcInstance, 1320 CpaDcSessionHandle pSessionHandle ); 1321 1322 /** 1323 ***************************************************************************** 1324 * @ingroup cpaDc 1325 * Compression Session Update Function. 1326 * 1327 * @description 1328 * This function is used to modify some select compression parameters 1329 * of a previously initialized session handle. 1330 * Th update will fail if resources required for the new session settings 1331 * are not available. Specifically, this function may fail if no 1332 * intermediate buffers are associated with the instance, and the 1333 * intended change would require these buffers. 1334 * This function can be called at any time after a successful call of 1335 * cpaDcDpInitSession(). 1336 * This function does not change the parameters to compression request 1337 * already in flight. 1338 * 1339 * @context 1340 * This is a synchronous function that cannot sleep. It can be 1341 * executed in a context that does not permit sleeping. 1342 * @assumptions 1343 * None 1344 * @sideEffects 1345 * None 1346 * @blocking 1347 * No. 1348 * @reentrant 1349 * No 1350 * @threadSafe 1351 * Yes 1352 * 1353 * @param[in] dcInstance Instance handle. 1354 * @param[in,out] pSessionHandle Session handle. 1355 * @param[in] pSessionUpdateData Session Data. 1356 * 1357 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1358 * @retval CPA_STATUS_FAIL Function failed. 1359 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1360 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1361 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 1362 * Resubmit the request 1363 * 1364 * 1365 * @pre 1366 * The component has been initialized via cpaDcStartInstance function. 1367 * The session has been initialized via cpaDcInitSession function. 1368 * @post 1369 * None 1370 * @note 1371 * This is a synchronous function and has no completion callback 1372 * associated with it. 1373 * 1374 * @see 1375 * cpaDcInitSession() 1376 * 1377 *****************************************************************************/ 1378 CpaStatus cpaDcUpdateSession(const CpaInstanceHandle dcInstance, 1379 CpaDcSessionHandle pSessionHandle, 1380 CpaDcSessionUpdateData *pSessionUpdateData ); 1381 1382 /** 1383 ***************************************************************************** 1384 * @ingroup cpaDc 1385 * Compression Session Remove Function. 1386 * 1387 * @description 1388 * This function will remove a previously initialized session handle 1389 * and the installed callback handler function. Removal will fail if 1390 * outstanding calls still exist for the initialized session handle. 1391 * The client needs to retry the remove function at a later time. 1392 * The memory for the session handle MUST not be freed until this call 1393 * has completed successfully. 1394 * 1395 * @context 1396 * This is a synchronous function that cannot sleep. It can be 1397 * executed in a context that does not permit sleeping. 1398 * @assumptions 1399 * None 1400 * @sideEffects 1401 * None 1402 * @blocking 1403 * No. 1404 * @reentrant 1405 * No 1406 * @threadSafe 1407 * Yes 1408 * 1409 * @param[in] dcInstance Instance handle. 1410 * @param[in,out] pSessionHandle Session handle. 1411 * 1412 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1413 * @retval CPA_STATUS_FAIL Function failed. 1414 * @retval CPA_STATUS_RETRY Resubmit the request. 1415 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1416 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1417 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1418 * the request. 1419 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1420 * 1421 * @pre 1422 * The component has been initialized via cpaDcStartInstance function. 1423 * @post 1424 * None 1425 * @note 1426 * This is a synchronous function and has no completion callback 1427 * associated with it. 1428 * 1429 * @see 1430 * cpaDcInitSession() 1431 * 1432 *****************************************************************************/ 1433 CpaStatus 1434 cpaDcRemoveSession(const CpaInstanceHandle dcInstance, 1435 CpaDcSessionHandle pSessionHandle ); 1436 1437 /** 1438 ***************************************************************************** 1439 * @ingroup cpaDc 1440 * Deflate Compression Bound API 1441 * 1442 * @description 1443 * This function provides the maximum output buffer size for a Deflate 1444 * compression operation in the "worst case" (non-compressible) scenario. 1445 * It's primary purpose is for output buffer memory allocation. 1446 * 1447 * @context 1448 * This is a synchronous function that will not sleep. It can be 1449 * executed in a context that does not permit sleeping. 1450 * @assumptions 1451 * None 1452 * @sideEffects 1453 * None 1454 * @blocking 1455 * No. 1456 * @reentrant 1457 * No 1458 * @threadSafe 1459 * Yes 1460 * 1461 * @param[in] dcInstance Instance handle. 1462 * @param[in] huffType CpaDcHuffType to be used with this operation. 1463 * @param[in] inputSize Input Buffer size. 1464 * @param[out] outputSize Maximum output buffer size. 1465 * 1466 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1467 * @retval CPA_STATUS_FAIL Function failed. 1468 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1469 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1470 * 1471 * @pre 1472 * The component has been initialized via cpaDcStartInstance function. 1473 * @post 1474 * None 1475 * @note 1476 * This is a synchronous function and has no completion callback 1477 * associated with it. 1478 * The cpaDcDeflateCompressBound() API is intended to reduce the likelihood 1479 * of overflow occurring during compression operations. An overflow may 1480 * occur in some exception cases. 1481 * 1482 * @see 1483 * None 1484 * 1485 *****************************************************************************/ 1486 CpaStatus 1487 cpaDcDeflateCompressBound(const CpaInstanceHandle dcInstance, 1488 CpaDcHuffType huffType, 1489 Cpa32U inputSize, 1490 Cpa32U *outputSize ); 1491 1492 /** 1493 ***************************************************************************** 1494 * @ingroup cpaDc 1495 * LZ4 Compression Bound API 1496 * 1497 * @description 1498 * This function provides the maximum output buffer size for a LZ4 1499 * compression operation in the "worst case" (non-compressible) scenario. 1500 * It's primary purpose is for output buffer memory allocation. 1501 * 1502 * @context 1503 * This is a synchronous function that will not sleep. It can be 1504 * executed in a context that does not permit sleeping. 1505 * @assumptions 1506 * None 1507 * @sideEffects 1508 * None 1509 * @blocking 1510 * No. 1511 * @reentrant 1512 * No 1513 * @threadSafe 1514 * Yes 1515 * 1516 * @param[in] dcInstance Instance handle. 1517 * @param[in] inputSize Input Buffer size. 1518 * @param[out] outputSize Maximum output buffer size. 1519 * 1520 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1521 * @retval CPA_STATUS_FAIL Function failed. 1522 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1523 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1524 * 1525 * @pre 1526 * The component has been initialized via cpaDcStartInstance function. 1527 * @post 1528 * None 1529 * @note 1530 * This is a synchronous function and has no completion callback 1531 * associated with it. 1532 * 1533 * @see 1534 * None 1535 * 1536 *****************************************************************************/ 1537 CpaStatus 1538 cpaDcLZ4CompressBound(const CpaInstanceHandle dcInstance, 1539 Cpa32U inputSize, 1540 Cpa32U *outputSize ); 1541 1542 /** 1543 ***************************************************************************** 1544 * @ingroup cpaDc 1545 * LZ4S Compression Bound API 1546 * 1547 * @description 1548 * This function provides the maximum output buffer size for a LZ4S 1549 * compression operation in the "worst case" (non-compressible) scenario. 1550 * It's primary purpose is for output buffer memory allocation. 1551 * 1552 * @context 1553 * This is a synchronous function that will not sleep. It can be 1554 * executed in a context that does not permit sleeping. 1555 * @assumptions 1556 * None 1557 * @sideEffects 1558 * None 1559 * @blocking 1560 * No. 1561 * @reentrant 1562 * No 1563 * @threadSafe 1564 * Yes 1565 * 1566 * @param[in] dcInstance Instance handle. 1567 * @param[in] inputSize Input Buffer size. 1568 * @param[out] outputSize Maximum output buffer size. 1569 * 1570 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1571 * @retval CPA_STATUS_FAIL Function failed. 1572 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1573 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1574 * 1575 * @pre 1576 * The component has been initialized via cpaDcStartInstance function. 1577 * @post 1578 * None 1579 * @note 1580 * This is a synchronous function and has no completion callback 1581 * associated with it. 1582 * 1583 * @see 1584 * None 1585 * 1586 *****************************************************************************/ 1587 CpaStatus 1588 cpaDcLZ4SCompressBound(const CpaInstanceHandle dcInstance, 1589 Cpa32U inputSize, 1590 Cpa32U *outputSize ); 1591 1592 /** 1593 ***************************************************************************** 1594 * @ingroup cpaDc 1595 * Submit a request to compress a buffer of data. 1596 * 1597 * @description 1598 * This API consumes data from the input buffer and generates compressed 1599 * data in the output buffer. 1600 * 1601 * @context 1602 * When called as an asynchronous function it cannot sleep. It can be 1603 * executed in a context that does not permit sleeping. 1604 * When called as a synchronous function it may sleep. It MUST NOT be 1605 * executed in a context that DOES NOT permit sleeping. 1606 * @assumptions 1607 * None 1608 * @sideEffects 1609 * None 1610 * @blocking 1611 * Yes when configured to operate in synchronous mode. 1612 * @reentrant 1613 * No 1614 * @threadSafe 1615 * Yes 1616 * 1617 * @param[in] dcInstance Target service instance. 1618 * @param[in,out] pSessionHandle Session handle. 1619 * @param[in] pSrcBuff Pointer to data buffer for compression. 1620 * @param[in] pDestBuff Pointer to buffer space for data after 1621 * compression. 1622 * @param[in,out] pResults Pointer to results structure 1623 * @param[in] flushFlag Indicates the type of flush to be 1624 * performed. 1625 * @param[in] callbackTag User supplied value to help correlate 1626 * the callback with its associated 1627 * request. 1628 * 1629 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1630 * @retval CPA_STATUS_FAIL Function failed. 1631 * @retval CPA_STATUS_RETRY Resubmit the request. 1632 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1633 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1634 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1635 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1636 * the request. 1637 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1638 * 1639 * @pre 1640 * pSessionHandle has been setup using cpaDcInitSession() 1641 * @post 1642 * pSessionHandle has session related state information 1643 * @note 1644 * This function passes control to the compression service for processing 1645 * 1646 * In synchronous mode the function returns the error status returned from the 1647 * service. In asynchronous mode the status is returned by the callback 1648 * function. 1649 * 1650 * This function may be called repetitively with input until all of the 1651 * input has been consumed by the compression service and all the output 1652 * has been produced. 1653 * 1654 * When this function returns, it may be that all of the available data 1655 * in the input buffer has not been compressed. This situation will 1656 * occur when there is insufficient space in the output buffer. The 1657 * calling application should note the amount of data processed, and clear 1658 * the output buffer and then submit the request again, with the input 1659 * buffer pointer to the data that was not previously compressed. 1660 * 1661 * Relationship between input buffers and results buffers. 1662 * -# Implementations of this API must not modify the individual 1663 * flat buffers of the input buffer list. 1664 * -# The implementation communicates the amount of data 1665 * consumed from the source buffer list via pResults->consumed arg. 1666 * -# The implementation communicates the amount of data in the 1667 * destination buffer list via pResults->produced arg. 1668 * 1669 * Source Buffer Setup Rules 1670 * -# The buffer list must have the correct number of flat buffers. This 1671 * is specified by the numBuffers element of the CpaBufferList. 1672 * -# Each flat buffer must have a pointer to contiguous memory that has 1673 * been allocated by the calling application. The 1674 * number of octets to be compressed or decompressed must be stored 1675 * in the dataLenInBytes element of the flat buffer. 1676 * -# It is permissible to have one or more flat buffers with a zero length 1677 * data store. This function will process all flat buffers until the 1678 * destination buffer is full or all source data has been processed. 1679 * If a buffer has zero length, then no data will be processed from 1680 * that buffer. 1681 * 1682 * Source Buffer Processing Rules. 1683 * -# The buffer list is processed in index order - SrcBuff->pBuffers[0] 1684 * will be completely processed before SrcBuff->pBuffers[1] begins to 1685 * be processed. 1686 * -# The application must drain the destination buffers. 1687 * If the source data was not completely consumed, the application 1688 * must resubmit the request. 1689 * -# On return, the pResults->consumed will indicate the number of bytes 1690 * consumed from the input buffers. 1691 * 1692 * Destination Buffer Setup Rules 1693 * -# The destination buffer list must have storage for processed data. 1694 * This implies at least one flat buffer must exist in the buffer list. 1695 * -# For each flat buffer in the buffer list, the dataLenInBytes element 1696 * must be set to the size of the buffer space. 1697 * -# It is permissible to have one or more flat buffers with a zero length 1698 * data store. 1699 * If a buffer has zero length, then no data will be added to 1700 * that buffer. 1701 * 1702 * Destination Buffer Processing Rules. 1703 * -# The buffer list is processed in index order - DestBuff->pBuffers[0] 1704 * will be completely processed before DestBuff->pBuffers[1] begins to 1705 * be processed. 1706 * -# On return, the pResults->produced will indicate the number of bytes 1707 * written to the output buffers. 1708 * -# If processing has not been completed, the application must drain the 1709 * destination buffers and resubmit the request. The application must 1710 * reset the dataLenInBytes for each flat buffer in the destination 1711 * buffer list. 1712 * 1713 * Checksum rules. 1714 * If a checksum is specified in the session setup data, then: 1715 * -# For the first request for a particular data segment the checksum 1716 * is initialised internally by the implementation. 1717 * -# The checksum is maintained by the implementation between calls 1718 * until the flushFlag is set to CPA_DC_FLUSH_FINAL indicating the 1719 * end of a particular data segment. 1720 * -# Intermediate checksum values are returned to the application, 1721 * via the CpaDcRqResults structure, in response to each request. 1722 * However these checksum values are not guaranteed to the valid 1723 * until the call with flushFlag set to CPA_DC_FLUSH_FINAL 1724 * completes successfully. 1725 * 1726 * The application should set flushFlag to 1727 * CPA_DC_FLUSH_FINAL to indicate processing a particular data segment 1728 * is complete. It should be noted that this function may have to be 1729 * called more than once to process data after the flushFlag parameter has 1730 * been set to CPA_DC_FLUSH_FINAL if the destination buffer fills. Refer 1731 * to buffer processing rules. 1732 * 1733 * For stateful operations, when the function is invoked with flushFlag 1734 * set to CPA_DC_FLUSH_NONE or CPA_DC_FLUSH_SYNC, indicating more data 1735 * is yet to come, the function may or may not retain data. When the 1736 * function is invoked with flushFlag set to CPA_DC_FLUSH_FULL or 1737 * CPA_DC_FLUSH_FINAL, the function will process all buffered data. 1738 * 1739 * For stateless operations, CPA_DC_FLUSH_FINAL will cause the BFINAL 1740 * bit to be set for deflate compression. The initial checksum for the 1741 * stateless operation should be set to 0. CPA_DC_FLUSH_NONE and 1742 * CPA_DC_FLUSH_SYNC should not be used for stateless operations. 1743 * 1744 * It is possible to maintain checksum and length information across 1745 * cpaDcCompressData() calls with a stateless session without maintaining 1746 * the full history state that is maintained by a stateful session. In this 1747 * mode of operation, an initial checksum value of 0 is passed into the 1748 * first cpaDcCompressData() call with the flush flag set to 1749 * CPA_DC_FLUSH_FULL. On subsequent calls to cpaDcCompressData() for this 1750 * session, the checksum passed to cpaDcCompressData should be set to the 1751 * checksum value produced by the previous call to cpaDcCompressData(). 1752 * When the last block of input data is passed to cpaDcCompressData(), the 1753 * flush flag should be set to CP_DC_FLUSH_FINAL. This will cause the BFINAL 1754 * bit to be set in a deflate stream. It is the responsibility of the calling 1755 * application to maintain overall lengths across the stateless requests 1756 * and to pass the checksum produced by one request into the next request. 1757 * 1758 * When an instance supports compressAndVerifyAndRecover, it is enabled by 1759 * default when using cpaDcCompressData(). If this feature needs to be 1760 * disabled, cpaDcCompressData2() must be used. 1761 * 1762 * Synchronous or Asynchronous operation of the API is determined by 1763 * the value of the callbackFn parameter passed to cpaDcInitSession() 1764 * when the sessionHandle was setup. If a non-NULL value was specified 1765 * then the supplied callback function will be invoked asynchronously 1766 * with the response of this request. 1767 * 1768 * Response ordering: 1769 * For each session, the implementation must maintain the order of 1770 * responses. That is, if in asynchronous mode, the order of the callback 1771 * functions must match the order of jobs submitted by this function. 1772 * In a simple synchronous mode implementation, the practice of submitting 1773 * a request and blocking on its completion ensure ordering is preserved. 1774 * 1775 * This limitation does not apply if the application employs multiple 1776 * threads to service a single session. 1777 * 1778 * If this API is invoked asynchronous, the return code represents 1779 * the success or not of asynchronously scheduling the request. 1780 * The results of the operation, along with the amount of data consumed 1781 * and produced become available when the callback function is invoked. 1782 * As such, pResults->consumed and pResults->produced are available 1783 * only when the operation is complete. 1784 * 1785 * The application must not use either the source or destination buffers 1786 * until the callback has completed. 1787 * 1788 * @see 1789 * None 1790 * 1791 *****************************************************************************/ 1792 CpaStatus 1793 cpaDcCompressData( CpaInstanceHandle dcInstance, 1794 CpaDcSessionHandle pSessionHandle, 1795 CpaBufferList *pSrcBuff, 1796 CpaBufferList *pDestBuff, 1797 CpaDcRqResults *pResults, 1798 CpaDcFlush flushFlag, 1799 void *callbackTag ); 1800 1801 /** 1802 ***************************************************************************** 1803 * @ingroup cpaDc 1804 * Submit a request to compress a buffer of data. 1805 * 1806 * @description 1807 * This API consumes data from the input buffer and generates compressed 1808 * data in the output buffer. This API is very similar to 1809 * cpaDcCompressData() except it provides a CpaDcOpData structure for 1810 * passing additional input parameters not covered in cpaDcCompressData(). 1811 * 1812 * @context 1813 * When called as an asynchronous function it cannot sleep. It can be 1814 * executed in a context that does not permit sleeping. 1815 * When called as a synchronous function it may sleep. It MUST NOT be 1816 * executed in a context that DOES NOT permit sleeping. 1817 * @assumptions 1818 * None 1819 * @sideEffects 1820 * None 1821 * @blocking 1822 * Yes when configured to operate in synchronous mode. 1823 * @reentrant 1824 * No 1825 * @threadSafe 1826 * Yes 1827 * 1828 * @param[in] dcInstance Target service instance. 1829 * @param[in,out] pSessionHandle Session handle. 1830 * @param[in] pSrcBuff Pointer to data buffer for compression. 1831 * @param[in] pDestBuff Pointer to buffer space for data after 1832 * compression. 1833 * @param[in,out] pOpData Additional parameters. 1834 * @param[in,out] pResults Pointer to results structure 1835 * @param[in] callbackTag User supplied value to help correlate 1836 * the callback with its associated 1837 * request. 1838 * 1839 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1840 * @retval CPA_STATUS_FAIL Function failed. 1841 * @retval CPA_STATUS_RETRY Resubmit the request. 1842 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1843 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1844 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1845 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1846 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1847 * the request. 1848 * 1849 * @pre 1850 * pSessionHandle has been setup using cpaDcInitSession() 1851 * @post 1852 * pSessionHandle has session related state information 1853 * @note 1854 * This function passes control to the compression service for processing 1855 * 1856 * @see 1857 * cpaDcCompressData() 1858 * 1859 *****************************************************************************/ 1860 CpaStatus 1861 cpaDcCompressData2( CpaInstanceHandle dcInstance, 1862 CpaDcSessionHandle pSessionHandle, 1863 CpaBufferList *pSrcBuff, 1864 CpaBufferList *pDestBuff, 1865 CpaDcOpData *pOpData, 1866 CpaDcRqResults *pResults, 1867 void *callbackTag ); 1868 1869 /** 1870 ***************************************************************************** 1871 * @ingroup cpaDc 1872 * Submit a request to compress a buffer of data without requiring a 1873 * session to be created. This is a No-Session (Ns) variant of the 1874 * cpaDcCompressData function. 1875 * 1876 * @description 1877 * This API consumes data from the input buffer and generates compressed 1878 * data in the output buffer. Unlike the other compression APIs this 1879 * does not use a previously created session. This is a "one-shot" API 1880 * that requests can be directly submitted to. 1881 * 1882 * @context 1883 * When called as an asynchronous function it cannot sleep. It can be 1884 * executed in a context that does not permit sleeping. 1885 * When called as a synchronous function it may sleep. It MUST NOT be 1886 * executed in a context that DOES NOT permit sleeping. 1887 * @assumptions 1888 * None 1889 * @sideEffects 1890 * None 1891 * @blocking 1892 * Yes when configured to operate in synchronous mode. 1893 * @reentrant 1894 * No 1895 * @threadSafe 1896 * Yes 1897 * 1898 * @param[in] dcInstance Target service instance. 1899 * @param[in] pSetupData Configuration structure for compression. 1900 * @param[in] pSrcBuff Pointer to data buffer for compression. 1901 * @param[in] pDestBuff Pointer to buffer space for data after 1902 * compression. 1903 * @param[in] pOpData Additional input parameters. 1904 * @param[in,out] pResults Pointer to results structure 1905 * @param[in] callbackFn For synchronous operation this callback 1906 * shall be a null pointer. 1907 * @param[in] callbackTag User supplied value to help correlate 1908 * the callback with its associated 1909 * request. 1910 * 1911 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1912 * @retval CPA_STATUS_FAIL Function failed. 1913 * @retval CPA_STATUS_RETRY Resubmit the request. 1914 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1915 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1916 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1917 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1918 * the request. 1919 * 1920 * @pre 1921 * None 1922 * @post 1923 * None 1924 * @note 1925 * This function passes control to the compression service for processing 1926 * 1927 * Checksum rules. 1928 * The checksum rules are the same as those for the session based APIs 1929 * (cpaDcCompressData or cpaDcCompressData2) with the following exception. 1930 * -# If the algorithm specified is CPA_DC_LZ4 or CPA_DC_LZ4S the xxHash32 1931 * checksum will not be maintained across calls to the API. The 1932 * implication is that the xxHash32 value will only be valid for the 1933 * output of a single request, no state will be saved. If an LZ4 frame is 1934 * required, even in recoverable error scenarios such as CPA_DC_OVERFLOW, 1935 * the checksum will not be continued. If that is required the session 1936 * based API must be used. 1937 * 1938 * @see 1939 * None 1940 * 1941 *****************************************************************************/ 1942 CpaStatus 1943 cpaDcNsCompressData( CpaInstanceHandle dcInstance, 1944 CpaDcNsSetupData *pSetupData, 1945 CpaBufferList *pSrcBuff, 1946 CpaBufferList *pDestBuff, 1947 CpaDcOpData *pOpData, 1948 CpaDcRqResults *pResults, 1949 CpaDcCallbackFn callbackFn, 1950 void *callbackTag ); 1951 /** 1952 ***************************************************************************** 1953 * @ingroup cpaDc 1954 * Submit a request to decompress a buffer of data. 1955 * 1956 * @description 1957 * This API consumes compressed data from the input buffer and generates 1958 * uncompressed data in the output buffer. 1959 * 1960 * @context 1961 * When called as an asynchronous function it cannot sleep. It can be 1962 * executed in a context that does not permit sleeping. 1963 * When called as a synchronous function it may sleep. It MUST NOT be 1964 * executed in a context that DOES NOT permit sleeping. 1965 * @assumptions 1966 * None 1967 * @sideEffects 1968 * None 1969 * @blocking 1970 * Yes when configured to operate in synchronous mode. 1971 * @reentrant 1972 * No 1973 * @threadSafe 1974 * Yes 1975 * 1976 * @param[in] dcInstance Target service instance. 1977 * @param[in,out] pSessionHandle Session handle. 1978 * @param[in] pSrcBuff Pointer to data buffer for compression. 1979 * @param[in] pDestBuff Pointer to buffer space for data 1980 * after decompression. 1981 * @param[in,out] pResults Pointer to results structure 1982 * @param[in] flushFlag When set to CPA_DC_FLUSH_FINAL, indicates 1983 * that the input buffer contains all of 1984 * the data for the compression session, 1985 * allowing the function to release 1986 * history data. 1987 * @param[in] callbackTag User supplied value to help correlate 1988 * the callback with its associated 1989 * request. 1990 * 1991 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1992 * @retval CPA_STATUS_FAIL Function failed. 1993 * @retval CPA_STATUS_RETRY Resubmit the request. 1994 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1995 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1996 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1997 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1998 * the request. 1999 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2000 * 2001 * @pre 2002 * pSessionHandle has been setup using cpaDcInitSession() 2003 * @post 2004 * pSessionHandle has session related state information 2005 * @note 2006 * This function passes control to the compression service for 2007 * decompression. The function returns the status from the service. 2008 * 2009 * This function may be called repetitively with input until all of the 2010 * input has been provided and all the output has been consumed. 2011 * 2012 * This function has identical buffer processing rules as 2013 * cpaDcCompressData(). 2014 * 2015 * This function has identical checksum processing rules as 2016 * cpaDcCompressData(). 2017 * 2018 * The application should set flushFlag to 2019 * CPA_DC_FLUSH_FINAL to indicate processing a particular compressed 2020 * data segment is complete. It should be noted that this function may 2021 * have to be called more than once to process data after flushFlag 2022 * has been set if the destination buffer fills. Refer to 2023 * buffer processing rules in cpaDcCompressData(). 2024 * 2025 * Synchronous or Asynchronous operation of the API is determined by 2026 * the value of the callbackFn parameter passed to cpaDcInitSession() 2027 * when the sessionHandle was setup. If a non-NULL value was specified 2028 * then the supplied callback function will be invoked asynchronously 2029 * with the response of this request, along with the callbackTag 2030 * specified in the function. 2031 * 2032 * The same response ordering constraints identified in the 2033 * cpaDcCompressData API apply to this function. 2034 * 2035 * @see 2036 * cpaDcCompressData() 2037 * 2038 *****************************************************************************/ 2039 CpaStatus 2040 cpaDcDecompressData( CpaInstanceHandle dcInstance, 2041 CpaDcSessionHandle pSessionHandle, 2042 CpaBufferList *pSrcBuff, 2043 CpaBufferList *pDestBuff, 2044 CpaDcRqResults *pResults, 2045 CpaDcFlush flushFlag, 2046 void *callbackTag ); 2047 2048 2049 /** 2050 ***************************************************************************** 2051 * @ingroup cpaDc 2052 * Submit a request to decompress a buffer of data. 2053 * 2054 * @description 2055 * This API consumes compressed data from the input buffer and generates 2056 * uncompressed data in the output buffer. This API is very similar to 2057 * cpaDcDecompressData() except it provides a CpaDcOpData structure for 2058 * passing additional input parameters not covered in cpaDcDecompressData(). 2059 * 2060 * @context 2061 * When called as an asynchronous function it cannot sleep. It can be 2062 * executed in a context that does not permit sleeping. 2063 * When called as a synchronous function it may sleep. It MUST NOT be 2064 * executed in a context that DOES NOT permit sleeping. 2065 * @assumptions 2066 * None 2067 * @sideEffects 2068 * None 2069 * @blocking 2070 * Yes when configured to operate in synchronous mode. 2071 * @reentrant 2072 * No 2073 * @threadSafe 2074 * Yes 2075 * 2076 * @param[in] dcInstance Target service instance. 2077 * @param[in,out] pSessionHandle Session handle. 2078 * @param[in] pSrcBuff Pointer to data buffer for compression. 2079 * @param[in] pDestBuff Pointer to buffer space for data 2080 * after decompression. 2081 * @param[in] pOpData Additional input parameters. 2082 * @param[in,out] pResults Pointer to results structure 2083 * @param[in] callbackTag User supplied value to help correlate 2084 * the callback with its associated 2085 * request. 2086 * 2087 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2088 * @retval CPA_STATUS_FAIL Function failed. 2089 * @retval CPA_STATUS_RETRY Resubmit the request. 2090 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2091 * @retval CPA_STATUS_RESOURCE Error related to system resources. 2092 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 2093 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2094 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2095 * the request. 2096 * 2097 * @pre 2098 * pSessionHandle has been setup using cpaDcInitSession() 2099 * @post 2100 * pSessionHandle has session related state information 2101 * @note 2102 * This function passes control to the compression service for 2103 * decompression. The function returns the status from the service. 2104 * 2105 * @see 2106 * cpaDcDecompressData() 2107 * cpaDcCompressData2() 2108 * cpaDcCompressData() 2109 * 2110 *****************************************************************************/ 2111 CpaStatus 2112 cpaDcDecompressData2( CpaInstanceHandle dcInstance, 2113 CpaDcSessionHandle pSessionHandle, 2114 CpaBufferList *pSrcBuff, 2115 CpaBufferList *pDestBuff, 2116 CpaDcOpData *pOpData, 2117 CpaDcRqResults *pResults, 2118 void *callbackTag ); 2119 2120 /** 2121 ***************************************************************************** 2122 * @ingroup cpaDc 2123 * Submit a request to decompress a buffer of data without requiring a 2124 * session to be created. This is a No-Session (Ns) variant of the 2125 * cpaDcDecompressData function. 2126 * 2127 * @description 2128 * This API consumes data from the input buffer and generates decompressed 2129 * data in the output buffer. Unlike the other decompression APIs this 2130 * does not use a previously created session. This is a "one-shot" API 2131 * that requests can be directly submitted to. 2132 * 2133 * @context 2134 * When called as an asynchronous function it cannot sleep. It can be 2135 * executed in a context that does not permit sleeping. 2136 * When called as a synchronous function it may sleep. It MUST NOT be 2137 * executed in a context that DOES NOT permit sleeping. 2138 * @assumptions 2139 * None 2140 * @sideEffects 2141 * None 2142 * @blocking 2143 * Yes when configured to operate in synchronous mode. 2144 * @reentrant 2145 * No 2146 * @threadSafe 2147 * Yes 2148 * 2149 * @param[in] dcInstance Target service instance. 2150 * @param[in] pSetupData Configuration structure for decompression.. 2151 * @param[in] pSrcBuff Pointer to data buffer for decompression. 2152 * @param[in] pDestBuff Pointer to buffer space for data 2153 * after decompression. 2154 * @param[in] pOpData Additional input parameters. 2155 * @param[in,out] pResults Pointer to results structure 2156 * @param[in] callbackFn For synchronous operation this callback 2157 * shall be a null pointer. 2158 * @param[in] callbackTag User supplied value to help correlate 2159 * the callback with its associated 2160 * request. 2161 * 2162 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2163 * @retval CPA_STATUS_FAIL Function failed. 2164 * @retval CPA_STATUS_RETRY Resubmit the request. 2165 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2166 * @retval CPA_STATUS_RESOURCE Error related to system resources. 2167 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2168 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2169 * the request. 2170 * 2171 * @pre 2172 * None 2173 * @post 2174 * None 2175 * @note 2176 * This function passes control to the decompression service. The function 2177 * returns the status from the service. 2178 * 2179 * @see 2180 * cpaDcDecompressData() 2181 * cpaDcCompressData2() 2182 * cpaDcCompressData() 2183 * 2184 *****************************************************************************/ 2185 CpaStatus 2186 cpaDcNsDecompressData( CpaInstanceHandle dcInstance, 2187 CpaDcNsSetupData *pSetupData, 2188 CpaBufferList *pSrcBuff, 2189 CpaBufferList *pDestBuff, 2190 CpaDcOpData *pOpData, 2191 CpaDcRqResults *pResults, 2192 CpaDcCallbackFn callbackFn, 2193 void *callbackTag ); 2194 2195 /** 2196 ***************************************************************************** 2197 * @ingroup cpaDc 2198 * Generate compression header. 2199 * 2200 * @description 2201 * This function generates the gzip header, zlib header or LZ4 frame 2202 * header and stores it in the destination buffer. The type of header 2203 * created is determined using the compression algorithm selected using 2204 * CpaDcSessionSetupData.compType, for the session associated with the 2205 * session handle. 2206 * 2207 * @context 2208 * This function may be call from any context. 2209 * @assumptions 2210 * None 2211 * @sideEffects 2212 * None 2213 * @blocking 2214 * No 2215 * @reentrant 2216 * No 2217 * @threadSafe 2218 * Yes 2219 * 2220 * @param[in] pSessionHandle Session handle. 2221 * @param[in] pDestBuff Pointer to data buffer where the 2222 * compression header will go. 2223 * @param[out] count Pointer to counter filled in with 2224 * header size. 2225 * 2226 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2227 * @retval CPA_STATUS_FAIL Function failed. 2228 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2229 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2230 * the request. 2231 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2232 * 2233 * @pre 2234 * pSessionHandle has been setup using cpaDcInitSession() 2235 * 2236 * @note 2237 * When the deflate compression algorithm is used, this function can output 2238 * a 10 byte gzip header or 2 byte zlib header to the destination buffer. 2239 * The session properties are used to determine the header type. To 2240 * output a Gzip or a Zlib header the session must have been initialized 2241 * with CpaDcCompType CPA_DC_DEFLATE. 2242 * To output a gzip header the session must have been initialized with 2243 * CpaDcChecksum CPA_DC_CRC32. To output a zlib header the session must 2244 * have been initialized with CpaDcChecksum CPA_DC_ADLER32. 2245 * For CpaDcChecksum CPA_DC_NONE no header is output. 2246 * 2247 * If the compression requires a gzip header, then this header requires 2248 * at a minimum the following fields, defined in RFC1952: 2249 * ID1: 0x1f 2250 * ID2: 0x8b 2251 * CM: Compression method = 8 for deflate 2252 * 2253 * The zlib header is defined in RFC1950 and this function must implement 2254 * as a minimum: 2255 * CM: four bit compression method - 8 is deflate with window size to 2256 * 32k 2257 * CINFO: four bit window size (see RFC1950 for details), 7 is 32k 2258 * window 2259 * FLG: defined as: 2260 * - Bits 0 - 4: check bits for CM, CINFO and FLG (see RFC1950) 2261 * - Bit 5: FDICT 0 = default, 1 is preset dictionary 2262 * - Bits 6 - 7: FLEVEL, compression level (see RFC 1950) 2263 * 2264 * When LZ4 algorithm is used, this function can output a 7 byte frame 2265 * header. This function will set the LZ4 frame header with: 2266 * - Magic number 0x184D2204 2267 * - The LZ4 max block size defined in the CpaDcSessionSetupData 2268 * - Flag byte as: 2269 * * Version = 1 2270 * * Block independence = 0 2271 * * Block checksum = 0 2272 * * Content size present = 0 2273 * * Content checksum present = 1 2274 * * Dictionary ID present = 0 2275 * - Content size = 0 2276 * - Dictionary ID = 0 2277 * - Header checksum = 1 byte representing the second byte of the 2278 * XXH32 of the frame decriptor field. 2279 * 2280 * The counter parameter will be set to the number of bytes added to the 2281 * buffer. The pData will be not be changed. 2282 * 2283 * For any of the compression algorithms used, the application is 2284 * responsible to offset the pData pointer in CpaBufferList by the length 2285 * of the header before calling the CpaDcCompressData() or 2286 * CpaDcCompressData2() functions. 2287 * @see 2288 * None 2289 * 2290 *****************************************************************************/ 2291 CpaStatus 2292 cpaDcGenerateHeader( CpaDcSessionHandle pSessionHandle, 2293 CpaFlatBuffer *pDestBuff, Cpa32U *count ); 2294 2295 /** 2296 ***************************************************************************** 2297 * @ingroup cpaDc 2298 * Generate compression footer. 2299 * 2300 * @description 2301 * This function generates the footer for gzip, zlib or LZ4. 2302 * The generated footer is stored it in the destination buffer. 2303 * The type of footer created is determined using the compression 2304 * algorithm selected for the session associated with the session handle. 2305 * 2306 * @context 2307 * This function may be call from any context. 2308 * @assumptions 2309 * None 2310 * @sideEffects 2311 * All session variables are reset 2312 * @blocking 2313 * No 2314 * @reentrant 2315 * No 2316 * @threadSafe 2317 * Yes 2318 * 2319 * @param[in,out] pSessionHandle Session handle. 2320 * @param[in] pDestBuff Pointer to data buffer where the 2321 * compression footer will go. 2322 * @param[in,out] pResults Pointer to results structure filled by 2323 * CpaDcCompressData. Updated with the 2324 * results of this API call 2325 * 2326 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2327 * @retval CPA_STATUS_FAIL Function failed. 2328 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2329 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2330 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2331 * the request. 2332 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2333 * 2334 * @pre 2335 * pSessionHandle has been setup using cpaDcInitSession() 2336 * pResults structure has been filled by CpaDcCompressData(). 2337 * 2338 * @note 2339 * Depending on the session variables, this function can add the 2340 * alder32 footer to the zlib compressed data as defined in RFC1950. 2341 * If required, it can also add the gzip footer, which is the crc32 of the 2342 * uncompressed data and the length of the uncompressed data. 2343 * This section is defined in RFC1952. The session variables used to 2344 * determine the header type are CpaDcCompType and CpaDcChecksum, see 2345 * cpaDcGenerateHeader for more details. 2346 * 2347 * For LZ4 compression, this function adds the LZ4 frame footer 2348 * using XXH32 algorithm of the uncompressed data. The XXH32 checksum is 2349 * added after the end mark. This section is defined in the documentation 2350 * of the LZ4 frame format at: 2351 * https://github.com/lz4/lz4/blob/dev/doc/lz4_Frame_format.md 2352 * 2353 * An artifact of invoking this function for writing the footer data is 2354 * that all opaque session specific data is re-initialized. If the 2355 * compression level and file types are consistent, the upper level 2356 * application can continue processing compression requests using the 2357 * same session handle. 2358 * 2359 * The produced element of the pResults structure will be incremented by 2360 * the numbers bytes added to the buffer. The pointer to the buffer will 2361 * not be modified. It is necessary for the application to ensure that 2362 * there is always sufficient memory in the destination buffer to append 2363 * the footer. In the event that the destination buffer would be too small 2364 * to accept the footer, overflow will not be reported. 2365 * 2366 * @see 2367 * None 2368 * 2369 *****************************************************************************/ 2370 CpaStatus 2371 cpaDcGenerateFooter( CpaDcSessionHandle pSessionHandle, 2372 CpaFlatBuffer *pDestBuff, 2373 CpaDcRqResults *pResults ); 2374 2375 2376 /** 2377 ***************************************************************************** 2378 * @ingroup cpaDc 2379 * Generate compression header without requiring a session to be created. 2380 * This is a No-Session (Ns) variant of the cpaDcGenerateHeader function. 2381 * 2382 * @description 2383 * This API generates the required compression format header and stores it 2384 * in the output buffer. 2385 * 2386 * @context 2387 * This function may be called from any context. 2388 * @assumptions 2389 * None 2390 * @sideEffects 2391 * None 2392 * @blocking 2393 * No 2394 * @reentrant 2395 * No 2396 * @threadSafe 2397 * Yes 2398 * 2399 * @param[in] pSetupData Pointer to Ns Configuration structure. 2400 * @param[in] pDestBuff Pointer to data buffer where the 2401 * compression header will go. 2402 * @param[out] count Pointer to counter filled in with 2403 * header size. 2404 * 2405 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2406 * @retval CPA_STATUS_FAIL Function failed. 2407 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2408 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2409 * the request. 2410 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2411 * 2412 * @pre 2413 * None 2414 * 2415 * @note 2416 * This function outputs the required compression format header to 2417 * the destination buffer. The CpaDcNsSetupData structure fields are used to 2418 * determine the header type. 2419 * 2420 * To output an LZ4 header the structure must have been initialized with 2421 * with CpaDcCompType CPA_DC_LZ4. 2422 * To output a gzip or zlib header the structure must have been initialized 2423 * with CpaDcCompType CPA_DC_DEFLATE. 2424 * To output a gzip header the structure must have been initialized with 2425 * CpaDcChecksum CPA_DC_CRC32. 2426 * To output a zlib header the structure must have been initialized with 2427 * CpaDcChecksum CPA_DC_ADLER32. 2428 * For CpaDcChecksum CPA_DC_NONE no header is output. 2429 * 2430 * The counter parameter will be set to the number of bytes added to the 2431 * buffer. 2432 * 2433 * @see 2434 * cpaDcGenerateHeader 2435 * 2436 *****************************************************************************/ 2437 CpaStatus 2438 cpaDcNsGenerateHeader( CpaDcNsSetupData *pSetupData, 2439 CpaFlatBuffer *pDestBuff, 2440 Cpa32U *count ); 2441 2442 /** 2443 ***************************************************************************** 2444 * @ingroup cpaDc 2445 * Generate compression footer without requiring a session to be created. 2446 * This is a No-Session (Ns) variant of the cpaDcGenerateFooter function. 2447 * 2448 * @description 2449 * This API generates the footer for the required format and stores it in 2450 * the destination buffer. 2451 * @context 2452 * This function may be call from any context. 2453 * @assumptions 2454 * None 2455 * @sideEffects 2456 * All session variables are reset 2457 * @blocking 2458 * No 2459 * @reentrant 2460 * No 2461 * @threadSafe 2462 * Yes 2463 * 2464 * @param[in] pSetupData Pointer to Ns Configuration structure. 2465 * @param[in] totalLength Total accumulated length of input data 2466 * processed. See description for formats 2467 * that make use of this parameter. 2468 * @param[in] pDestBuff Pointer to data buffer where the 2469 * compression footer will go. 2470 * @param[in,out] pResults Pointer to results structure filled by 2471 * CpaDcNsCompressData. Updated with the 2472 * results of this API call 2473 * 2474 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2475 * @retval CPA_STATUS_FAIL Function failed. 2476 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2477 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2478 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2479 * the request. 2480 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2481 * 2482 * @pre 2483 * pResults structure has been filled by CpaDcNsCompressData(). 2484 * 2485 * @note 2486 * This function outputs the required compression format footer to 2487 * the destination buffer. The CpaDcNsSetupData structure fields are used to 2488 * determine the footer type created. 2489 * 2490 * To output an LZ4 footer the structure must have been initialized with 2491 * with CpaDcCompType CPA_DC_LZ4. 2492 * To output a gzip or zlib footer the structure must have been initialized 2493 * with CpaDcCompType CPA_DC_DEFLATE. 2494 * To output a gzip footer the structure must have been initialized with 2495 * CpaDcChecksum CPA_DC_CRC32 and the totalLength parameter initialized to 2496 * the total accumulated length of data processed. 2497 * To output a zlib footer the structure must have been initialized with 2498 * CpaDcChecksum CPA_DC_ADLER32. 2499 * For CpaDcChecksum CPA_DC_NONE no footer is output. 2500 * 2501 * The produced element of the pResults structure will be incremented by the 2502 * number of bytes added to the buffer. The pointer to the buffer 2503 * will not be modified. 2504 * 2505 * @see 2506 * CpaDcNsSetupData 2507 * cpaDcNsGenerateHeader 2508 * cpaDcGenerateFooter 2509 * 2510 *****************************************************************************/ 2511 CpaStatus 2512 cpaDcNsGenerateFooter( CpaDcNsSetupData *pSetupData, 2513 Cpa64U totalLength, 2514 CpaFlatBuffer *pDestBuff, 2515 CpaDcRqResults *pResults ); 2516 2517 2518 /** 2519 ***************************************************************************** 2520 * @ingroup cpaDc 2521 * Retrieve statistics 2522 * 2523 * @description 2524 * This API retrieves the current statistics for a compression instance. 2525 * 2526 * @context 2527 * This function may be call from any context. 2528 * @assumptions 2529 * None 2530 * @sideEffects 2531 * None 2532 * @blocking 2533 * Yes 2534 * @reentrant 2535 * No 2536 * @threadSafe 2537 * Yes 2538 * 2539 * @param[in] dcInstance Instance handle. 2540 * @param[out] pStatistics Pointer to statistics structure. 2541 * 2542 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2543 * @retval CPA_STATUS_FAIL Function failed. 2544 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2545 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 2546 * the request. 2547 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2548 * 2549 * @pre 2550 * None 2551 * @post 2552 * None 2553 * 2554 * @see 2555 * None 2556 * 2557 *****************************************************************************/ 2558 CpaStatus 2559 cpaDcGetStats( CpaInstanceHandle dcInstance, 2560 CpaDcStats *pStatistics ); 2561 2562 /*****************************************************************************/ 2563 /* Instance Discovery Functions */ 2564 2565 /** 2566 ***************************************************************************** 2567 * @ingroup cpaDc 2568 * Get the number of device instances that are supported by the API 2569 * implementation. 2570 * 2571 * @description 2572 * 2573 * This function will get the number of device instances that are supported 2574 * by an implementation of the compression API. This number is then used to 2575 * determine the size of the array that must be passed to 2576 * cpaDcGetInstances(). 2577 * 2578 * @context 2579 * This function MUST NOT be called from an interrupt context as it MAY 2580 * sleep. 2581 * @assumptions 2582 * None 2583 * @sideEffects 2584 * None 2585 * @blocking 2586 * This function is synchronous and blocking. 2587 * @reentrant 2588 * No 2589 * @threadSafe 2590 * Yes 2591 * 2592 * @param[out] pNumInstances Pointer to where the number of 2593 * instances will be written. 2594 * 2595 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2596 * @retval CPA_STATUS_FAIL Function failed. 2597 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2598 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2599 * 2600 * @pre 2601 * None 2602 * @post 2603 * None 2604 * @note 2605 * This function operates in a synchronous manner and no asynchronous 2606 * callback will be generated 2607 * 2608 * @see 2609 * cpaDcGetInstances 2610 * 2611 *****************************************************************************/ 2612 CpaStatus 2613 cpaDcGetNumInstances(Cpa16U* pNumInstances); 2614 2615 /** 2616 ***************************************************************************** 2617 * @ingroup cpaDc 2618 * Get the handles to the device instances that are supported by the 2619 * API implementation. 2620 * 2621 * @description 2622 * 2623 * This function will return handles to the device instances that are 2624 * supported by an implementation of the compression API. These instance 2625 * handles can then be used as input parameters with other compression API 2626 * functions. 2627 * 2628 * This function will populate an array that has been allocated by the 2629 * caller. The size of this API is determined by the 2630 * cpaDcGetNumInstances() function. 2631 * 2632 * @context 2633 * This function MUST NOT be called from an interrupt context as it MAY 2634 * sleep. 2635 * @assumptions 2636 * None 2637 * @sideEffects 2638 * None 2639 * @blocking 2640 * This function is synchronous and blocking. 2641 * @reentrant 2642 * No 2643 * @threadSafe 2644 * Yes 2645 * 2646 * @param[in] numInstances Size of the array. 2647 * @param[out] dcInstances Pointer to where the instance 2648 * handles will be written. 2649 * 2650 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2651 * @retval CPA_STATUS_FAIL Function failed. 2652 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2653 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2654 * 2655 * @pre 2656 * None 2657 * @post 2658 * None 2659 * @note 2660 * This function operates in a synchronous manner and no asynchronous 2661 * callback will be generated 2662 * 2663 * @see 2664 * cpaDcGetInstances 2665 * 2666 *****************************************************************************/ 2667 CpaStatus 2668 cpaDcGetInstances(Cpa16U numInstances, 2669 CpaInstanceHandle* dcInstances); 2670 2671 /** 2672 ***************************************************************************** 2673 * @ingroup cpaDc 2674 * Compression Component utility function to determine the number of 2675 * intermediate buffers required by an implementation. 2676 * 2677 * @description 2678 * This function will determine the number of intermediate buffer lists 2679 * required by an implementation for a compression instance. These buffers 2680 * should then be allocated and provided when calling @ref cpaDcStartInstance() 2681 * to start a compression instance that will use dynamic compression. 2682 * 2683 * @context 2684 * This function may sleep, and MUST NOT be called in interrupt context. 2685 * @assumptions 2686 * None 2687 * @sideEffects 2688 * None 2689 * @blocking 2690 * This function is synchronous and blocking. 2691 * @reentrant 2692 * No 2693 * @threadSafe 2694 * Yes 2695 * @param[in,out] instanceHandle Handle to an instance of this API to be 2696 * initialized. 2697 * @param[out] pNumBuffers When the function returns, this will 2698 * specify the number of buffer lists that 2699 * should be used as intermediate buffers 2700 * when calling cpaDcStartInstance(). 2701 * 2702 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2703 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 2704 * is to shutdown and restart. 2705 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2706 * 2707 * @pre 2708 * None 2709 * @post 2710 * None 2711 * @note 2712 * Note that this is a synchronous function and has no completion callback 2713 * associated with it. 2714 * 2715 * @see 2716 * cpaDcStartInstance() 2717 * 2718 *****************************************************************************/ 2719 CpaStatus 2720 cpaDcGetNumIntermediateBuffers(CpaInstanceHandle instanceHandle, 2721 Cpa16U *pNumBuffers); 2722 2723 /** 2724 ***************************************************************************** 2725 * @ingroup cpaDc 2726 * Compression Component Initialization and Start function. 2727 * 2728 * @description 2729 * This function will initialize and start the compression component. 2730 * It MUST be called before any other compress function is called. This 2731 * function SHOULD be called only once (either for the very first time, 2732 * or after an cpaDcStopInstance call which succeeded) per instance. 2733 * Subsequent calls will have no effect. 2734 * 2735 * If required by an implementation, this function can be provided with 2736 * instance specific intermediate buffers. The intent is to provide an 2737 * instance specific location to store intermediate results during dynamic 2738 * instance Huffman tree compression requests. The memory should be 2739 * accessible by the compression engine. The buffers are to support 2740 * deflate compression with dynamic Huffman Trees. Each buffer list 2741 * should be similar in size to twice the destination buffer size passed 2742 * to the compress API. The number of intermediate buffer lists may vary 2743 * between implementations and so @ref cpaDcGetNumIntermediateBuffers() 2744 * should be called first to determine the number of intermediate 2745 * buffers required by the implementation. 2746 * 2747 * If not required, this parameter can be passed in as NULL. 2748 * 2749 * @context 2750 * This function may sleep, and MUST NOT be called in interrupt context. 2751 * @assumptions 2752 * None 2753 * @sideEffects 2754 * None 2755 * @blocking 2756 * This function is synchronous and blocking. 2757 * @reentrant 2758 * No 2759 * @threadSafe 2760 * Yes 2761 * @param[in,out] instanceHandle Handle to an instance of this API to be 2762 * initialized. 2763 * @param[in] numBuffers Number of buffer lists represented by 2764 * the pIntermediateBuffers parameter. 2765 * Note: @ref cpaDcGetNumIntermediateBuffers() 2766 * can be used to determine the number of 2767 * intermediate buffers that an implementation 2768 * requires. 2769 * @param[in] pIntermediateBuffers Optional pointer to Instance specific 2770 * DRAM buffer. 2771 * 2772 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2773 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 2774 * is to shutdown and restart. 2775 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2776 * 2777 * @pre 2778 * None 2779 * @post 2780 * None 2781 * @note 2782 * Note that this is a synchronous function and has no completion callback 2783 * associated with it. 2784 * 2785 * @see 2786 * cpaDcStopInstance() 2787 * cpaDcGetNumIntermediateBuffers() 2788 * 2789 *****************************************************************************/ 2790 CpaStatus 2791 cpaDcStartInstance(CpaInstanceHandle instanceHandle, 2792 Cpa16U numBuffers, 2793 CpaBufferList **pIntermediateBuffers); 2794 2795 /** 2796 ***************************************************************************** 2797 * @ingroup cpaDc 2798 * Compress Component Stop function. 2799 * 2800 * @description 2801 * This function will stop the Compression component and free 2802 * all system resources associated with it. The client MUST ensure that 2803 * all outstanding operations have completed before calling this function. 2804 * The recommended approach to ensure this is to deregister all session or 2805 * callback handles before calling this function. If outstanding 2806 * operations still exist when this function is invoked, the callback 2807 * function for each of those operations will NOT be invoked and the 2808 * shutdown will continue. If the component is to be restarted, then a 2809 * call to cpaDcStartInstance is required. 2810 * 2811 * @context 2812 * This function may sleep, and so MUST NOT be called in interrupt 2813 * context. 2814 * @assumptions 2815 * None 2816 * @sideEffects 2817 * None 2818 * @blocking 2819 * This function is synchronous and blocking. 2820 * @reentrant 2821 * No 2822 * @threadSafe 2823 * Yes 2824 * @param[in] instanceHandle Handle to an instance of this API to be 2825 * shutdown. 2826 * 2827 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2828 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 2829 * is to ensure requests are not still being 2830 * submitted and that all sessions are 2831 * deregistered. If this does not help, then 2832 * forcefully remove the component from the 2833 * system. 2834 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2835 * 2836 * @pre 2837 * The component has been initialized via cpaDcStartInstance 2838 * @post 2839 * None 2840 * @note 2841 * Note that this is a synchronous function and has no completion callback 2842 * associated with it. 2843 * 2844 * @see 2845 * cpaDcStartInstance() 2846 * 2847 *****************************************************************************/ 2848 CpaStatus 2849 cpaDcStopInstance(CpaInstanceHandle instanceHandle); 2850 2851 2852 /** 2853 ***************************************************************************** 2854 * @ingroup cpaDc 2855 * Function to get information on a particular instance. 2856 * 2857 * @description 2858 * This function will provide instance specific information through a 2859 * @ref CpaInstanceInfo2 structure. 2860 * 2861 * @context 2862 * This function will be executed in a context that requires that sleeping 2863 * MUST NOT be permitted. 2864 * @assumptions 2865 * None 2866 * @sideEffects 2867 * None 2868 * @blocking 2869 * Yes 2870 * @reentrant 2871 * No 2872 * @threadSafe 2873 * Yes 2874 * 2875 * @param[in] instanceHandle Handle to an instance of this API to be 2876 * initialized. 2877 * @param[out] pInstanceInfo2 Pointer to the memory location allocated by 2878 * the client into which the CpaInstanceInfo2 2879 * structure will be written. 2880 * 2881 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2882 * @retval CPA_STATUS_FAIL Function failed. 2883 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2884 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2885 * 2886 * @pre 2887 * The client has retrieved an instanceHandle from successive calls to 2888 * @ref cpaDcGetNumInstances and @ref cpaDcGetInstances. 2889 * @post 2890 * None 2891 * @note 2892 * None 2893 * @see 2894 * cpaDcGetNumInstances, 2895 * cpaDcGetInstances, 2896 * CpaInstanceInfo2 2897 * 2898 *****************************************************************************/ 2899 CpaStatus 2900 cpaDcInstanceGetInfo2(const CpaInstanceHandle instanceHandle, 2901 CpaInstanceInfo2 * pInstanceInfo2); 2902 2903 /*****************************************************************************/ 2904 /* Instance Notification Functions */ 2905 /*****************************************************************************/ 2906 /** 2907 ***************************************************************************** 2908 * @ingroup cpaDc 2909 * Callback function for instance notification support. 2910 * 2911 * @description 2912 * This is the prototype for the instance notification callback function. 2913 * The callback function is passed in as a parameter to the 2914 * @ref cpaDcInstanceSetNotificationCb function. 2915 * 2916 * @context 2917 * This function will be executed in a context that requires that sleeping 2918 * MUST NOT be permitted. 2919 * @assumptions 2920 * None 2921 * @sideEffects 2922 * None 2923 * @blocking 2924 * No 2925 * @reentrant 2926 * No 2927 * @threadSafe 2928 * Yes 2929 * 2930 * @param[in] instanceHandle Instance handle. 2931 * @param[in] pCallbackTag Opaque value provided by user while making 2932 * individual function calls. 2933 * @param[in] instanceEvent The event that will trigger this function to 2934 * get invoked. 2935 * 2936 * @retval 2937 * None 2938 * @pre 2939 * Component has been initialized and the notification function has been 2940 * set via the cpaDcInstanceSetNotificationCb function. 2941 * @post 2942 * None 2943 * @note 2944 * None 2945 * @see 2946 * cpaDcInstanceSetNotificationCb(), 2947 * 2948 *****************************************************************************/ 2949 typedef void (*CpaDcInstanceNotificationCbFunc)( 2950 const CpaInstanceHandle instanceHandle, 2951 void * pCallbackTag, 2952 const CpaInstanceEvent instanceEvent); 2953 2954 /** 2955 ***************************************************************************** 2956 * @ingroup cpaDc 2957 * Subscribe for instance notifications. 2958 * 2959 * @description 2960 * Clients of the CpaDc interface can subscribe for instance notifications 2961 * by registering a @ref CpaDcInstanceNotificationCbFunc function. 2962 * 2963 * @context 2964 * This function may be called from any context. 2965 * @assumptions 2966 * None 2967 * @sideEffects 2968 * None 2969 * @blocking 2970 * No 2971 * @reentrant 2972 * No 2973 * @threadSafe 2974 * Yes 2975 * 2976 * @param[in] instanceHandle Instance handle. 2977 * @param[in] pInstanceNotificationCb Instance notification callback 2978 * function pointer. 2979 * @param[in] pCallbackTag Opaque value provided by user while 2980 * making individual function calls. 2981 * 2982 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2983 * @retval CPA_STATUS_FAIL Function failed. 2984 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2985 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2986 * 2987 * @pre 2988 * Instance has been initialized. 2989 * @post 2990 * None 2991 * @note 2992 * None 2993 * @see 2994 * CpaDcInstanceNotificationCbFunc 2995 * 2996 *****************************************************************************/ 2997 CpaStatus 2998 cpaDcInstanceSetNotificationCb( 2999 const CpaInstanceHandle instanceHandle, 3000 const CpaDcInstanceNotificationCbFunc pInstanceNotificationCb, 3001 void *pCallbackTag); 3002 3003 3004 /** 3005 ***************************************************************************** 3006 * @ingroup cpaDc 3007 * Get the size of the memory required to hold the session information. 3008 * 3009 * @description 3010 * 3011 * The client of the Data Compression API is responsible for 3012 * allocating sufficient memory to hold session information and the context 3013 * data. This function provides a means for determining the size of the 3014 * session information and the size of the context data. 3015 * 3016 * @context 3017 * No restrictions 3018 * @assumptions 3019 * None 3020 * @sideEffects 3021 * None 3022 * @blocking 3023 * No 3024 * @reentrant 3025 * No 3026 * @threadSafe 3027 * Yes 3028 * 3029 * @param[in] dcInstance Instance handle. 3030 * @param[in] pSessionData Pointer to a user instantiated structure 3031 * containing session data. 3032 * @param[out] pSessionSize On return, this parameter will be the size 3033 * of the memory that will be 3034 * required by cpaDcInitSession() for session 3035 * data. 3036 * @param[out] pContextSize On return, this parameter will be the size 3037 * of the memory that will be required 3038 * for context data. Context data is 3039 * save/restore data including history and 3040 * any implementation specific data that is 3041 * required for a save/restore operation. 3042 * 3043 * @retval CPA_STATUS_SUCCESS Function executed successfully. 3044 * @retval CPA_STATUS_FAIL Function failed. 3045 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 3046 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 3047 * 3048 * @pre 3049 * None 3050 * @post 3051 * None 3052 * @note 3053 * Only a synchronous version of this function is provided. 3054 * 3055 * It is expected that context data is comprised of the history and 3056 * any data stores that are specific to the history such as linked 3057 * lists or hash tables. 3058 * For stateless sessions the context size returned from this function 3059 * will be zero. For stateful sessions the context size returned will 3060 * depend on the session setup data and may be zero. 3061 * 3062 * Session data is expected to include interim checksum values, various 3063 * counters and other session related data that needs to persist 3064 * between invocations. 3065 * For a given implementation of this API, it is safe to assume that 3066 * cpaDcGetSessionSize() will always return the same session size and 3067 * that the size will not be different for different setup data 3068 * parameters. However, it should be noted that the size may change: 3069 * (1) between different implementations of the API (e.g. between software 3070 * and hardware implementations or between different hardware 3071 * implementations) 3072 * (2) between different releases of the same API implementation. 3073 * 3074 * @see 3075 * cpaDcInitSession() 3076 * 3077 *****************************************************************************/ 3078 CpaStatus 3079 cpaDcGetSessionSize(CpaInstanceHandle dcInstance, 3080 CpaDcSessionSetupData* pSessionData, 3081 Cpa32U* pSessionSize, Cpa32U* pContextSize ); 3082 3083 /** 3084 ***************************************************************************** 3085 * @ingroup cpaDc 3086 * Function to return the size of the memory which must be allocated for 3087 * the pPrivateMetaData member of CpaBufferList. 3088 * 3089 * @description 3090 * This function is used to obtain the size (in bytes) required to allocate 3091 * a buffer descriptor for the pPrivateMetaData member in the 3092 * CpaBufferList structure. 3093 * Should the function return zero then no meta data is required for the 3094 * buffer list. 3095 * 3096 * @context 3097 * This function may be called from any context. 3098 * @assumptions 3099 * None 3100 * @sideEffects 3101 * None 3102 * @blocking 3103 * No 3104 * @reentrant 3105 * No 3106 * @threadSafe 3107 * Yes 3108 * 3109 * @param[in] instanceHandle Handle to an instance of this API. 3110 * @param[in] numBuffers The number of pointers in the CpaBufferList. 3111 * This is the maximum number of CpaFlatBuffers 3112 * which may be contained in this CpaBufferList. 3113 * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be 3114 * allocated when the client wishes to allocate 3115 * a cpaFlatBuffer. 3116 * 3117 * @retval CPA_STATUS_SUCCESS Function executed successfully. 3118 * @retval CPA_STATUS_FAIL Function failed. 3119 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 3120 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 3121 * 3122 * @pre 3123 * None 3124 * @post 3125 * None 3126 * @note 3127 * None 3128 * @see 3129 * cpaDcGetInstances() 3130 * 3131 *****************************************************************************/ 3132 CpaStatus 3133 cpaDcBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, 3134 Cpa32U numBuffers, 3135 Cpa32U *pSizeInBytes); 3136 3137 3138 /** 3139 ***************************************************************************** 3140 * @ingroup cpaDc 3141 * Function to return a string indicating the specific error that occurred 3142 * within the system. 3143 * 3144 * @description 3145 * When a function returns any error including CPA_STATUS_SUCCESS, the 3146 * client can invoke this function to get a string which describes the 3147 * general error condition, and if available additional information on 3148 * the specific error. 3149 * The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for the buffer 3150 * string. 3151 * 3152 * @context 3153 * This function may be called from any context. 3154 * @assumptions 3155 * None 3156 * @sideEffects 3157 * None 3158 * @blocking 3159 * No 3160 * @reentrant 3161 * No 3162 * @threadSafe 3163 * Yes 3164 * 3165 * @param[in] dcInstance Handle to an instance of this API. 3166 * @param[in] errStatus The error condition that occurred. 3167 * @param[in,out] pStatusText Pointer to the string buffer that will 3168 * be updated with the status text. The invoking 3169 * application MUST allocate this buffer to be 3170 * exactly CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. 3171 * 3172 * @retval CPA_STATUS_SUCCESS Function executed successfully. 3173 * @retval CPA_STATUS_FAIL Function failed. Note, in this scenario 3174 * it is INVALID to call this function a 3175 * second time. 3176 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 3177 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 3178 * 3179 * @pre 3180 * None 3181 * @post 3182 * None 3183 * @note 3184 * None 3185 * @see 3186 * CpaStatus 3187 * 3188 *****************************************************************************/ 3189 3190 CpaStatus 3191 cpaDcGetStatusText(const CpaInstanceHandle dcInstance, 3192 const CpaStatus errStatus, 3193 Cpa8S * pStatusText); 3194 3195 3196 /** 3197 ***************************************************************************** 3198 * @ingroup cpaDc 3199 * Set Address Translation function 3200 * 3201 * @description 3202 * This function is used to set the virtual to physical address 3203 * translation routine for the instance. The specified routine 3204 * is used by the instance to perform any required translation of 3205 * a virtual address to a physical address. If the application 3206 * does not invoke this function, then the instance will use its 3207 * default method, such as virt2phys, for address translation. 3208 * 3209 * @assumptions 3210 * None 3211 * @sideEffects 3212 * None 3213 * @blocking 3214 * This function is synchronous and blocking. 3215 * @reentrant 3216 * No 3217 * @threadSafe 3218 * Yes 3219 * 3220 * @param[in] instanceHandle Data Compression API instance handle. 3221 * @param[in] virtual2Physical Routine that performs virtual to 3222 * physical address translation. 3223 * @retval CPA_STATUS_SUCCESS Function executed successfully. 3224 * @retval CPA_STATUS_FAIL Function failed. 3225 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 3226 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 3227 * 3228 * @pre 3229 * None 3230 * @post 3231 * None 3232 * @see 3233 * None 3234 * 3235 *****************************************************************************/ 3236 CpaStatus 3237 cpaDcSetAddressTranslation(const CpaInstanceHandle instanceHandle, 3238 CpaVirtualToPhysical virtual2Physical); 3239 #ifdef __cplusplus 3240 } /* close the extern "C" { */ 3241 #endif 3242 3243 #endif /* CPA_DC_H */ 3244