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
89extern "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 ****************************************************************************/
103typedef 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 ****************************************************************************/
137typedef 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 *****************************************************************************/
299typedef 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 *****************************************************************************/
363CpaStatus
364cpaDcDpGetSessionSize(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 *****************************************************************************/
441CpaStatus
442cpaDcDpInitSession( 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 *****************************************************************************/
502CpaStatus 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 *****************************************************************************/
557CpaStatus
558cpaDcDpRemoveSession(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 *****************************************************************************/
604CpaStatus 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 *****************************************************************************/
686CpaStatus
687cpaDcDpEnqueueOp(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 *****************************************************************************/
761CpaStatus
762cpaDcDpEnqueueOpWithPartRead(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 *****************************************************************************/
833CpaStatus
834cpaDcDpEnqueueOpWithZeroPad(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 *****************************************************************************/
928CpaStatus
929cpaDcDpEnqueueOpBatch(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 *****************************************************************************/
1015CpaStatus
1016cpaDcDpEnqueueOpWithPartReadBatch(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 *****************************************************************************/
1100CpaStatus
1101cpaDcDpEnqueueOpWithZeroPadBatch(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 *****************************************************************************/
1151CpaStatus
1152cpaDcDpPerformOpNow(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 *****************************************************************************/
1195CpaStatus
1196cpaDcDpIsPartReadSupported(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 *****************************************************************************/
1240CpaStatus
1241cpaDcDpIsZeroPadSupported(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