Device Polling APIs

APIs documented in this section are used for polling devices.

icp_sal_poll_device_events

This function polls for device reset events.

Syntax

CpaStatus icp_sal_poll_device_events(void);

Parameters

None

Return Value

The icp_sal_poll_device_events function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Successful operation.
`CPA_STATUS_FAIL`	Indicates a failure.

Note

The events are sent to each instance that has registered a callback function. The callbacks are registered using cpaCyInstanceSetNotificationCb and cpaDcInstanceSetNotificationCb.

Important

Limitation: epoll mode does not work with Data Plane (DP) APIs. This limitation applies to both in-tree and out-of-tree (OOT) stacks. Applications using DP APIs should not expect epoll-based event notification to function.

When using epoll mode (CPA_INST_RX_NOTIFY_BY_EVENT), this function can be called on returning from epoll_wait() to handle Device Events, especially when the single VF interrupt line shared by the ring pairs causes epoll_wait() to return even if no ring pairs have responses ready. Additionally, applications should call the appropriate polling function at least once after epoll_wait() times out to ensure all responses are processed.

cpaCyInstanceSetNotificationCb

Cryptographic instances use this function to register for device event notifications.

Syntax

CpaStatus cpaCyInstanceSetNotificationCb(const CpaInstanceHandle instanceHandle, const CpaCyInstanceNotificationCbFunc pinstanceNotificationCb, void *pCallbackTag);

Parameters

`instanceHandle`	Instance handle.
`pinstanceNotificationCb`	Instance notification callback function pointer.
`*pCallbackTag`	Opaque value provided by user.

Return Value

The cpaCyInstanceSetNotificationCb function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_FAIL`	Indicates a failure.
`CPA_STATUS_INVALID_PARAM`	Invalid parameter passed in.
`CPA_STATUS_UNSUPPORTED`	Function is not supported.

The signature for the callback function is:

typedef void (*CpaCyInstanceNotificationCbFunc)(
      const CpaInstanceHandle instanceHandle,
      void * pCallbackTag,
      const CpaInstanceEvent instanceEvent);

Parameter:

typedef enum _CpaInstanceEvent
{
   CPA_INSTANCE_EVENT_RESTARTING = 0,
   CPA_INSTANCE_EVENT_RESTARTED,
   CPA_INSTANCE_EVENT_FATAL_ERROR
} CpaInstanceEvent;

cpaDcInstanceSetNotificationCb

Data compression instances use this function to register for device event notifications.

Syntax

CpaStatus cpaDcInstanceSetNotificationCb(const CpaInstanceHandle instanceHandle, const CpaDcInstanceNotificationCbFunc pinstanceNotificationCb, void *pCallbackTag);

Parameters

`instanceHandle`	Instance handle.
`pinstanceNotificationCb`	Instance notification callback function pointer.
`*pCallbackTag`	Opaque value provided by user.

Return Value

The cpaDcInstanceSetNotificationCb function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_FAIL`	Indicates a failure.
`CPA_STATUS_INVALID_PARAM`	Invalid parameter passed in.
`CPA_STATUS_UNSUPPORTED`	Function is not supported.

The signature for the callback function is:

typedef void (*CpaDcInstanceNotificationCbFunc)(
      const CpaInstanceHandle instanceHandle,
      void * pCallbackTag,
      const CpaInstanceEvent instanceEvent);

Parameter:

typedef enum _CpaInstanceEvent
{
   CPA_INSTANCE_EVENT_RESTARTING = 0,
   CPA_INSTANCE_EVENT_RESTARTED,
   CPA_INSTANCE_EVENT_FATAL_ERROR
} CpaInstanceEvent;

Response Mode Configuration

Note

The following APIs (cpaInstanceSetResponseMode, cpaInstanceGetResponseMode, and CpaInstanceResponseMode) are only supported with the in-tree stack.

The following APIs configure how an application is notified when responses are ready from a service instance.

CpaInstanceResponseMode

This enumeration defines the modes which can be set to configure how the application wants to be notified when responses are ready on a service instance.

Definition

typedef enum
{
   CPA_INST_RX_NOTIFY_NONE = 1,
   /**< The application is not notified when responses are ready.
    * It collects responses by periodically calling one of the
    * polling APIs. */
   CPA_INST_RX_NOTIFY_BY_EVENT = 2
   /**< The device will be configured to generate an interrupt when
    * responses are ready. The application can monitor for this event.
    * On detection, the application should collect responses by calling
    * one of the polling APIs. */
} CpaInstanceResponseMode;

cpaInstanceSetResponseMode

This function configures how the application will be notified when responses are ready from the service instance.

Syntax

CpaStatus cpaInstanceSetResponseMode(
    const CpaInstanceHandle instanceHandle,
    const CpaAccelerationServiceType accelerationServiceType,
    const CpaInstanceResponseMode responseMode);

Parameters

`instanceHandle`	Instance handle.
`accelerationServiceType`	This must match the Acceleration Service of the instance. In an instance which has two service types, e.g. `CPA_ACC_SVC_TYPE_CRYPTO` includes both ASYM and SYM services, both of the services will be set to the same mode.
`responseMode`	The mode which will be used to notify the application that responses are ready.

Return Value

The cpaInstanceSetResponseMode function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_FAIL`	Indicates a failure.
`CPA_STATUS_INVALID_PARAM`	Invalid parameter passed in.
`CPA_STATUS_UNSUPPORTED`	Function is not supported.

Note

Preconditions:

This function should only be called when there are no operations in-flight in the instance. The behaviour will be undefined for operations which are in-flight.

Service-Specific Behavior:

In a crypto instance where both symmetric and asymmetric services are configured, both services will have the same ResponseMode configuration.

in-tree Default Mode:

In the in-tree driver, the default mode for a device is poll mode (CPA_INST_RX_NOTIFY_NONE). Using this API, epoll mode can be enabled at the instance level.

Interrupt Line Sharing:

A single VF interrupt line is shared by the 4 ring pairs in a device. This causes ring pair events to unblock all instances. PF2VF messages also share the same interrupt line, so these also trigger epoll events. This means it’s possible to return from epoll_wait() even if no ring pairs have responses. The icp_sal_poll_device_events() API can be called on returning from epoll_wait() to handle Device Events in this case.

Usage with epoll_wait Timeout:

When using epoll mode, applications should call the appropriate polling function (e.g., icp_sal_CyPollInstance(), icp_sal_DcPollInstance()) at least once after epoll_wait() times out to ensure all responses are processed.

cpaInstanceGetResponseMode

This function returns the configured mode of being notified when responses are ready from a service instance.

Syntax

CpaStatus cpaInstanceGetResponseMode(
    const CpaInstanceHandle instanceHandle,
    const CpaAccelerationServiceType accelerationServiceType,
    CpaInstanceResponseMode *pResponseMode);

Parameters

`instanceHandle`	Instance handle.
`accelerationServiceType`	This must match the Acceleration service supported by the instance, except for `CPA_ACC_SVC_TYPE_CRYPTO`. In this case the instance supports two services, so this parameter must be set to either `CPA_ACC_SVC_TYPE_CRYPTO_ASYM` or `CPA_ACC_SVC_TYPE_CRYPTO_SYM`.
`*pResponseMode`	A pointer to the location where the configured mode will be stored.

Return Value

The cpaInstanceGetResponseMode function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_FAIL`	Indicates a failure.
`CPA_STATUS_INVALID_PARAM`	Invalid parameter passed in.
`CPA_STATUS_UNSUPPORTED`	Function is not supported.