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 * Operation Data for compression data plane API. 98 * 99 * @description 100 * This structure contains data relating to a request to perform 101 * compression processing on one or more data buffers. 102 * 103 * The physical memory to which this structure points should be 104 * at least 8-byte aligned. 105 * 106 * All reserved fields SHOULD NOT be written or read by the 107 * calling code. 108 * 109 * @see 110 * cpaDcDpEnqueueOp, cpaDcDpEnqueueOpBatch 111 ****************************************************************************/ 112 typedef struct _CpaDcDpOpData 113 { 114 Cpa64U reserved0; 115 /**< Reserved for internal use. Source code should not read or write 116 * this field. 117 */ 118 Cpa32U bufferLenToCompress; 119 /**< The number of bytes from the source buffer to compress. This must be 120 * less than, or more typically equal to, the total size of the source 121 * buffer (or buffer list). 122 */ 123 124 Cpa32U bufferLenForData; 125 /**< The maximum number of bytes that should be written to the destination 126 * buffer. This must be less than, or more typically equal to, the total 127 * size of the destination buffer (or buffer list). 128 */ 129 130 Cpa64U reserved1; 131 /**< Reserved for internal use. Source code should not read or write */ 132 133 Cpa64U reserved2; 134 /**< Reserved for internal use. Source code should not read or write */ 135 136 Cpa64U reserved3; 137 /**< Reserved for internal use. Source code should not read or write */ 138 139 CpaDcRqResults results; 140 /**< Results of the operation. Contents are valid upon completion. */ 141 142 CpaInstanceHandle dcInstance; 143 /**< Instance to which the request is to be enqueued */ 144 145 CpaDcSessionHandle pSessionHandle; 146 /**< DC Session associated with the stream of requests. 147 * This field is only valid when using the session based API functions. 148 * This field must be set to NULL if the application wishes to use 149 * the No-Session (Ns) API. 150 */ 151 152 CpaPhysicalAddr srcBuffer; 153 /**< Physical address of the source buffer on which to operate. 154 * This is either the location of the data, of length srcBufferLen; or, 155 * if srcBufferLen has the special value @ref CPA_DP_BUFLIST, then 156 * srcBuffer contains the location where a @ref CpaPhysBufferList is 157 * stored. 158 */ 159 160 Cpa32U srcBufferLen; 161 /**< If the source buffer is a "flat buffer", then this field 162 * specifies the size of the buffer, in bytes. If the source buffer 163 * is a "buffer list" (of type @ref CpaPhysBufferList), then this field 164 * should be set to the value @ref CPA_DP_BUFLIST. 165 */ 166 167 CpaPhysicalAddr destBuffer; 168 /**< Physical address of the destination buffer on which to operate. 169 * This is either the location of the data, of length destBufferLen; or, 170 * if destBufferLen has the special value @ref CPA_DP_BUFLIST, then 171 * destBuffer contains the location where a @ref CpaPhysBufferList is 172 * stored. 173 */ 174 175 Cpa32U destBufferLen; 176 /**< If the destination buffer is a "flat buffer", then this field 177 * specifies the size of the buffer, in bytes. If the destination buffer 178 * is a "buffer list" (of type @ref CpaPhysBufferList), then this field 179 * should be set to the value @ref CPA_DP_BUFLIST. 180 */ 181 182 CpaDcSessionDir sessDirection; 183 /**<Session direction indicating whether session is used for 184 * compression, decompression. For the DP implementation, 185 * CPA_DC_DIR_COMBINED is not a valid selection. 186 */ 187 188 CpaBoolean compressAndVerify; 189 /**< If set to true, for compression operations, the implementation 190 * will verify that compressed data, generated by the compression 191 * operation, can be successfully decompressed. 192 * This behavior is only supported for stateless compression. 193 * This behavior is only supported on instances that support the 194 * compressAndVerify capability. */ 195 196 CpaBoolean compressAndVerifyAndRecover; 197 /**< If set to true, for compression operations, the implementation 198 * will automatically recover from a compressAndVerify error. 199 * This behavior is only supported for stateless compression. 200 * This behavior is only supported on instances that support the 201 * compressAndVerifyAndRecover capability. 202 * The compressAndVerify field in CpaDcOpData MUST be set to CPA_TRUE 203 * if compressAndVerifyAndRecover is set to CPA_TRUE. */ 204 205 CpaStatus responseStatus; 206 /**< Status of the operation. Valid values are CPA_STATUS_SUCCESS, 207 * CPA_STATUS_FAIL and CPA_STATUS_UNSUPPORTED. 208 */ 209 210 CpaPhysicalAddr thisPhys; 211 /**< Physical address of this data structure */ 212 213 void* pCallbackTag; 214 /**< Opaque data that will be returned to the client in the function 215 * completion callback. 216 * 217 * This opaque data is not used by the implementation of the API, 218 * but is simply returned as part of the asynchronous response. 219 * It may be used to store information that might be useful when 220 * processing the response later. 221 */ 222 223 CpaDcNsSetupData *pSetupData; 224 /**< Pointer to the No-session (Ns) Setup data for configuration of this 225 * request. 226 * 227 * This @ref CpaDcNsSetupData structure must be initialised when using the 228 * Data Plane No-Session (Ns) API. Otherwise it should be set to NULL. 229 * When initialized, the existing Data Plane API functions can be used 230 * as is. 231 */ 232 233 } CpaDcDpOpData; 234 235 /** 236 ***************************************************************************** 237 * @ingroup cpaDcDp 238 * Definition of callback function for compression data plane API. 239 * 240 * @description 241 * This is the callback function prototype. The callback function is 242 * registered by the application using the @ref cpaDcDpRegCbFunc 243 * function call, and called back on completion of asynchronous 244 * requests made via calls to @ref cpaDcDpEnqueueOp or @ref 245 * cpaDcDpEnqueueOpBatch. 246 * 247 * @context 248 * This callback function can be executed in a context that DOES NOT 249 * permit sleeping to occur. 250 * @assumptions 251 * None 252 * @sideEffects 253 * None 254 * @reentrant 255 * No 256 * @threadSafe 257 * No 258 * 259 * @param[in] pOpData Pointer to the @ref CpaDcDpOpData object which 260 * was supplied as part of the original request. 261 262 * @return 263 * None 264 * @pre 265 * Instance has been initialized. 266 * Callback has been registered with @ref cpaDcDpRegCbFunc. 267 * @post 268 * None 269 * @note 270 * None 271 * @see 272 * @ref cpaDcDpRegCbFunc 273 *****************************************************************************/ 274 typedef void (*CpaDcDpCallbackFn)(CpaDcDpOpData *pOpData); 275 276 /** 277 ***************************************************************************** 278 * @ingroup cpaDc 279 * Get the size of the memory required to hold the data plane 280 * session information. 281 * 282 * @description 283 * 284 * The client of the Data Compression API is responsible for 285 * allocating sufficient memory to hold session information. This 286 * function provides a means for determining the size of the session 287 * information and statistics information. 288 * 289 * @context 290 * No restrictions 291 * @assumptions 292 * None 293 * @sideEffects 294 * None 295 * @blocking 296 * Yes 297 * @reentrant 298 * No 299 * @threadSafe 300 * Yes 301 * 302 * @param[in] dcInstance Instance handle. 303 * @param[in] pSessionData Pointer to a user instantiated structure 304 * containing session data. 305 * @param[out] pSessionSize On return, this parameter will be the size 306 * of the memory that will be 307 * required by cpaDcInitSession() for session 308 * data. 309 * 310 * @retval CPA_STATUS_SUCCESS Function executed successfully. 311 * @retval CPA_STATUS_FAIL Function failed. 312 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 313 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 314 * 315 * @pre 316 * None 317 * @post 318 * None 319 * @note 320 * Only a synchronous version of this function is provided. 321 * 322 * Session data is expected to include interim checksum values, various 323 * counters and other session related data that needs to persist between 324 * invocations. 325 * For a given implementation of this API, it is safe to assume that 326 * cpaDcDpGetSessionSize() will always return the same session size and 327 * that the size will not be different for different setup data 328 * parameters. However, it should be noted that the size may change: 329 * (1) between different implementations of the API (e.g. between software 330 * and hardware implementations or between different hardware 331 * implementations) 332 * (2) between different releases of the same API implementation 333 * 334 * @see 335 * cpaDcDpInitSession() 336 * 337 *****************************************************************************/ 338 CpaStatus 339 cpaDcDpGetSessionSize(CpaInstanceHandle dcInstance, 340 CpaDcSessionSetupData* pSessionData, 341 Cpa32U* pSessionSize ); 342 343 344 /** 345 ***************************************************************************** 346 * @ingroup cpaDcDp 347 * Initialize compression or decompression data plane session. 348 * 349 * @description 350 * This function is used to initialize a compression/decompression session. 351 * A single session can be used for both compression and decompression 352 * requests. Clients MUST register a callback 353 * function for the compression service using this function. 354 * This function returns a unique session handle each time this function 355 * is invoked. 356 * The order of the callbacks are guaranteed to be in the same order the 357 * compression or decompression requests were submitted for each session, 358 * so long as a single thread of execution is used for job submission. 359 * 360 * @context 361 * This function may be called from any context. 362 * @assumptions 363 * None 364 * @sideEffects 365 * None 366 * @blocking 367 * Yes 368 * @reentrant 369 * No 370 * @threadSafe 371 * Yes 372 * 373 * @param[in] dcInstance Instance handle derived from discovery 374 * functions. 375 * @param[in,out] pSessionHandle Pointer to a session handle. 376 * @param[in,out] pSessionData Pointer to a user instantiated structure 377 * containing session data. 378 * 379 * @retval CPA_STATUS_SUCCESS Function executed successfully. 380 * @retval CPA_STATUS_FAIL Function failed. 381 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 382 * @retval CPA_STATUS_RESOURCE Error related to system resources. 383 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 384 * the request. 385 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 386 * 387 * @pre 388 * dcInstance has been started using @ref cpaDcStartInstance. 389 * @post 390 * None 391 * @note 392 * Only a synchronous version of this function is provided. 393 * 394 * This initializes opaque data structures in the session handle. Data 395 * compressed under this session will be compressed to the level 396 * specified in the pSessionData structure. Lower compression level 397 * numbers indicate a request for faster compression at the 398 * expense of compression ratio. Higher compression level numbers 399 * indicate a request for higher compression ratios at the expense of 400 * execution time. 401 * 402 * The session is opaque to the user application and the session handle 403 * contains job specific data. 404 * 405 * The window size specified in the pSessionData must match exactly 406 * one of the supported window sizes specified in the capability 407 * structure. If a bi-directional session is being initialized, then 408 * the window size must be valid for both compress and decompress. 409 * 410 * Note stateful sessions are not supported by this API. 411 * 412 * @see 413 * None 414 * 415 *****************************************************************************/ 416 CpaStatus 417 cpaDcDpInitSession( CpaInstanceHandle dcInstance, 418 CpaDcSessionHandle pSessionHandle, 419 CpaDcSessionSetupData *pSessionData ); 420 421 422 /** 423 ***************************************************************************** 424 * @ingroup cpaDc 425 * Compression Session Update Function. 426 * 427 * @description 428 * This function is used to modify some select compression parameters 429 * of a previously initialized session handlei for a data plane session. 430 * Th update will fail if resources required for the new session settings 431 * are not available. Specifically, this function may fail if no 432 * intermediate buffers are associated with the instance, and the 433 * intended change would require these buffers. 434 * This function can be called at any time after a successful call of 435 * cpaDcDpInitSession(). 436 * This function does not change the parameters to compression request 437 * already in flight. 438 * 439 * @context 440 * This is a synchronous function that cannot sleep. It can be 441 * executed in a context that does not permit sleeping. 442 * @assumptions 443 * None 444 * @sideEffects 445 * None 446 * @blocking 447 * No. 448 * @reentrant 449 * No 450 * @threadSafe 451 * No 452 * 453 * @param[in] dcInstance Instance handle. 454 * @param[in,out] pSessionHandle Session handle. 455 * @param[in] pSessionUpdateData Session Data. 456 * 457 * @retval CPA_STATUS_SUCCESS Function executed successfully. 458 * @retval CPA_STATUS_FAIL Function failed. 459 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 460 * @retval CPA_STATUS_RESOURCE Error related to system resources. 461 * @retval CPA_STATUS_RESTARTING API implementation is restarting. 462 * Resubmit the request 463 * 464 * @pre 465 * The component has been initialized via cpaDcStartInstance function. 466 * The session has been initialized via cpaDcDpInitSession function. 467 * @post 468 * None 469 * @note 470 * This is a synchronous function and has no completion callback 471 * associated with it. 472 * 473 * @see 474 * cpaDcDpInitSession() 475 * 476 *****************************************************************************/ 477 CpaStatus cpaDcDpUpdateSession( const CpaInstanceHandle dcInstance, 478 CpaDcSessionHandle pSessionHandle, 479 CpaDcSessionUpdateData *pSessionUpdateData ); 480 481 /** 482 ***************************************************************************** 483 * @ingroup cpaDc 484 * Compression Data Plane Session Remove Function. 485 * 486 * @description 487 * This function will remove a previously initialized session handle 488 * and the installed callback handler function. Removal will fail if 489 * outstanding calls still exist for the initialized session handle. 490 * The client needs to retry the remove function at a later time. 491 * The memory for the session handle MUST not be freed until this call 492 * has completed successfully. 493 * 494 * @context 495 * This is a synchronous function that cannot sleep. It can be 496 * executed in a context that does not permit sleeping. 497 * @assumptions 498 * None 499 * @sideEffects 500 * None 501 * @blocking 502 * No. 503 * @reentrant 504 * No 505 * @threadSafe 506 * Yes 507 * 508 * @param[in] dcInstance Instance handle. 509 * @param[in,out] pSessionHandle Session handle. 510 * 511 * @retval CPA_STATUS_SUCCESS Function executed successfully. 512 * @retval CPA_STATUS_FAIL Function failed. 513 * @retval CPA_STATUS_RETRY Resubmit the request. 514 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 515 * @retval CPA_STATUS_RESOURCE Error related to system resources. 516 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 517 * the request. 518 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 519 * 520 * @pre 521 * The component has been initialized via @ref cpaDcStartInstance function. 522 * @post 523 * None 524 * @note 525 * This is a synchronous function and has no completion callback 526 * associated with it. 527 * 528 * @see 529 * @ref cpaDcDpInitSession 530 * 531 *****************************************************************************/ 532 CpaStatus 533 cpaDcDpRemoveSession(const CpaInstanceHandle dcInstance, 534 CpaDcSessionHandle pSessionHandle ); 535 536 /** 537 ***************************************************************************** 538 * @ingroup cpaDcDp 539 * Registration of the operation completion callback function. 540 * 541 * @description 542 * This function allows a completion callback function to be registered. 543 * The registered callback function is invoked on completion of 544 * asynchronous requests made via calls to @ref cpaDcDpEnqueueOp 545 * or @ref cpaDcDpEnqueueOpBatch. 546 * @context 547 * This is a synchronous function and it cannot sleep. It can be 548 * executed in a context that DOES NOT permit sleeping. 549 * @assumptions 550 * None 551 * @sideEffects 552 * None 553 * @reentrant 554 * No 555 * @threadSafe 556 * No 557 * 558 * @param[in] dcInstance Instance on which the callback function is to be 559 * registered. 560 * @param[in] pNewCb Callback function for this instance. 561 * 562 * @retval CPA_STATUS_SUCCESS Function executed successfully. 563 * @retval CPA_STATUS_FAIL Function failed. 564 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 565 * @retval CPA_STATUS_RESOURCE Error related to system resources. 566 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 567 * the request. 568 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 569 * 570 * @pre 571 * Instance has been initialized. 572 * @post 573 * None 574 * @note 575 * None 576 * @see 577 * cpaDcDpCbFunc 578 *****************************************************************************/ 579 CpaStatus cpaDcDpRegCbFunc(const CpaInstanceHandle dcInstance, 580 const CpaDcDpCallbackFn pNewCb); 581 582 /** 583 ***************************************************************************** 584 * @ingroup cpaDcDp 585 * Enqueue a single compression or decompression request. 586 * 587 * @description 588 * This function enqueues a single request to perform a compression, 589 * decompression operation. 590 * 591 * The function is asynchronous; control is returned to the user once 592 * the request has been submitted. On completion of the request, the 593 * application may poll for responses, which will cause a callback 594 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 595 * Callbacks within a session are guaranteed 596 * to be in the same order in which they were submitted. 597 * 598 * The following restrictions apply to the pOpData parameter: 599 * 600 * - The memory MUST be aligned on an 8-byte boundary. 601 * - The reserved fields of the structure MUST NOT be written to 602 * or read from. 603 * - The structure MUST reside in physically contiguous memory. 604 * 605 * @context 606 * This function will not sleep, and hence can be executed in a context 607 * that does not permit sleeping. 608 * 609 * @sideEffects 610 * None 611 * @blocking 612 * No 613 * @reentrant 614 * No 615 * @threadSafe 616 * No 617 * 618 * @param[in] pOpData Pointer to a structure containing the 619 * request parameters. The client code allocates 620 * the memory for this structure. This component 621 * takes ownership of the memory until it is 622 * returned in the callback, which was registered 623 * on the instance via @ref cpaDcDpRegCbFunc. 624 * See the above Description for some restrictions 625 * that apply to this parameter. 626 * @param[in] performOpNow Flag to indicate whether the operation should be 627 * performed immediately (CPA_TRUE), or simply 628 * enqueued to be performed later (CPA_FALSE). 629 * In the latter case, the request is submitted 630 * to be performed either by calling this function 631 * again with this flag set to CPA_TRUE, or by 632 * invoking the function @ref 633 * cpaDcDpPerformOpNow. 634 * 635 * @retval CPA_STATUS_SUCCESS Function executed successfully. 636 * @retval CPA_STATUS_FAIL Function failed. 637 * @retval CPA_STATUS_RETRY Resubmit the request. 638 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 639 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 640 * the request. 641 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 642 * 643 * @pre 644 * The session identified by pOpData->pSessionHandle was setup using 645 * @ref cpaDcDpInitSession OR pOpData->pSetupData data structure was 646 * initialized for No-Session (Ns) usage. 647 * The instance identified by pOpData->dcInstance has had a 648 * callback function registered via @ref cpaDcDpRegCbFunc. 649 * 650 * @post 651 * None 652 * 653 * @note 654 * A callback of type @ref CpaDcDpCallbackFn is generated in 655 * response to this function call. Any errors generated during 656 * processing are reported as part of the callback status code. 657 * 658 * @see 659 * @ref cpaDcDpPerformOpNow 660 *****************************************************************************/ 661 CpaStatus 662 cpaDcDpEnqueueOp(CpaDcDpOpData *pOpData, 663 const CpaBoolean performOpNow); 664 665 666 /** 667 ***************************************************************************** 668 * @ingroup cpaDcDp 669 * Enqueue multiple requests to the compression data plane API. 670 * 671 * @description 672 * This function enqueues multiple requests to perform compression or 673 * decompression operations. 674 * 675 * The function is asynchronous; control is returned to the user once 676 * the request has been submitted. On completion of the request, the 677 * application may poll for responses, which will cause a callback 678 * function (registered via @ref cpaDcDpRegCbFunc) to be invoked. 679 * Separate callbacks will be invoked for each request. 680 * Callbacks within a session and at the same priority are guaranteed 681 * to be in the same order in which they were submitted. 682 * 683 * The following restrictions apply to each element of the pOpData 684 * array: 685 * 686 * - The memory MUST be aligned on an 8-byte boundary. 687 * - The reserved fields of the structure MUST be set to zero. 688 * - The structure MUST reside in physically contiguous memory. 689 * 690 * @context 691 * This function will not sleep, and hence can be executed in a context 692 * that does not permit sleeping. 693 * 694 * @assumptions 695 * Client MUST allocate the request parameters to 8 byte alignment. 696 * Reserved elements of the CpaDcDpOpData structure MUST not used 697 * The CpaDcDpOpData structure MUST reside in physically 698 * contiguous memory. 699 * 700 * @sideEffects 701 * None 702 * @blocking 703 * No 704 * @reentrant 705 * No 706 * @threadSafe 707 * No 708 * 709 * @param[in] numberRequests The number of requests in the array of 710 * CpaDcDpOpData structures. 711 * @param[in] pOpData An array of pointers to CpaDcDpOpData 712 * structures. Each CpaDcDpOpData 713 * structure contains the request parameters for 714 * that request. The client code allocates the 715 * memory for this structure. This component takes 716 * ownership of the memory until it is returned in 717 * the callback, which was registered on the 718 * instance via @ref cpaDcDpRegCbFunc. 719 * See the above Description for some restrictions 720 * that apply to this parameter. 721 * @param[in] performOpNow Flag to indicate whether the operation should be 722 * performed immediately (CPA_TRUE), or simply 723 * enqueued to be performed later (CPA_FALSE). 724 * In the latter case, the request is submitted 725 * to be performed either by calling this function 726 * again with this flag set to CPA_TRUE, or by 727 * invoking the function @ref 728 * cpaDcDpPerformOpNow. 729 * 730 * @retval CPA_STATUS_SUCCESS Function executed successfully. 731 * @retval CPA_STATUS_FAIL Function failed. 732 * @retval CPA_STATUS_RETRY Resubmit the request. 733 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 734 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 735 * the request. 736 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 737 * 738 * @pre 739 * The session identified by pOpData[i]->pSessionHandle was setup using 740 * @ref cpaDcDpInitSession OR pOpData[i]->pSetupData data structure was 741 * initialized for No-Session (Ns) usage. 742 * The instance identified by pOpData[i]->dcInstance has had a 743 * callback function registered via @ref cpaDcDpRegCbFunc. 744 * 745 * @post 746 * None 747 * 748 * @note 749 * Multiple callbacks of type @ref CpaDcDpCallbackFn are generated in 750 * response to this function call (one per request). Any errors 751 * generated during processing are reported as part of the callback 752 * status code. 753 * 754 * @see 755 * cpaDcDpEnqueueOp 756 *****************************************************************************/ 757 CpaStatus 758 cpaDcDpEnqueueOpBatch(const Cpa32U numberRequests, 759 CpaDcDpOpData *pOpData[], 760 const CpaBoolean performOpNow); 761 762 763 /** 764 ***************************************************************************** 765 * @ingroup cpaDcDp 766 * Submit any previously enqueued requests to be performed now on the 767 * compression data plane API. 768 * 769 * @description 770 * This function triggers processing of previously enqueued requests on the 771 * referenced instance. 772 * 773 * 774 * @context 775 * Will not sleep. It can be executed in a context that does not 776 * permit sleeping. 777 * 778 * @sideEffects 779 * None 780 * @blocking 781 * No 782 * @reentrant 783 * No 784 * @threadSafe 785 * No 786 * 787 * @param[in] dcInstance Instance to which the requests will be 788 * submitted. 789 * 790 * @retval CPA_STATUS_SUCCESS Function executed successfully. 791 * @retval CPA_STATUS_FAIL Function failed. 792 * @retval CPA_STATUS_RETRY Resubmit the request. 793 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in. 794 * @retval CPA_STATUS_RESTARTING API implementation is restarting. Resubmit 795 * the request. 796 * @retval CPA_STATUS_UNSUPPORTED Function is not supported. 797 * 798 * @pre 799 * The component has been initialized via @ref cpaDcStartInstance function. 800 * A compression session has been previously setup using the 801 * @ref cpaDcDpInitSession function call. 802 * 803 * @post 804 * None 805 * 806 * @see 807 * cpaDcDpEnqueueOp, cpaDcDpEnqueueOpBatch 808 *****************************************************************************/ 809 CpaStatus 810 cpaDcDpPerformOpNow(CpaInstanceHandle dcInstance); 811 812 813 814 #ifdef __cplusplus 815 } /* close the extern "C" { */ 816 #endif 817 818 #endif /* CPA_DC_DP_H */ 819 820