FreeBSD/Linux Kernel Cross Reference
sys/dev/qat/qat_api/include/lac/cpa_cy_sym_dp.h

     /***************************************************************************
      *
      *   BSD LICENSE
      * 
      *   Copyright(c) 2007-2022 Intel Corporation. All rights reserved.
      *   All rights reserved.
      * 
      *   Redistribution and use in source and binary forms, with or without
      *   modification, are permitted provided that the following conditions
     *   are met:
     * 
     *     * Redistributions of source code must retain the above copyright
     *       notice, this list of conditions and the following disclaimer.
     *     * Redistributions in binary form must reproduce the above copyright
     *       notice, this list of conditions and the following disclaimer in
     *       the documentation and/or other materials provided with the
     *       distribution.
     *     * Neither the name of Intel Corporation nor the names of its
     *       contributors may be used to endorse or promote products derived
     *       from this software without specific prior written permission.
     * 
     *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
     *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
     *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
     *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
     *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
     *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     * 
     *
     ***************************************************************************/
    
    /*
     *****************************************************************************
     * Doxygen group definitions
     ****************************************************************************/
    
    /**
     *****************************************************************************
     * @file cpa_cy_sym_dp.h
     *
     * @defgroup cpaCySymDp Symmetric cryptographic Data Plane API
     *
     * @ingroup cpaCySym
     *
     * @description
     *      These data structures and functions specify the Data Plane API
     *      for symmetric cipher, hash, and combined cipher and hash
     *      operations.
     *
     *      This API is recommended for data plane applications, in which the
     *      cost of offload - that is, the cycles consumed by the driver in
     *      sending requests to the hardware, and processing responses - needs
     *      to be minimized.  In particular, use of this API is recommended
     *      if the following constraints are acceptable to your application:
     *
     *      - Thread safety is not guaranteed.  Each software thread should
     *        have access to its own unique instance (CpaInstanceHandle) to
     *        avoid contention.
     *      - Polling is used, rather than interrupts (which are expensive).
     *        Implementations of this API will provide a function (not
     *        defined as part of this API) to read responses from the hardware
     *        response queue and dispatch callback functions, as specified on
     *        this API.
     *      - Buffers and buffer lists are passed using physical addresses,
     *        to avoid virtual to physical address translation costs.
     *      - For GCM and CCM modes of AES, when performing decryption and
     *        verification, if verification fails, then the message buffer
     *        will NOT be zeroed.  (This is a consequence of using physical
     *        addresses for the buffers.)
     *      - The ability to enqueue one or more requests without submitting
     *        them to the hardware allows for certain costs to be amortized
     *        across multiple requests.
     *      - Only asynchronous invocation is supported.
     *      - There is no support for partial packets.
     *      - Implementations may provide certain features as optional at
     *        build time, such as atomic counters.
     *      - The "default" instance (@ref CPA_INSTANCE_HANDLE_SINGLE) is not
     *        supported on this API.  The specific handle should be obtained
     *        using the instance discovery functions (@ref cpaCyGetNumInstances,
     *        @ref cpaCyGetInstances).
     *
     * @note Performance Trade-Offs
     *      Different implementations of this API may have different performance
     *      trade-offs; please refer to the documentation for your implementation
     *      for details.  However, the following concepts informed the definition
     *      of this API.
     *
     *      The API distinguishes between <i>enqueuing</i> a request and actually
     *      <i>submitting</i> that request to the cryptographic acceleration
     *      engine to be performed.  This allows multiple requests to be enqueued
     *      (either individually or in batch), and then for all enqueued requests
     *      to be submitted in a single operation.  The rationale is that in some
     *      (especially hardware-based) implementations, the submit operation
     *      is expensive; for example, it may incur an MMIO instruction.  The
    *      API allows this cost to be amortized over a number of requests.  The
    *      precise number of such requests can be tuned for optimal
    *      performance.
    *
    *      Specifically:
    *
    *      - The function @ref cpaCySymDpEnqueueOp allows one request to be
    *        enqueued, and optionally for that request (and all previously
    *        enqueued requests) to be submitted.
    *      - The function @ref cpaCySymDpEnqueueOpBatch allows multiple
    *        requests to be enqueued, and optionally for those requests (and all
    *        previously enqueued requests) to be submitted.
    *      - The function @ref cpaCySymDpPerformOpNow enqueues no requests, but
    *        submits all previously enqueued requests.
    *****************************************************************************/
   
   #ifndef CPA_CY_SYM_DP_H
   #define CPA_CY_SYM_DP_H
   
   #ifdef __cplusplus
   extern "C" {
   #endif
   
   #include "cpa_cy_common.h"
   #include "cpa_cy_sym.h"
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Cryptographic component symmetric session context handle for the
    *      data plane API.
    * @description
    *      Handle to a cryptographic data plane session context. The memory for
    *      this handle is allocated by the client. The size of the memory that
    *      the client needs to allocate is determined by a call to the @ref
    *      cpaCySymDpSessionCtxGetSize or @ref cpaCySymDpSessionCtxGetDynamicSize
    *      functions. The session context memory is initialized with a call to 
    *      the @ref cpaCySymInitSession function.
    *      This memory MUST not be freed until a call to @ref
    *      cpaCySymDpRemoveSession has completed successfully.
    *
    *****************************************************************************/
   typedef void * CpaCySymDpSessionCtx;
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Operation Data for cryptographic data plane API.
    *
    * @description
    *      This structure contains data relating to a request to perform
    *      symmetric cryptographic processing on one or more data buffers.
    *
    *      The physical memory to which this structure points needs to be
    *      at least 8-byte aligned.
    *
    *      All reserved fields SHOULD NOT be written or read by the
    *      calling code.
    *
    * @see
    *        cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch
    ****************************************************************************/
   typedef struct _CpaCySymDpOpData {
       Cpa64U reserved0;
       /**< Reserved for internal usage. */
       Cpa32U cryptoStartSrcOffsetInBytes;
       /**< Starting point for cipher processing, specified as number of bytes
        * from start of data in the source buffer. The result of the cipher
        * operation will be written back into the buffer starting at this
        * location in the destination buffer.
        */
       Cpa32U messageLenToCipherInBytes;
       /**< The message length, in bytes, of the source buffer on which the
        * cryptographic operation will be computed. This must be a multiple of
        * the block size if a block cipher is being used. This is also the
        * same as the result length.
        *
        * @note In the case of CCM (@ref CPA_CY_SYM_HASH_AES_CCM), this value
        * should not include the length of the padding or the length of the
        * MAC; the driver will compute the actual number of bytes over which
        * the encryption will occur, which will include these values.
        *
        * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC), this field
        * should be set to 0.
        *
        * @note On some implementations, this length may be limited to a 16-bit
        * value (65535 bytes).
        */
       CpaPhysicalAddr iv;
       /**< Initialization Vector or Counter.  Specifically, this is the
        * physical address of one of the following:
        *
        * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for
        *   SNOW3G in UEA2 mode, this is the Initialization Vector (IV)
        *   value.
        * - For ARC4, this is reserved for internal usage.
        * - For block ciphers in CTR mode, this is the counter.
        * - For GCM mode, this is either the IV (if the length is 96 bits) or J0
        *   (for other sizes), where J0 is as defined by NIST SP800-38D.
        *   Regardless of the IV length, a full 16 bytes needs to be allocated.
        * - For CCM mode, the first byte is reserved, and the nonce should be
        *   written starting at &pIv[1] (to allow space for the implementation
        *   to write in the flags in the first byte).  Note that a full 16 bytes
        *   should be allocated, even though the ivLenInBytes field will have
        *   a value less than this.
        *   The macro @ref CPA_CY_SYM_CCM_SET_NONCE may be used here.
        */
       Cpa64U reserved1;
       /**< Reserved for internal usage. */
       Cpa32U hashStartSrcOffsetInBytes;
       /**< Starting point for hash processing, specified as number of bytes
        * from start of packet in source buffer.
        *
        * @note For CCM and GCM modes of operation, this value in this field
        * is ignored, and the field is reserved for internal usage.
        * The fields @ref additionalAuthData and @ref pAdditionalAuthData
        * should be set instead.
        *
        * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of
        * operation, this field specifies the start of the AAD data in
        * the source buffer.
        */
       Cpa32U messageLenToHashInBytes;
       /**< The message length, in bytes, of the source buffer that the hash
        * will be computed on.
        *
        * @note For CCM and GCM modes of operation, this value in this field
        * is ignored, and the field is reserved for internal usage.
        * The fields @ref additionalAuthData and @ref pAdditionalAuthData
        * should be set instead.
        *
        * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of
        * operation, this field specifies the length of the AAD data in the
        * source buffer.
        *
        * @note On some implementations, this length may be limited to a 16-bit
        * value (65535 bytes).
        */
       CpaPhysicalAddr additionalAuthData;
       /**< Physical address of the Additional Authenticated Data (AAD),
        * which is needed for authenticated cipher mechanisms (CCM and
        * GCM), and to the IV for  SNOW3G authentication (@ref
        * CPA_CY_SYM_HASH_SNOW3G_UIA2). For other authentication
        * mechanisms, this value is ignored, and the field is reserved for
        * internal usage.
        *
        * The length of the data pointed to by this field is set up for
        * the session in the @ref CpaCySymHashAuthModeSetupData structure
        * as part of the @ref cpaCySymDpInitSession function call.  This length
        * must not exceed 240 bytes.
   
        * If AAD is not used, this address must be set to zero.
        *
        * Specifically for CCM (@ref CPA_CY_SYM_HASH_AES_CCM) and GCM (@ref
        * CPA_CY_SYM_HASH_AES_GCM), the caller should be setup as described in
        * the same way as the corresponding field, pAdditionalAuthData, on the
        * "traditional" API (see the @ref CpaCySymOpData).
        *
        * @note For AES-GMAC (@ref CPA_CY_SYM_HASH_AES_GMAC) mode of
        * operation, this field is not used and should be set to 0. Instead
        * the AAD data should be placed in the source buffer.
        *
        */
       CpaPhysicalAddr digestResult;
       /**<  If the digestIsAppended member of the @ref CpaCySymSessionSetupData
        * structure is NOT set then this is the physical address of the location
        * where the digest result should be inserted (in the case of digest
        * generation) or where the purported digest exists (in the case of digest
        * verification).
        *
        * At session registration time, the client specified the digest result
        * length with the digestResultLenInBytes member of the @ref
        * CpaCySymHashSetupData structure. The client must allocate at least
        * digestResultLenInBytes of physically contiguous memory at this location.
        *
        * For digest generation, the digest result will overwrite any data
        * at this location.
        *
        * @note For GCM (@ref CPA_CY_SYM_HASH_AES_GCM), for "digest result"
        * read "authentication tag T".
        *
        * If the digestIsAppended member of the @ref CpaCySymSessionSetupData
        * structure is set then this value is ignored and the digest result
        * is understood to be in the destination buffer for digest generation,
        * and in the source buffer for digest verification. The location of the
        * digest result in this case is immediately following the region over
        * which the digest is computed.
        */
   
       CpaInstanceHandle instanceHandle;
       /**< Instance to which the request is to be enqueued.
        * @note A callback function must have been registered on the instance
        * using @ref cpaCySymDpRegCbFunc.
        */
       CpaCySymDpSessionCtx sessionCtx;
       /**< Session context specifying the cryptographic parameters for this
        * request.
        * @note The session must have been created using @ref
        * cpaCySymDpInitSession.
        */
       Cpa32U ivLenInBytes;
       /**< Length of valid IV data pointed to by the pIv parameter.
        *
        * - For block ciphers in CBC mode, or for Kasumi in F8 mode, or for
        *   SNOW3G in UEA2 mode, this is the length of the IV (which
        *   must be the same as the block length of the cipher).
        * - For block ciphers in CTR mode, this is the length of the counter
        *   (which must be the same as the block length of the cipher).
        * - For GCM mode, this is either 12 (for 96-bit IVs) or 16, in which
        *   case pIv points to J0.
        * - For CCM mode, this is the length of the nonce, which can be in the
        *   range 7 to 13 inclusive.
        */
       CpaPhysicalAddr srcBuffer;
       /**< Physical address of the source buffer on which to operate.
        * This is either:
        *
        * - The location of the data, of length srcBufferLen; or,
        * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then
        *   srcBuffer contains the location where a @ref CpaPhysBufferList is
        *   stored.  In this case, the CpaPhysBufferList MUST be aligned
        *   on an 8-byte boundary.
        * - For optimum performance, the buffer should only contain the data 
        *   region that the cryptographic operation(s) must be performed on. 
        *   Any additional data in the source buffer may be copied to the 
        *   destination buffer and this copy may degrade performance.
        */
       Cpa32U  srcBufferLen;
       /**< Length of source buffer, or @ref CPA_DP_BUFLIST. */
       CpaPhysicalAddr dstBuffer;
       /**< Physical address of the destination buffer on which to operate.
        * This is either:
        *
        * - The location of the data, of length srcBufferLen; or,
        * - If srcBufferLen has the special value @ref CPA_DP_BUFLIST, then
        *   srcBuffer contains the location where a @ref CpaPhysBufferList is
        *   stored.  In this case, the CpaPhysBufferList MUST be aligned
        *   on an 8-byte boundary.
        *
        * For "in-place" operation, the dstBuffer may be identical to the
        * srcBuffer.
        */
       Cpa32U  dstBufferLen;
       /**< Length of destination buffer, or @ref CPA_DP_BUFLIST. */
   
       CpaPhysicalAddr thisPhys;
       /**< Physical address of this data structure */
   
       Cpa8U* pIv;
       /**< Pointer to (and therefore, the virtual address of) the IV field
        * above.
        * Needed here because the driver in some cases writes to this field,
        * in addition to sending it to the accelerator.
        */
       Cpa8U *pAdditionalAuthData;
       /**< Pointer to (and therefore, the virtual address of) the
        * additionalAuthData field above.
        * Needed here because the driver in some cases writes to this field,
        * in addition to sending it to the accelerator.
        */
       void* pCallbackTag;
       /**< Opaque data that will be returned to the client in the function
        * completion callback.
        *
        * This opaque data is not used by the implementation of the API,
        * but is simply returned as part of the asynchronous response.
        * It may be used to store information that might be useful when
        * processing the response later.
        */
   } CpaCySymDpOpData;
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Definition of callback function for cryptographic data plane API.
    *
    * @description
    *      This is the callback function prototype. The callback function is
    *      registered by the application using the @ref cpaCySymDpRegCbFunc
    *      function call, and called back on completion of asycnhronous
    *      requests made via calls to @ref cpaCySymDpEnqueueOp or @ref
    *      cpaCySymDpEnqueueOpBatch.
    *
    * @context
    *      This callback function can be executed in a context that DOES NOT
    *      permit sleeping to occur.
    * @assumptions
    *      None
    * @sideEffects
    *      None
    * @reentrant
    *      No
    * @threadSafe
    *      No
    *
    * @param[in] pOpData           Pointer to the CpaCySymDpOpData object which
    *                              was supplied as part of the original request.
    * @param[in] status            Status of the operation. Valid values are
    *                              CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
    *                              CPA_STATUS_UNSUPPORTED.
    * @param[in] 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.
    *
    * @return
    *      None
    * @pre
    *      Component has been initialized.
    *      Callback has been registered with @ref cpaCySymDpRegCbFunc.
    * @post
    *      None
    * @note
    *      None
    * @see
    *      cpaCySymDpRegCbFunc
    *****************************************************************************/
   typedef void (*CpaCySymDpCbFunc)(CpaCySymDpOpData *pOpData,
           CpaStatus status,
           CpaBoolean verifyResult);
   
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Registration of the operation completion callback function.
    *
    * @description
    *      This function allows a completion callback function to be registered.
    *      The registered callback function is invoked on completion of
    *      asycnhronous requests made via calls to @ref cpaCySymDpEnqueueOp
    *      or @ref cpaCySymDpEnqueueOpBatch.
    *
    *      If a callback function was previously registered, it is overwritten.
    *
    * @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
    * @reentrant
    *      No
    * @threadSafe
    *      No
    *
    * @param[in] instanceHandle    Instance on which the callback function is to be
    *                                 registered.
    * @param[in] pSymNewCb         Callback function for this instance.
   
    * @retval CPA_STATUS_SUCCESS        Function executed successfully.
    * @retval CPA_STATUS_FAIL           Function failed.
    * @retval CPA_STATUS_RESTARTING     API implementation is restarting. Resubmit
    *                                   the request.
    * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
    *
    * @pre
    *      Component has been initialized.
    * @post
    *      None
    * @note
    *      None
    * @see
    *      CpaCySymDpCbFunc
    *****************************************************************************/
   CpaStatus cpaCySymDpRegCbFunc(const CpaInstanceHandle instanceHandle,
           const CpaCySymDpCbFunc pSymNewCb);
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Gets the size required to store a session context for the data plane
    *      API.
    *
    * @description
    *      This function is used by the client to determine the size of the memory
    *      it must allocate in order to store the session context. This MUST be
    *      called before the client allocates the memory for the session context
    *      and before the client calls the @ref cpaCySymDpInitSession function.
    *
    *      For a given implementation of this API, it is safe to assume that
    *      cpaCySymDpSessionCtxGetSize() will always return the same size and that
    *      the size will not be different for different setup data parameters.
    *      However, it should be noted that the size may change:
    *        (1) between different implementations of the API (e.g. between software
    *            and hardware implementations or between different hardware
    *            implementations)
    *        (2) between different releases of the same API implementation.
    *
    *      The size returned by this function is the smallest size needed to 
    *      support all possible combinations of setup data parameters. Some
    *      setup data parameter combinations may fit within a smaller session 
    *      context size. The alternate cpaCySymDpSessionCtxGetDynamicSize() 
    *      function will return the smallest size needed to fit the
    *      provided setup data parameters.
    *
    * @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]  instanceHandle            Instance handle.
    * @param[in]  pSessionSetupData         Pointer to session setup data which
    *                                       contains parameters which are static
    *                                       for a given cryptographic session such
    *                                       as operation type, mechanisms, and keys
    *                                       for cipher and/or hash operations.
    * @param[out] pSessionCtxSizeInBytes    The amount of memory in bytes required
    *                                       to hold the Session Context.
    *
    * @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
    *      The component has been initialized.
    * @post
    *      None
    * @note
    *      This is a synchronous function and has no completion callback
    *      associated with it.
    * @see
    *      CpaCySymSessionSetupData
    *      cpaCySymDpSessionCtxGetDynamicSize()
    *      cpaCySymDpInitSession()
    *****************************************************************************/
   CpaStatus
   cpaCySymDpSessionCtxGetSize(const CpaInstanceHandle instanceHandle,
           const CpaCySymSessionSetupData *pSessionSetupData,
           Cpa32U *pSessionCtxSizeInBytes);
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Gets the minimum size required to store a session context for the data 
    *      plane API.
    *
    * @description
    *      This function is used by the client to determine the smallest size of
    *      the memory it must allocate in order to store the session context. 
    *      This MUST be called before the client allocates the memory for the 
    *      session context and before the client calls the 
    *      @ref cpaCySymDpInitSession function.
    *
    *      This function is an alternate to cpaCySymDpSessionGetSize().
    *      cpaCySymDpSessionCtxGetSize() will return a fixed size which is the 
    *      minimum memory size needed to support all possible setup data parameter 
    *      combinations. cpaCySymDpSessionCtxGetDynamicSize() will return the 
    *      minimum memory size needed to support the specific session setup 
    *      data parmeters provided. This size may be different for different setup
    *      data parameters.
    *
    * @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]  instanceHandle            Instance handle.
    * @param[in]  pSessionSetupData         Pointer to session setup data which
    *                                       contains parameters which are static
    *                                       for a given cryptographic session such
    *                                       as operation type, mechanisms, and keys
    *                                       for cipher and/or hash operations.
    * @param[out] pSessionCtxSizeInBytes    The amount of memory in bytes required
    *                                       to hold the Session Context.
    *
    * @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
    *      The component has been initialized.
    * @post
    *      None
    * @note
    *      This is a synchronous function and has no completion callback
    *      associated with it.
    * @see
    *      CpaCySymSessionSetupData
    *      cpaCySymDpSessionCtxGetSize()
    *      cpaCySymDpInitSession()
    *****************************************************************************/
   CpaStatus
   cpaCySymDpSessionCtxGetDynamicSize(const CpaInstanceHandle instanceHandle,
           const CpaCySymSessionSetupData *pSessionSetupData,
           Cpa32U *pSessionCtxSizeInBytes);
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Initialize a session for the symmetric cryptographic data plane API.
    *
    * @description
    *      This function is used by the client to initialize an asynchronous
    *      session context for symmetric cryptographic data plane operations.
    *      The returned session context is the handle to the session and needs to
    *      be passed when requesting cryptographic operations to be performed.
    *
    *      Only sessions created using this function may be used when
    *      invoking functions on this API
    *
    *      The session can be removed using @ref cpaCySymDpRemoveSession.
    *
    * @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
    *      No
    *
    * @param[in] instanceHandle        Instance to which the requests will be
    *                                  submitted.
    * @param[in]  pSessionSetupData    Pointer to session setup data which
    *                                     contains parameters that are static
    *                                     for a given cryptographic session such
    *                                     as operation type, algorithm, and keys
    *                                     for cipher and/or hash operations.
    * @param[out] sessionCtx           Pointer to the memory allocated by the
    *                                  client to store the session context. This
    *                                  memory must be physically contiguous, and
    *                                  its length (in bytes) must be at least as
    *                                  big as specified by a call to @ref
    *                                  cpaCySymDpSessionCtxGetSize.  This memory
    *                                  will be initialized with this function. This
    *                                  value needs to be passed to subsequent
    *                                  processing calls.
    *
    * @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.
    * @post
    *      None
    * @note
    *      This is a synchronous function and has no completion callback
    *      associated with it.
    * @see
    *      cpaCySymDpSessionCtxGetSize, cpaCySymDpRemoveSession
    *****************************************************************************/
   CpaStatus
   cpaCySymDpInitSession(CpaInstanceHandle instanceHandle,
           const CpaCySymSessionSetupData *pSessionSetupData,
           CpaCySymDpSessionCtx sessionCtx);
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *      Remove (delete) a symmetric cryptographic session for the data plane
    *      API.
    *
    * @description
    *      This function will remove a previously initialized session context
    *      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 context 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
    *      No
    *
    * @param[in]      instanceHandle    Instance handle.
    * @param[in,out]  sessionCtx        Session context to be removed.
    *
    * @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.
    * @post
    *      None
    * @note
    *      Note that this is a synchronous function and has no completion callback
    *      associated with it.
    *
    * @see
    *      CpaCySymDpSessionCtx,
    *      cpaCySymDpInitSession()
    *
    *****************************************************************************/
   CpaStatus
   cpaCySymDpRemoveSession(const CpaInstanceHandle instanceHandle,
           CpaCySymDpSessionCtx sessionCtx);
   
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *         Enqueue a single symmetric cryptographic request.
    *
    * @description
    *      This function enqueues a single request to perform a cipher,
    *      hash or combined (cipher and hash) operation.  Optionally, the
    *      request is also submitted to the cryptographic engine to be
    *      performed.
    *
    *      See note about performance trade-offs on the @ref cpaCySymDp API.
    *
    *      The function is asynchronous; control is returned to the user once
    *      the request has been submitted.  On completion of the request, the
    *      application may poll for responses, which will cause a callback
    *      function (registered via @ref cpaCySymDpRegCbFunc) to be invoked.
    *      Callbacks within a session are guaranteed to be in the same order
    *      in which they were submitted.
    *
    *      The following restrictions apply to the pOpData parameter:
    *
    *      - The memory MUST be aligned on an 8-byte boundary.
    *      - The structure MUST reside in physically contiguous memory.
    *      - The reserved fields of the structure SHOULD NOT be written
    *        or read by the calling code.
    *
    * @context
    *      This function will not sleep, and hence can be executed in a context
    *      that does not permit sleeping.
    *
    * @sideEffects
    *      None
    * @blocking
    *      No
    * @reentrant
    *      No
    * @threadSafe
    *      No
    *
    * @param[in] pOpData           Pointer to a structure containing the
    *                              request parameters. The client code allocates
    *                              the memory for this structure. This component
    *                              takes ownership of the memory until it is
    *                              returned in the callback, which was registered
    *                              on the instance via @ref cpaCySymDpRegCbFunc.
    *                              See the above Description for restrictions
    *                              that apply to this parameter.
    * @param[in] performOpNow      Flag to specify whether the operation should be
    *                                 performed immediately (CPA_TRUE), or simply
    *                                 enqueued to be performed later (CPA_FALSE).
    *                                 In the latter case, the request is submitted
    *                                 to be performed either by calling this function
    *                                 again with this flag set to CPA_TRUE, or by
    *                                 invoking the function @ref
    *                                 cpaCySymDpPerformOpNow.
    *
    * @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_RESTARTING     API implementation is restarting. Resubmit
    *                                   the request.
    * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
    *
    * @pre
    *      The session identified by pOpData->sessionCtx was setup using
    *      @ref cpaCySymDpInitSession.
    *      The instance identified by pOpData->instanceHandle has had a
    *      callback function registered via @ref cpaCySymDpRegCbFunc.
    *
    * @post
    *      None
    *
    * @note
    *      A callback of type @ref CpaCySymDpCbFunc is generated in response to
    *      this function call. Any errors generated during processing are
    *      reported as part of the callback status code.
    *
    * @see
    *      cpaCySymDpInitSession,
    *      cpaCySymDpPerformOpNow
    *****************************************************************************/
   CpaStatus
   cpaCySymDpEnqueueOp(CpaCySymDpOpData *pOpData,
           const CpaBoolean performOpNow);
   
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *         Enqueue multiple requests to the symmetric cryptographic data plane
    *      API.
    *
    * @description
    *      This function enqueues multiple requests to perform cipher, hash
    *      or combined (cipher and hash) operations.
   
    *      See note about performance trade-offs on the @ref cpaCySymDp API.
    *
    *      The function is asynchronous; control is returned to the user once
    *      the request has been submitted.  On completion of the request, the
    *      application may poll for responses, which will cause a callback
    *      function (registered via @ref cpaCySymDpRegCbFunc) to be invoked.
    *      Separate callbacks will be invoked for each request.
    *      Callbacks within a session are guaranteed to be in the same order
    *      in which they were submitted.
    *
    *      The following restrictions apply to each element of the pOpData
    *      array:
    *
    *      - The memory MUST be aligned on an 8-byte boundary.
    *      - The structure MUST reside in physically contiguous memory.
    *      - The reserved fields of the structure SHOULD NOT be
    *        written or read by the calling code.
    *
    * @context
    *      This function will not sleep, and hence can be executed in a context
    *      that does not permit sleeping.
    *
    * @assumptions
    *      Client MUST allocate the request parameters to 8 byte alignment.
    *      Reserved elements of the CpaCySymDpOpData structure MUST be 0.
    *      The CpaCySymDpOpData structure MUST reside in physically
    *      contiguous memory.
    *
    * @sideEffects
    *      None
    * @blocking
    *      No
    * @reentrant
    *      No
    * @threadSafe
    *      No
    *
    * @param[in] numberRequests    The number of requests in the array of
    *                              CpaCySymDpOpData structures.
    * @param[in] pOpData           An array of pointers to CpaCySymDpOpData
    *                              structures.  Each of the CpaCySymDpOpData
    *                              structure contains the request parameters for
    *                              that request. The client code allocates the
    *                              memory for this structure. This component takes
    *                              ownership of the memory until it is returned in
    *                              the callback, which was registered on the
    *                              instance via @ref cpaCySymDpRegCbFunc.
    *                              See the above Description for restrictions
    *                              that apply to this parameter.
    * @param[in] performOpNow      Flag to specify whether the operation should be
    *                                 performed immediately (CPA_TRUE), or simply
    *                                 enqueued to be performed later (CPA_FALSE).
    *                                 In the latter case, the request is submitted
    *                                 to be performed either by calling this function
    *                                 again with this flag set to CPA_TRUE, or by
    *                                 invoking the function @ref
    *                                 cpaCySymDpPerformOpNow.
    *
    * @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_RESTARTING     API implementation is restarting. Resubmit
    *                                   the request.
    * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
    *
    * @pre
    *      The session identified by pOpData[i]->sessionCtx was setup using
    *      @ref cpaCySymDpInitSession.
    *      The instance identified by pOpData->instanceHandle[i] has had a
    *      callback function registered via @ref cpaCySymDpRegCbFunc.
    *
    * @post
    *      None
    *
    * @note
    *      Multiple callbacks of type @ref CpaCySymDpCbFunc are generated in
    *      response to this function call (one per request).  Any errors
    *      generated during processing are reported as part of the callback
    *      status code.
    *
    * @see
    *      cpaCySymDpInitSession,
    *      cpaCySymDpEnqueueOp
    *****************************************************************************/
   CpaStatus
   cpaCySymDpEnqueueOpBatch(const Cpa32U numberRequests,
           CpaCySymDpOpData *pOpData[],
           const CpaBoolean performOpNow);
   
   
   /**
    *****************************************************************************
    * @ingroup cpaCySymDp
    *         Submit any previously enqueued requests to be performed now on the
    *         symmetric cryptographic data plane API.
    *
    * @description
    *      If any requests/operations were enqueued via calls to @ref
    *      cpaCySymDpEnqueueOp and/or @ref cpaCySymDpEnqueueOpBatch, but with
    *      the flag performOpNow set to @ref CPA_FALSE, then these operations
    *      will now be submitted to the accelerator to be performed.
    *
    *      See note about performance trade-offs on the @ref cpaCySymDp API.
    *
    * @context
    *      Will not sleep. It can be executed in a context that does not
    *      permit sleeping.
    *
    * @sideEffects
    *      None
    * @blocking
    *      No
    * @reentrant
    *      No
    * @threadSafe
    *      No
    *
    * @param[in] instanceHandle        Instance to which the requests will be
    *                                     submitted.
    *
    * @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_RESTARTING     API implementation is restarting. Resubmit
    *                                   the request.
    * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
    *
    * @pre
    *      The component has been initialized.
    *      A cryptographic session has been previously setup using the
    *      @ref cpaCySymDpInitSession function call.
    *
    * @post
    *      None
    *
    * @see
    *      cpaCySymDpEnqueueOp, cpaCySymDpEnqueueOpBatch
    *****************************************************************************/
   CpaStatus
   cpaCySymDpPerformOpNow(CpaInstanceHandle instanceHandle);
   
   
   #ifdef __cplusplus
   } /* close the extern "C" { */
   #endif
   
   #endif /* CPA_CY_SYM_DP_H */

Cache object: c00af5853277094b5fa2855b6556b9e9