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

/* SPDX-License-Identifier: BSD-3-Clause */
/* Copyright(c) 2007-2022 Intel Corporation */
/**
 ***************************************************************************
 * @file icp_sal_user.h
 *
 * @ingroup SalUser
 *
 * User space process init and shutdown functions.
 *
 ***************************************************************************/

#ifndef ICP_SAL_USER_H
#define ICP_SAL_USER_H

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function initialises and starts user space service access layer
  *    (SAL) - it registers SAL with ADF and initialises the ADF proxy.
  *    This function must only be called once per user space process.
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @param[in] pProcessName           Process address space name described in
  *                                   the config file for this device
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  *************************************************************************/
CpaStatus icp_sal_userStart(const char *pProcessName);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function is to be used with simplified config file, where user
  *    defines many user space processes. The driver generates unique
  *    process names based on the pProcessName provided.
  *    For example:
  *    If a config file in simplified format contains:
  *    [SSL]
  *    NumProcesses = 3
  *
  *    Then three internal sections will be generated and the three
  *    applications can be started at a given time. Each application can call
  *    icp_sal_userStartMultiProcess("SSL"). In this case the driver will
  *    figure out the unique name to use for each process.
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @param[in] pProcessName           Process address space name described in
  *                                   the new format of the config file
  *                                   for this device.
  *
  * @param[in] limitDevAccess         Specifies if the address space is limited
  *                                   to one device (true) or if it spans
  *                                   accross multiple devices.
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed. In this case user
  *                                   can wait and retry.
  *
  *************************************************************************/
CpaStatus icp_sal_userStartMultiProcess(const char *pProcessName,
					CpaBoolean limitDevAccess);

/*************************************************************************
 * @ingroup SalUser
 * @description
 *    This function stops and shuts down user space SAL
 *     - it deregisters SAL with ADF and shuts down ADF proxy
 *
 * @context
 *      This function is called from the user process context
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @retval CPA_STATUS_SUCCESS        No error
 * @retval CPA_STATUS_FAIL           Operation failed
 *
 ************************************************************************/
CpaStatus icp_sal_userStop(void);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function gets the number of the available dynamic allocated
  *    crypto instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userCyGetAvailableNumDynInstances(Cpa32U *pNumCyInstances);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function gets the number of the available dynamic allocated
  *    compression instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userDcGetAvailableNumDynInstances(Cpa32U *pNumDcInstances);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function gets the number of the available dynamic allocated
  *    crypto instances which are from the specific device package.
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus
icp_sal_userCyGetAvailableNumDynInstancesByDevPkg(Cpa32U *pNumCyInstances,
						  Cpa32U devPkgID);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function gets the number of the available dynamic allocated
  *    crypto instances which are from the specific device package and specific
  *    accelerator.
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus
icp_sal_userCyGetAvailableNumDynInstancesByPkgAccel(Cpa32U *pNumCyInstances,
						    Cpa32U devPkgID,
						    Cpa32U accelerator_number);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function gets the number of the available dynamic allocated
  *    compression instances which are from the specific device package.
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus
icp_sal_userDcGetAvailableNumDynInstancesByDevPkg(Cpa32U *pNumDcInstances,
						  Cpa32U devPkgID);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function allocates crypto instances
  *    from dynamic crypto instance pool
  *     - it adds new allocated instances into crypto_services
  *     - it initializes new allocated instances
  *     - it starts new allocated instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userCyInstancesAlloc(Cpa32U numCyInstances,
				       CpaInstanceHandle *pCyInstances);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function allocates crypto instances
  *    from dynamic crypto instance pool
  *    which are from the specific device package.
  *     - it adds new allocated instances into crypto_services
  *     - it initializes new allocated instances
  *     - it starts new allocated instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userCyInstancesAllocByDevPkg(Cpa32U numCyInstances,
					       CpaInstanceHandle *pCyInstances,
					       Cpa32U devPkgID);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function allocates crypto instances
  *    from dynamic crypto instance pool
  *    which are from the specific device package and specific accelerator
  *     - it adds new allocated instances into crypto_services
  *     - it initializes new allocated instances
  *     - it starts new allocated instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus
icp_sal_userCyInstancesAllocByPkgAccel(Cpa32U numCyInstances,
				       CpaInstanceHandle *pCyInstances,
				       Cpa32U devPkgID,
				       Cpa32U accelerator_number);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function frees crypto instances allocated
  *    from dynamic crypto instance pool
  *     - it stops the instances
  *     - it shutdowns the instances
  *     - it removes the instances from crypto_services
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userCyFreeInstances(Cpa32U numCyInstances,
				      CpaInstanceHandle *pCyInstances);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function allocates compression instances
  *    from dynamic compression instance pool
  *     - it adds new allocated instances into compression_services
  *     - it initializes new allocated instances
  *     - it starts new allocated instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userDcInstancesAlloc(Cpa32U numDcInstances,
				       CpaInstanceHandle *pDcInstances);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function allocates compression instances
  *    from dynamic compression instance pool
  *    which are from the specific device package.
  *     - it adds new allocated instances into compression_services
  *     - it initializes new allocated instances
  *     - it starts new allocated instances
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userDcInstancesAllocByDevPkg(Cpa32U numDcInstances,
					       CpaInstanceHandle *pDcInstances,
					       Cpa32U devPkgID);

/*************************************************************************
  * @ingroup SalUser
  * @description
  *    This function frees compression instances allocated
  *    from dynamic compression instance pool
  *     - it stops the instances
  *     - it shutdowns the instances
  *     - it removes the instances from compression_services
  *
  * @context
  *      This function is called from the user process context
  *
  * @assumptions
  *      None
  * @sideEffects
  *      None
  * @reentrant
  *      No
  * @threadSafe
  *      Yes
  *
  * @retval CPA_STATUS_SUCCESS        No error
  * @retval CPA_STATUS_FAIL           Operation failed
  *
  ************************************************************************/
CpaStatus icp_sal_userDcFreeInstances(Cpa32U numDcInstances,
				      CpaInstanceHandle *pDcInstances);

/*************************************************************************
 * @ingroup SalUser
 * @description
 *    This function checks if new devices have been started and if so
 *    starts to use them.
 *
 * @context
 *      This function is called from the user process context
 *      in threadless mode
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No
 *
 * @retval CPA_STATUS_SUCCESS        No error
 * @retval CPA_STATUS_FAIL           Operation failed
 *
 ************************************************************************/
CpaStatus icp_sal_find_new_devices(void);

/*************************************************************************
 * @ingroup SalUser
 * @description
 *    This function polls device events.
 *
 * @context
 *      This function is called from the user process context
 *      in threadless mode
 *
 * @assumptions
 *      None
 * @sideEffects
 *      In case a device has beed stoped or restarted the application
 *      will get restarting/stop/shutdown events
 * @reentrant
 *      No
 * @threadSafe
 *      No
 *
 * @retval CPA_STATUS_SUCCESS        No error
 * @retval CPA_STATUS_FAIL           Operation failed
 *
 ************************************************************************/
CpaStatus icp_sal_poll_device_events(void);

/*
 * icp_adf_check_device
 *
 * @description:
 *  This function checks the status of the firmware/hardware for a given device.
 *  This function is used as part of the heartbeat functionality.
 *
 * @context
 *      This function is called from the user process context
 * @assumptions
 *      None
 * @sideEffects
 *      In case a device is unresponsive the device will
 *      be restarted.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] accelId                Device Id.
 * @retval CPA_STATUS_SUCCESS        No error
 * @retval CPA_STATUS_FAIL           Operation failed
 */
CpaStatus icp_sal_check_device(Cpa32U accelId);

/*
 * icp_adf_check_all_devices
 *
 * @description:
 *  This function checks the status of the firmware/hardware for all devices.
 *  This function is used as part of the heartbeat functionality.
 *
 * @context
 *      This function is called from the user process context
 * @assumptions
 *      None
 * @sideEffects
 *      In case a device is unresponsive the device will
 *      be restarted.
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @retval CPA_STATUS_SUCCESS        No error
 * @retval CPA_STATUS_FAIL           Operation failed
 */
CpaStatus icp_sal_check_all_devices(void);

/*
 * @ingroup icp_sal_user
 * @description
 *      This is a stub function to send messages to VF
 *
 * @context
 *      None
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      Yes
 * @threadSafe
 *      Yes
 *
*/
CpaStatus icp_sal_userSendMsgToVf(Cpa32U accelId, Cpa32U vfNum, Cpa32U message);

/*
 * @ingroup icp_sal_user
 * @description
 *      This is a stub function to send messages to PF
 *
 * @context
 *      None
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      Yes
 * @threadSafe
 *      Yes
 *
*/
CpaStatus icp_sal_userSendMsgToPf(Cpa32U accelId, Cpa32U message);

/*
 * @ingroup icp_sal_user
 * @description
 *      This is a stub function to get messages from VF
 *
 * @context
 *      None
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      Yes
 * @threadSafe
 *      Yes
 *
*/
CpaStatus icp_sal_userGetMsgFromVf(Cpa32U accelId,
				   Cpa32U vfNum,
				   Cpa32U *message,
				   Cpa32U *messageCounter);

/*
 * @ingroup icp_sal_user
 * @description
 *      This is a stub function to get messages from PF
 *
 * @context
 *      None
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      Yes
 * @threadSafe
 *      Yes
 *
*/
CpaStatus icp_sal_userGetMsgFromPf(Cpa32U accelId,
				   Cpa32U *message,
				   Cpa32U *messageCounter);

/*
 * @ingroup icp_sal_user
 * @description
 *      This is a stub function to get pfvf comms status
 *
 * @context
 *      None
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      Yes
 * @threadSafe
 *      Yes
 *
*/
CpaStatus icp_sal_userGetPfVfcommsStatus(CpaBoolean *unreadMessage);

/*
 * @ingroup icp_sal_user
 * @description
 *      This is a stub function to reset the device
 *
 * @context
 *     None
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @reentrant
 *      Yes
 * @threadSafe
 *      Yes
 *
*/
CpaStatus icp_sal_reset_device(Cpa32U accelId);

/**
 *****************************************************************************
 * @ingroup icp_sal_user
 *      Retrieve number of in flight requests for a nrbg tx ring
 *      from a crypto instance (Traditional API).
 *
 * @description
 *      This function is a part of back-pressure mechanism.
 *      Applications can query for inflight requests in
 *      the appropriate service/ring on each instance
 *      and select any instance with sufficient space or
 *      the instance with the lowest number.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle         Crypto API instance handle.
 * @param[out] maxInflightRequests    Maximal number of in flight requests.
 * @param[out] numInflightRequests    Current number of in flight requests.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @pre
 *      None
 * @post
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus icp_sal_NrbgGetInflightRequests(CpaInstanceHandle instanceHandle,
					  Cpa32U *maxInflightRequests,
					  Cpa32U *numInflightRequests);

/**
 *****************************************************************************
 * @ingroup icp_sal_user
 *      Retrieve number of in flight requests for a symmetric tx ring
 *      from a crypto instance (Traditional API).
 *
 * @description
 *      This function is a part of back-pressure mechanism.
 *      Applications can query for inflight requests in
 *      the appropriate service/ring on each instance
 *      and select any instance with sufficient space or
 *      the instance with the lowest number.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle         Crypto API instance handle.
 * @param[out] maxInflightRequests    Maximal number of in flight requests.
 * @param[out] numInflightRequests    Current number of in flight requests.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @pre
 *      None
 * @post
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus icp_sal_SymGetInflightRequests(CpaInstanceHandle instanceHandle,
					 Cpa32U *maxInflightRequests,
					 Cpa32U *numInflightRequests);

/**
 *****************************************************************************
 * @ingroup icp_sal_user
 *      Retrieve number of in flight requests for an asymmetric tx ring
 *      from a crypto instance (Traditional API).
 *
 * @description
 *      This function is a part of back-pressure mechanism.
 *      Applications can query the appropriate service/ring on each instance
 *      and select any instance with sufficient space or
 *      the instance with the lowest number.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle         Crypto API instance handle.
 * @param[out] maxInflightRequests    Maximal number of in flight requests.
 * @param[out] numInflightRequests    Current number of in flight requests.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @pre
 *      None
 * @post
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus icp_sal_AsymGetInflightRequests(CpaInstanceHandle instanceHandle,
					  Cpa32U *maxInflightRequests,
					  Cpa32U *numInflightRequests);

/**
 *****************************************************************************
 * @ingroup icp_sal_user
 *      Retrieve number of in flight requests for a symmetric tx ring
 *      from a crypto instancei (Data Plane API).
 *
 * @description
 *      This function is a part of back-pressure mechanism.
 *      Applications can query the appropriate service/ring on each instance
 *      and select any instance with sufficient space or
 *      the instance with the lowest number.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in]  instanceHandle         Crypto API instance handle.
 * @param[out] maxInflightRequests    Maximal number of in flight requests.
 * @param[out] numInflightRequests    Current number of in flight requests.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @pre
 *      None
 * @post
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus icp_sal_dp_SymGetInflightRequests(CpaInstanceHandle instanceHandle,
					    Cpa32U *maxInflightRequests,
					    Cpa32U *numInflightRequests);

/**
 *****************************************************************************
 * @ingroup icp_sal_user
 *      Updates the CSR with queued requests in the asymmetric tx ring.
 *
 * @description
 *      The function writes current shadow tail pointer of the asymmetric
 *      TX ring into ring's CSR. Updating the CSR will notify the HW that
 *      there are request(s) queued to be processed. The CSR is updated
 *      always, disregarding the current value of shadow tail pointer and
 *      the current CSR's tail value.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      Yes
 *
 * @param[in] instanceHandle         Crypto API instance handle.
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @pre
 *      None
 * @post
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus icp_sal_AsymPerformOpNow(CpaInstanceHandle instanceHandle);

/**
 *****************************************************************************
 * @ingroup icp_sal_setForceAEADMACVerify
 *      Sets forceAEADMacVerify for particular instance to force HW MAC
 *      validation.
 *
 * @description
 * 	By default HW MAC verification is set to CPA_TRUE - this utility
 * 	function allows to change default behavior.
 *
 * @assumptions
 *      None
 * @sideEffects
 *      None
 * @blocking
 *      None
 * @reentrant
 *      No
 * @threadSafe
 *      No
 *
 * @param[in] instanceHandle         Crypto API instance handle.
 * @param[in] forceAEADMacVerify     new value
 *
 * @retval CPA_STATUS_SUCCESS        Function executed successfully.
 * @retval CPA_STATUS_FAIL           Function failed.
 * @pre
 *      None
 * @post
 *      None
 * @see
 *      None
 *
 *****************************************************************************/
CpaStatus icp_sal_setForceAEADMACVerify(CpaInstanceHandle instanceHandle,
					CpaBoolean forceAEADMacVerify);
#endif