/***************************************************************************
*
* BSD LICENSE
*
* Copyright(c) 2007-2023 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 enqueuing a request and actually
* submitting 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 parameters 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 */