/****************************************************************************
 *
 *   SPDX-License-Identifier: BSD-3-Clause
 *   Copyright(c) 2007-2026 Intel Corporation
 * 
 *   These contents may have been developed with support from one or more
 *   Intel-operated generative artificial intelligence solutions.
 *
 ***************************************************************************/

/*
 *****************************************************************************
 * Doxygen group definitions
 ****************************************************************************/

/**
 *****************************************************************************
 * @file cpa_dc_chain.h
 *
 * @defgroup cpaDcChain Data Compression Chaining API
 *
 * @ingroup cpaDc
 *
 * @description
 *      These functions specify the API for Data Compression Chaining
 *      operations.
 *
 * @remarks
 *
 *
 *****************************************************************************/

#ifndef CPA_DC_CHAIN_H
#define CPA_DC_CHAIN_H

#ifdef __cplusplus
extern "C" {
#endif

#include "cpa_dc.h"
#include "cpa_cy_sym.h"

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Supported operations for compression chaining
 *
 * @description
 *      This enumeration lists the supported operations for compression chaining
 *
 *****************************************************************************/
typedef enum
{
    CPA_DC_CHAIN_COMPRESS_THEN_HASH = 0,
    /**< 2 operations for chaining:
     * 1st operation is to perform compression on plain text
     * 2nd operation is to perform hash on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for compression setup data
     * 2nd entry is for hash setup data
     */
    CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT = 1,
    /**< 2 operations for chaining:
     * 1st operation is to perform compression on plain text
     * 2nd operation is to perform encryption on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for compression setup data
     * 2nd entry is for encryption setup data
     */
    CPA_DC_CHAIN_COMPRESS_THEN_HASH_ENCRYPT = 2,
    /**< 2 operations for chaining:
     * 1st operation is to perform compression on plain text
     * 2nd operation is to perform hash on compressed text and
     * encryption on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for compression setup data
     * 2nd entry is for hash and encryption setup data
     */
    CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT_HASH = 3,
    /**< 2 operations for chaining:
     * 1st operation is to perform compression on plain text
     * 2nd operation is to perform encryption on compressed text and
     * hash on compressed & encrypted text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for compression setup data
     * 2nd entry is for encryption and hash setup data
     */
    CPA_DC_CHAIN_COMPRESS_THEN_AEAD = 4,
    /**< 2 operations for chaining:
     * 1st operation is to perform compression on plain text
     * 2nd operation is to perform AEAD encryption on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for compression setup data
     * 2nd entry is for AEAD encryption setup data
     */
    CPA_DC_CHAIN_HASH_THEN_COMPRESS = 5,
    /**< 2 operations for chaining:
     * 1st operation is to perform hash on plain text
     * 2nd operation is to perform compression on plain text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for hash setup data
     * 2nd entry is for compression setup data
     */
    CPA_DC_CHAIN_HASH_VERIFY_THEN_DECOMPRESS = 6,
    /**< 2 operations for chaining:
     * 1st operation is to perform hash verify on compressed text
     * 2nd operation is to perform decompression on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for hash setup data
     * 2nd entry is for decompression setup data
     */
    CPA_DC_CHAIN_DECRYPT_THEN_DECOMPRESS = 7,
    /**< 2 operations for chaining:
     * 1st operation is to perform decryption on compressed & encrypted text
     * 2nd operation is to perform decompression on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for decryption setup data
     * 2nd entry is for decompression setup data
     */
    CPA_DC_CHAIN_HASH_VERIFY_DECRYPT_THEN_DECOMPRESS = 8,
    /**< 2 operations for chaining:
     * 1st operation is to perform hash verify on compressed & encrypted text
     * and decryption on compressed & encrypted text
     * 2nd operation is to perform decompression on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for hash and decryption setup data
     * 2nd entry is for decompression setup data
     */
    CPA_DC_CHAIN_DECRYPT_HASH_VERIFY_THEN_DECOMPRESS = 9,
    /**< 2 operations for chaining:
     * 1st operation is to perform decryption on compressed & encrypted text
     * and hash verify on compressed text
     * 2nd operation is to perform decompression on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for decryption and hash setup data
     * 2nd entry is for decompression setup data
     */
    CPA_DC_CHAIN_AEAD_THEN_DECOMPRESS = 10,
    /**< 2 operations for chaining:
     * 1st operation is to perform AEAD decryption on compressed & encrypted
     * text
     * 2nd operation is to perform decompression on compressed text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for AEAD decryption setup data
     * 2nd entry is for decompression setup data
     */
    CPA_DC_CHAIN_DECOMPRESS_THEN_HASH_VERIFY = 11,
    /**< 2 operations for chaining:
     * 1st operation is to perform decompression on compressed text
     * 2nd operation is to perform hash verify on plain text
     * 2 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for decompression setup data
     * 2nd entry is for hash setup data
     */
    CPA_DC_CHAIN_COMPRESS_THEN_AEAD_THEN_HASH = 12,
    /**< 3 operations for chaining:
     * 1st operation is to perform compression on plain text
     * 2nd operation is to perform AEAD encryption on compressed text
     * 3rd operation is to perform hash on compressed & encrypted text
     * 3 entries in CpaDcChainSessionSetupData array:
     * 1st entry is for compression setup data
     * 2nd entry is for AEAD encryption setup data
     * 3rd entry is for hash setup data
     */
} CpaDcChainOperations;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Supported session types for data compression chaining.
 *
 * @description
 *      This enumeration lists the supported session types
 *      for data compression chaining.
 *****************************************************************************/
typedef enum
{
    CPA_DC_CHAIN_COMPRESS_DECOMPRESS = 0,
    /**< Indicate the session is for compression or decompression */
    CPA_DC_CHAIN_SYMMETRIC_CRYPTO
    /**< Indicate the session is for symmetric crypto */
} CpaDcChainSessionType;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Chaining Session Setup Data.
 * @description
 *      This structure contains data relating to the setup of a chaining
 *      session.
 *      This structure can comprise either compression or crypto session data
 *      determined by the sessType.
 *      The client needs to complete the information in this structure in order
 *      to setup a chaining session.
 *      This structure contains settings for use with the
 *      cpaDcChainInitSession API.
 *
 ****************************************************************************/
typedef struct
{
    CpaDcChainSessionType sessType;
    /**< Indicate the type for this session */
    union {
        CpaDcSessionSetupData *pDcSetupData;
        /**< Pointer to compression session setup data */
        CpaCySymSessionSetupData *pCySetupData;
        /**< Pointer to symmetric crypto session setup data */
    };
} CpaDcChainSessionSetupData;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Compression chaining request input parameters.
 * @description
 *      This structure contains the request information to use with
 *      compression chaining operations.
 *      This structure contains settings for use with the
 *      cpaDcChainPerformOp API.
 *
 ****************************************************************************/
typedef struct
{
    CpaDcChainSessionType opType;
    /**< Indicate the type for this operation */
    union {
        CpaDcOpData *pDcOp;
        /**< Pointer to compression operation data */
        CpaCySymOpData *pCySymOp;
        /**< Pointer to symmetric crypto operation data with
         * append crc64 option
         */
    };
} CpaDcChainOpData;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Compression chaining request input parameters.
 * @description
 *      This structure contains the request information to use with
 *      compression chaining sub-request operations.
 *      This structure contains settings for use with the
 *      cpaDcChainPerformOp2 API.
 *
 ****************************************************************************/
typedef struct
{
    CpaDcChainSessionType opType;
    /**< Indicate the type for this operation */
    union {
        CpaDcOpData2 *pDcOp2;
        /**< Pointer to compression operation data */
        CpaCySymOpData2 *pCySymOp2;
        /**< Pointer to symmetric crypto operation data with
         * additional options.
         */
    };
} CpaDcChainSubOpData2;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Chaining request result data
 * @description
 *      This structure contains the request results.
 *      This result structure is used with the cpaDcChainPerformOp API.
 *
 ****************************************************************************/
typedef struct
{
    CpaDcReqStatus dcStatus;
    /**< Additional status details from compression accelerator */
    CpaStatus cyStatus;
    /**< Additional status details from symmetric crypto accelerator */
    CpaBoolean verifyResult;
    /**< This parameter is valid when the verifyDigest option is set in the
     * CpaCySymSessionSetupData structure. A value of CPA_TRUE indicates
     * that the compare succeeded. A value of CPA_FALSE indicates that the
     * compare failed
     */
    Cpa32U produced;
    /**< Octets produced to the output buffer */
    Cpa32U consumed;
    /**< Octets consumed from the input buffer */
    Cpa32U crc32;
    /**< Crc32 checksum produced by chaining operations */
    Cpa32U adler32;
    /**< Adler32 checksum produced by chaining operations */
} CpaDcChainRqResults;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Chaining request result data for chained operations with optional
 *      verification step.
 * @description
 *      This structure contains the request results.
 *      This result structure is used with the cpaDcChainPerformOp2 API.
 *
 ****************************************************************************/
typedef struct
{
    CpaDcChainRqResults chainRqResults;
    /**< Chain result structure. */
    Cpa64U ctxCrc64;
    /**< Crc64 of context structure.
     * Applicable to store2 flow.
     */
    Cpa64U iDcCrc64;
    /**< Input crc of DC operation */
    Cpa64U oDcCrc64;
    /**< Output crc of DC operation */
    Cpa64U storedCrc64;
    /**< Crc64 that was appended to compressed data.
     * Only valid if decrypt and decompress operations
     * were performed successfully and appendCrc was requested.
     */
    CpaBoolean reserved1;
    /**< Reserved for future use */
    CpaStatus chainStatus;
    /**< Status of chain command. In the event the request is invalid,
     * a value of CPA_STATUS_INVALID_PARAM or CPA_STATUS_UNSUPPORTED may
     * be returned. If the request has been successfully sent to the
     * accelerator and has been processed, this value will be set to
     * CPA_STATUS_SUCCESS. To verify the success of the entire chain
     * operation, the return status of each operation must be examined.
     */
} CpaDcChainRqVResults;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Chaining request data for chained operations with optional
 *      verification step.
 * @description
 *      This structure contains arguments for the cpaDcChainPerformOp2 API.
 *
 ****************************************************************************/
typedef struct
{
    CpaBoolean testIntegrity;
    /**< True if integrity check is required */
    CpaDcChainOperations operation;
    /**< Description of operations */
    Cpa8U numOpDatas;
    /**< Number of elements in pChainOpData, which define the chain
     * operation.
     */
    CpaDcChainSubOpData2 *pChainOpData;
    /**< Array of operations for chaining */
} CpaDcChainOpData2;

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Get the size of the memory required to hold the chaining session
 *      information.
 *
 * @description
 *      The client of the Data Compression API is responsible for
 *      allocating sufficient memory to hold chaining session information.
 *      This function provides a way for determining the size of a chaining
 *      session.
 *
 * @context
 *      No restrictions
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] dcInstance             Instance handle.
 * @param[in] operation              The operation for chaining
 * @param[in] numSessions            Number of sessions for the chaining
 * @param[in] pSessionData           Pointer to an array of
 *                                   CpaDcChainSessionSetupData structures.
 *                                   There should be numSessions entries in
 *                                   the array.
 * @param[out] pSessionSize          On return, this parameter will be the size
 *                                   of the memory that will be required
 *                                   to be allocated for the session handle.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
 *
 * @pre
 *      dcInstance has been started using cpaDcStartInstance.
 * @post
 *      pSessionSize will contain the size in bytes to be allocated for the
 *      session handle.
 * @note
 *      Only a synchronous version of this function is provided.
 *
 * @see
 *      cpaDcChainInitSession()
 *
 *****************************************************************************/
CpaStatus cpaDcChainGetSessionSize(CpaInstanceHandle dcInstance,
                                   CpaDcChainOperations operation,
                                   Cpa8U numSessions,
                                   CpaDcChainSessionSetupData *pSessionData,
                                   Cpa32U *pSessionSize);

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Initialize data compression chaining session
 *
 * @description
 *      This function is used to initialize a compression/decompression
 *      chaining session.
 *      This function returns a unique session handle each time this function
 *      is invoked.
 *      If the session has been configured with a callback function, then
 *      the order of the callbacks are guaranteed to be in the same order the
 *      compression or decompression requests were submitted for each session,
 *      so long as a single thread of execution is used for job submission.
 *      For data integrity computations the default CRC algorithm parameters
 *      are used.
 *
 * @context
 *      This is a synchronous function and it cannot sleep. It can be executed
 *      in a context that does not permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]     dcInstance        Instance handle derived from discovery
 *                                  functions.
 * @param[in,out] pSessionHandle    Pointer to a session handle.
 * @param[in]     operation         The operations for chaining
 * @param[in]     numSessions       Number of sessions for chaining
 * @param[in,out] pSessionData      Pointer to an array of
 *                                  CpaDcChainSessionSetupData structures.
 *                                  There should be numSessions entries in
 *                                  the array.
 * @param[in]     callbackFn        For synchronous operation this callback
 *                                  shall be a null pointer.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE       Error related to system resources.
 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
 *
 * @pre
 *      dcInstance has been started using cpaDcStartInstance.
 *      Before the session is initialized with this function,
 *      cpaDcChainGetSessionSize() function should be used to determine the
 *      size of the session handle. Memory needs to be allocated of the
 *      required size and passed in as the pSessionHandle.
 * @post
 *      Internal state and session parameters will be stored within the
 *      session handle.
 * @note
 *      Only a synchronous version of this function is provided.
 *
 *  pSessionData Setup Rules
 *  -# Each element in CpaDcChainSessionSetupData structure array provides
 *     (de)compression or a symmetric crypto session setup data.
 *
 *  -# The supported chaining operations are listed in CpaDcChainOperations.
 *     This enum indicates the number of operations in a chain and the order
 *     in which they are performed.
 *
 *  -# The order of entries in pSessionData[] should be consistent with the
 *     CpaDcChainOperations perform order.
 *     As an example, for CPA_DC_CHAIN_COMPRESS_THEN_ENCRYPT, pSessionData[0]
 *     holds the compression setup data and pSessionData[1] holds the
 *     encryption setup data..
 *
 *  -# The numSessions for each chaining operation are provided in
 *     the documentation of enum CpaDcChainOperations.
 *
 *  -# For a (de)compression session, the corresponding
 *     pSessionData[]->sessType should be set to
 *     CPA_DC_CHAIN_COMPRESS_DECOMPRESS and pSessionData[]->pDcSetupData
 *     should point to a CpaDcSessionSetupData structure.
 *
 *  -# For a symmetric crypto session, the corresponding
 *     pSessionData[]->sessType should be set to CPA_DC_CHAIN_SYMMETRIC_CRYPTO
 *     and pSessionData[]->pCySetupData should point to a
 *     CpaCySymSessionSetupData structure.
 *
 *  -# Combined compression sessions are not supported for chaining.
 *
 *  -# Stateful compression/decompression is not supported for chaining.
 *
 *  -# Simultaneous CRC32 and Adler32 over the input data are supported for
 *     chaining.
 *
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus cpaDcChainInitSession(CpaInstanceHandle dcInstance,
                                CpaDcSessionHandle pSessionHandle,
                                CpaDcChainOperations operation,
                                Cpa8U numSessions,
                                CpaDcChainSessionSetupData *pSessionData,
                                CpaDcCallbackFn callbackFn);

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Initialize CRC parameters for a DC Chaining session
 *
 * @description
 *      This function is used to initialize E2E programmable CRC parameters.
 *
 * @context
 *      This is a synchronous function and it cannot sleep. It can be executed
 *      in a context that does not permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]       dcInstance      Instance handle derived from discovery
 *                                  functions.
 * @param[in,out]   pSessionHandle  Pointer to a session handle.
 * @param[in]       pCrcControlData Pointer to a user instantiated structure
 *                                  containing the CRC parameters.
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_FAIL          Operation failed.
 * @retval CPA_STATUS_UNSUPPORTED   Unsupported feature.
 *
 * @pre
 *      dcInstance has been started using cpaDcStartInstance.
 *      cpaDcInitSession has been called to initialize session parameters.
 * @post
 *      None
 * @note
 *      Only a synchronous version of this function is provided.
 *
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus cpaDcChainSetCrcControlData(CpaInstanceHandle dcInstance,
                                      CpaDcSessionHandle pSessionHandle,
                                      CpaCrcControlData *pCrcControlData);

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *       Reset a compression chaining session.
 *
 * @description
 *      This function will reset a previously initialized session handle.
 *      Reset will return CPA_STATUS_RETRY if outstanding calls still exist
 *      for the initialized session handle. In that case the client needs to
 *      retry the reset function at a later time.
 *
 * @context
 *      This is a synchronous function that cannot sleep. It can be
 *      executed in a context that does not permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]      dcInstance      Instance handle.
 * @param[in,out]  pSessionHandle  Session handle.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @retval CPA_STATUS_RETRY          Resubmit the request.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
 *
 * @pre
 *      The component has been initialized via cpaDcStartInstance function.
 *      The session has been initialized via cpaDcChainInitSession.
 *      This function will work with either standard or extended chained
 *      requests.
 * @post
 *      Internal state within the chained session will be cleared allowing
 *      the session to be reused again without calling either
 *      cpaDcChainRemoveSession or cpaDcChainInitSession.
 * @note
 *      This is a synchronous function and has no completion callback
 *      associated with it.
 *      cpaDcChainResetSession() API will have the capability to reset a
 *      session previously initialized with cpaDcChainInitSession().
 *
 * @see
 *      cpaDcChainInitSession()
 *
 *****************************************************************************/
CpaStatus cpaDcChainResetSession(const CpaInstanceHandle dcInstance,
                                 CpaDcSessionHandle pSessionHandle);

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Remove a compression chaining session.
 *
 * @description
 *      This function will remove a previously initialized session handle
 *      and the installed callback handler function. Removal will fail if
 *      outstanding calls still exist for the initialized session handle.
 *      The client needs to retry the remove function at a later time.
 *      The memory for the session handle MUST not be freed until this call
 *      has completed successfully.
 *
 * @context
 *      This is a synchronous function that cannot sleep. It can be executed
 *      in a context that does not permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]      dcInstance      Instance handle.
 * @param[in,out]  pSessionHandle  Session handle.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @retval CPA_STATUS_RETRY          Resubmit the request.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE       Error related to system resources.
 * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
 *                                   the request.
 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
 *
 * @pre
 *      The component has been initialized via cpaDcStartInstance function.
 *      pSessionHandle has been setup using cpaDcChainInitSession().
 *      This function will work with either standard or extended chained
 *      requests.
 * @post
 *      Following a retval of CPA_STATUS_SUCCESS it is safe to free the
 *      memory allocated for the session handle.
 * @note
 *      This is a synchronous function and has no completion callback
 *      associated with it.
 *      cpaDcChainRemoveSession() API will have the capability to remove a
 *      session initialized with cpaDcChainInitSession().
 *
 * @see
 *      cpaDcChainInitSession()
 *
 *****************************************************************************/
CpaStatus cpaDcChainRemoveSession(const CpaInstanceHandle dcInstance,
                                  CpaDcSessionHandle pSessionHandle);

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Submit a request to perform chaining operations.
 *
 * @description
 *      This function is used to perform chaining operations over data from
 *      the source buffer.
 *
 * @context
 *      When called as an asynchronous function it cannot sleep. It can be
 *      executed in a context that does not permit sleeping.
 *      When called as a synchronous function it may sleep. It MUST NOT be
 *      executed in a context that DOES NOT permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      Yes when configured to operate in synchronous mode.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]     dcInstance        Target service instance.
 * @param[in,out] pSessionHandle    Session handle.
 * @param[in]     pSrcBuff          Pointer to input data buffer.
 * @param[out]    pDestBuff         Pointer to output data buffer.
 * @param[in]     operation         Operation for the chaining request
 * @param[in]     numOpData         The number of CpaDcChainOpData array items
 * @param[in]     pChainOpData      Pointer to an array of CpaDcChainOpData
 *                                  structures. There should be numOpData
 *                                  items in the array.
 * @param[in,out] pResults          Pointer to CpaDcChainRqResults
 * @param[in]     callbackTag       User supplied value to help correlate
 *                                  the callback with its associated request.
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_FAIL          Function failed.
 * @retval CPA_STATUS_RETRY         Resubmit the request.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
 * @retval CPA_DC_BAD_DATA          The input data was not properly formed.
 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
 *                                  the request.
 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
 *
 * @pre
 *     pSessionHandle has been setup using cpaDcChainInitSession()
 * @post
 *     Following synchronous operation:
 *     The pSessionHandle will contain updated session related state
 *     information.
 *     The pDestBuff will contain processed data following the chained
 *     operation.
 *     The pResults will contain the status/checksums/additional outputs
 *     from the completed chained operation.
 *     Following asynchronous operation:
 *     The call has been submitted and the data dependent structures will
 *     only be safe to use once the asynchronous callback is called.
 * @note
 *     This function passes control to the compression service for chaining
 *     processing, the supported chaining operations are described in
 *     CpaDcChainOperations.
 *     This function does not support the additional integrity checking
 *     chaining features supported in cpaDcChainPerformOp2() and should only
 *     be used if these features are not required.
 *
 *  pChainOpData Setup Rules
 *  -# Each element in CpaDcChainOpData structure array holds either a
 *     (de)compression or a symmetric crypto operation data.
 *
 *  -# The order of entries in pChainOpData[] must be consistent with the
 *     order of operations described for the chaining operation in
 *     CpaDcChainOperations.
 *     As an example, for CPA_DC_CHAIN_HASH_THEN_COMPRESS, pChainOpData[0]
 *     must contain the hash operation data and pChainOpData[1] must
 *     contain the compress operation data.
 *
 *  -# The numOpData for each chaining operation are specified in the
 *     documentation for the operation in CpaDcChainOperations.
 *
 *  -# For a (de)compression operation, the corresponding
 *     pChainOpData[]->opType should be set to
 *     CPA_DC_CHAIN_COMPRESS_DECOMPRESS and pChainOpData[]->pDcOp should
 *     point to a CpaDcOpData structure.
 *
 *  -# For a symmetric crypto operation,  the corresponding
 *     pChainOpData[]->opType should be set to
 *     CPA_DC_CHAIN_SYMMETRIC_CRYPTO and pChainOpData[]->pCySymOp should
 *     point to a CpaCySymOpData structure.
 *
 *   -# Partial packet processing is not supported.
 *
 *   This function has identical buffer processing rules as
 *   cpaDcCompressData().
 *
 *   This function has identical checksum processing rules as
 *   cpaDcCompressData(), except:
 *   -# pResults->crc32 is available to the application if
 *      CpaDcSessionSetupData->checksum is set to CPA_DC_CRC32
 *      and will contain a crc32 checksum.
 *
 *   -# pResults->adler32 is available to the application if
 *      CpaDcSessionSetupData->checksum is set to CPA_DC_ADLER32
 *      and will contain an adler32 checksum.
 *
 *   -# pResults->adler32 is available to the application if
 *      CpaDcSessionSetupData->checksum is set to CPA_DC_XXHASH32
 *      and will contain an xxhash32 checksum.
 *
 *   -# Both pResults->crc32 and pResults->adler32 are available if
 *      CpaDcSessionSetupData->checksum is set to CPA_DC_CRC32_ADLER32
 *      and will contain crc32 and adler32 checksums respectively.
 *
 *  Synchronous or asynchronous operation of the API is determined by
 *  the value of the callbackFn parameter passed to cpaDcChainInitSession()
 *  when the sessionHandle was setup. If a non-NULL value was specified
 *  then the supplied callback function will be invoked asynchronously
 *  with the response of this request.
 *
 *  This function has identical response ordering rules as
 *  cpaDcCompressData().
 *
 * @see
 *      cpaDcCompressData
 *
 *****************************************************************************/
CpaStatus cpaDcChainPerformOp(CpaInstanceHandle dcInstance,
                              CpaDcSessionHandle pSessionHandle,
                              CpaBufferList *pSrcBuff,
                              CpaBufferList *pDestBuff,
                              CpaDcChainOperations operation,
                              Cpa8U numOpData,
                              CpaDcChainOpData *pChainOpData,
                              CpaDcChainRqResults *pResults,
                              void *callbackTag);

/**
 *****************************************************************************
 * @ingroup cpaDcChain
 *      Submit a request to perform chaining with integrity operations.
 *
 * @description
 *      This function is used to perform chaining operations over data from
 *      the source buffer with optional integrity checking.
 *
 * @context
 *      When called as an asynchronous function it cannot sleep. It can be
 *      executed in a context that does not permit sleeping.
 *      When called as a synchronous function it may sleep. It MUST NOT be
 *      executed in a context that DOES NOT permit sleeping.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      Yes when configured to operate in synchronous mode.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]     dcInstance        Target service instance.
 * @param[in,out] pSessionHandle    Session handle.
 * @param[in]     pSrcBuff          Pointer to input data buffer.
 * @param[out]    pDestBuff         Pointer to output data buffer.
 * @param[in]     pInterBuff        Pointer to intermediate buffer to be used
 *                                  as internal staging area for chaining
 *                                  operations.
 * @param[in]     opData            User supplied CpaDcChainOpData2
 *                                  structure.
 * @param[in,out] pResults          Pointer to CpaDcChainRqVResults
 *                                  structure.
 * @param[in]     callbackTag       User supplied value to help correlate
 *                                  the callback with its associated request.
 *
 * @retval CPA_STATUS_SUCCESS       Function executed successfully.
 * @retval CPA_STATUS_FAIL          Function failed.
 * @retval CPA_STATUS_RETRY         Resubmit the request.
 * @retval CPA_STATUS_INVALID_PARAM Invalid parameter passed in.
 * @retval CPA_STATUS_RESOURCE      Error related to system resources.
 * @retval CPA_DC_BAD_DATA          The input data was not properly formed.
 * @retval CPA_STATUS_RESTARTING    API implementation is restarting. Resubmit
 *                                  the request.
 * @retval CPA_STATUS_UNSUPPORTED   Function is not supported.
 *
 * @pre
 *     pSessionHandle has been setup using cpaDcChainInitSession()
 * @post
 *     Following synchronous operation:
 *     The pSessionHandle will contain updated session related state
 *     information.
 *     The pDestBuff will contain processed data following the chained
 *     operation.
 *     The pResults will contain the status/checksums/additional outputs
 *     from the completed chained operation.
 *     Following asynchronous operation:
 *     The call has been submitted only and the data structures above will
 *     only be safe to use once the asynchronous callback is called.
 * @note
 *     This function passes control to the compression service for chaining
 *     processing, the supported chaining operations are described in
 *     CpaDcChainOperations.
 *     This function is a replacement for cpaDcChainPerformOp() supporting
 *     additional integrity chaining features and should be used if these
 *     additional features are required.
 *
 *  User supplied opData contains pChainOpData
 *  -# Refer to cpaDcChainPerformOp for pChainOpData Setup Rules
 *
 *  This function has identical buffer processing rules as
 *  cpaDcCompressData().
 *
 *  Synchronous or asynchronous operation of the API is determined by
 *  the value of the callbackFn parameter passed to cpaDcChainInitSession()
 *  when the sessionHandle was setup. If a non-NULL value was specified
 *  then the supplied callback function will be invoked asynchronously
 *  with the response of this request.
 *
 *  This function has identical response ordering rules as
 *  cpaDcCompressData().
 *
 * @see
 *      cpaDcCompressData
 *
 *****************************************************************************/
CpaStatus cpaDcChainPerformOp2(CpaInstanceHandle dcInstance,
                               CpaDcSessionHandle pSessionHandle,
                               CpaBufferList *pSrcBuff,
                               CpaBufferList *pDestBuff,
                               CpaBufferList *pInterBuff,
                               CpaDcChainOpData2 opData,
                               CpaDcChainRqVResults *pResults,
                               void *callbackTag);

#ifdef __cplusplus
} /* close the extern "C" { */
#endif

#endif /* CPA_DC_CHAIN_H */
