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