1 /*************************************************************************** 2 * 3 * BSD LICENSE 4 * 5 * Copyright(c) 2007-2023 Intel Corporation. All rights reserved. 6 * All rights reserved. 7 * 8 * Redistribution and use in source and binary forms, with or without 9 * modification, are permitted provided that the following conditions 10 * are met: 11 * 12 * * Redistributions of source code must retain the above copyright 13 * notice, this list of conditions and the following disclaimer. 14 * * Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in 16 * the documentation and/or other materials provided with the 17 * distribution. 18 * * Neither the name of Intel Corporation nor the names of its 19 * contributors may be used to endorse or promote products derived 20 * from this software without specific prior written permission. 21 * 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 23 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 24 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 25 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 26 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 27 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 28 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 30 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 33 * 34 * 35 ***************************************************************************/ 36 37 /* 38 ***************************************************************************** 39 * Doxygen group definitions 40 ****************************************************************************/ 41 42 /** 43 ***************************************************************************** 44 * @file cpa_dc_dp.h 45 * 46 * @defgroup cpaDcDp Data Compression Data Plane API 47 * 48 * @ingroup cpaDc 49 * 50 * @description 51 * These data structures and functions specify the Data Plane API 52 * for compression and decompression operations. 53 * 54 * This API is recommended for data plane applications, in which the 55 * cost of offload - that is, the cycles consumed by the driver in 56 * sending requests to the hardware, and processing responses - needs 57 * to be minimized. In particular, use of this API is recommended 58 * if the following constraints are acceptable to your application: 59 * 60 * - Thread safety is not guaranteed. Each software thread should 61 * have access to its own unique instance (CpaInstanceHandle) to 62 * avoid contention. 63 * - Polling is used, rather than interrupts (which are expensive). 64 * Implementations of this API will provide a function (not 65 * defined as part of this API) to read responses from the hardware 66 * response queue and dispatch callback functions, as specified on 67 * this API. 68 * - Buffers and buffer lists are passed using physical addresses, 69 * to avoid virtual to physical address translation costs. 70 * - The ability to enqueue one or more requests without submitting 71 * them to the hardware allows for certain costs to be amortized 72 * across multiple requests. 73 * - Only asynchronous invocation is supported. 74 * - There is no support for partial packets. 75 * - Implementations may provide certain features as optional at 76 * build time, such as atomic counters. 77 * - There is no support for stateful operations. 78 * - The "default" instance (CPA_INSTANCE_HANDLE_SINGLE) is not 79 * supported on this API. The specific handle should be obtained 80 * using the instance discovery functions (@ref cpaDcGetNumInstances, 81 * @ref cpaDcGetInstances). 82 * 83 *****************************************************************************/ 84 85 #ifndef CPA_DC_DP_H 86 #define CPA_DC_DP_H 87 88 #ifdef __cplusplus 89 extern "C" { 90 #endif 91 92 #include "cpa_dc.h" 93 94 /** 95 ***************************************************************************** 96 * @ingroup cpaDcDp 97 * Decompression partial read data. 98 * @description 99 * This structure contains configuration related to requesting 100 * specific chunk of decompression data. 101 * 102 ****************************************************************************/ 103 typedef struct _CpaDcDpPartialReadData { 104 Cpa32U bufferOffset; 105 /**< Number of bytes to skip in a destination buffer (or buffers list) 106 * before writing. At this point only zero is supported. 107 */ 108 Cpa32U dataOffset; 109 /**< The offset in the decompressed data of the first byte written to 110 * the destination buffer. The data offset length should be an integer 111 * multiple of 4KB in order to achieve the best performance. 112 */ 113 Cpa32U length; 114 /**< Size of requested decompressed data chunk. The length should be 115 * an integer multiple of 4KB in order to achieve the best performance. 116 */ 117 } CpaDcDpPartialReadData; 118 119 /** 120 ***************************************************************************** 121 * @ingroup cpaDcDp 122 * Operation Data for compression data plane API. 123 * 124 * @description 125 * This structure contains data relating to a request to perform 126 * compression processing on one or more data buffers. 127 * 128 * The physical memory to which this structure points should be 129 * at least 8-byte aligned. 130 * 131 * All reserved fields SHOULD NOT be written or read by the 132 * calling code. 133 * 134 * @see 135 * cpaDcDpEnqueueOp, cpaDcDpEnqueueOpBatch 136 ****************************************************************************/ 137 typedef struct _CpaDcDpOpData 138 { 139 Cpa64U reserved0; 140 /**< Reserved for internal use. Source code should not read or write 141 * this field. 142 */ 143 Cpa32U bufferLenToCompress; 144 /**< The number of bytes from the source buffer to compress. This must be 145 * less than, or more typically equal to, the total size of the source 146 * buffer (or buffer list). 147 */ 148 149 Cpa32U bufferLenForData; 150 /**< The maximum number of bytes that should be written to the destination 151 * buffer. This must be less than, or more typically equal to, the total 152 * size of the destination buffer (or buffer list). 153 */ 154 155 Cpa64U reserved1; 156 /**< Reserved for internal use. Source code should not read or write */ 157 158 Cpa64U reserved2; 159 /**< Reserved for internal use. Source code should not read or write */ 160 161 Cpa64U reserved3; 162 /**< Reserved for internal use. Source code should not read or write */ 163 164 CpaDcRqResults results; 165 /**< Results of the operation. Contents are valid upon completion. */ 166 167 CpaInstanceHandle dcInstance; 168 /**< Instance to which the request is to be enqueued */ 169 170 CpaDcSessionHandle pSessionHandle; 171 /**< DC Session associated with the stream of requests. 172 * This field is only valid when using the session based API functions. 173 * This field must be set to NULL if the application wishes to use 174 * the No-Session (Ns) API. 175 */ 176 177 CpaPhysicalAddr srcBuffer; 178 /**< Physical address of the source buffer on which to operate. 179 * This is either the location of the data, of length srcBufferLen; or, 180 * if srcBufferLen has the special value @ref CPA_DP_BUFLIST, then 181 * srcBuffer contains the location where a @ref CpaPhysBufferList is 182 * stored. 183 */ 184 185 Cpa32U srcBufferLen; 186 /**< If the source buffer is a "flat buffer", then this field 187 * specifies the size of the buffer, in bytes. If the source buffer 188 * is a "buffer list" (of type @ref CpaPhysBufferList), then this field 189 * should be set to the value @ref CPA_DP_BUFLIST. 190 */ 191 192 CpaPhysicalAddr destBuffer; 193 /**< Physical address of the destination buffer on which to operate. 194 * This is either the location of the data, of length destBufferLen; or, 195 * if destBufferLen has the special value @ref CPA_DP_BUFLIST, then 196 * destBuffer contains the location where a @ref CpaPhysBufferList is 197 * stored. 198 */ 199 200 Cpa32U destBufferLen; 201 /**< If the destination buffer is a "flat buffer", then this field 202 * specifies the size of the buffer, in bytes. If the destination buffer 203 * is a "buffer list" (of type @ref CpaPhysBufferList), then this field 204 * should be set to the value @ref CPA_DP_BUFLIST. 205 */ 206 207 CpaDcSessionDir sessDirection; 208 /**<Session direction indicating whether session is used for 209 * compression, decompression. For the DP implementation, 210 * CPA_DC_DIR_COMBINED is not a valid selection. 211 */ 212 213 CpaBoolean compressAndVerify; 214 /**< If set to true, for compression operations, the implementation 215 * will verify that compressed data, generated by the compression 216 * operation, can be successfully decompressed. 217 * This behavior is only supported for stateless compression. 218 * This behavior is only supported on instances that support the 219 * compressAndVerify capability. */ 220 221 CpaBoolean compressAndVerifyAndRecover; 222 /**< If set to true, for compression operations, the implementation 223 * will automatically recover from a compressAndVerify error. 224 * This behavior is only supported for stateless compression. 225 * This behavior is only supported on instances that support the 226 * compressAndVerifyAndRecover capability. 227 * The compressAndVerify field in CpaDcOpData MUST be set to CPA_TRUE 228 * if compressAndVerifyAndRecover is set to CPA_TRUE. */ 229 230 CpaStatus responseStatus; 231 /**< Status of the operation. Valid values are CPA_STATUS_SUCCESS, 232 * CPA_STATUS_FAIL and CPA_STATUS_UNSUPPORTED. 233 */ 234 235 CpaPhysicalAddr thisPhys; 236 /**< Physical address of this data structure */ 237 238 void* pCallbackTag; 239 /**< Opaque data that will be returned to the client in the function 240 * completion callback. 241 * 242 * This opaque data is not used by the implementation of the API, 243 * but is simply returned as part of the asynchronous response. 244 * It may be used to store information that might be useful when 245 * processing the response later. 246 */ 247 248 CpaDcNsSetupData *pSetupData; 249 /**< Pointer to the No-session (Ns) Setup data for configuration of this 250 * request. 251 * 252 * This @ref CpaDcNsSetupData structure must be initialised when using the 253 * Data Plane No-Session (Ns) API. Otherwise it should be set to NULL. 254 * When initialized, the existing Data Plane API functions can be used 255 * as is. 256 */ 257 258 } CpaDcDpOpData; 259 260 /** 261 ***************************************************************************** 262 * @ingroup cpaDcDp 263 * Definition of callback function for compression data plane API. 264 * 265 * @description 266 * This is the callback function prototype. The callback function is 267 * registered by the application using the @ref cpaDcDpRegCbFunc 268 * function call, and called back on completion of asynchronous 269 * requests made via calls to @ref cpaDcDpEnqueueOp or @ref 270 * cpaDcDpEnqueueOpBatch. 271 * 272 * @context 273 * This callback function can be executed in a context that DOES NOT 274 * permit sleeping to occur. 275 * @assumptions 276 * None 277 * @sideEffects 278 * None 279 * @reentrant 280 * No 281 * @threadSafe 282 * No 283 * 284 * @param[in] pOpData Pointer to the @ref CpaDcDpOpData object which 285 * was supplied as part of the original request. 286 287 * @return 288 * None 289 * @pre 290 * Instance has been initialized. 291 * Callback has been registered with @ref cpaDcDpRegCbFunc. 292 * @post 293 * None 294 * @note 295 * None 296 * @see 297 * @ref cpaDcDpRegCbFunc 298 *****************************************************************************/ 299 typedef void (*CpaDcDpCallbackFn)(CpaDcDpOpData *pOpData); 300 301 /** 302 ***************************************************************************** 303 * @ingroup cpaDc 304 * Get the size of the memory required to hold the data plane 305 * session information. 306 * 307 * @description 308 * 309 * The client of the Data Compression API is responsible for 310 * allocating sufficient memory to hold session information. This 311 * function provides a means for determining the size of the session 312 * information and statistics information. 313 * 314 * @context 315 * No restrictions 316 * @assumptions 317 * None 318 * @sideEffects 319 * None 320 * @blocking 321 * Yes 322 * @reentrant 323 * No 324 * @threadSafe 325 * Yes 326 * 327 * @param[in] dcInstance Instance handle. 328 * @param[in] pSessionData Pointer to a user instantiated structure 329 * containing session data. 330 * @param[out] pSessionSize On return, this parameter will be the size 331 * of the memory that will be 332 * required by cpaDcInitSession() for session 333 * data. 334 * 335 * @retval CPA_STATUS_SUCCESS Function executed successfully. 336 * @retval CPA_STATUS_FAIL Function failed. 337 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 338 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 339 * 340 * @pre 341 * None 342 * @post 343 * None 344 * @note 345 * Only a synchronous version of this function is provided. 346 * 347 * Session data is expected to include interim checksum values, various 348 * counters and other session related data that needs to persist between 349 * invocations. 350 * For a given implementation of this API, it is safe to assume that 351 * cpaDcDpGetSessionSize() will always return the same session size and 352 * that the size will not be different for different setup data 353 * parameters. However, it should be noted that the size may change: 354 * (1) between different implementations of the API (e.g. between software 355 * and hardware implementations or between different hardware 356 * implementations) 357 * (2) between different releases of the same API implementation 358 * 359 * @see 360 * cpaDcDpInitSession() 361 * 362 *****************************************************************************/ 363 CpaStatus 364 cpaDcDpGetSessionSize(CpaInstanceHandle dcInstance, 365 CpaDcSessionSetupData* pSessionData, 366 Cpa32U* pSessionSize ); 367 368 369 /** 370 ***************************************************************************** 371 * @ingroup cpaDcDp 372 * Initialize compression or decompression data plane session. 373 * 374 * @description 375 * This function is used to initialize a compression/decompression session. 376 * A single session can be used for both compression and decompression 377 * requests. Clients MUST register a callback 378 * function for the compression service using this function. 379 * This function returns a unique session handle each time this function 380 * is invoked. 381 * The order of the callbacks are guaranteed to be in the same order the 382 * compression or decompression requests were submitted for each session, 383 * so long as a single thread of execution is used for job submission. 384 * 385 * @context 386 * This function may be called from any context. 387 * @assumptions 388 * None 389 * @sideEffects 390 * None 391 * @blocking 392 * Yes 393 * @reentrant 394 * No 395 * @threadSafe 396 * Yes 397 * 398 * @param[in] dcInstance Instance handle derived from discovery 399 * functions. 400 * @param[in,out] pSessionHandle Pointer to a session handle. 401 * @param[in,out] pSessionData Pointer to a user instantiated structure 402 * containing session data. 403 * 404 * @retval CPA_STATUS_SUCCESS Function executed successfully. 405 * @retval CPA_STATUS_FAIL Function failed. 406 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 407 * @retval CPA_STATUS_RESOURCE Error related to system resources. 408 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 409 * the request. 410 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 411 * 412 * @pre 413 * dcInstance has been started using @ref cpaDcStartInstance. 414 * @post 415 * None 416 * @note 417 * Only a synchronous version of this function is provided. 418 * 419 * This initializes opaque data structures in the session handle. Data 420 * compressed under this session will be compressed to the level 421 * specified in the pSessionData structure. Lower compression level 422 * numbers indicate a request for faster compression at the 423 * expense of compression ratio. Higher compression level numbers 424 * indicate a request for higher compression ratios at the expense of 425 * execution time. 426 * 427 * The session is opaque to the user application and the session handle 428 * contains job specific data. 429 * 430 * The window size specified in the pSessionData must match exactly 431 * one of the supported window sizes specified in the capability 432 * structure. If a bi-directional session is being initialized, then 433 * the window size must be valid for both compress and decompress. 434 * 435 * Note stateful sessions are not supported by this API. 436 * 437 * @see 438 * None 439 * 440 *****************************************************************************/ 441 CpaStatus 442 cpaDcDpInitSession( CpaInstanceHandle dcInstance, 443 CpaDcSessionHandle pSessionHandle, 444 CpaDcSessionSetupData *pSessionData ); 445 446 447 /** 448 ***************************************************************************** 449 * @ingroup cpaDc 450 * Compression Session Update Function. 451 * 452 * @description 453 * This function is used to modify some select compression parameters 454 * of a previously initialized session handlei for a data plane session. 455 * Th update will fail if resources required for the new session settings 456 * are not available. Specifically, this function may fail if no 457 * intermediate buffers are associated with the instance, and the 458 * intended change would require these buffers. 459 * This function can be called at any time after a successful call of 460 * cpaDcDpInitSession(). 461 * This function does not change the parameters to compression request 462 * already in flight. 463 * 464 * @context 465 * This is a synchronous function that cannot sleep. It can be 466 * executed in a context that does not permit sleeping. 467 * @assumptions 468 * None 469 * @sideEffects 470 * None 471 * @blocking 472 * No. 473 * @reentrant 474 * No 475 * @threadSafe 476 * No 477 * 478 * @param[in] dcInstance Instance handle. 479 * @param[in,out] pSessionHandle Session handle. 480 * @param[in] pSessionUpdateData Session Data. 481 * 482 * @retval CPA_STATUS_SUCCESS Function executed successfully. 483 * @retval CPA_STATUS_FAIL Function failed. 484 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 485 * @retval CPA_STATUS_RESOURCE Error related to system resources. 486 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 487 * Resubmit the request 488 * 489 * @pre 490 * The component has been initialized via cpaDcStartInstance function. 491 * The session has been initialized via cpaDcDpInitSession function. 492 * @post 493 * None 494 * @note 495 * This is a synchronous function and has no completion callback 496 * associated with it. 497 * 498 * @see 499 * cpaDcDpInitSession() 500 * 501 *****************************************************************************/ 502 CpaStatus cpaDcDpUpdateSession( const CpaInstanceHandle dcInstance, 503 CpaDcSessionHandle pSessionHandle, 504 CpaDcSessionUpdateData *pSessionUpdateData ); 505 506 /** 507 ***************************************************************************** 508 * @ingroup cpaDc 509 * Compression Data Plane Session Remove Function. 510 * 511 * @description 512 * This function will remove a previously initialized session handle 513 * and the installed callback handler function. Removal will fail if 514 * outstanding calls still exist for the initialized session handle. 515 * The client needs to retry the remove function at a later time. 516 * The memory for the session handle MUST not be freed until this call 517 * has completed successfully. 518 * 519 * @context 520 * This is a synchronous function that cannot sleep. It can be 521 * executed in a context that does not permit sleeping. 522 * @assumptions 523 * None 524 * @sideEffects 525 * None 526 * @blocking 527 * No. 528 * @reentrant 529 * No 530 * @threadSafe 531 * Yes 532 * 533 * @param[in] dcInstance Instance handle. 534 * @param[in,out] pSessionHandle Session handle. 535 * 536 * @retval CPA_STATUS_SUCCESS Function executed successfully. 537 * @retval CPA_STATUS_FAIL Function failed. 538 * @retval CPA_STATUS_RETRY Resubmit the request. 539 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 540 * @retval CPA_STATUS_RESOURCE Error related to system resources. 541 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 542 * the request. 543 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 544 * 545 * @pre 546 * The component has been initialized via @ref cpaDcStartInstance function. 547 * @post 548 * None 549 * @note 550 * This is a synchronous function and has no completion callback 551 * associated with it. 552 * 553 * @see 554 * @ref cpaDcDpInitSession 555 * 556 *****************************************************************************/ 557 CpaStatus 558 cpaDcDpRemoveSession(const CpaInstanceHandle dcInstance, 559 CpaDcSessionHandle pSessionHandle ); 560 561 /** 562 ***************************************************************************** 563 * @ingroup cpaDcDp 564 * Registration of the operation completion callback function. 565 * 566 * @description 567 * This function allows a completion callback function to be registered. 568 * The registered callback function is invoked on completion of 569 * asynchronous requests made via calls to @ref cpaDcDpEnqueueOp 570 * or @ref cpaDcDpEnqueueOpBatch. 571 * @context 572 * This is a synchronous function and it cannot sleep. It can be 573 * executed in a context that DOES NOT permit sleeping. 574 * @assumptions 575 * None 576 * @sideEffects 577 * None 578 * @reentrant 579 * No 580 * @threadSafe 581 * No 582 * 583 * @param[in] dcInstance Instance on which the callback function is to be 584 * registered. 585 * @param[in] pNewCb Callback function for this instance. 586 * 587 * @retval CPA_STATUS_SUCCESS Function executed successfully. 588 * @retval CPA_STATUS_FAIL Function failed. 589 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 590 * @retval CPA_STATUS_RESOURCE Error related to system resources. 591 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 592 * the request. 593 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 594 * 595 * @pre 596 * Instance has been initialized. 597 * @post 598 * None 599 * @note 600 * None 601 * @see 602 * cpaDcDpCbFunc 603 *****************************************************************************/ 604 CpaStatus cpaDcDpRegCbFunc(const CpaInstanceHandle dcInstance, 605 const CpaDcDpCallbackFn pNewCb); 606 607 /** 608 ***************************************************************************** 609 * @ingroup cpaDcDp 610 * Enqueue a single compression or decompression request. 611 * 612 * @description 613 * This function enqueues a single request to perform a compression, 614 * decompression operation. 615 * 616 * The function is asynchronous; control is returned to the user once 617 * the request has been submitted. On completion of the request, the 618 * application may poll for responses, which will cause a callback 619 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 620 * Callbacks within a session are guaranteed 621 * to be in the same order in which they were submitted. 622 * 623 * The following restrictions apply to the pOpData parameter: 624 * 625 * - The memory MUST be aligned on an 8-byte boundary. 626 * - The reserved fields of the structure MUST NOT be written to 627 * or read from. 628 * - The structure MUST reside in physically contiguous memory. 629 * 630 * @context 631 * This function will not sleep, and hence can be executed in a context 632 * that does not permit sleeping. 633 * 634 * @sideEffects 635 * None 636 * @blocking 637 * No 638 * @reentrant 639 * No 640 * @threadSafe 641 * No 642 * 643 * @param[in] pOpData Pointer to a structure containing the 644 * request parameters. The client code allocates 645 * the memory for this structure. This component 646 * takes ownership of the memory until it is 647 * returned in the callback, which was registered 648 * on the instance via @ref cpaDcDpRegCbFunc. 649 * See the above Description for some restrictions 650 * that apply to this parameter. 651 * @param[in] performOpNow Flag to indicate whether the operation should be 652 * performed immediately (CPA_TRUE), or simply 653 * enqueued to be performed later (CPA_FALSE). 654 * In the latter case, the request is submitted 655 * to be performed either by calling this function 656 * again with this flag set to CPA_TRUE, or by 657 * invoking the function @ref 658 * cpaDcDpPerformOpNow. 659 * 660 * @retval CPA_STATUS_SUCCESS Function executed successfully. 661 * @retval CPA_STATUS_FAIL Function failed. 662 * @retval CPA_STATUS_RETRY Resubmit the request. 663 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 664 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 665 * the request. 666 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 667 * 668 * @pre 669 * The session identified by pOpData->pSessionHandle was setup using 670 * @ref cpaDcDpInitSession OR pOpData->pSetupData data structure was 671 * initialized for No-Session (Ns) usage. 672 * The instance identified by pOpData->dcInstance has had a 673 * callback function registered via @ref cpaDcDpRegCbFunc. 674 * 675 * @post 676 * None 677 * 678 * @note 679 * A callback of type @ref CpaDcDpCallbackFn is generated in 680 * response to this function call. Any errors generated during 681 * processing are reported as part of the callback status code. 682 * 683 * @see 684 * @ref cpaDcDpPerformOpNow 685 *****************************************************************************/ 686 CpaStatus 687 cpaDcDpEnqueueOp(CpaDcDpOpData *pOpData, 688 const CpaBoolean performOpNow); 689 690 /** 691 ***************************************************************************** 692 * @ingroup cpaDcDp 693 * Enqueue a single decompression request with partial read configuration. 694 * See @CpaDcDpPartialReadData for more details. 695 * 696 * @description 697 * This function enqueues a single request to perform a decompression 698 * operation and allows to specify particular region of decompressed 699 * data to be placed in to the destination buffer (or buffer list). 700 * 701 * The function is asynchronous; control is returned to the user once 702 * the request has been submitted. On completion of the request, the 703 * application may poll for responses, which will cause a callback 704 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 705 * Callbacks within a session are guaranteed to be in the same order 706 * in which they were submitted. 707 * 708 * The following restrictions apply to the pOpData parameter: 709 * 710 * - The memory MUST be aligned on an 8-byte boundary. 711 * - The reserved fields of the structure MUST NOT be written to 712 * or read from. 713 * - The structure MUST reside in physically contiguous memory. 714 * 715 * @context 716 * This function will not sleep, and hence can be executed in a context 717 * that does not permit sleeping. 718 * 719 * @sideEffects 720 * None 721 * @blocking 722 * No 723 * @reentrant 724 * No 725 * @threadSafe 726 * No 727 * 728 * @param[in,out] pOpData See @ref cpaDcDpEnqueueOp pOpData description. 729 * 730 * @param[in] pPartReadData Pointer to a structure containing the partial 731 * read configuration parameters. 732 * See @CpaDcDpPartialReadData for more details. 733 * 734 * @param[in] performOpNow See @ref cpaDcDpEnqueueOp performOpNow input 735 * parameter. 736 * 737 * @retval CPA_STATUS_SUCCESS Function executed successfully. 738 * @retval CPA_STATUS_FAIL Function failed. 739 * @retval CPA_STATUS_RETRY Resubmit the request. 740 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 741 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 742 * the request. 743 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 744 * 745 * @pre 746 * The session identified by pOpData->pSessionHandle was setup using 747 * @ref cpaDcDpInitSession. The instance identified by pOpData->dcInstance 748 * has had a callback function registered via @ref cpaDcDpRegCbFunc. 749 * 750 * @post 751 * None 752 * 753 * @note 754 * A callback of type @ref CpaDcDpCallbackFn is generated in 755 * response to this function call. Any errors generated during 756 * processing are reported as part of the callback status code. 757 * 758 * @see 759 * @ref cpaDcDpPerformOpNow 760 *****************************************************************************/ 761 CpaStatus 762 cpaDcDpEnqueueOpWithPartRead(CpaDcDpOpData *pOpData, 763 CpaDcDpPartialReadData *pPartReadData, 764 const CpaBoolean performOpNow); 765 766 /** 767 ***************************************************************************** 768 * @ingroup cpaDcDp 769 * Enqueue a single compression request with an option set to zero-fill 770 * data after the compression output in the leftover bytes. 771 * 772 * @description 773 * This function enqueues a single request to perform a compression 774 * operation with zero-filling leftover bytes with 4KB alignment 775 * in the destination buffer (or buffer list). 776 * 777 * The function is asynchronous; control is returned to the user once 778 * the request has been submitted. On completion of the request, the 779 * application may poll for responses, which will cause a callback 780 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 781 * Callbacks within a session are guaranteed to be in the same order 782 * in which they were submitted. 783 * 784 * The following restrictions apply to the pOpData parameter: 785 * 786 * - The memory MUST be aligned on an 8-byte boundary. 787 * - The reserved fields of the structure MUST NOT be written to 788 * or read from. 789 * - The structure MUST reside in physically contiguous memory. 790 * 791 * @context 792 * This function will not sleep, and hence can be executed in a context 793 * that does not permit sleeping. 794 * 795 * @sideEffects 796 * None 797 * @blocking 798 * No 799 * @reentrant 800 * No 801 * @threadSafe 802 * No 803 * 804 * @param[in,out] pOpData See @ref cpaDcDpEnqueueOp pOpData description. 805 * 806 * @param[in] performOpNow See @ref cpaDcDpEnqueueOp performOpNow input 807 * parameter. 808 * 809 * @retval CPA_STATUS_SUCCESS Function executed successfully. 810 * @retval CPA_STATUS_FAIL Function failed. 811 * @retval CPA_STATUS_RETRY Resubmit the request. 812 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 813 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 814 * the request. 815 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 816 * 817 * @pre 818 * The session identified by pOpData->pSessionHandle was setup using 819 * @ref cpaDcDpInitSession. The instance identified by pOpData->dcInstance 820 * has had a callback function registered via @ref cpaDcDpRegCbFunc. 821 * 822 * @post 823 * None 824 * 825 * @note 826 * A callback of type @ref CpaDcDpCallbackFn is generated in 827 * response to this function call. Any errors generated during 828 * processing are reported as part of the callback status code. 829 * 830 * @see 831 * @ref cpaDcDpPerformOpNow 832 *****************************************************************************/ 833 CpaStatus 834 cpaDcDpEnqueueOpWithZeroPad(CpaDcDpOpData *pOpData, 835 const CpaBoolean performOpNow); 836 837 /** 838 ***************************************************************************** 839 * @ingroup cpaDcDp 840 * Enqueue multiple requests to the compression data plane API. 841 * 842 * @description 843 * This function enqueues multiple requests to perform compression or 844 * decompression operations. 845 * 846 * The function is asynchronous; control is returned to the user once 847 * the request has been submitted. On completion of the request, the 848 * application may poll for responses, which will cause a callback 849 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 850 * Separate callbacks will be invoked for each request. 851 * Callbacks within a session and at the same priority are guaranteed 852 * to be in the same order in which they were submitted. 853 * 854 * The following restrictions apply to each element of the pOpData 855 * array: 856 * 857 * - The memory MUST be aligned on an 8-byte boundary. 858 * - The reserved fields of the structure MUST be set to zero. 859 * - The structure MUST reside in physically contiguous memory. 860 * 861 * @context 862 * This function will not sleep, and hence can be executed in a context 863 * that does not permit sleeping. 864 * 865 * @assumptions 866 * Client MUST allocate the request parameters to 8 byte alignment. 867 * Reserved elements of the CpaDcDpOpData structure MUST not used 868 * The CpaDcDpOpData structure MUST reside in physically 869 * contiguous memory. 870 * 871 * @sideEffects 872 * None 873 * @blocking 874 * No 875 * @reentrant 876 * No 877 * @threadSafe 878 * No 879 * 880 * @param[in] numberRequests The number of requests in the array of 881 * CpaDcDpOpData structures. 882 * @param[in] pOpData An array of pointers to CpaDcDpOpData 883 * structures. Each CpaDcDpOpData 884 * structure contains the request parameters for 885 * that request. The client code allocates the 886 * memory for this structure. This component takes 887 * ownership of the memory until it is returned in 888 * the callback, which was registered on the 889 * instance via @ref cpaDcDpRegCbFunc. 890 * See the above Description for some restrictions 891 * that apply to this parameter. 892 * @param[in] performOpNow Flag to indicate whether the operation should be 893 * performed immediately (CPA_TRUE), or simply 894 * enqueued to be performed later (CPA_FALSE). 895 * In the latter case, the request is submitted 896 * to be performed either by calling this function 897 * again with this flag set to CPA_TRUE, or by 898 * invoking the function @ref 899 * cpaDcDpPerformOpNow. 900 * 901 * @retval CPA_STATUS_SUCCESS Function executed successfully. 902 * @retval CPA_STATUS_FAIL Function failed. 903 * @retval CPA_STATUS_RETRY Resubmit the request. 904 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 905 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 906 * the request. 907 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 908 * 909 * @pre 910 * The session identified by pOpData[i]->pSessionHandle was setup using 911 * @ref cpaDcDpInitSession OR pOpData[i]->pSetupData data structure was 912 * initialized for No-Session (Ns) usage. 913 * The instance identified by pOpData[i]->dcInstance has had a 914 * callback function registered via @ref cpaDcDpRegCbFunc. 915 * 916 * @post 917 * None 918 * 919 * @note 920 * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in 921 * response to this function call (one per request). Any errors 922 * generated during processing are reported as part of the callback 923 * status code. 924 * 925 * @see 926 * cpaDcDpEnqueueOp 927 *****************************************************************************/ 928 CpaStatus 929 cpaDcDpEnqueueOpBatch(const Cpa32U numberRequests, 930 CpaDcDpOpData *pOpData[], 931 const CpaBoolean performOpNow); 932 933 /** 934 ***************************************************************************** 935 * @ingroup cpaDcDp 936 * Enqueue multiple decompression request with partial read configuration. 937 * See @CpaDcDpPartialReadData for more details. 938 * 939 * @description 940 * This function enqueues multiple requests to perform decompression 941 * operations and allows to specify particular region of decompressed 942 * data to be placed in to the destination buffer (or buffer list) for 943 * each individual request. 944 * 945 * The function is asynchronous; control is returned to the user once 946 * the request has been submitted. On completion of the request, the 947 * application may poll for responses, which will cause a callback 948 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 949 * Separate callbacks will be invoked for each request. 950 * Callbacks within a session and at the same priority are guaranteed 951 * to be in the same order in which they were submitted. 952 * 953 * The following restrictions apply to each element of the pOpData 954 * array: 955 * 956 * - The memory MUST be aligned on an 8-byte boundary. 957 * - The reserved fields of the structure MUST be set to zero. 958 * - The structure MUST reside in physically contiguous memory. 959 * 960 * @context 961 * See @ref cpaDcDpEnqueueOpBatch context. 962 * 963 * @assumptions 964 * See @ref cpaDcDpEnqueueOpBatch assumptions. 965 * 966 * @sideEffects 967 * None 968 * @blocking 969 * No 970 * @reentrant 971 * No 972 * @threadSafe 973 * No 974 * 975 * @param[in] numberRequests The number of requests in the array of 976 * CpaDcDpOpData structures. 977 * 978 * @param[in,out] pOpData See @ref cpaDcDpEnqueueOpBatch pOpData for more 979 * details. 980 * 981 * @param[in] pPartReadData An array of pointers to a structures containing 982 * the partial read configuration parameters. 983 * See @CpaDcDpPartialReadData for more details. 984 * 985 * @param[in] performOpNow See @ref cpaDcDpEnqueueOpBatch performOpNow 986 * input parameter. 987 * 988 * @retval CPA_STATUS_SUCCESS Function executed successfully. 989 * @retval CPA_STATUS_FAIL Function failed. 990 * @retval CPA_STATUS_RETRY Resubmit the request. 991 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 992 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 993 * the request. 994 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 995 * 996 * 997 * @pre 998 * The session identified by pOpData[i]->pSessionHandle was setup using 999 * @ref cpaDcDpInitSession. The instance identified by 1000 * pOpData[i]->dcInstance has had a callback function registered via 1001 * @ref cpaDcDpRegCbFunc. 1002 * 1003 * @post 1004 * None 1005 * 1006 * @note 1007 * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in 1008 * response to this function call (one per request). Any errors 1009 * generated during processing are reported as part of the callback 1010 * status code. 1011 * 1012 * @see 1013 * @ref cpaDcDpEnqueueOp 1014 *****************************************************************************/ 1015 CpaStatus 1016 cpaDcDpEnqueueOpWithPartReadBatch(const Cpa32U numberRequests, 1017 CpaDcDpOpData *pOpData[], 1018 CpaDcDpPartialReadData *pPartReadData[], 1019 const CpaBoolean performOpNow); 1020 1021 /** 1022 ***************************************************************************** 1023 * @ingroup cpaDcDp 1024 * Enqueue multiple compression requests with an option set to zero-fill 1025 * data after the compression output in the leftover bytes. 1026 * 1027 * @description 1028 * This function enqueues multiple requests to perform compression 1029 * operations with an option set to zero-fill leftover bytes in the 1030 * destination buffer (of buffer list) for each individual request. 1031 * Please note that optional zero-filling leftover output buffer bytes 1032 * is aligned to 4KB. 1033 * 1034 * The function is asynchronous; control is returned to the user once 1035 * the request has been submitted. On completion of the request, the 1036 * application may poll for responses, which will cause a callback 1037 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 1038 * Separate callbacks will be invoked for each request. 1039 * Callbacks within a session and at the same priority are guaranteed 1040 * to be in the same order in which they were submitted. 1041 * 1042 * The following restrictions apply to each element of the pOpData 1043 * array: 1044 * 1045 * - The memory MUST be aligned on an 8-byte boundary. 1046 * - The reserved fields of the structure MUST be set to zero. 1047 * - The structure MUST reside in physically contiguous memory. 1048 * 1049 * @context 1050 * See @ref cpaDcDpEnqueueOpBatch context. 1051 * 1052 * @assumptions 1053 * See @ref cpaDcDpEnqueueOpBatch assumptions. 1054 * 1055 * @sideEffects 1056 * None 1057 * @blocking 1058 * No 1059 * @reentrant 1060 * No 1061 * @threadSafe 1062 * No 1063 * 1064 * @param[in] numberRequests The number of requests in the array of 1065 * CpaDcDpOpData structures. 1066 * 1067 * @param[in,out] pOpData See @ref cpaDcDpEnqueueOpBatch pOpData for more 1068 * details. 1069 * 1070 * @param[in] performOpNow See @ref cpaDcDpEnqueueOpBatch performOpNow 1071 * input parameter. 1072 * 1073 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1074 * @retval CPA_STATUS_FAIL Function failed. 1075 * @retval CPA_STATUS_RETRY Resubmit the request. 1076 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1077 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1078 * the request. 1079 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1080 * 1081 * 1082 * @pre 1083 * The session identified by pOpData[i]->pSessionHandle was setup using 1084 * @ref cpaDcDpInitSession. The instance identified by 1085 * pOpData[i]->dcInstance has had a callback function registered via 1086 * @ref cpaDcDpRegCbFunc. 1087 * 1088 * @post 1089 * None 1090 * 1091 * @note 1092 * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in 1093 * response to this function call (one per request). Any errors 1094 * generated during processing are reported as part of the callback 1095 * status code. 1096 * 1097 * @see 1098 * @ref cpaDcDpEnqueueOp 1099 *****************************************************************************/ 1100 CpaStatus 1101 cpaDcDpEnqueueOpWithZeroPadBatch(const Cpa32U numberRequests, 1102 CpaDcDpOpData *pOpData[], 1103 const CpaBoolean performOpNow); 1104 1105 /** 1106 ***************************************************************************** 1107 * @ingroup cpaDcDp 1108 * Submit any previously enqueued requests to be performed now on the 1109 * compression data plane API. 1110 * 1111 * @description 1112 * This function triggers processing of previously enqueued requests on the 1113 * referenced instance. 1114 * 1115 * 1116 * @context 1117 * Will not sleep. It can be executed in a context that does not 1118 * permit sleeping. 1119 * 1120 * @sideEffects 1121 * None 1122 * @blocking 1123 * No 1124 * @reentrant 1125 * No 1126 * @threadSafe 1127 * No 1128 * 1129 * @param[in] dcInstance Instance to which the requests will be 1130 * submitted. 1131 * 1132 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1133 * @retval CPA_STATUS_FAIL Function failed. 1134 * @retval CPA_STATUS_RETRY Resubmit the request. 1135 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1136 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 1137 * the request. 1138 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1139 * 1140 * @pre 1141 * The component has been initialized via @ref cpaDcStartInstance function. 1142 * A compression session has been previously setup using the 1143 * @ref cpaDcDpInitSession function call. 1144 * 1145 * @post 1146 * None 1147 * 1148 * @see 1149 * cpaDcDpEnqueueOp, cpaDcDpEnqueueOpBatch 1150 *****************************************************************************/ 1151 CpaStatus 1152 cpaDcDpPerformOpNow(CpaInstanceHandle dcInstance); 1153 1154 /** 1155 ***************************************************************************** 1156 * @ingroup cpaDc 1157 * Function to return the "partial read" feature support. 1158 * 1159 * @description 1160 * This function is used to determine if given instance supports 1161 * "partial read" feature. 1162 * 1163 * @context 1164 * This function may be called from any context. 1165 * @assumptions 1166 * None 1167 * @sideEffects 1168 * None 1169 * @blocking 1170 * No 1171 * @reentrant 1172 * No 1173 * @threadSafe 1174 * Yes 1175 * 1176 * @param[in] instanceHandle Handle to an instance of this API. 1177 * @param[out] pFlag Pointer to boolean flag which indicates 1178 * whether a feature is supported. 1179 * 1180 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1181 * @retval CPA_STATUS_FAIL Function failed. 1182 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1183 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1184 * 1185 * @pre 1186 * None 1187 * @post 1188 * None 1189 * @note 1190 * None 1191 * @see 1192 * cpaDcQueryCapabilities() 1193 * 1194 *****************************************************************************/ 1195 CpaStatus 1196 cpaDcDpIsPartReadSupported(const CpaInstanceHandle instanceHandle, 1197 CpaBoolean *pFlag); 1198 1199 /** 1200 ***************************************************************************** 1201 * @ingroup cpaDc 1202 * Function to return the "zero pad" feature support. 1203 * 1204 * @description 1205 * This function is used to determine if given instance supports 1206 * "zero pad" feature. 1207 * 1208 * @context 1209 * This function may be called from any context. 1210 * @assumptions 1211 * None 1212 * @sideEffects 1213 * None 1214 * @blocking 1215 * No 1216 * @reentrant 1217 * No 1218 * @threadSafe 1219 * Yes 1220 * 1221 * @param[in] instanceHandle Handle to an instance of this API. 1222 * @param[out] pFlag Pointer to boolean flag which indicates 1223 * whether a feature is supported. 1224 * 1225 * @retval CPA_STATUS_SUCCESS Function executed successfully. 1226 * @retval CPA_STATUS_FAIL Function failed. 1227 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 1228 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 1229 * 1230 * @pre 1231 * None 1232 * @post 1233 * None 1234 * @note 1235 * None 1236 * @see 1237 * cpaDcQueryCapabilities() 1238 * 1239 *****************************************************************************/ 1240 CpaStatus 1241 cpaDcDpIsZeroPadSupported(const CpaInstanceHandle instanceHandle, 1242 CpaBoolean *pFlag); 1243 1244 1245 #ifdef __cplusplus 1246 } /* close the extern "C" { */ 1247 #endif 1248 1249 #endif /* CPA_DC_DP_H */ 1250 1251