Polling Functions

These functions are intended for retrieving response messages that are on the rings and dispatching the associated callbacks.

All polling function definitions are located in: $ICP_ROOT/quickassist/lookaside/access_layer/include/icp_sal_poll.h

icp_sal_pollBank

Poll all rings on the given Intel^® QAT Endpoint on a given bank number to determine if any of the rings contain response messages from the Intel^® QAT Endpoint. The response_quota input parameter is per ring.

Syntax

CpaStatus icp_sal_pollBank(Cpa32U accelId, Cpa32U bank_number, Cpa32U response_quota);

Parameters

`accelId`	The device number associated with the Intel^® QAT Endpoint. valid range is 0 to number of Intel^® QAT Endpoints in the system.
`bank_number`	The number of the memory bank on the Intel^® QAT Endpoint that will be polled for response messages. The valid range is 0 to 31.
`response_quota`	The maximum number of responses to take from the ring in one call.

Return Value

The icp_sal_pollBank function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Successfully polled a ring with data.
`CPA_STATUS_RETRY`	There is no data on any ring on any bank or the banks are already being polled.
`CPA_STATUS_FAIL`	Indicates a failure.

icp_sal_pollAllBanks

Poll all banks on the given Intel^® QAT Endpoint to determine if any of the rings contain response messages from the Intel^® QAT Endpoint. The response_quota input parameter is per ring.

Syntax

CpaStatus icp_sal_pollAllBanks(Cpa32U accelId, Cpa32U response_quota);

Parameters

`accelId`	The device number associated with the Intel^® QAT Endpoint. valid range is 0 to number of Intel^® QAT Endpoints in the system.
`response_quota`	The maximum number of responses to take from the ring in one call.

Return Value

The icp_sal_pollAllBanks function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Successfully polled a ring with data.
`CPA_STATUS_RETRY`	There is no data on any ring on any bank or the banks are already being polled.
`CPA_STATUS_FAIL`	Indicates a failure.

icp_sal_CyPollInstance

Poll the Cryptographic (CY) logical instance associated with the instanceHandle to retrieve requests that are on response rings associated with that instance and dispatch the associated callbacks. The response_quota input parameter is the maximum number of responses to process in one call.

Note

The icp_sal_CyPollInstance() function is used in conjunction with the CyXIsPolled parameter in the acceleration configuration file.

Syntax

CpaStatus icp_sal_CyPollInstance(CpaInstanceHandle instanceHandle, Cpa32U response_quota);

Parameters

`instanceHandle`	The logical instance to poll for responses on the response ring.
`response_quota`	The maximum number of responses to take from the ring in one call. When set to 0, all responses are retrieved.

Return Value

The icp_sal_CyPollInstance function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_RETRY`	There are no responses on the rings associated with the specified logical instance.
`CPA_STATUS_FAIL`	Indicates a failure.

Note

A ring is only polled if it contains data.

icp_sal_DcPollInstance

Poll the Data Compression (DC) logical instance associated with the instanceHandle to retrieve requests that are on response rings associated with that instance and dispatch the associated callbacks. The response_quota input parameter is the maximum number of responses to process in one call.

Note

The icp_sal_DcPollInstance() function is used in conjunction with the DcXIsPolled parameter in the acceleration configuration file.

Syntax

CpaStatus icp_sal_DcPollInstance(CpaInstanceHandle instanceHandle, Cpa32U response_quota);

Parameters

`instanceHandle`	The logical instance to poll for responses on the response ring.
`response_quota`	The maximum number of responses to take from the ring in one call. When set to 0, all responses are retrieved.

Return Value

The icp_sal_DcPollInstance function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_RETRY`	There are no responses on the rings associated with the specified logical instance.
`CPA_STATUS_FAIL`	Indicates a failure.

Note

A ring is only polled if it contains data.

icp_sal_CyPollDpInstance

Poll a particular Cryptographic (CY) data path logical instance associated with the instanceHandle to retrieve requests that are on the high-priority symmetric ring associated with that instance and dispatch the associated callbacks. The response_quota input parameter is the maximum number of responses to process in one call.

Note

This function is a Data Plane API function and consequently the restrictions in Usage Constraints on the Data Plane APIs apply.

Syntax

CpaStatus icp_sal_CyPollDpInstance(CpaInstanceHandle instanceHandle, Cpa32U response_quota);

Parameters

`instanceHandle`	The logical instance to poll for responses on the response ring.
`response_quota`	The maximum number of responses to take from the ring in one call. When set to 0, all responses are retrieved.

Return Value

The icp_sal_CyPollDpInstance function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_RETRY`	There are no responses on the rings associated with the specified logical instance.
`CPA_STATUS_FAIL`	Indicates a failure.

icp_sal_DcPollDpInstance

Poll a particular Data Compression (DC) data path logical instance associated with the instanceHandle to retrieve requests that are on the response ring associated with that instance. The response_quota input parameter is the maximum number of responses to process in one call.

Note

This function is a Data Plane API function and consequently the restrictions in Usage Constraints on the Data Plane APIs apply.

Syntax

CpaStatus icp_sal_DcPollDpInstance(CpaInstanceHandle instanceHandle, Cpa32U response_quota);

Parameters

`instanceHandle`	The logical instance to poll for responses on the response ring.
`response_quota`	The maximum number of responses to take from the ring in one call. When set to 0, all responses are retrieved.

Return Value

The icp_sal_DcPollDpInstance function returns one of the following codes:

`CPA_STATUS_SUCCESS`	The function was successful.
`CPA_STATUS_RETRY`	There are no responses on the rings associated with the specified logical instance.
`CPA_STATUS_FAIL`	Indicates a failure.

icp_sal_CyGetFileDescriptor

Get the file descriptor for a cryptographic instance when operating in epoll mode. The file descriptor is used with the Linux* epoll interface (epoll_ctl(), epoll_wait()). The file descriptor will only be returned when the instance response mode is configured for CPA_INST_RX_NOTIFY_BY_EVENT (epoll mode).

Note

The file descriptor is persistent for the lifetime of the instance. If the instance response mode is changed from epoll to poll mode and back to epoll, the same file descriptor remains valid and does not need to be queried again. This API will return CPA_STATUS_UNSUPPORTED when the instance is not in epoll mode, even though the file descriptor continues to exist and will be valid if the instance is later switched back to epoll mode.

Syntax

CpaStatus icp_sal_CyGetFileDescriptor(CpaInstanceHandle instanceHandle, int *fd);

Parameters

`instanceHandle`	Cryptographic API instance handle.
`fd`	File descriptor address to be set. The fd will be set only in case of success and be kept unchanged otherwise.

Return Value

The icp_sal_CyGetFileDescriptor function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Function executed successfully and the file descriptor has been set.
`CPA_STATUS_FAIL`	Function failed.
`CPA_STATUS_UNSUPPORTED`	Instance not in epoll mode (`CPA_INST_RX_NOTIFY_BY_EVENT`).

icp_sal_CyPutFileDescriptor

Put (release) the file descriptor for a cryptographic instance. This function exists for compatibility reasons.

Syntax

CpaStatus icp_sal_CyPutFileDescriptor(CpaInstanceHandle instanceHandle, int fd);

Parameters

`instanceHandle`	Cryptographic API instance handle.
`fd`	File descriptor.

Return Value

The icp_sal_CyPutFileDescriptor function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Function executed successfully.
`CPA_STATUS_FAIL`	Function failed.
`CPA_STATUS_UNSUPPORTED`	Instance not in epoll mode (`CPA_INST_RX_NOTIFY_BY_EVENT`).

icp_sal_DcGetFileDescriptor

Get the file descriptor for a data compression instance when operating in epoll mode. The file descriptor is used with the Linux* epoll interface (epoll_ctl(), epoll_wait()). The file descriptor will only be returned when the instance response mode is configured for CPA_INST_RX_NOTIFY_BY_EVENT (epoll mode).

Note

The file descriptor is persistent for the lifetime of the instance. If the instance response mode is changed from epoll to poll mode and back to epoll, the same file descriptor remains valid and does not need to be queried again. This API will return CPA_STATUS_UNSUPPORTED when the instance is not in epoll mode, even though the file descriptor continues to exist and will be valid if the instance is later switched back to epoll mode.

Syntax

CpaStatus icp_sal_DcGetFileDescriptor(CpaInstanceHandle instanceHandle, int *fd);

Parameters

`instanceHandle`	Data Compression API instance handle.
`fd`	File descriptor address to be set. The fd will be set only in case of success and be kept unchanged otherwise.

Return Value

The icp_sal_DcGetFileDescriptor function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Function executed successfully and the file descriptor has been set.
`CPA_STATUS_FAIL`	Function failed.
`CPA_STATUS_UNSUPPORTED`	Instance not in epoll mode (`CPA_INST_RX_NOTIFY_BY_EVENT`).

icp_sal_DcPutFileDescriptor

Put (release) the file descriptor for a data compression instance. This function exists for compatibility reasons.

Syntax

CpaStatus icp_sal_DcPutFileDescriptor(CpaInstanceHandle instanceHandle, int fd);

Parameters

`instanceHandle`	Data Compression API instance handle.
`fd`	File descriptor.

Return Value

The icp_sal_DcPutFileDescriptor function returns one of the following codes:

`CPA_STATUS_SUCCESS`	Function executed successfully.
`CPA_STATUS_FAIL`	Function failed.
`CPA_STATUS_UNSUPPORTED`	Instance not in epoll mode (`CPA_INST_RX_NOTIFY_BY_EVENT`).