1 /**************************************************************************** 2 * 3 * BSD LICENSE 4 * 5 * Copyright(c) 2007-2022 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 * @remarks 54 * 55 * 56 *****************************************************************************/ 57 58 #ifndef CPA_DC_H 59 #define CPA_DC_H 60 61 #ifdef __cplusplus 62 extern"C" { 63 #endif 64 65 66 #ifndef CPA_H 67 #include "cpa.h" 68 #endif 69 70 /** 71 ***************************************************************************** 72 * @ingroup cpaDc 73 * CPA Dc Major Version Number 74 * @description 75 * The CPA_DC API major version number. This number will be incremented 76 * when significant churn to the API has occurred. The combination of the 77 * major and minor number definitions represent the complete version number 78 * for this interface. 79 * 80 *****************************************************************************/ 81 #define CPA_DC_API_VERSION_NUM_MAJOR (2) 82 83 /** 84 ***************************************************************************** 85 * @ingroup cpaDc 86 * CPA DC Minor Version Number 87 * @description 88 * The CPA_DC API minor version number. This number will be incremented 89 * when minor changes to the API has occurred. The combination of the major 90 * and minor number definitions represent the complete version number for 91 * this interface. 92 * 93 *****************************************************************************/ 94 #define CPA_DC_API_VERSION_NUM_MINOR (2) 95 96 /** 97 ***************************************************************************** 98 * @ingroup cpaDc 99 * Compression API session handle type 100 * 101 * @description 102 * Handle used to uniquely identify a Compression API session handle. This 103 * handle is established upon registration with the API using 104 * cpaDcInitSession(). 105 * 106 * 107 * 108 *****************************************************************************/ 109 typedef void * CpaDcSessionHandle; 110 111 112 /** 113 ***************************************************************************** 114 * @ingroup cpaDc 115 * Supported file types 116 * 117 * @description 118 * This enumerated lists identified file types. Used to select Huffman 119 * trees. 120 * File types are associated with Precompiled Huffman Trees. 121 * 122 * @deprecated 123 * As of v1.6 of the Compression API, this enum has been deprecated. 124 * 125 *****************************************************************************/ 126 typedef enum _CpaDcFileType 127 { 128 CPA_DC_FT_ASCII, 129 /**< ASCII File Type */ 130 CPA_DC_FT_CSS, 131 /**< Cascading Style Sheet File Type */ 132 CPA_DC_FT_HTML, 133 /**< HTML or XML (or similar) file type */ 134 CPA_DC_FT_JAVA, 135 /**< File Java code or similar */ 136 CPA_DC_FT_OTHER 137 /**< Other file types */ 138 } CpaDcFileType; 139 /** 140 ***************************************************************************** 141 * @ingroup cpaDc 142 * Supported flush flags 143 * 144 * @description 145 * This enumerated list identifies the types of flush that can be 146 * specified for stateful and stateless cpaDcCompressData and 147 * cpaDcDecompressData functions. 148 * 149 *****************************************************************************/ 150 typedef enum _CpaDcFlush 151 { 152 CPA_DC_FLUSH_NONE = 0, 153 /**< No flush request. */ 154 CPA_DC_FLUSH_FINAL, 155 /**< Indicates that the input buffer contains all of the data for 156 the compression session allowing any buffered data to be released. 157 For Deflate, BFINAL is set in the compression header.*/ 158 CPA_DC_FLUSH_SYNC, 159 /**< Used for stateful deflate compression to indicate that all pending 160 output is flushed, byte aligned, to the output buffer. The session state 161 is not reset.*/ 162 CPA_DC_FLUSH_FULL 163 /**< Used for deflate compression to indicate that all pending output is 164 flushed to the output buffer and the session state is reset.*/ 165 } CpaDcFlush; 166 /** 167 ***************************************************************************** 168 * @ingroup cpaDc 169 * Supported Huffman Tree types 170 * 171 * @description 172 * This enumeration lists support for Huffman Tree types. 173 * Selecting Static Huffman trees generates compressed blocks with an RFC 174 * 1951 header specifying "compressed with fixed Huffman trees". 175 * 176 * Selecting Full Dynamic Huffman trees generates compressed blocks with 177 * an RFC 1951 header specifying "compressed with dynamic Huffman codes". 178 * The headers are calculated on the data being compressed, requiring two 179 * passes. 180 * 181 * Selecting Precompiled Huffman Trees generates blocks with RFC 1951 182 * dynamic headers. The headers are pre-calculated and are specified by 183 * the file type. 184 * 185 *****************************************************************************/ 186 typedef enum _CpaDcHuffType 187 { 188 CPA_DC_HT_STATIC, 189 /**< Static Huffman Trees */ 190 CPA_DC_HT_PRECOMP, 191 /**< Precompiled Huffman Trees */ 192 CPA_DC_HT_FULL_DYNAMIC 193 /**< Full Dynamic Huffman Trees */ 194 } CpaDcHuffType; 195 196 /** 197 ***************************************************************************** 198 * @ingroup cpaDc 199 * Supported compression types 200 * 201 * @description 202 * This enumeration lists the supported data compression algorithms. 203 * In combination with CpaDcChecksum it is used to decide on the file 204 * header and footer format. 205 * 206 * @deprecated 207 * As of v1.6 of the Compression API, CPA_DC_LZS, CPA_DC_ELZS and 208 * CPA_DC_LZSS have been deprecated and should not be used. 209 * 210 *****************************************************************************/ 211 typedef enum _CpaDcCompType 212 { 213 CPA_DC_LZS, 214 /**< LZS Compression */ 215 CPA_DC_ELZS, 216 /**< Extended LZS Compression */ 217 CPA_DC_LZSS, 218 /**< LZSS Compression */ 219 CPA_DC_DEFLATE 220 /**< Deflate Compression */ 221 } CpaDcCompType; 222 223 /** 224 ***************************************************************************** 225 * @ingroup cpaDc 226 * Supported checksum algorithms 227 * 228 * @description 229 * This enumeration lists the supported checksum algorithms 230 * Used to decide on file header and footer specifics. 231 * 232 *****************************************************************************/ 233 typedef enum _CpaDcChecksum 234 { 235 CPA_DC_NONE, 236 /**< No checksums required */ 237 CPA_DC_CRC32, 238 /**< application requires a CRC32 checksum */ 239 CPA_DC_ADLER32 240 /**< Application requires Adler-32 checksum */ 241 } CpaDcChecksum; 242 243 244 /** 245 ***************************************************************************** 246 * @ingroup cpaDc 247 * Supported session directions 248 * 249 * @description 250 * This enumerated list identifies the direction of a session. 251 * A session can be compress, decompress or both. 252 * 253 *****************************************************************************/ 254 typedef enum _CpaDcSessionDir 255 { 256 CPA_DC_DIR_COMPRESS, 257 /**< Session will be used for compression */ 258 CPA_DC_DIR_DECOMPRESS, 259 /**< Session will be used for decompression */ 260 CPA_DC_DIR_COMBINED 261 /**< Session will be used for both compression and decompression */ 262 } CpaDcSessionDir; 263 264 /** 265 ***************************************************************************** 266 * @ingroup cpaDc 267 * Supported session state settings 268 * 269 * @description 270 * This enumerated list identifies the stateful setting of a session. 271 * A session can be either stateful or stateless. 272 * 273 * Stateful sessions are limited to have only one in-flight message per 274 * session. This means a compress or decompress request must be complete 275 * before a new request can be started. This applies equally to sessions 276 * that are uni-directional in nature and sessions that are combined 277 * compress and decompress. Completion occurs when the synchronous function 278 * returns, or when the asynchronous callback function has completed. 279 * 280 *****************************************************************************/ 281 typedef enum _CpaDcSessionState 282 { 283 CPA_DC_STATEFUL, 284 /**< Session will be stateful, implying that state may need to be 285 saved in some situations */ 286 CPA_DC_STATELESS 287 /**< Session will be stateless, implying no state will be stored*/ 288 } CpaDcSessionState; 289 290 /** 291 ***************************************************************************** 292 * @ingroup cpaDc 293 * Supported compression levels 294 * 295 * @description 296 * This enumerated lists the supported compressed levels. 297 * Lower values will result in less compressibility in less time. 298 * 299 * 300 *****************************************************************************/ 301 typedef enum _CpaDcCompLvl 302 { 303 CPA_DC_L1 = 1, 304 /**< Compression level 1 */ 305 CPA_DC_L2, 306 /**< Compression level 2 */ 307 CPA_DC_L3, 308 /**< Compression level 3 */ 309 CPA_DC_L4, 310 /**< Compression level 4 */ 311 CPA_DC_L5, 312 /**< Compression level 5 */ 313 CPA_DC_L6, 314 /**< Compression level 6 */ 315 CPA_DC_L7, 316 /**< Compression level 7 */ 317 CPA_DC_L8, 318 /**< Compression level 8 */ 319 CPA_DC_L9 320 /**< Compression level 9 */ 321 } CpaDcCompLvl; 322 323 /** 324 ***************************************************************************** 325 * @ingroup cpaDc 326 * Supported additional details from accelerator 327 * 328 * @description 329 * This enumeration lists the supported additional details from the 330 * accelerator. These may be useful in determining the best way to 331 * recover from a failure. 332 * 333 * 334 *****************************************************************************/ 335 typedef enum _CpaDcReqStatus 336 { 337 CPA_DC_OK = 0, 338 /**< No error detected by compression slice */ 339 CPA_DC_INVALID_BLOCK_TYPE = -1, 340 /**< Invalid block type (type == 3) */ 341 CPA_DC_BAD_STORED_BLOCK_LEN = -2, 342 /**< Stored block length did not match one's complement */ 343 CPA_DC_TOO_MANY_CODES = -3, 344 /**< Too many length or distance codes */ 345 CPA_DC_INCOMPLETE_CODE_LENS = -4, 346 /**< Code length codes incomplete */ 347 CPA_DC_REPEATED_LENS = -5, 348 /**< Repeated lengths with no first length */ 349 CPA_DC_MORE_REPEAT = -6, 350 /**< Repeat more than specified lengths */ 351 CPA_DC_BAD_LITLEN_CODES = -7, 352 /**< Invalid literal/length code lengths */ 353 CPA_DC_BAD_DIST_CODES = -8, 354 /**< Invalid distance code lengths */ 355 CPA_DC_INVALID_CODE = -9, 356 /**< Invalid literal/length or distance code in fixed or dynamic block */ 357 CPA_DC_INVALID_DIST = -10, 358 /**< Distance is too far back in fixed or dynamic block */ 359 CPA_DC_OVERFLOW = -11, 360 /**< Overflow detected. This is an indication that output buffer has overflowed. 361 * For stateful sessions, this is a warning (the input can be adjusted and 362 * resubmitted). 363 * For stateless sessions this is an error condition */ 364 CPA_DC_SOFTERR = -12, 365 /**< Other non-fatal detected */ 366 CPA_DC_FATALERR = -13, 367 /**< Fatal error detected */ 368 CPA_DC_MAX_RESUBITERR = -14, 369 /**< On an error being detected, the firmware attempted to correct and resubmitted the 370 * request, however, the maximum resubmit value was exceeded */ 371 CPA_DC_INCOMPLETE_FILE_ERR = -15, 372 /**< The input file is incomplete. Note this is an indication that the request was 373 * submitted with a CPA_DC_FLUSH_FINAL, however, a BFINAL bit was not found in the 374 * request */ 375 CPA_DC_WDOG_TIMER_ERR = -16, 376 /**< The request was not completed as a watchdog timer hardware event occurred */ 377 CPA_DC_EP_HARDWARE_ERR = -17, 378 /**< Request was not completed as an end point hardware error occurred (for 379 * example, a parity error) */ 380 CPA_DC_VERIFY_ERROR = -18, 381 /**< Error detected during "compress and verify" operation */ 382 CPA_DC_EMPTY_DYM_BLK = -19, 383 /**< Decompression request contained an empty dynamic stored block 384 * (not supported) */ 385 CPA_DC_CRC_INTEG_ERR = -20, 386 /**< A data integrity CRC error was detected */ 387 } CpaDcReqStatus; 388 389 /** 390 ***************************************************************************** 391 * @ingroup cpaDc 392 * Supported modes for automatically selecting the best compression type. 393 * 394 * @description 395 * This enumeration lists the supported modes for automatically selecting 396 * the best Huffman encoding which would lead to the best compression 397 * results. 398 * 399 * The CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_NO_HDRS value is deprecated 400 * and should not be used. 401 * 402 *****************************************************************************/ 403 typedef enum _CpaDcAutoSelectBest 404 { 405 CPA_DC_ASB_DISABLED = 0, 406 /**< Auto select best mode is disabled */ 407 CPA_DC_ASB_STATIC_DYNAMIC = 1, 408 /**< Auto select between static and dynamic compression */ 409 CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_STORED_HDRS = 2, 410 /**< Auto select between uncompressed, static and dynamic compression, 411 * using stored block deflate headers if uncompressed is selected */ 412 CPA_DC_ASB_UNCOMP_STATIC_DYNAMIC_WITH_NO_HDRS = 3 413 /**< Auto select between uncompressed, static and dynamic compression, 414 * using no deflate headers if uncompressed is selected */ 415 } CpaDcAutoSelectBest; 416 417 /** 418 ***************************************************************************** 419 * @ingroup cpaDc 420 * Supported modes for skipping regions of input or output buffers. 421 * 422 * @description 423 * This enumeration lists the supported modes for skipping regions of 424 * input or output buffers. 425 * 426 *****************************************************************************/ 427 typedef enum _CpaDcSkipMode 428 { 429 CPA_DC_SKIP_DISABLED = 0, 430 /**< Skip mode is disabled */ 431 CPA_DC_SKIP_AT_START = 1, 432 /**< Skip region is at the start of the buffer. */ 433 CPA_DC_SKIP_AT_END = 2, 434 /**< Skip region is at the end of the buffer. */ 435 CPA_DC_SKIP_STRIDE = 3 436 /**< Skip region occurs at regular intervals within the buffer. 437 CpaDcSkipData.strideLength specifies the number of bytes between each 438 skip region. */ 439 } CpaDcSkipMode; 440 441 /** 442 ***************************************************************************** 443 * @ingroup cpaDc 444 * Service specific return codes 445 * 446 * @description 447 * Compression specific return codes 448 * 449 * 450 *****************************************************************************/ 451 452 #define CPA_DC_BAD_DATA (-100) 453 /**<Input data in invalid */ 454 455 /** 456 ***************************************************************************** 457 * @ingroup cpaDc 458 * Definition of callback function invoked for asynchronous cpaDc 459 * requests. 460 * 461 * @description 462 * This is the prototype for the cpaDc compression callback functions. 463 * The callback function is registered by the application using the 464 * cpaDcInitSession() function call. 465 * 466 * @context 467 * This callback function can be executed in a context that DOES NOT 468 * permit sleeping to occur. 469 * @assumptions 470 * None 471 * @sideEffects 472 * None 473 * @reentrant 474 * No 475 * @threadSafe 476 * Yes 477 * 478 * @param callbackTag User-supplied value to help identify request. 479 * @param status Status of the operation. Valid values are 480 * CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and 481 * CPA_STATUS_UNSUPPORTED. 482 * 483 * @retval 484 * None 485 * @pre 486 * Component has been initialized. 487 * @post 488 * None 489 * @note 490 * None 491 * @see 492 * None 493 * 494 *****************************************************************************/ 495 typedef void (*CpaDcCallbackFn)( 496 void *callbackTag, 497 CpaStatus status); 498 499 500 /** 501 ***************************************************************************** 502 * @ingroup cpaDc 503 * Implementation Capabilities Structure 504 * @description 505 * This structure contains data relating to the capabilities of an 506 * implementation. The capabilities include supported compression 507 * algorithms, RFC 1951 options and whether the implementation supports 508 * both stateful and stateless compress and decompress sessions. 509 * 510 ****************************************************************************/ 511 typedef struct _CpaDcInstanceCapabilities { 512 CpaBoolean statefulLZSCompression; 513 /**<True if the Instance supports Stateful LZS compression */ 514 CpaBoolean statefulLZSDecompression; 515 /**<True if the Instance supports Stateful LZS decompression */ 516 CpaBoolean statelessLZSCompression; 517 /**<True if the Instance supports Stateless LZS compression */ 518 CpaBoolean statelessLZSDecompression; 519 /**<True if the Instance supports Stateless LZS decompression */ 520 CpaBoolean statefulLZSSCompression; 521 /**<True if the Instance supports Stateful LZSS compression */ 522 CpaBoolean statefulLZSSDecompression; 523 /**<True if the Instance supports Stateful LZSS decompression */ 524 CpaBoolean statelessLZSSCompression; 525 /**<True if the Instance supports Stateless LZSS compression */ 526 CpaBoolean statelessLZSSDecompression; 527 /**<True if the Instance supports Stateless LZSS decompression */ 528 CpaBoolean statefulELZSCompression; 529 /**<True if the Instance supports Stateful Extended LZS 530 compression */ 531 CpaBoolean statefulELZSDecompression; 532 /**<True if the Instance supports Stateful Extended LZS 533 decompression */ 534 CpaBoolean statelessELZSCompression; 535 /**<True if the Instance supports Stateless Extended LZS 536 compression */ 537 CpaBoolean statelessELZSDecompression; 538 /**<True if the Instance supports Stateless Extended LZS 539 decompression */ 540 CpaBoolean statefulDeflateCompression; 541 /**<True if the Instance supports Stateful Deflate compression */ 542 CpaBoolean statefulDeflateDecompression; 543 /**<True if the Instance supports Stateful Deflate 544 decompression */ 545 CpaBoolean statelessDeflateCompression; 546 /**<True if the Instance supports Stateless Deflate compression */ 547 CpaBoolean statelessDeflateDecompression; 548 /**<True if the Instance supports Stateless Deflate 549 decompression */ 550 CpaBoolean checksumCRC32; 551 /**<True if the Instance can calculate a CRC32 checksum over 552 the uncompressed data*/ 553 CpaBoolean checksumAdler32; 554 /**<True if the Instance can calculate an Adler-32 checksum over 555 the uncompressed data */ 556 CpaBoolean dynamicHuffman; 557 /**<True if the Instance supports dynamic Huffman trees in deflate 558 blocks*/ 559 CpaBoolean dynamicHuffmanBufferReq; 560 /**<True if an Instance specific buffer is required to perform 561 a dynamic Huffman tree deflate request */ 562 CpaBoolean precompiledHuffman; 563 /**<True if the Instance supports precompiled Huffman trees in 564 deflate blocks*/ 565 CpaBoolean autoSelectBestHuffmanTree; 566 /**<True if the Instance has the ability to automatically select 567 between different Huffman encoding schemes for better 568 compression ratios */ 569 Cpa8U validWindowSizeMaskCompression; 570 /**<Bits set to '1' for each valid window size supported by 571 the compression implementation */ 572 Cpa8U validWindowSizeMaskDecompression; 573 /**<Bits set to '1' for each valid window size supported by 574 the decompression implementation */ 575 Cpa32U internalHuffmanMem; 576 /**<Number of bytes internally available to be used when 577 constructing dynamic Huffman trees. */ 578 CpaBoolean endOfLastBlock; 579 /**< True if the Instance supports stopping at the end of the last 580 * block in a deflate stream during a decompression operation and 581 * reporting that the end of the last block has been reached as 582 * part of the CpaDcReqStatus data. */ 583 CpaBoolean reportParityError; 584 /**<True if the instance supports parity error reporting. */ 585 CpaBoolean batchAndPack; 586 /**< True if the instance supports 'batch and pack' compression */ 587 CpaBoolean compressAndVerify; 588 /**<True if the instance supports checking that compressed data, 589 * generated as part of a compression operation, can be 590 * successfully decompressed. */ 591 CpaBoolean compressAndVerifyStrict; 592 /**< True if compressAndVerify is 'strictly' enabled for the 593 * instance. If strictly enabled, compressAndVerify will be enabled 594 * by default for compression operations and cannot be disabled by 595 * setting opData.compressAndVerify=0 with cpaDcCompressData2(). 596 * Compression operations with opData.compressAndVerify=0 will 597 * return a CPA_STATUS_INVALID_PARAM error status when in 598 * compressAndVerify strict mode. 599 */ 600 CpaBoolean compressAndVerifyAndRecover; 601 /**<True if the instance supports recovering from errors detected 602 * by compressAndVerify by generating a stored block in the 603 * compressed output data buffer. This stored block replaces any 604 * compressed content that resulted in a compressAndVerify error. 605 */ 606 CpaBoolean integrityCrcs; 607 /**<True if the instance supports integrity CRC checking in the 608 * compression/decompression datapath. */ 609 } CpaDcInstanceCapabilities; 610 611 /** 612 ***************************************************************************** 613 * @ingroup cpaDc 614 * Session Setup Data. 615 * @description 616 * This structure contains data relating to setting up a session. The 617 * client needs to complete the information in this structure in order to 618 * setup a session. 619 * 620 * @deprecated 621 * As of v1.6 of the Compression API, the fileType and deflateWindowSize 622 * fields in this structure have been deprecated and should not be used. 623 * 624 ****************************************************************************/ 625 typedef struct _CpaDcSessionSetupData { 626 CpaDcCompLvl compLevel; 627 /**<Compression Level from CpaDcCompLvl */ 628 CpaDcCompType compType; 629 /**<Compression type from CpaDcCompType */ 630 CpaDcHuffType huffType; 631 /**<Huffman type from CpaDcHuffType */ 632 CpaDcAutoSelectBest autoSelectBestHuffmanTree; 633 /**<Indicates if and how the implementation should select the best 634 * Huffman encoding. */ 635 CpaDcFileType fileType; 636 /**<File type for the purpose of determining Huffman Codes from 637 * CpaDcFileType. 638 * As of v1.6 of the Compression API, this field has been deprecated 639 * and should not be used. */ 640 CpaDcSessionDir sessDirection; 641 /**<Session direction indicating whether session is used for 642 compression, decompression or both */ 643 CpaDcSessionState sessState; 644 /**<Session state indicating whether the session should be configured 645 as stateless or stateful */ 646 Cpa32U deflateWindowSize; 647 /**<Base 2 logarithm of maximum window size minus 8 (a value of 7 for 648 * a 32K window size). Permitted values are 0 to 7. cpaDcDecompressData 649 * may return an error if an attempt is made to decompress a stream that 650 * has a larger window size. 651 * As of v1.6 of the Compression API, this field has been deprecated and 652 * should not be used. */ 653 CpaDcChecksum checksum; 654 /**<Desired checksum required for the session */ 655 } CpaDcSessionSetupData; 656 657 /** 658 ***************************************************************************** 659 * @ingroup cpaDc 660 * Compression Statistics Data. 661 * @description 662 * This structure contains data elements corresponding to statistics. 663 * Statistics are collected on a per instance basis and include: 664 * jobs submitted and completed for both compression and decompression. 665 * 666 ****************************************************************************/ 667 typedef struct _CpaDcStats { 668 Cpa64U numCompRequests; 669 /**< Number of successful compression requests */ 670 Cpa64U numCompRequestsErrors; 671 /**< Number of compression requests that had errors and 672 could not be processed */ 673 Cpa64U numCompCompleted; 674 /**< Compression requests completed */ 675 Cpa64U numCompCompletedErrors; 676 /**< Compression requests not completed due to errors */ 677 Cpa64U numCompCnvErrorsRecovered; 678 /**< Compression CNV errors that have been recovered */ 679 680 Cpa64U numDecompRequests; 681 /**< Number of successful decompression requests */ 682 Cpa64U numDecompRequestsErrors; 683 /**< Number of decompression requests that had errors and 684 could not be processed */ 685 Cpa64U numDecompCompleted; 686 /**< Decompression requests completed */ 687 Cpa64U numDecompCompletedErrors; 688 /**< Decompression requests not completed due to errors */ 689 690 } CpaDcStats; 691 692 /** 693 ***************************************************************************** 694 * @ingroup cpaDc 695 * Request results data 696 * @description 697 * This structure contains the request results. 698 * 699 * For stateful sessions the status, produced, consumed and 700 * endOfLastBlock results are per request values while the checksum 701 * value is cumulative across all requests on the session so far. 702 * In this case the checksum value is not guaranteed to be correct 703 * until the final compressed data has been processed. 704 * 705 * For stateless sessions, an initial checksum value is passed into 706 * the stateless operation. Once the stateless operation completes, 707 * the checksum value will contain checksum produced by the operation. 708 * 709 ****************************************************************************/ 710 typedef struct _CpaDcRqResults { 711 CpaDcReqStatus status; 712 /**< Additional status details from accelerator */ 713 Cpa32U produced; 714 /**< Octets produced by the operation */ 715 Cpa32U consumed; 716 /**< Octets consumed by the operation */ 717 Cpa32U checksum; 718 /**< Initial checksum passed into stateless operations. 719 Will also be updated to the checksum produced by the operation */ 720 CpaBoolean endOfLastBlock; 721 /**< Decompression operation has stopped at the end of the last 722 * block in a deflate stream. */ 723 } CpaDcRqResults; 724 725 /** 726 ***************************************************************************** 727 * @ingroup cpaDc 728 * Integrity CRC calculation details 729 * @description 730 * This structure contains information about resulting integrity CRC 731 * calculations performed for a single request. 732 * 733 ****************************************************************************/ 734 typedef struct _CpaIntegrityCrc { 735 Cpa32U iCrc; /**< CRC calculated on request's input buffer */ 736 Cpa32U oCrc; /**< CRC calculated on request's output buffer */ 737 } CpaIntegrityCrc; 738 739 /** 740 ***************************************************************************** 741 * @ingroup cpaDc 742 * Collection of CRC related data 743 * @description 744 * This structure contains data facilitating CRC calculations. 745 * After successful request, this structure will contain 746 * all resulting CRCs. 747 * Integrity specific CRCs (when enabled/supported) are located in 748 * 'CpaIntegrityCrc integrityCrc' field. 749 * @note 750 * this structure must be allocated in physical contiguous memory 751 * 752 ****************************************************************************/ 753 typedef struct _CpaCrcData { 754 Cpa32U crc32; 755 /**< CRC32 calculated on the input buffer during compression 756 * requests and on the output buffer during decompression requests. */ 757 Cpa32U adler32; 758 /**< ADLER32 calculated on the input buffer during compression 759 * requests and on the output buffer during decompression requests. */ 760 CpaIntegrityCrc integrityCrc; 761 /**< Integrity CRCs */ 762 } CpaCrcData; 763 764 /** 765 ***************************************************************************** 766 * @ingroup cpaDc 767 * Skip Region Data. 768 * @description 769 * This structure contains data relating to configuring skip region 770 * behaviour. A skip region is a region of an input buffer that 771 * should be omitted from processing or a region that should be inserted 772 * into the output buffer. 773 * 774 ****************************************************************************/ 775 typedef struct _CpaDcSkipData { 776 CpaDcSkipMode skipMode; 777 /**<Skip mode from CpaDcSkipMode for buffer processing */ 778 Cpa32U skipLength; 779 /**<Number of bytes to skip when skip mode is enabled */ 780 Cpa32U strideLength; 781 /**<Size of the stride between skip regions when skip mode is 782 * set to CPA_DC_SKIP_STRIDE. */ 783 Cpa32U firstSkipOffset; 784 /**< Number of bytes to skip in a buffer before reading/writing the 785 * input/output data. */ 786 } CpaDcSkipData; 787 788 /** 789 ***************************************************************************** 790 * @ingroup cpaDc 791 * (De)Compression request input parameters. 792 * @description 793 * This structure contains the request information for use with 794 * compression operations. 795 * 796 ****************************************************************************/ 797 typedef struct _CpaDcOpData { 798 CpaDcFlush flushFlag; 799 /**< Indicates the type of flush to be performed. */ 800 CpaBoolean compressAndVerify; 801 /**< If set to true, for compression operations, the implementation 802 * will verify that compressed data, generated by the compression 803 * operation, can be successfully decompressed. 804 * This behavior is only supported for stateless compression. 805 * This behavior is only supported on instances that support the 806 * compressAndVerify capability. */ 807 CpaBoolean compressAndVerifyAndRecover; 808 /**< If set to true, for compression operations, the implementation 809 * will automatically recover from a compressAndVerify error. 810 * This behavior is only supported for stateless compression. 811 * This behavior is only supported on instances that support the 812 * compressAndVerifyAndRecover capability. 813 * The compressAndVerify field in CpaDcOpData MUST be set to CPA_TRUE 814 * if compressAndVerifyAndRecover is set to CPA_TRUE. */ 815 CpaBoolean integrityCrcCheck; 816 /**< If set to true, the implementation will verify that data 817 * integrity is preserved through the processing pipeline. 818 * This behaviour supports stateless and stateful behavior for 819 * both static and dynamic Huffman encoding. 820 * 821 * Integrity CRC checking is not supported for decompression operations 822 * over data that contains multiple gzip headers. */ 823 CpaBoolean verifyHwIntegrityCrcs; 824 /**< If set to true, software calculated CRCs will be compared 825 * against hardware generated integrity CRCs to ensure that data 826 * integrity is maintained when transferring data to and from the 827 * hardware accelerator. */ 828 CpaDcSkipData inputSkipData; 829 /**< Optional skip regions in the input buffers */ 830 CpaDcSkipData outputSkipData; 831 /**< Optional skip regions in the output buffers */ 832 CpaCrcData *pCrcData; 833 /**< Pointer to CRCs for this operation, when integrity checks 834 * are enabled. */ 835 } CpaDcOpData; 836 837 /** 838 ***************************************************************************** 839 * @ingroup cpaDc 840 * Retrieve Instance Capabilities 841 * 842 * @description 843 * This function is used to retrieve the capabilities matrix of 844 * an instance. 845 * 846 * @context 847 * This function shall not be called in an interrupt context. 848 * @assumptions 849 * None 850 * @sideEffects 851 * None 852 * @blocking 853 * Yes 854 * @reentrant 855 * No 856 * @threadSafe 857 * Yes 858 * 859 * @param[in] dcInstance Instance handle derived from discovery 860 * functions 861 * @param[in,out] pInstanceCapabilities Pointer to a capabilities struct 862 * 863 * @retval CPA_STATUS_SUCCESS Function executed successfully. 864 * @retval CPA_STATUS_FAIL Function failed. 865 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 866 * @retval CPA_STATUS_RESOURCE Error related to system resources. 867 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 868 * the request. 869 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 870 * 871 * @pre 872 * None 873 * @post 874 * None 875 * @note 876 * Only a synchronous version of this function is provided. 877 * 878 * @see 879 * None 880 * 881 *****************************************************************************/ 882 CpaStatus 883 cpaDcQueryCapabilities( CpaInstanceHandle dcInstance, 884 CpaDcInstanceCapabilities *pInstanceCapabilities ); 885 886 /** 887 ***************************************************************************** 888 * @ingroup cpaDc 889 * Initialize compression decompression session 890 * 891 * @description 892 * This function is used to initialize a compression/decompression 893 * session. 894 * This function specifies a BufferList for context data. 895 * A single session can be used for both compression and decompression 896 * requests. Clients MAY register a callback 897 * function for the compression service using this function. 898 * This function returns a unique session handle each time this function 899 * is invoked. 900 * If the session has been configured with a callback function, then 901 * the order of the callbacks are guaranteed to be in the same order the 902 * compression or decompression requests were submitted for each session, 903 * so long as a single thread of execution is used for job submission. 904 * 905 * @context 906 * This is a synchronous function and it cannot sleep. It can be executed in 907 * a context that does not permit sleeping. 908 * @assumptions 909 * None 910 * @sideEffects 911 * None 912 * @blocking 913 * No 914 * @reentrant 915 * No 916 * @threadSafe 917 * Yes 918 * 919 * @param[in] dcInstance Instance handle derived from discovery 920 * functions. 921 * @param[in,out] pSessionHandle Pointer to a session handle. 922 * @param[in,out] pSessionData Pointer to a user instantiated structure 923 * containing session data. 924 * @param[in] pContextBuffer pointer to context buffer. This is not 925 * required for stateless operations. 926 * The total size of the buffer list must 927 * be equal to or larger than the specified 928 * contextSize retrieved from the 929 * cpaDcGetSessionSize() function. 930 * @param[in] callbackFn For synchronous operation this callback 931 * shall be a null pointer. 932 * 933 * @retval CPA_STATUS_SUCCESS Function executed successfully. 934 * @retval CPA_STATUS_FAIL Function failed. 935 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 936 * @retval CPA_STATUS_RESOURCE Error related to system resources. 937 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 938 * the request. 939 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 940 * 941 * @pre 942 * dcInstance has been started using cpaDcStartInstance. 943 * @post 944 * None 945 * @note 946 * Only a synchronous version of this function is provided. 947 * 948 * This initializes opaque data structures in the session handle. Data 949 * compressed under this session will be compressed to the level 950 * specified in the pSessionData structure. Lower compression level 951 * numbers indicate a request for faster compression at the 952 * expense of compression ratio. Higher compression level numbers 953 * indicate a request for higher compression ratios at the expense of 954 * execution time. 955 * 956 * The session is opaque to the user application and the session handle 957 * contains job specific data. 958 * 959 * The pointer to the ContextBuffer will be stored in session specific 960 * data if required by the implementation. 961 * 962 * It is not permitted to have multiple 963 * outstanding asynchronous compression requests for stateful sessions. 964 * It is possible to add 965 * parallelization to compression by using multiple sessions. 966 * 967 * The window size specified in the pSessionData must be match exactly 968 * one of the supported window sizes specified in the capabilities 969 * structure. If a bi-directional session is being initialized, then 970 * the window size must be valid for both compress and decompress. 971 * 972 * @see 973 * None 974 * 975 *****************************************************************************/ 976 CpaStatus 977 cpaDcInitSession( CpaInstanceHandle dcInstance, 978 CpaDcSessionHandle pSessionHandle, 979 CpaDcSessionSetupData *pSessionData, 980 CpaBufferList *pContextBuffer, 981 CpaDcCallbackFn callbackFn ); 982 983 984 /** 985 ***************************************************************************** 986 * @ingroup cpaDc 987 * Compression Session Reset Function. 988 * 989 * @description 990 * This function will reset a previously initialized session handle 991 * Reset will fail if outstanding calls still exist for the initialized 992 * session handle. 993 * The client needs to retry the reset function at a later time. 994 * 995 * @context 996 * This is a synchronous function that cannot sleep. It can be 997 * executed in a context that does not permit sleeping. 998 * @assumptions 999 * None 1000 * @sideEffects 1001 * None 1002 * @blocking 1003 * No. 1004 * @reentrant 1005 * No 1006 * @threadSafe 1007 * Yes 1008 * 1009 * @param[in] dcInstance Instance handle. 1010 * @param[in,out] pSessionHandle Session handle. 1011 * 1012 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1013 * @retval CPA_STATUS_FAIL Function failed. 1014 * @retval CPA_STATUS_RETRY Resubmit the request. 1015 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1016 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1017 * 1018 * @pre 1019 * The component has been initialized via cpaDcStartInstance function. 1020 * The session has been initialized via cpaDcInitSession function. 1021 * @post 1022 * None 1023 * @note 1024 * This is a synchronous function and has no completion callback 1025 * associated with it. 1026 * 1027 * @see 1028 * cpaDcInitSession() 1029 * 1030 *****************************************************************************/ 1031 CpaStatus 1032 cpaDcResetSession(const CpaInstanceHandle dcInstance, 1033 CpaDcSessionHandle pSessionHandle ); 1034 1035 1036 /** 1037 ***************************************************************************** 1038 * @ingroup cpaDc 1039 * Compression Session Remove Function. 1040 * 1041 * @description 1042 * This function will remove a previously initialized session handle 1043 * and the installed callback handler function. Removal will fail if 1044 * outstanding calls still exist for the initialized session handle. 1045 * The client needs to retry the remove function at a later time. 1046 * The memory for the session handle MUST not be freed until this call 1047 * has completed successfully. 1048 * 1049 * @context 1050 * This is a synchronous function that cannot sleep. It can be 1051 * executed in a context that does not permit sleeping. 1052 * @assumptions 1053 * None 1054 * @sideEffects 1055 * None 1056 * @blocking 1057 * No. 1058 * @reentrant 1059 * No 1060 * @threadSafe 1061 * Yes 1062 * 1063 * @param[in] dcInstance Instance handle. 1064 * @param[in,out] pSessionHandle Session handle. 1065 * 1066 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1067 * @retval CPA_STATUS_FAIL Function failed. 1068 * @retval CPA_STATUS_RETRY Resubmit the request. 1069 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1070 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1071 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1072 * the request. 1073 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1074 * 1075 * @pre 1076 * The component has been initialized via cpaDcStartInstance function. 1077 * @post 1078 * None 1079 * @note 1080 * This is a synchronous function and has no completion callback 1081 * associated with it. 1082 * 1083 * @see 1084 * cpaDcInitSession() 1085 * 1086 *****************************************************************************/ 1087 CpaStatus 1088 cpaDcRemoveSession(const CpaInstanceHandle dcInstance, 1089 CpaDcSessionHandle pSessionHandle ); 1090 1091 /** 1092 ***************************************************************************** 1093 * @ingroup cpaDc 1094 * Deflate Compression Bound API 1095 * 1096 * @description 1097 * This function provides the maximum output buffer size for a Deflate 1098 * compression operation in the "worst case" (non-compressible) scenario. 1099 * It's primary purpose is for output buffer memory allocation. 1100 * 1101 * @context 1102 * This is a synchronous function that will not sleep. It can be 1103 * executed in a context that does not permit sleeping. 1104 * @assumptions 1105 * None 1106 * @sideEffects 1107 * None 1108 * @blocking 1109 * No. 1110 * @reentrant 1111 * No 1112 * @threadSafe 1113 * Yes 1114 * 1115 * @param[in] dcInstance Instance handle. 1116 * @param[in] huffType CpaDcHuffType to be used with this operation. 1117 * @param[in] inputSize Input Buffer size. 1118 * @param[out] outputSize Maximum output buffer size. 1119 * 1120 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1121 * @retval CPA_STATUS_FAIL Function failed. 1122 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1123 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1124 * 1125 * @pre 1126 * The component has been initialized via cpaDcStartInstance function. 1127 * @post 1128 * None 1129 * @note 1130 * This is a synchronous function and has no completion callback 1131 * associated with it. 1132 * 1133 * @see 1134 * None 1135 * 1136 *****************************************************************************/ 1137 CpaStatus 1138 cpaDcDeflateCompressBound(const CpaInstanceHandle dcInstance, 1139 CpaDcHuffType huffType, 1140 Cpa32U inputSize, 1141 Cpa32U *outputSize ); 1142 1143 /** 1144 ***************************************************************************** 1145 * @ingroup cpaDc 1146 * Submit a request to compress a buffer of data. 1147 * 1148 * @description 1149 * This API consumes data from the input buffer and generates compressed 1150 * data in the output buffer. 1151 * 1152 * @context 1153 * When called as an asynchronous function it cannot sleep. It can be 1154 * executed in a context that does not permit sleeping. 1155 * When called as a synchronous function it may sleep. It MUST NOT be 1156 * executed in a context that DOES NOT permit sleeping. 1157 * @assumptions 1158 * None 1159 * @sideEffects 1160 * None 1161 * @blocking 1162 * Yes when configured to operate in synchronous mode. 1163 * @reentrant 1164 * No 1165 * @threadSafe 1166 * Yes 1167 * 1168 * @param[in] dcInstance Target service instance. 1169 * @param[in,out] pSessionHandle Session handle. 1170 * @param[in] pSrcBuff Pointer to data buffer for compression. 1171 * @param[in] pDestBuff Pointer to buffer space for data after 1172 * compression. 1173 * @param[in,out] pResults Pointer to results structure 1174 * @param[in] flushFlag Indicates the type of flush to be 1175 * performed. 1176 * @param[in] callbackTag User supplied value to help correlate 1177 * the callback with its associated 1178 * request. 1179 * 1180 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1181 * @retval CPA_STATUS_FAIL Function failed. 1182 * @retval CPA_STATUS_RETRY Resubmit the request. 1183 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1184 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1185 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1186 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1187 * the request. 1188 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1189 * 1190 * @pre 1191 * pSessionHandle has been setup using cpaDcInitSession() 1192 * @post 1193 * pSessionHandle has session related state information 1194 * @note 1195 * This function passes control to the compression service for processing 1196 * 1197 * In synchronous mode the function returns the error status returned from the 1198 * service. In asynchronous mode the status is returned by the callback 1199 * function. 1200 * 1201 * This function may be called repetitively with input until all of the 1202 * input has been consumed by the compression service and all the output 1203 * has been produced. 1204 * 1205 * When this function returns, it may be that all of the available data 1206 * in the input buffer has not been compressed. This situation will 1207 * occur when there is insufficient space in the output buffer. The 1208 * calling application should note the amount of data processed, and clear 1209 * the output buffer and then submit the request again, with the input 1210 * buffer pointer to the data that was not previously compressed. 1211 * 1212 * Relationship between input buffers and results buffers. 1213 * -# Implementations of this API must not modify the individual 1214 * flat buffers of the input buffer list. 1215 * -# The implementation communicates the amount of data 1216 * consumed from the source buffer list via pResults->consumed arg. 1217 * -# The implementation communicates the amount of data in the 1218 * destination buffer list via pResults->produced arg. 1219 * 1220 * Source Buffer Setup Rules 1221 * -# The buffer list must have the correct number of flat buffers. This 1222 * is specified by the numBuffers element of the CpaBufferList. 1223 * -# Each flat buffer must have a pointer to contiguous memory that has 1224 * been allocated by the calling application. The 1225 * number of octets to be compressed or decompressed must be stored 1226 * in the dataLenInBytes element of the flat buffer. 1227 * -# It is permissible to have one or more flat buffers with a zero length 1228 * data store. This function will process all flat buffers until the 1229 * destination buffer is full or all source data has been processed. 1230 * If a buffer has zero length, then no data will be processed from 1231 * that buffer. 1232 * 1233 * Source Buffer Processing Rules. 1234 * -# The buffer list is processed in index order - SrcBuff->pBuffers[0] 1235 * will be completely processed before SrcBuff->pBuffers[1] begins to 1236 * be processed. 1237 * -# The application must drain the destination buffers. 1238 * If the source data was not completely consumed, the application 1239 * must resubmit the request. 1240 * -# On return, the pResults->consumed will indicate the number of bytes 1241 * consumed from the input buffers. 1242 * 1243 * Destination Buffer Setup Rules 1244 * -# The destination buffer list must have storage for processed data. 1245 * This implies at least one flat buffer must exist in the buffer list. 1246 * -# For each flat buffer in the buffer list, the dataLenInBytes element 1247 * must be set to the size of the buffer space. 1248 * -# It is permissible to have one or more flat buffers with a zero length 1249 * data store. 1250 * If a buffer has zero length, then no data will be added to 1251 * that buffer. 1252 * 1253 * Destination Buffer Processing Rules. 1254 * -# The buffer list is processed in index order - DestBuff->pBuffers[0] 1255 * will be completely processed before DestBuff->pBuffers[1] begins to 1256 * be processed. 1257 * -# On return, the pResults->produced will indicate the number of bytes 1258 * written to the output buffers. 1259 * -# If processing has not been completed, the application must drain the 1260 * destination buffers and resubmit the request. The application must 1261 * reset the dataLenInBytes for each flat buffer in the destination 1262 * buffer list. 1263 * 1264 * Checksum rules. 1265 * If a checksum is specified in the session setup data, then: 1266 * -# For the first request for a particular data segment the checksum 1267 * is initialised internally by the implementation. 1268 * -# The checksum is maintained by the implementation between calls 1269 * until the flushFlag is set to CPA_DC_FLUSH_FINAL indicating the 1270 * end of a particular data segment. 1271 * -# Intermediate checksum values are returned to the application, 1272 * via the CpaDcRqResults structure, in response to each request. 1273 * However these checksum values are not guaranteed to the valid 1274 * until the call with flushFlag set to CPA_DC_FLUSH_FINAL 1275 * completes successfully. 1276 * 1277 * The application should set flushFlag to 1278 * CPA_DC_FLUSH_FINAL to indicate processing a particular data segment 1279 * is complete. It should be noted that this function may have to be 1280 * called more than once to process data after the flushFlag parameter has 1281 * been set to CPA_DC_FLUSH_FINAL if the destination buffer fills. Refer 1282 * to buffer processing rules. 1283 * 1284 * For stateful operations, when the function is invoked with flushFlag 1285 * set to CPA_DC_FLUSH_NONE or CPA_DC_FLUSH_SYNC, indicating more data 1286 * is yet to come, the function may or may not retain data. When the 1287 * function is invoked with flushFlag set to CPA_DC_FLUSH_FULL or 1288 * CPA_DC_FLUSH_FINAL, the function will process all buffered data. 1289 * 1290 * For stateless operations, CPA_DC_FLUSH_FINAL will cause the BFINAL 1291 * bit to be set for deflate compression. The initial checksum for the 1292 * stateless operation should be set to 0. CPA_DC_FLUSH_NONE and 1293 * CPA_DC_FLUSH_SYNC should not be used for stateless operations. 1294 * 1295 * It is possible to maintain checksum and length information across 1296 * cpaDcCompressData() calls with a stateless session without maintaining 1297 * the full history state that is maintained by a stateful session. In this 1298 * mode of operation, an initial checksum value of 0 is passed into the 1299 * first cpaDcCompressData() call with the flush flag set to 1300 * CPA_DC_FLUSH_FULL. On subsequent calls to cpaDcCompressData() for this 1301 * session, the checksum passed to cpaDcCompressData should be set to the 1302 * checksum value produced by the previous call to cpaDcCompressData(). 1303 * When the last block of input data is passed to cpaDcCompressData(), the 1304 * flush flag should be set to CP_DC_FLUSH_FINAL. This will cause the BFINAL 1305 * bit to be set in a deflate stream. It is the responsibility of the calling 1306 * application to maintain overall lengths across the stateless requests 1307 * and to pass the checksum produced by one request into the next request. 1308 * 1309 * When an instance supports compressAndVerifyAndRecover, it is enabled by 1310 * default when using cpaDcCompressData(). If this feature needs to be 1311 * disabled, cpaDcCompressData2() must be used. 1312 * 1313 * Synchronous or Asynchronous operation of the API is determined by 1314 * the value of the callbackFn parameter passed to cpaDcInitSession() 1315 * when the sessionHandle was setup. If a non-NULL value was specified 1316 * then the supplied callback function will be invoked asynchronously 1317 * with the response of this request. 1318 * 1319 * Response ordering: 1320 * For each session, the implementation must maintain the order of 1321 * responses. That is, if in asynchronous mode, the order of the callback 1322 * functions must match the order of jobs submitted by this function. 1323 * In a simple synchronous mode implementation, the practice of submitting 1324 * a request and blocking on its completion ensure ordering is preserved. 1325 * 1326 * This limitation does not apply if the application employs multiple 1327 * threads to service a single session. 1328 * 1329 * If this API is invoked asynchronous, the return code represents 1330 * the success or not of asynchronously scheduling the request. 1331 * The results of the operation, along with the amount of data consumed 1332 * and produced become available when the callback function is invoked. 1333 * As such, pResults->consumed and pResults->produced are available 1334 * only when the operation is complete. 1335 * 1336 * The application must not use either the source or destination buffers 1337 * until the callback has completed. 1338 * 1339 * @see 1340 * None 1341 * 1342 *****************************************************************************/ 1343 CpaStatus 1344 cpaDcCompressData( CpaInstanceHandle dcInstance, 1345 CpaDcSessionHandle pSessionHandle, 1346 CpaBufferList *pSrcBuff, 1347 CpaBufferList *pDestBuff, 1348 CpaDcRqResults *pResults, 1349 CpaDcFlush flushFlag, 1350 void *callbackTag ); 1351 1352 /** 1353 ***************************************************************************** 1354 * @ingroup cpaDc 1355 * Submit a request to compress a buffer of data. 1356 * 1357 * @description 1358 * This API consumes data from the input buffer and generates compressed 1359 * data in the output buffer. This API is very similar to 1360 * cpaDcCompressData() except it provides a CpaDcOpData structure for 1361 * passing additional input parameters not covered in cpaDcCompressData(). 1362 * 1363 * @context 1364 * When called as an asynchronous function it cannot sleep. It can be 1365 * executed in a context that does not permit sleeping. 1366 * When called as a synchronous function it may sleep. It MUST NOT be 1367 * executed in a context that DOES NOT permit sleeping. 1368 * @assumptions 1369 * None 1370 * @sideEffects 1371 * None 1372 * @blocking 1373 * Yes when configured to operate in synchronous mode. 1374 * @reentrant 1375 * No 1376 * @threadSafe 1377 * Yes 1378 * 1379 * @param[in] dcInstance Target service instance. 1380 * @param[in,out] pSessionHandle Session handle. 1381 * @param[in] pSrcBuff Pointer to data buffer for compression. 1382 * @param[in] pDestBuff Pointer to buffer space for data after 1383 * compression. 1384 * @param[in] pOpData Additional input parameters. 1385 * @param[in,out] pResults Pointer to results structure 1386 * @param[in] callbackTag User supplied value to help correlate 1387 * the callback with its associated 1388 * request. 1389 * 1390 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1391 * @retval CPA_STATUS_FAIL Function failed. 1392 * @retval CPA_STATUS_RETRY Resubmit the request. 1393 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1394 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1395 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1396 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1397 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1398 * the request. 1399 * 1400 * @pre 1401 * pSessionHandle has been setup using cpaDcInitSession() 1402 * @post 1403 * pSessionHandle has session related state information 1404 * @note 1405 * This function passes control to the compression service for processing 1406 * 1407 * @see 1408 * cpaDcCompressData() 1409 * 1410 *****************************************************************************/ 1411 CpaStatus 1412 cpaDcCompressData2( CpaInstanceHandle dcInstance, 1413 CpaDcSessionHandle pSessionHandle, 1414 CpaBufferList *pSrcBuff, 1415 CpaBufferList *pDestBuff, 1416 CpaDcOpData *pOpData, 1417 CpaDcRqResults *pResults, 1418 void *callbackTag ); 1419 1420 /** 1421 ***************************************************************************** 1422 * @ingroup cpaDc 1423 * Submit a request to decompress a buffer of data. 1424 * 1425 * @description 1426 * This API consumes compressed data from the input buffer and generates 1427 * uncompressed data in the output buffer. 1428 * 1429 * @context 1430 * When called as an asynchronous function it cannot sleep. It can be 1431 * executed in a context that does not permit sleeping. 1432 * When called as a synchronous function it may sleep. It MUST NOT be 1433 * executed in a context that DOES NOT permit sleeping. 1434 * @assumptions 1435 * None 1436 * @sideEffects 1437 * None 1438 * @blocking 1439 * Yes when configured to operate in synchronous mode. 1440 * @reentrant 1441 * No 1442 * @threadSafe 1443 * Yes 1444 * 1445 * @param[in] dcInstance Target service instance. 1446 * @param[in,out] pSessionHandle Session handle. 1447 * @param[in] pSrcBuff Pointer to data buffer for compression. 1448 * @param[in] pDestBuff Pointer to buffer space for data 1449 * after decompression. 1450 * @param[in,out] pResults Pointer to results structure 1451 * @param[in] flushFlag When set to CPA_DC_FLUSH_FINAL, indicates 1452 * that the input buffer contains all of 1453 * the data for the compression session, 1454 * allowing the function to release 1455 * history data. 1456 * @param[in] callbackTag User supplied value to help correlate 1457 * the callback with its associated 1458 * request. 1459 * 1460 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1461 * @retval CPA_STATUS_FAIL Function failed. 1462 * @retval CPA_STATUS_RETRY Resubmit the request. 1463 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1464 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1465 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1466 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1467 * the request. 1468 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1469 * 1470 * @pre 1471 * pSessionHandle has been setup using cpaDcInitSession() 1472 * @post 1473 * pSessionHandle has session related state information 1474 * @note 1475 * This function passes control to the compression service for 1476 * decompression. The function returns the status from the service. 1477 * 1478 * This function may be called repetitively with input until all of the 1479 * input has been provided and all the output has been consumed. 1480 * 1481 * This function has identical buffer processing rules as 1482 * cpaDcCompressData(). 1483 * 1484 * This function has identical checksum processing rules as 1485 * cpaDcCompressData(). 1486 * 1487 * The application should set flushFlag to 1488 * CPA_DC_FLUSH_FINAL to indicate processing a particular compressed 1489 * data segment is complete. It should be noted that this function may 1490 * have to be called more than once to process data after flushFlag 1491 * has been set if the destination buffer fills. Refer to 1492 * buffer processing rules in cpaDcCompressData(). 1493 * 1494 * Synchronous or Asynchronous operation of the API is determined by 1495 * the value of the callbackFn parameter passed to cpaDcInitSession() 1496 * when the sessionHandle was setup. If a non-NULL value was specified 1497 * then the supplied callback function will be invoked asynchronously 1498 * with the response of this request, along with the callbackTag 1499 * specified in the function. 1500 * 1501 * The same response ordering constraints identified in the 1502 * cpaDcCompressData API apply to this function. 1503 * 1504 * @see 1505 * cpaDcCompressData() 1506 * 1507 *****************************************************************************/ 1508 CpaStatus 1509 cpaDcDecompressData( CpaInstanceHandle dcInstance, 1510 CpaDcSessionHandle pSessionHandle, 1511 CpaBufferList *pSrcBuff, 1512 CpaBufferList *pDestBuff, 1513 CpaDcRqResults *pResults, 1514 CpaDcFlush flushFlag, 1515 void *callbackTag ); 1516 1517 1518 /** 1519 ***************************************************************************** 1520 * @ingroup cpaDc 1521 * Submit a request to decompress a buffer of data. 1522 * 1523 * @description 1524 * This API consumes compressed data from the input buffer and generates 1525 * uncompressed data in the output buffer. This API is very similar to 1526 * cpaDcDecompressData() except it provides a CpaDcOpData structure for 1527 * passing additional input parameters not covered in cpaDcDecompressData(). 1528 * 1529 * @context 1530 * When called as an asynchronous function it cannot sleep. It can be 1531 * executed in a context that does not permit sleeping. 1532 * When called as a synchronous function it may sleep. It MUST NOT be 1533 * executed in a context that DOES NOT permit sleeping. 1534 * @assumptions 1535 * None 1536 * @sideEffects 1537 * None 1538 * @blocking 1539 * Yes when configured to operate in synchronous mode. 1540 * @reentrant 1541 * No 1542 * @threadSafe 1543 * Yes 1544 * 1545 * @param[in] dcInstance Target service instance. 1546 * @param[in,out] pSessionHandle Session handle. 1547 * @param[in] pSrcBuff Pointer to data buffer for compression. 1548 * @param[in] pDestBuff Pointer to buffer space for data 1549 * after decompression. 1550 * @param[in] pOpData Additional input parameters. 1551 * @param[in,out] pResults Pointer to results structure 1552 * @param[in] callbackTag User supplied value to help correlate 1553 * the callback with its associated 1554 * request. 1555 * 1556 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1557 * @retval CPA_STATUS_FAIL Function failed. 1558 * @retval CPA_STATUS_RETRY Resubmit the request. 1559 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1560 * @retval CPA_STATUS_RESOURCE Error related to system resources. 1561 * @retval CPA_DC_BAD_DATA The input data was not properly formed. 1562 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1563 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1564 * the request. 1565 * 1566 * @pre 1567 * pSessionHandle has been setup using cpaDcInitSession() 1568 * @post 1569 * pSessionHandle has session related state information 1570 * @note 1571 * This function passes control to the compression service for 1572 * decompression. The function returns the status from the service. 1573 * 1574 * @see 1575 * cpaDcDecompressData() 1576 * cpaDcCompressData2() 1577 * cpaDcCompressData() 1578 * 1579 *****************************************************************************/ 1580 CpaStatus 1581 cpaDcDecompressData2( CpaInstanceHandle dcInstance, 1582 CpaDcSessionHandle pSessionHandle, 1583 CpaBufferList *pSrcBuff, 1584 CpaBufferList *pDestBuff, 1585 CpaDcOpData *pOpData, 1586 CpaDcRqResults *pResults, 1587 void *callbackTag ); 1588 1589 /** 1590 ***************************************************************************** 1591 * @ingroup cpaDc 1592 * Generate compression header. 1593 * 1594 * @description 1595 * This API generates the gzip or the zlib header and stores it in the 1596 * output buffer. 1597 * 1598 * @context 1599 * This function may be call from any context. 1600 * @assumptions 1601 * None 1602 * @sideEffects 1603 * None 1604 * @blocking 1605 * No 1606 * @reentrant 1607 * No 1608 * @threadSafe 1609 * Yes 1610 * 1611 * @param[in,out] pSessionHandle Session handle. 1612 * @param[in] pDestBuff Pointer to data buffer where the 1613 * compression header will go. 1614 * @param[out] count Pointer to counter filled in with 1615 * header size. 1616 * 1617 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1618 * @retval CPA_STATUS_FAIL Function failed. 1619 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1620 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1621 * the request. 1622 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1623 * 1624 * @pre 1625 * pSessionHandle has been setup using cpaDcInitSession() 1626 * 1627 * @note 1628 * This function can output a 10 byte gzip header or 2 byte zlib header to 1629 * the destination buffer. The session properties are used to determine 1630 * the header type. To output a header the session must have been 1631 * initialized with CpaDcCompType CPA_DC_DEFLATE for any other value no 1632 * header is produced. To output a gzip header the session must have been 1633 * initialized with CpaDcChecksum CPA_DC_CRC32. To output a zlib header 1634 * the session must have been initialized with CpaDcChecksum CPA_DC_ADLER32. 1635 * For CpaDcChecksum CPA_DC_NONE no header is output. 1636 * 1637 * If the compression requires a gzip header, then this header requires 1638 * at a minimum the following fields, defined in RFC1952: 1639 * ID1: 0x1f 1640 * ID2: 0x8b 1641 * CM: Compression method = 8 for deflate 1642 * 1643 * The zlib header is defined in RFC1950 and this function must implement 1644 * as a minimum: 1645 * CM: four bit compression method - 8 is deflate with window size to 1646 * 32k 1647 * CINFO: four bit window size (see RFC1950 for details), 7 is 32k 1648 * window 1649 * FLG: defined as: 1650 * - Bits 0 - 4: check bits for CM, CINFO and FLG (see RFC1950) 1651 * - Bit 5: FDICT 0 = default, 1 is preset dictionary 1652 * - Bits 6 - 7: FLEVEL, compression level (see RFC 1950) 1653 * 1654 * The counter parameter will be set 1655 * to the number of bytes added to the buffer. The pData will be 1656 * not be changed. 1657 * 1658 * @see 1659 * None 1660 * 1661 *****************************************************************************/ 1662 CpaStatus 1663 cpaDcGenerateHeader( CpaDcSessionHandle pSessionHandle, 1664 CpaFlatBuffer *pDestBuff, Cpa32U *count ); 1665 1666 /** 1667 ***************************************************************************** 1668 * @ingroup cpaDc 1669 * Generate compression footer. 1670 * 1671 * @description 1672 * This API generates the footer for gzip or zlib and stores it in the 1673 * output buffer. 1674 * @context 1675 * This function may be call from any context. 1676 * @assumptions 1677 * None 1678 * @sideEffects 1679 * All session variables are reset 1680 * @blocking 1681 * No 1682 * @reentrant 1683 * No 1684 * @threadSafe 1685 * Yes 1686 * 1687 * @param[in,out] pSessionHandle Session handle. 1688 * @param[in] pDestBuff Pointer to data buffer where the 1689 * compression footer will go. 1690 * @param[in,out] pResults Pointer to results structure filled by 1691 * CpaDcCompressData. Updated with the 1692 * results of this API call 1693 * 1694 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1695 * @retval CPA_STATUS_FAIL Function failed. 1696 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1697 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1698 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1699 * the request. 1700 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1701 * 1702 * @pre 1703 * pSessionHandle has been setup using cpaDcInitSession() 1704 * pResults structure has been filled by CpaDcCompressData(). 1705 * 1706 * @note 1707 * Depending on the session variables, this function can add the 1708 * alder32 footer to the zlib compressed data as defined in RFC1950. If 1709 * required, it can also add the gzip footer, which is the crc32 of the 1710 * uncompressed data and the length of the uncompressed data. This 1711 * section is defined in RFC1952. The session variables used to determine 1712 * the header type are CpaDcCompType and CpaDcChecksum, see cpaDcGenerateHeader 1713 * for more details. 1714 * 1715 * An artifact of invoking this function for writing the footer data is 1716 * that all opaque session specific data is re-initialized. If the 1717 * compression level and file types are consistent, the upper level 1718 * application can continue processing compression requests using the 1719 * same session handle. 1720 * 1721 * The produced element of the pResults structure will be incremented by the 1722 * numbers bytes added to the buffer. The pointer to the buffer 1723 * will not be modified. 1724 * 1725 * This function is not supported for stateless sessions. 1726 * 1727 * @see 1728 * None 1729 * 1730 *****************************************************************************/ 1731 CpaStatus 1732 cpaDcGenerateFooter( CpaDcSessionHandle pSessionHandle, 1733 CpaFlatBuffer *pDestBuff, CpaDcRqResults *pResults ); 1734 1735 1736 /** 1737 ***************************************************************************** 1738 * @ingroup cpaDc 1739 * Retrieve statistics 1740 * 1741 * @description 1742 * This API retrieves the current statistics for a compression instance. 1743 * 1744 * @context 1745 * This function may be call from any context. 1746 * @assumptions 1747 * None 1748 * @sideEffects 1749 * None 1750 * @blocking 1751 * Yes 1752 * @reentrant 1753 * No 1754 * @threadSafe 1755 * Yes 1756 * 1757 * @param[in] dcInstance Instance handle. 1758 * @param[out] pStatistics Pointer to statistics structure. 1759 * 1760 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1761 * @retval CPA_STATUS_FAIL Function failed. 1762 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1763 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1764 * the request. 1765 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1766 * 1767 * @pre 1768 * None 1769 * @post 1770 * None 1771 * 1772 * @see 1773 * None 1774 * 1775 *****************************************************************************/ 1776 CpaStatus 1777 cpaDcGetStats( CpaInstanceHandle dcInstance, 1778 CpaDcStats *pStatistics ); 1779 1780 /*****************************************************************************/ 1781 /* Instance Discovery Functions */ 1782 1783 /** 1784 ***************************************************************************** 1785 * @ingroup cpaDc 1786 * Get the number of device instances that are supported by the API 1787 * implementation. 1788 * 1789 * @description 1790 * 1791 * This function will get the number of device instances that are supported 1792 * by an implementation of the compression API. This number is then used to 1793 * determine the size of the array that must be passed to 1794 * cpaDcGetInstances(). 1795 * 1796 * @context 1797 * This function MUST NOT be called from an interrupt context as it MAY 1798 * sleep. 1799 * @assumptions 1800 * None 1801 * @sideEffects 1802 * None 1803 * @blocking 1804 * This function is synchronous and blocking. 1805 * @reentrant 1806 * No 1807 * @threadSafe 1808 * Yes 1809 * 1810 * @param[out] pNumInstances Pointer to where the number of 1811 * instances will be written. 1812 * 1813 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1814 * @retval CPA_STATUS_FAIL Function failed. 1815 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1816 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1817 * 1818 * @pre 1819 * None 1820 * @post 1821 * None 1822 * @note 1823 * This function operates in a synchronous manner and no asynchronous 1824 * callback will be generated 1825 * 1826 * @see 1827 * cpaDcGetInstances 1828 * 1829 *****************************************************************************/ 1830 CpaStatus 1831 cpaDcGetNumInstances(Cpa16U* pNumInstances); 1832 1833 /** 1834 ***************************************************************************** 1835 * @ingroup cpaDc 1836 * Get the handles to the device instances that are supported by the 1837 * API implementation. 1838 * 1839 * @description 1840 * 1841 * This function will return handles to the device instances that are 1842 * supported by an implementation of the compression API. These instance 1843 * handles can then be used as input parameters with other compression API 1844 * functions. 1845 * 1846 * This function will populate an array that has been allocated by the 1847 * caller. The size of this API is determined by the 1848 * cpaDcGetNumInstances() function. 1849 * 1850 * @context 1851 * This function MUST NOT be called from an interrupt context as it MAY 1852 * sleep. 1853 * @assumptions 1854 * None 1855 * @sideEffects 1856 * None 1857 * @blocking 1858 * This function is synchronous and blocking. 1859 * @reentrant 1860 * No 1861 * @threadSafe 1862 * Yes 1863 * 1864 * @param[in] numInstances Size of the array. 1865 * @param[out] dcInstances Pointer to where the instance 1866 * handles will be written. 1867 * 1868 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1869 * @retval CPA_STATUS_FAIL Function failed. 1870 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1871 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1872 * 1873 * @pre 1874 * None 1875 * @post 1876 * None 1877 * @note 1878 * This function operates in a synchronous manner and no asynchronous 1879 * callback will be generated 1880 * 1881 * @see 1882 * cpaDcGetInstances 1883 * 1884 *****************************************************************************/ 1885 CpaStatus 1886 cpaDcGetInstances(Cpa16U numInstances, 1887 CpaInstanceHandle* dcInstances); 1888 1889 /** 1890 ***************************************************************************** 1891 * @ingroup cpaDc 1892 * Compression Component utility function to determine the number of 1893 * intermediate buffers required by an implementation. 1894 * 1895 * @description 1896 * This function will determine the number of intermediate buffer lists 1897 * required by an implementation for a compression instance. These buffers 1898 * should then be allocated and provided when calling @ref cpaDcStartInstance() 1899 * to start a compression instance that will use dynamic compression. 1900 * 1901 * @context 1902 * This function may sleep, and MUST NOT be called in interrupt context. 1903 * @assumptions 1904 * None 1905 * @sideEffects 1906 * None 1907 * @blocking 1908 * This function is synchronous and blocking. 1909 * @reentrant 1910 * No 1911 * @threadSafe 1912 * Yes 1913 * @param[in,out] instanceHandle Handle to an instance of this API to be 1914 * initialized. 1915 * @param[out] pNumBuffers When the function returns, this will 1916 * specify the number of buffer lists that 1917 * should be used as intermediate buffers 1918 * when calling cpaDcStartInstance(). 1919 * 1920 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1921 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 1922 * is to shutdown and restart. 1923 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1924 * 1925 * @pre 1926 * None 1927 * @post 1928 * None 1929 * @note 1930 * Note that this is a synchronous function and has no completion callback 1931 * associated with it. 1932 * 1933 * @see 1934 * cpaDcStartInstance() 1935 * 1936 *****************************************************************************/ 1937 CpaStatus 1938 cpaDcGetNumIntermediateBuffers(CpaInstanceHandle instanceHandle, 1939 Cpa16U *pNumBuffers); 1940 1941 /** 1942 ***************************************************************************** 1943 * @ingroup cpaDc 1944 * Compression Component Initialization and Start function. 1945 * 1946 * @description 1947 * This function will initialize and start the compression component. 1948 * It MUST be called before any other compress function is called. This 1949 * function SHOULD be called only once (either for the very first time, 1950 * or after an cpaDcStopInstance call which succeeded) per instance. 1951 * Subsequent calls will have no effect. 1952 * 1953 * If required by an implementation, this function can be provided with 1954 * instance specific intermediate buffers. The intent is to provide an 1955 * instance specific location to store intermediate results during dynamic 1956 * instance Huffman tree compression requests. The memory should be 1957 * accessible by the compression engine. The buffers are to support 1958 * deflate compression with dynamic Huffman Trees. Each buffer list 1959 * should be similar in size to twice the destination buffer size passed 1960 * to the compress API. The number of intermediate buffer lists may vary 1961 * between implementations and so @ref cpaDcGetNumIntermediateBuffers() 1962 * should be called first to determine the number of intermediate 1963 * buffers required by the implementation. 1964 * 1965 * If not required, this parameter can be passed in as NULL. 1966 * 1967 * @context 1968 * This function may sleep, and MUST NOT be called in interrupt context. 1969 * @assumptions 1970 * None 1971 * @sideEffects 1972 * None 1973 * @blocking 1974 * This function is synchronous and blocking. 1975 * @reentrant 1976 * No 1977 * @threadSafe 1978 * Yes 1979 * @param[in,out] instanceHandle Handle to an instance of this API to be 1980 * initialized. 1981 * @param[in] numBuffers Number of buffer lists represented by 1982 * the pIntermediateBuffers parameter. 1983 * Note: @ref cpaDcGetNumIntermediateBuffers() 1984 * can be used to determine the number of 1985 * intermediate buffers that an implementation 1986 * requires. 1987 * @param[in] pIntermediateBuffers Optional pointer to Instance specific 1988 * DRAM buffer. 1989 * 1990 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1991 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 1992 * is to shutdown and restart. 1993 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1994 * 1995 * @pre 1996 * None 1997 * @post 1998 * None 1999 * @note 2000 * Note that this is a synchronous function and has no completion callback 2001 * associated with it. 2002 * 2003 * @see 2004 * cpaDcStopInstance() 2005 * cpaDcGetNumIntermediateBuffers() 2006 * 2007 *****************************************************************************/ 2008 CpaStatus 2009 cpaDcStartInstance(CpaInstanceHandle instanceHandle, 2010 Cpa16U numBuffers, 2011 CpaBufferList **pIntermediateBuffers); 2012 2013 /** 2014 ***************************************************************************** 2015 * @ingroup cpaDc 2016 * Compress Component Stop function. 2017 * 2018 * @description 2019 * This function will stop the Compression component and free 2020 * all system resources associated with it. The client MUST ensure that 2021 * all outstanding operations have completed before calling this function. 2022 * The recommended approach to ensure this is to deregister all session or 2023 * callback handles before calling this function. If outstanding 2024 * operations still exist when this function is invoked, the callback 2025 * function for each of those operations will NOT be invoked and the 2026 * shutdown will continue. If the component is to be restarted, then a 2027 * call to cpaDcStartInstance is required. 2028 * 2029 * @context 2030 * This function may sleep, and so MUST NOT be called in interrupt 2031 * context. 2032 * @assumptions 2033 * None 2034 * @sideEffects 2035 * None 2036 * @blocking 2037 * This function is synchronous and blocking. 2038 * @reentrant 2039 * No 2040 * @threadSafe 2041 * Yes 2042 * @param[in] instanceHandle Handle to an instance of this API to be 2043 * shutdown. 2044 * 2045 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2046 * @retval CPA_STATUS_FAIL Function failed. Suggested course of action 2047 * is to ensure requests are not still being 2048 * submitted and that all sessions are 2049 * deregistered. If this does not help, then 2050 * forcefully remove the component from the 2051 * system. 2052 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2053 * 2054 * @pre 2055 * The component has been initialized via cpaDcStartInstance 2056 * @post 2057 * None 2058 * @note 2059 * Note that this is a synchronous function and has no completion callback 2060 * associated with it. 2061 * 2062 * @see 2063 * cpaDcStartInstance() 2064 * 2065 *****************************************************************************/ 2066 CpaStatus 2067 cpaDcStopInstance(CpaInstanceHandle instanceHandle); 2068 2069 2070 /** 2071 ***************************************************************************** 2072 * @ingroup cpaDc 2073 * Function to get information on a particular instance. 2074 * 2075 * @description 2076 * This function will provide instance specific information through a 2077 * @ref CpaInstanceInfo2 structure. 2078 * 2079 * @context 2080 * This function will be executed in a context that requires that sleeping 2081 * MUST NOT be permitted. 2082 * @assumptions 2083 * None 2084 * @sideEffects 2085 * None 2086 * @blocking 2087 * Yes 2088 * @reentrant 2089 * No 2090 * @threadSafe 2091 * Yes 2092 * 2093 * @param[in] instanceHandle Handle to an instance of this API to be 2094 * initialized. 2095 * @param[out] pInstanceInfo2 Pointer to the memory location allocated by 2096 * the client into which the CpaInstanceInfo2 2097 * structure will be written. 2098 * 2099 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2100 * @retval CPA_STATUS_FAIL Function failed. 2101 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2102 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2103 * 2104 * @pre 2105 * The client has retrieved an instanceHandle from successive calls to 2106 * @ref cpaDcGetNumInstances and @ref cpaDcGetInstances. 2107 * @post 2108 * None 2109 * @note 2110 * None 2111 * @see 2112 * cpaDcGetNumInstances, 2113 * cpaDcGetInstances, 2114 * CpaInstanceInfo2 2115 * 2116 *****************************************************************************/ 2117 CpaStatus 2118 cpaDcInstanceGetInfo2(const CpaInstanceHandle instanceHandle, 2119 CpaInstanceInfo2 * pInstanceInfo2); 2120 2121 /*****************************************************************************/ 2122 /* Instance Notification Functions */ 2123 /*****************************************************************************/ 2124 /** 2125 ***************************************************************************** 2126 * @ingroup cpaDc 2127 * Callback function for instance notification support. 2128 * 2129 * @description 2130 * This is the prototype for the instance notification callback function. 2131 * The callback function is passed in as a parameter to the 2132 * @ref cpaDcInstanceSetNotificationCb function. 2133 * 2134 * @context 2135 * This function will be executed in a context that requires that sleeping 2136 * MUST NOT be permitted. 2137 * @assumptions 2138 * None 2139 * @sideEffects 2140 * None 2141 * @blocking 2142 * No 2143 * @reentrant 2144 * No 2145 * @threadSafe 2146 * Yes 2147 * 2148 * @param[in] instanceHandle Instance handle. 2149 * @param[in] pCallbackTag Opaque value provided by user while making 2150 * individual function calls. 2151 * @param[in] instanceEvent The event that will trigger this function to 2152 * get invoked. 2153 * 2154 * @retval 2155 * None 2156 * @pre 2157 * Component has been initialized and the notification function has been 2158 * set via the cpaDcInstanceSetNotificationCb function. 2159 * @post 2160 * None 2161 * @note 2162 * None 2163 * @see 2164 * cpaDcInstanceSetNotificationCb(), 2165 * 2166 *****************************************************************************/ 2167 typedef void (*CpaDcInstanceNotificationCbFunc)( 2168 const CpaInstanceHandle instanceHandle, 2169 void * pCallbackTag, 2170 const CpaInstanceEvent instanceEvent); 2171 2172 /** 2173 ***************************************************************************** 2174 * @ingroup cpaDc 2175 * Subscribe for instance notifications. 2176 * 2177 * @description 2178 * Clients of the CpaDc interface can subscribe for instance notifications 2179 * by registering a @ref CpaDcInstanceNotificationCbFunc function. 2180 * 2181 * @context 2182 * This function may be called from any context. 2183 * @assumptions 2184 * None 2185 * @sideEffects 2186 * None 2187 * @blocking 2188 * No 2189 * @reentrant 2190 * No 2191 * @threadSafe 2192 * Yes 2193 * 2194 * @param[in] instanceHandle Instance handle. 2195 * @param[in] pInstanceNotificationCb Instance notification callback 2196 * function pointer. 2197 * @param[in] pCallbackTag Opaque value provided by user while 2198 * making individual function calls. 2199 * 2200 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2201 * @retval CPA_STATUS_FAIL Function failed. 2202 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2203 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2204 * 2205 * @pre 2206 * Instance has been initialized. 2207 * @post 2208 * None 2209 * @note 2210 * None 2211 * @see 2212 * CpaDcInstanceNotificationCbFunc 2213 * 2214 *****************************************************************************/ 2215 CpaStatus 2216 cpaDcInstanceSetNotificationCb( 2217 const CpaInstanceHandle instanceHandle, 2218 const CpaDcInstanceNotificationCbFunc pInstanceNotificationCb, 2219 void *pCallbackTag); 2220 2221 2222 /** 2223 ***************************************************************************** 2224 * @ingroup cpaDc 2225 * Get the size of the memory required to hold the session information. 2226 * 2227 * @description 2228 * 2229 * The client of the Data Compression API is responsible for 2230 * allocating sufficient memory to hold session information and the context 2231 * data. This function provides a means for determining the size of the 2232 * session information and the size of the context data. 2233 * 2234 * @context 2235 * No restrictions 2236 * @assumptions 2237 * None 2238 * @sideEffects 2239 * None 2240 * @blocking 2241 * No 2242 * @reentrant 2243 * No 2244 * @threadSafe 2245 * Yes 2246 * 2247 * @param[in] dcInstance Instance handle. 2248 * @param[in] pSessionData Pointer to a user instantiated structure 2249 * containing session data. 2250 * @param[out] pSessionSize On return, this parameter will be the size 2251 * of the memory that will be 2252 * required by cpaDcInitSession() for session 2253 * data. 2254 * @param[out] pContextSize On return, this parameter will be the size 2255 * of the memory that will be required 2256 * for context data. Context data is 2257 * save/restore data including history and 2258 * any implementation specific data that is 2259 * required for a save/restore operation. 2260 * 2261 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2262 * @retval CPA_STATUS_FAIL Function failed. 2263 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2264 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2265 * 2266 * @pre 2267 * None 2268 * @post 2269 * None 2270 * @note 2271 * Only a synchronous version of this function is provided. 2272 * 2273 * It is expected that context data is comprised of the history and 2274 * any data stores that are specific to the history such as linked 2275 * lists or hash tables. 2276 * For stateless sessions the context size returned from this function 2277 * will be zero. For stateful sessions the context size returned will 2278 * depend on the session setup data. 2279 * 2280 * Session data is expected to include interim checksum values, various 2281 * counters and other session related data that needs to persist 2282 * between invocations. 2283 * For a given implementation of this API, it is safe to assume that 2284 * cpaDcGetSessionSize() will always return the same session size and 2285 * that the size will not be different for different setup data 2286 * parameters. However, it should be noted that the size may change: 2287 * (1) between different implementations of the API (e.g. between software 2288 * and hardware implementations or between different hardware 2289 * implementations) 2290 * (2) between different releases of the same API implementation. 2291 * 2292 * @see 2293 * cpaDcInitSession() 2294 * 2295 *****************************************************************************/ 2296 CpaStatus 2297 cpaDcGetSessionSize(CpaInstanceHandle dcInstance, 2298 CpaDcSessionSetupData* pSessionData, 2299 Cpa32U* pSessionSize, Cpa32U* pContextSize ); 2300 2301 /** 2302 ***************************************************************************** 2303 * @ingroup cpaDc 2304 * Function to return the size of the memory which must be allocated for 2305 * the pPrivateMetaData member of CpaBufferList. 2306 * 2307 * @description 2308 * This function is used to obtain the size (in bytes) required to allocate 2309 * a buffer descriptor for the pPrivateMetaData member in the 2310 * CpaBufferList structure. 2311 * Should the function return zero then no meta data is required for the 2312 * buffer list. 2313 * 2314 * @context 2315 * This function may be called from any context. 2316 * @assumptions 2317 * None 2318 * @sideEffects 2319 * None 2320 * @blocking 2321 * No 2322 * @reentrant 2323 * No 2324 * @threadSafe 2325 * Yes 2326 * 2327 * @param[in] instanceHandle Handle to an instance of this API. 2328 * @param[in] numBuffers The number of pointers in the CpaBufferList. 2329 * This is the maximum number of CpaFlatBuffers 2330 * which may be contained in this CpaBufferList. 2331 * @param[out] pSizeInBytes Pointer to the size in bytes of memory to be 2332 * allocated when the client wishes to allocate 2333 * a cpaFlatBuffer. 2334 * 2335 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2336 * @retval CPA_STATUS_FAIL Function failed. 2337 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2338 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2339 * 2340 * @pre 2341 * None 2342 * @post 2343 * None 2344 * @note 2345 * None 2346 * @see 2347 * cpaDcGetInstances() 2348 * 2349 *****************************************************************************/ 2350 CpaStatus 2351 cpaDcBufferListGetMetaSize(const CpaInstanceHandle instanceHandle, 2352 Cpa32U numBuffers, 2353 Cpa32U *pSizeInBytes); 2354 2355 2356 /** 2357 ***************************************************************************** 2358 * @ingroup cpaDc 2359 * Function to return a string indicating the specific error that occurred 2360 * within the system. 2361 * 2362 * @description 2363 * When a function returns any error including CPA_STATUS_SUCCESS, the 2364 * client can invoke this function to get a string which describes the 2365 * general error condition, and if available additional information on 2366 * the specific error. 2367 * The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for the buffer 2368 * string. 2369 * 2370 * @context 2371 * This function may be called from any context. 2372 * @assumptions 2373 * None 2374 * @sideEffects 2375 * None 2376 * @blocking 2377 * No 2378 * @reentrant 2379 * No 2380 * @threadSafe 2381 * Yes 2382 * 2383 * @param[in] dcInstance Handle to an instance of this API. 2384 * @param[in] errStatus The error condition that occurred. 2385 * @param[in,out] pStatusText Pointer to the string buffer that will 2386 * be updated with the status text. The invoking 2387 * application MUST allocate this buffer to be 2388 * exactly CPA_STATUS_MAX_STR_LENGTH_IN_BYTES. 2389 * 2390 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2391 * @retval CPA_STATUS_FAIL Function failed. Note, in this scenario 2392 * it is INVALID to call this function a 2393 * second time. 2394 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2395 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2396 * 2397 * @pre 2398 * None 2399 * @post 2400 * None 2401 * @note 2402 * None 2403 * @see 2404 * CpaStatus 2405 * 2406 *****************************************************************************/ 2407 2408 CpaStatus 2409 cpaDcGetStatusText(const CpaInstanceHandle dcInstance, 2410 const CpaStatus errStatus, 2411 Cpa8S * pStatusText); 2412 2413 2414 /** 2415 ***************************************************************************** 2416 * @ingroup cpaDc 2417 * Set Address Translation function 2418 * 2419 * @description 2420 * This function is used to set the virtual to physical address 2421 * translation routine for the instance. The specified routine 2422 * is used by the instance to perform any required translation of 2423 * a virtual address to a physical address. If the application 2424 * does not invoke this function, then the instance will use its 2425 * default method, such as virt2phys, for address translation. 2426 * 2427 * @assumptions 2428 * None 2429 * @sideEffects 2430 * None 2431 * @blocking 2432 * This function is synchronous and blocking. 2433 * @reentrant 2434 * No 2435 * @threadSafe 2436 * Yes 2437 * 2438 * @param[in] instanceHandle Data Compression API instance handle. 2439 * @param[in] virtual2Physical Routine that performs virtual to 2440 * physical address translation. 2441 * @retval CPA_STATUS_SUCCESS Function executed successfully. 2442 * @retval CPA_STATUS_FAIL Function failed. 2443 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 2444 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 2445 * 2446 * @pre 2447 * None 2448 * @post 2449 * None 2450 * @see 2451 * None 2452 * 2453 *****************************************************************************/ 2454 CpaStatus 2455 cpaDcSetAddressTranslation(const CpaInstanceHandle instanceHandle, 2456 CpaVirtualToPhysical virtual2Physical); 2457 #ifdef __cplusplus 2458 } /* close the extern "C" { */ 2459 #endif 2460 2461 #endif /* CPA_DC_H */ 2462