xref: /freebsd/sys/dev/qat/qat_api/common/include/lac_sal.h (revision 71625ec9ad2a9bc8c09784fbd23b759830e0ee5f)

/* SPDX-License-Identifier: BSD-3-Clause */
/* Copyright(c) 2007-2022 Intel Corporation */
/**
 *****************************************************************************
 * @file lac_sal.h
 *
 * @defgroup SalCtrl Service Access Layer Controller
 *
 * @ingroup SalCtrl
 *
 * @description
 *      These functions are the functions to be executed for each state
 *      of the state machine for each service.
 *
 *****************************************************************************/

#ifndef LAC_SAL_H
#define LAC_SAL_H

#include "cpa_cy_im.h"

/**
*******************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function allocates memory for a specific instance type.
 *      Zeros this memory and sets the generic service section of
 *      the instance memory.
 *
 * @context
 *      This function is called from the generic services init.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  service         The type of the service to be created
 *                             (e.g. CRYPTO)
 * @param[in]  instance_num    The logical instance number which will
 *                             run the service
 * @param[out] pObj            Pointer to specific service instance memory
 * @retVal CPA_STATUS_SUCCESS  Instance memory successfully allocated
 * @retVal CPA_STATUS_RESOURCE Instance memory not successfully allocated
 * @retVal CPA_STATUS_FAIL     Unsupported service type
 *
 *****************************************************************************/
CpaStatus SalCtrl_ServiceCreate(sal_service_type_t service,
				Cpa32U instance_num,
				sal_service_t **pObj);

/******************************************************************************
 * @ingroup SalCtl
 * @description
 *      This macro goes through the 'list' passed in as a parameter. For each
 *      element found in the list, it peforms a cast to the type of the element
 *      given by the 'type' parameter. Finally, it calls the function given by
 *      the 'function' parameter, passing itself and the device as parameters.
 *
 *      In case of error (i.e. 'function' does not return _SUCCESS or _RETRY)
 *      processing of the 'list' elements will stop and the status_ret will be
 *      updated.
 *
 *      In case of _RETRY status_ret will be updated but the 'list'
 *      will continue to be processed. _RETRY is only expected when
 *      'function' is stop.
 *
 * @context
 *      This macro is used by both the service and qat event handlers.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 *
 * @param[in]  list             The list of services or qats as a type of list_t
 * @param[in]  type             It identifies the type of the object inside the
 *                              list: service or qat
 * @param[in]  device           The ADF accelerator handle for the device
 * @param[in]  function         The function pointer to call
 * @param[in/out] status_ret    If an error occurred (i.e. status returned from
 *                              function is not _SUCCESS) then status_ret is
 *                              overwritten with status returned from function.
 *
 *****************************************************************************/
#define SAL_FOR_EACH(list, type, device, function, status_ret)                 \
	do {                                                                   \
		sal_list_t *curr_element = list;                               \
		CpaStatus status_temp = CPA_STATUS_SUCCESS;                    \
		typeof(type) *process = NULL;                                  \
		while (NULL != curr_element) {                                 \
			process =                                              \
			    (typeof(type) *)SalList_getObject(curr_element);   \
			status_temp = process->function(device, process);      \
			if ((CPA_STATUS_SUCCESS != status_temp) &&             \
			    (CPA_STATUS_RETRY != status_temp)) {               \
				status_ret = status_temp;                      \
				break;                                         \
			} else {                                               \
				if (CPA_STATUS_RETRY == status_temp) {         \
					status_ret = status_temp;              \
				}                                              \
			}                                                      \
			curr_element = SalList_next(curr_element);             \
		}                                                              \
	} while (0)

/**
*******************************************************************************
 * @ingroup SalCtl
 * @description
 *      This macro goes through the 'list' passed in as a parameter. For each
 *      element found in the list, it peforms a cast to the type of the element
 *      given by the 'type' parameter. Finally, it checks the state of the
 *      element and if it is in state 'state_check' then it calls the
 *      function given by the 'function' parameter, passing itself
 *      and the device as parameters.
 *      If the element is not in 'state_check' it returns from the macro.
 *
 *      In case of error (i.e. 'function' does not return _SUCCESS)
 *      processing of the 'list' elements will continue.
 *
 * @context
 *      This macro is used by both the service and qat event handlers.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 *
 * @param[in]  list             The list of services or qats as a type of list_t
 * @param[in]  type             It identifies the type of the object
 *                              inside the list: service or qat
 * @param[in]  device           The ADF accelerator handle for the device
 * @param[in]  function         The function pointer to call
 * @param[in]  state_check      The state to check for
 *
 *****************************************************************************/
#define SAL_FOR_EACH_STATE(list, type, device, function, state_check)          \
	do {                                                                   \
		sal_list_t *curr_element = list;                               \
		typeof(type) *process = NULL;                                  \
		while (NULL != curr_element) {                                 \
			process =                                              \
			    (typeof(type) *)SalList_getObject(curr_element);   \
			if (process->state == state_check) {                   \
				process->function(device, process);            \
			} else {                                               \
				break;                                         \
			}                                                      \
			curr_element = SalList_next(curr_element);             \
		}                                                              \
	} while (0)

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to initialize an instance of crypto service.
 *   It creates a crypto instance's memory pools. It calls ADF to create
 *   its required transport handles. It calls the sub crypto service init
 *   functions. Resets the stats.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventInit function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A crypto instance
 *
 *************************************************************************/
CpaStatus SalCtrl_CryptoInit(icp_accel_dev_t *device, sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to start an instance of crypto service.
 *  It sends the first messages to FW on its crypto instance transport
 *  handles. For asymmetric crypto it verifies the header on the downloaded
 *  MMP library.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventStart function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A crypto instance
 *
 *************************************************************************/
CpaStatus SalCtrl_CryptoStart(icp_accel_dev_t *device, sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to stop an instance of crypto service.
 *  It checks for inflight messages to the FW. If no messages are pending
 * it returns success. If messages are pending it returns retry.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventStop function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A crypto instance
 *
 *************************************************************************/
CpaStatus SalCtrl_CryptoStop(icp_accel_dev_t *device, sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to shutdown an instance of crypto service.
 *  It frees resources allocated at initialisation - e.g. frees the
 *  memory pools and ADF transport handles.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventShutdown function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A crypto instance
 *
 *************************************************************************/
CpaStatus SalCtrl_CryptoShutdown(icp_accel_dev_t *device,
				 sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function sets the capability info of crypto instances.
 *
 * @context
 *    This function is called from the cpaCyQueryCapabilities and
 *    LacSymSession_ParamCheck function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] service            A sal_service_t* type
 * @param[in] cyCapabilityInfo   A CpaCyCapabilitiesInfo* type
 *
 *************************************************************************/
void SalCtrl_CyQueryCapabilities(sal_service_t *pGenericService,
				 CpaCyCapabilitiesInfo *pCapInfo);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to initialize an instance of compression service.
 *   It creates a compression instance's memory pools. It calls ADF to create
 *   its required transport handles. It zeros an instances stats.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventInit function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A compression instance
 *
 *************************************************************************/

CpaStatus SalCtrl_CompressionInit(icp_accel_dev_t *device,
				  sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to start an instance of compression service.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventStart function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A compression instance
 *
 *************************************************************************/

CpaStatus SalCtrl_CompressionStart(icp_accel_dev_t *device,
				   sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to stop an instance of compression service.
 *  It checks for inflight messages to the FW. If no messages are pending
 * it returns success. If messages are pending it returns retry.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventStop function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A compression instance
 *
 *************************************************************************/

CpaStatus SalCtrl_CompressionStop(icp_accel_dev_t *device,
				  sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *      This function is used to shutdown an instance of compression service.
 *  It frees resources allocated at initialisation - e.g. frees the
 *  memory pools and ADF transport handles.
 *
 * @context
 *    This function is called from the SalCtrl_ServiceEventShutdown function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No (ADF ensures that this function doesn't need to be thread safe)
 *
 * @param[in] device    An icp_accel_dev_t* type
 * @param[in] service   A compression instance
 *
 *************************************************************************/

CpaStatus SalCtrl_CompressionShutdown(icp_accel_dev_t *device,
				      sal_service_t *service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *    This function is used to get the number of services enabled
 *    from the config table.
 *
 * @context
 *    This function is called from the SalCtrl_QatInit
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No
 *
 * param[in] device            An icp_accel_dev_t* type
 * param[in] pEnabledServices  pointer to a variable used to store
 *                             the enabled services
 *
 *************************************************************************/

CpaStatus SalCtrl_GetEnabledServices(icp_accel_dev_t *device,
				     Cpa32U *pEnabledServices);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *    This function is used to check if a service is enabled
 *
 * @context
 *    This function is called from the SalCtrl_QatInit
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * param[in] enabled_services
 * param[in] service
 *
 *************************************************************************/

CpaBoolean SalCtrl_IsServiceEnabled(Cpa32U enabled_services,
				    sal_service_type_t service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *    This function is used to check if a service is supported on the device
 *    The key difference between this and SalCtrl_GetSupportedServices() is
 *    that the latter treats it as an error if the service is unsupported.
 *
 * @context
 *      This can be called anywhere.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * param[in] device
 * param[in] service    service or services to check
 *
 *************************************************************************/
CpaBoolean SalCtrl_IsServiceSupported(icp_accel_dev_t *device,
				      sal_service_type_t service);

/*************************************************************************
 * @ingroup SalCtrl
 * @description
 *    This function is used to check whether enabled services has associated
 *    hardware capability support
 *
 * @context
 *      This functions is called from the SalCtrl_ServiceEventInit function.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * param[in] device              A pointer to an icp_accel_dev_t
 * param[in] enabled_services    It is the bitmask for the enabled services
 *************************************************************************/

CpaStatus SalCtrl_GetSupportedServices(icp_accel_dev_t *device,
				       Cpa32U enabled_services);

#endif