/***************************************************************************
 *
 *   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_cy_common.h
 *
 * @defgroup cpaCy Cryptographic API
 *
 * @ingroup cpa
 *
 * @description
 *      These functions specify the Cryptographic API.
 *
 *****************************************************************************/

/**
 *****************************************************************************
 * @file cpa_cy_common.h
 * @defgroup cpaCyCommon Cryptographic Common API
 *
 * @ingroup cpaCy
 *
 * @description
 *      This file specifies items which are common for both the asymmetric
 *      (public key cryptography) and the symmetric operations for the
 *      Cryptographic API.
 *
 *****************************************************************************/
#ifndef CPA_CY_COMMON_H
#define CPA_CY_COMMON_H

#ifdef __cplusplus
extern "C" {
#endif

#include "cpa.h"

/**
 *****************************************************************************
 * @ingroup cpa_cyCommon
 *      CPA CY Major Version Number
 * @deprecated
 *      As of v5.0 of the Crypto API, this define has been deprecated,
 *      replaced by @ref CPA_API_VERSION_NUM_MAJOR.
 * @description
 *      The CPA_CY API major version number. This number will be incremented
 *      when significant churn to the API has occurred. The combination of the
 *      major and minor number definitions represent the complete version number
 *      for this interface.
 *
 *****************************************************************************/
#define CPA_CY_API_VERSION_NUM_MAJOR (CPA_API_VERSION_NUM_MAJOR)

/**
 *****************************************************************************
 * @ingroup cpa_cyCommon
 *       CPA CY Minor Version Number
 * @deprecated
 *      As of v5.0 of the Crypto API, this define has been deprecated,
 *      replaced by @ref CPA_API_VERSION_NUM_MINOR.
 * @description
 *      The CPA_CY API minor version number. This number will be incremented
 *      when minor changes to the API has occurred. The combination of the major
 *      and minor number definitions represent the complete version number for
 *      this interface.
 *
 *****************************************************************************/
#define CPA_CY_API_VERSION_NUM_MINOR (CPA_API_VERSION_NUM_MINOR)

/**
 *****************************************************************************
 * @file cpa_cy_common.h
 * @ingroup cpa_cyCommon
 *       CPA CY API version at least
 * @description
 *      The minimal supported CPA_CY API version. Allow to check if the API
 *      version is equal or above some version to avoid compilation issues
 *      with an older API version.
 *
 *****************************************************************************/
#define CPA_CY_API_VERSION_AT_LEAST(major, minor)                              \
    (CPA_CY_API_VERSION_NUM_MAJOR > major ||                                   \
     (CPA_CY_API_VERSION_NUM_MAJOR == major &&                                 \
      CPA_CY_API_VERSION_NUM_MINOR >= minor))

/**
 *****************************************************************************
 * @file cpa_cy_common.h
 * @ingroup cpa_cyCommon
 *       CPA CY API version less than
 * @description
 *      The maximum supported CPA_CY API version. Allow to check if the API
 *      version is below some version to avoid compilation issues with a newer
 *      API version.
 *
 *****************************************************************************/
#define CPA_CY_API_VERSION_LESS_THAN(major, minor)                             \
    (CPA_CY_API_VERSION_NUM_MAJOR < major ||                                   \
     (CPA_CY_API_VERSION_NUM_MAJOR == major &&                                 \
      CPA_CY_API_VERSION_NUM_MINOR < minor))

/**
 *****************************************************************************
 * @file cpa_cy_common.h
 * @ingroup cpaCyCommon
 *      Request priority
 * @description
 *      Enumeration of priority of the request to be given to the API.
 *      Currently two levels - HIGH and NORMAL are supported. HIGH priority
 *      requests will be prioritized on a "best-effort" basis over requests
 *      that are marked with a NORMAL priority.
 *
 *****************************************************************************/
typedef enum
{
    CPA_CY_PRIORITY_NORMAL = 1, /**< Normal priority */
    CPA_CY_PRIORITY_HIGH        /**< High priority */
} CpaCyPriority;

/*****************************************************************************/
/* Callback Definitions                                                      */
/*****************************************************************************/
/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Definition of the crypto generic callback function
 *
 * @description
 *      This data structure specifies the prototype for a generic callback
 *      function
 *
 * @context
 *      This callback function can be executed in a context that DOES NOT
 *      permit sleeping to occur.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] pCallbackTag Opaque value provided by user while making individual
 *                         function call.
 * @param[in] status       Status of the operation. Valid values are
 *                         CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
 *                         CPA_STATUS_UNSUPPORTED.
 * @param[in] pOpData      Opaque Pointer to the operation data that was
 *                         submitted in the request
 *
 * @retval
 *      None
 * @pre
 *      Component has been initialized.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      cpaCyKeyGenSsl()
 *
 *****************************************************************************/
typedef void (*CpaCyGenericCbFunc)(void *pCallbackTag,
                                   CpaStatus status,
                                   void *pOpData);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Definition of generic callback function with an additional output
 *      CpaFlatBuffer parameter.
 *
 * @description
 *      This data structure specifies the prototype for a generic callback
 *      function which provides an output buffer (of type CpaFlatBuffer).
 *
 * @context
 *      This callback function can be executed in a context that DOES NOT
 *      permit sleeping to occur.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] pCallbackTag Opaque value provided by user while making individual
 *                         function call.
 * @param[in] status       Status of the operation. Valid values are
 *                         CPA_STATUS_SUCCESS, CPA_STATUS_FAIL and
 *                         CPA_STATUS_UNSUPPORTED.
 * @param[in] pOpData      Opaque Pointer to the operation data that was
 *                         submitted in the request
 * @param[in] pOut         Pointer to the output buffer provided in the request
 *                         invoking this callback.
 *
 * @retval
 *      None
 * @pre
 *      Component has been initialized.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
typedef void (*CpaCyGenFlatBufCbFunc)(void *pCallbackTag,
                                      CpaStatus status,
                                      void *pOpdata,
                                      CpaFlatBuffer *pOut);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Function to return the size of the memory which must be allocated for
 *      the pPrivateMetaData member of CpaBufferList.
 *
 * @description
 *      This function is used obtain the size (in bytes) required to allocate
 *      a buffer descriptor for the pPrivateMetaData member in the
 *      CpaBufferList the structure.
 *      Should the function return zero then no meta data is required for the
 *      buffer list.
 *
 * @context
 *      This function may be called from any context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle      Handle to an instance of this API.
 * @param[in]  numBuffers          The number of pointers in the CpaBufferList.
 *                                 this is the maximum number of CpaFlatBuffers
 *                                 which may be contained in this CpaBufferList.
 * @param[out] pSizeInBytes        Pointer to the size in bytes of memory to be
 *                                 allocated when the client wishes to allocate
 *                                 a cpaFlatBuffer
 *
 * @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
 *      None.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      cpaCyGetInstances()
 *
 *****************************************************************************/
CpaStatus cpaCyBufferListGetMetaSize(const CpaInstanceHandle instanceHandle,
                                     Cpa32U numBuffers,
                                     Cpa32U *pSizeInBytes);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Function to return a string indicating the specific error that occurred
 *      for a particular instance.
 *
 * @description
 *      When a function invocation on a particular instance returns an error,
 *      the client can invoke this function to query the instance for a null
 *      terminated string which describes the general error condition, and if
 *      available additional text on the specific error.
 *      The Client MUST allocate CPA_STATUS_MAX_STR_LENGTH_IN_BYTES bytes for
 *      the buffer string.
 *
 * @context
 *      This function may be called from any context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle   Handle to an instance of this API.
 * @param[in]  errStatus        The error condition that occurred
 * @param[out] pStatusText      Pointer to the string buffer that will be
 *                              updated with a null terminated status text
 *                              string.
 *                              The invoking application MUST allocate this
 *                              buffer to be CPA_STATUS_MAX_STR_LENGTH_IN_BYTES.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed. Note, In this scenario it
 *                                   is INVALID to call this function a further
 *                                   time.
 * @retval CPA_STATUS_INVALID_PARAM  Invalid parameter passed in.
 * @retval CPA_STATUS_UNSUPPORTED    Function is not supported.
 *
 * @pre
 *      None.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      CpaStatus
 *
 *****************************************************************************/
CpaStatus cpaCyGetStatusText(const CpaInstanceHandle instanceHandle,
                             CpaStatus errStatus,
                             Cpa8S *pStatusText);

/*****************************************************************************/
/* Instance Discovery Functions                                              */
/*****************************************************************************/
/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Get the number of instances that are supported by the API
 *      implementation.
 *
 * @description
 *     This function will get the number of instances that are supported
 *     by an implementation of the Cryptographic API. This number is then
 *     used to determine the size of the array that must be passed to
 *     @ref cpaCyGetInstances().
 *
 * @context
 *      This function MUST NOT be called from an interrupt context as it MAY
 *      sleep.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      This function is synchronous and blocking.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[out] pNumInstances         Pointer to where the number of
 *                                   instances will be written.
 *
 * @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
 *      None
 * @post
 *      None
 * @note
 *      This function operates in a synchronous manner and no asynchronous
 *      callback will be generated
 *
 * @see
 *      cpaCyGetInstances
 *
 *****************************************************************************/
CpaStatus cpaCyGetNumInstances(Cpa16U *pNumInstances);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Get the handles to the instances that are supported by the
 *      API implementation.
 *
 * @description
 *      This function will return handles to the instances that are
 *      supported by an implementation of the Cryptographic API. These
 *      instance handles can then be used as input parameters with other
 *      Cryptographic API functions.
 *
 *      This function will populate an array that has been allocated by the
 *      caller. The size of this API will have been determined by the
 *      cpaCyGetNumInstances() function.
 *
 * @context
 *      This function MUST NOT be called from an interrupt context as it MAY
 *      sleep.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      This function is synchronous and blocking.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]     numInstances       Size of the array.  If the value is not
 *                                      the same as the number of instances
 *                                      supported, then an error (@ref
 *                                      CPA_STATUS_INVALID_PARAM) is returned.
 * @param[in,out] cyInstances        Pointer to where the instance
 *                                   handles will be written.
 *
 * @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
 *      None
 * @post
 *      None
 * @note
 *      This function operates in a synchronous manner and no asynchronous
 *      callback will be generated
 *
 * @see
 *      cpaCyGetNumInstances
 *
 *****************************************************************************/
CpaStatus cpaCyGetInstances(Cpa16U numInstances,
                            CpaInstanceHandle *cyInstances);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Function to get information on a particular instance.
 *
 * @deprecated
 *         As of v1.3 of the Crypto API, this function has been deprecated,
 *         replaced by @ref cpaCyInstanceGetInfo2.
 *
 * @description
 *      This function will provide instance specific information through a
 *      @ref CpaInstanceInfo structure.
 *
 * @context
 *      This function may be called from any context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle       Handle to an instance of this API to be
 *                                  initialized.
 * @param[out] pInstanceInfo        Pointer to the memory location allocated by
 *                                  the client into which the CpaInstanceInfo
 *                                  structure will be written.
 *
 * @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
 *      The client has retrieved an instanceHandle from successive calls to
 *      @ref cpaCyGetNumInstances and @ref cpaCyGetInstances.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      cpaCyGetNumInstances,
 *      cpaCyGetInstances,
 *      CpaInstanceInfo
 *
 *****************************************************************************/
CpaStatus CPA_DEPRECATED
cpaCyInstanceGetInfo(const CpaInstanceHandle instanceHandle,
                     CpaInstanceInfo *pInstanceInfo);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Function to get information on a particular instance.
 *
 * @description
 *      This function will provide instance specific information through a
 *      @ref CpaInstanceInfo2 structure.
 *      Supersedes @ref cpaCyInstanceGetInfo.
 *
 * @context
 *      This function may be called from any context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle       Handle to an instance of this API to be
 *                                  initialized.
 * @param[out] pInstanceInfo2       Pointer to the memory location allocated by
 *                                  the client into which the CpaInstanceInfo2
 *                                  structure will be written.
 *
 * @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
 *      The client has retrieved an instanceHandle from successive calls to
 *      @ref cpaCyGetNumInstances and @ref cpaCyGetInstances.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      cpaCyGetNumInstances,
 *      cpaCyGetInstances,
 *      CpaInstanceInfo
 *
 *****************************************************************************/
CpaStatus cpaCyInstanceGetInfo2(const CpaInstanceHandle instanceHandle,
                                CpaInstanceInfo2 *pInstanceInfo2);

/*****************************************************************************/
/* Instance Notification Functions                                           */
/*****************************************************************************/
/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Callback function for instance notification support.
 *
 * @description
 *      This is the prototype for the instance notification callback function.
 *      The callback function is passed in as a parameter to the
 *      @ref cpaCyInstanceSetNotificationCb function.
 *
 * @context
 *      This function will be executed in a context that requires that sleeping
 *      MUST NOT be permitted.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] instanceHandle   Instance handle.
 * @param[in] pCallbackTag     Opaque value provided by user while making
 *                             individual function calls.
 * @param[in] instanceEvent    The event that will trigger this function to
 *                             get invoked.
 *
 * @retval
 *      None
 * @pre
 *      Component has been initialized and the notification function has been
 *  set via the cpaCyInstanceSetNotificationCb function.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      cpaCyInstanceSetNotificationCb(),
 *
 *****************************************************************************/
typedef void (*CpaCyInstanceNotificationCbFunc)(
    const CpaInstanceHandle instanceHandle,
    void *pCallbackTag,
    const CpaInstanceEvent instanceEvent);

/**
 *****************************************************************************
 * @ingroup cpaCyCommon
 *      Subscribe for instance notifications.
 *
 * @description
 *      Clients of the CpaCy interface can subscribe for instance notifications
 *      by registering a @ref CpaCyInstanceNotificationCbFunc function.
 *
 * @context
 *      This function may be called from any context.
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      No
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] instanceHandle           Instance handle.
 * @param[in] pInstanceNotificationCb  Instance notification callback
 *                                     function pointer.
 * @param[in] pCallbackTag             Opaque value provided by user while
 *                                     making individual function calls.
 *
 * @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
 *      Instance has been initialized.
 * @post
 *      None
 * @note
 *      None
 * @see
 *      CpaCyInstanceNotificationCbFunc
 *
 *****************************************************************************/
CpaStatus cpaCyInstanceSetNotificationCb(
    const CpaInstanceHandle instanceHandle,
    const CpaCyInstanceNotificationCbFunc pInstanceNotificationCb,
    void *pCallbackTag);

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

#endif /* CPA_CY_COMMON_H */
