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