Engine Control Messages - Intel QAT Engine

Overview

The QAT Engine supports custom control messages that allow applications to communicate directly with the engine. These messages serve two primary purposes:

Configuration: Set engine options before initialization
Runtime Control: Control engine operation during execution

Using Engine Control Messages

Engine control messages use the OpenSSL ENGINE_ctrl_cmd() function:

ENGINE_ctrl_cmd(<Engine>, <Message String>, <Param 3>, <Param 4>, NULL, 0);

Parameters

Engine

ENGINE*

Pointer to the QAT Engine instance

Message String

const char*

String identifying the message type (see reference table below)

Param 3

long

Long integer for passing numbers, or a pointer cast to long

Param 4

void*

Void pointer for passing data structures

The last two parameters to ENGINE_ctrl_cmd() are always NULL and 0 when used with the QAT Engine.

Polling Mode Messages

ENABLE_EXTERNAL_POLLING

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation, before initialization

Enables external polling mode where the application is responsible for polling the hardware accelerator using the POLL message. Example:

ENGINE_ctrl_cmd(e, "ENABLE_EXTERNAL_POLLING", 0, NULL, NULL, 0);

POLL

Param 3

long

default:"0"

Not used

Param 4

int*

required

Pointer to int that receives the poll status

When to send

string

Any time after engine initialization

Requests a poll of all instances when external polling is enabled. The poll status is returned in the variable passed as Param 4. Example:

int poll_status;
ENGINE_ctrl_cmd(e, "POLL", 0, &poll_status, NULL, 0);

ENABLE_EVENT_DRIVEN_POLLING_MODE

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation, before initialization

Enables event-driven polling using the QAT driver’s event notification feature.

Not supported on FreeBSD or with qatlib RPM.

DISABLE_EVENT_DRIVEN_POLLING_MODE

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation, before initialization

Switches back to timer-based polling mode.

Not supported on FreeBSD or with qatlib RPM.

ENABLE_INLINE_POLLING

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation, before initialization

Enables inline polling mode where a busy loop checks for messages from the hardware accelerator after requests are sent.

Currently only available for synchronous RSA computation.

ENABLE_HEURISTIC_POLLING

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation, before initialization

Enables heuristic polling mode where applications can intelligently determine when to poll based on in-flight request counts.

Requires external polling mode to be enabled first.

Polling Configuration Messages

SET_INTERNAL_POLL_INTERVAL

Param 3

unsigned long

Interval in nanoseconds (min: 1, max: 10,000,000, default: 10,000)

Param 4

void*

default:"NULL"

Not used

When to send

string

Any time after engine creation

Sets the interval between polls for messages from the hardware accelerator. Example:

ENGINE_ctrl_cmd(e, "SET_INTERNAL_POLL_INTERVAL", 15000, NULL, NULL, 0);

SET_EPOLL_TIMEOUT

Param 3

int

Timeout in milliseconds (min: 1, max: 10,000, default: 1,000)

Param 4

void*

default:"NULL"

Not used

When to send

string

Any time after engine creation

Sets the timeout for epoll_wait() when event-driven polling is enabled.

Not supported on FreeBSD or with qatlib RPM.

SET_MAX_RETRY_COUNT

Param 3

int

Number of retries (default: 5, max: 100,000, -1: infinite)

Param 4

void*

default:"NULL"

Not used

When to send

string

Any time after engine creation

Sets how many times the engine should retry a synchronous operation before flagging a failure. Example:

// Set to infinite retries
ENGINE_ctrl_cmd(e, "SET_MAX_RETRY_COUNT", -1, NULL, NULL, 0);

Instance and Thread Management

GET_NUM_CRYPTO_INSTANCES

Param 3

long

default:"0"

Not used

Param 4

int*

required

Pointer to int that receives the instance count

When to send

string

After engine initialization

Retrieves the total number of crypto instances available as specified in the QAT driver config file. Example:

int num_instances;
ENGINE_ctrl_cmd(e, "GET_NUM_CRYPTO_INSTANCES", 0, &num_instances, NULL, 0);

GET_EXTERNAL_POLLING_FD

Param 3

int

Instance number to retrieve fd for

Param 4

int*

required

Pointer to int that receives the file descriptor

When to send

string

After engine initialization

Retrieves the file descriptor for event notification in event-driven polling mode.

Not supported on FreeBSD or with qatlib RPM.

Example:

int num_instances, fd;
ENGINE_ctrl_cmd(e, "GET_NUM_CRYPTO_INSTANCES", 0, &num_instances, NULL, 0);

for (int i = 0; i < num_instances; i++) {
    ENGINE_ctrl_cmd(e, "GET_EXTERNAL_POLLING_FD", i, &fd, NULL, 0);
    // Use fd for epoll/select
}

SET_INSTANCE_FOR_THREAD

Param 3

long

Instance number to bind to

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation (automatically triggers initialization)

Binds the current thread to a specific crypto instance. Example:

ENGINE_ctrl_cmd(e, "SET_INSTANCE_FOR_THREAD", 2, NULL, NULL, 0);

Monitoring and Statistics

GET_NUM_REQUESTS_IN_FLIGHT

Param 3

int

Request type: 1 (asym), 2 (KDF), 3 (cipher)

Param 4

int**

required

Pointer to int pointer that receives the address of the counter

When to send

string

Any time after engine initialization

Retrieves the address of the counter for in-flight requests of a specific type. Requires heuristic polling to be enabled. Request Types:

1: Asymmetric key operations
2: KDF operations (PRF and HKDF)
3: Cipher operations (or pipelines when pipelining is used)

Example:

int *asym_requests_ptr;
ENGINE_ctrl_cmd(e, "GET_NUM_REQUESTS_IN_FLIGHT", 1, &asym_requests_ptr, NULL, 0);
// Read directly: int count = *asym_requests_ptr;

GET_NUM_OP_RETRIES

Param 3

long

default:"0"

Not used

Param 4

unsigned int*

required

Pointer to unsigned int that receives the retry count

When to send

string

Any time after engine initialization

Retrieves the total number of retry operations that have occurred. Example:

unsigned int retries;
ENGINE_ctrl_cmd(e, "GET_NUM_OP_RETRIES", 0, &retries, NULL, 0);

Engine Initialization and Lifecycle

INIT_ENGINE

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation

Manually initializes the engine. Normally not necessary as the engine initializes automatically via ENGINE_init() or after fork.

Useful for performance optimization when engine is compiled with --disable-qat_auto_engine_init_on_fork.

SET_CONFIGURATION_SECTION_NAME

Param 3

long

default:"0"

Not used

Param 4

char*

required

NULL-terminated section name (max 64 bytes including NULL)

When to send

string

After engine creation, before initialization

Configures the engine to use a custom section name in the QAT driver config file instead of the default [SHIM]. Example:

ENGINE_ctrl_cmd(e, "SET_CONFIGURATION_SECTION_NAME", 0, "MY_SECTION", NULL, 0);

Fallback and Offload Control

ENABLE_SW_FALLBACK

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

After engine creation, before initialization

Enables automatic fallback to software (on-core) crypto operations if acceleration devices go offline.

Not supported on FreeBSD or with qatlib RPM.

HEARTBEAT_POLL

Param 3

long

default:"0"

Not used

Param 4

int*

required

Pointer to int that receives success/failure status

When to send

string

Any time after engine initialization

Checks if acceleration devices are still functioning. Used with software fallback and external polling.

Recommended polling interval: 0.5 to 1 second for timely detection of device status changes.

Example:

int status;
ENGINE_ctrl_cmd(e, "HEARTBEAT_POLL", 0, &status, NULL, 0);
if (!status) {
    // Devices are offline
}

DISABLE_QAT_OFFLOAD

Param 3

long

default:"0"

Not used

Param 4

void*

default:"NULL"

Not used

When to send

string

Any time after engine initialization

Disables hardware acceleration immediately, performing all operations on-core instead. Example:

ENGINE_ctrl_cmd(e, "DISABLE_QAT_OFFLOAD", 0, NULL, NULL, 0);

Algorithm Control

SET_CRYPTO_SMALL_PACKET_OFFLOAD_THRESHOLD

Param 3

long

default:"0"

Not used

Param 4

char*

required

NULL-terminated configuration string (max 1024 bytes)

When to send

string

Any time after engine creation

Sets the packet size threshold for hardware acceleration. Packets below this size are processed on-core for better performance. Supported Algorithms:

AES-128-CBC-HMAC-SHA1
AES-256-CBC-HMAC-SHA1
AES-128-CBC-HMAC-SHA256
AES-256-CBC-HMAC-SHA256

Format:

ALGORITHM:THRESHOLD[,ALGORITHM:THRESHOLD...]

Example:

char *config = "AES-128-CBC-HMAC-SHA1:4096,AES-256-CBC-HMAC-SHA1:8192";
ENGINE_ctrl_cmd(e, "SET_CRYPTO_SMALL_PACKET_OFFLOAD_THRESHOLD", 0, config, NULL, 0);

Threshold Values:

Default: 2048 bytes
Minimum: 0 bytes
Maximum: 16,384 bytes

The threshold includes the entire TLS record: header (5B), IV (16B), payload, HMAC (20/32B), padding (0-255B), and padding length (1B).

Not supported when compiled with --enable-qat_small_pkt_offload.

HW_ALGO_BITMAP

Param 3

long

default:"0"

Not used

Param 4

unsigned long*

required

Pointer to hex value bitmap

When to send

string

Any time after engine initialization

Sets the QAT hardware algorithm bitmap and reloads algorithm methods. Example:

unsigned long bitmap = 0x82EF;
ENGINE_ctrl_cmd(e, "HW_ALGO_BITMAP", 0, &bitmap, NULL, 0);

Default bitmap is 0xFFFF (all algorithms enabled). Only the first 16 bits are used.

SW_ALGO_BITMAP

Param 3

long

default:"0"

Not used

Param 4

unsigned long*

required

Pointer to hex value bitmap

When to send

string

Any time after engine initialization

Sets the QAT software algorithm bitmap and reloads algorithm methods. Example:

unsigned long bitmap = 0x82EF;
ENGINE_ctrl_cmd(e, "SW_ALGO_BITMAP", 0, &bitmap, NULL, 0);

Quick Reference Table

Message	Timing	Param 3	Param 4	Purpose
`ENABLE_EXTERNAL_POLLING`	Before init	0	NULL	Enable external polling mode
`POLL`	After init	0	int*	Poll all instances
`ENABLE_EVENT_DRIVEN_POLLING_MODE`	Before init	0	NULL	Enable event-driven polling
`DISABLE_EVENT_DRIVEN_POLLING_MODE`	Before init	0	NULL	Disable event-driven polling
`ENABLE_INLINE_POLLING`	Before init	0	NULL	Enable inline polling
`ENABLE_HEURISTIC_POLLING`	Before init	0	NULL	Enable heuristic polling
`SET_INTERNAL_POLL_INTERVAL`	Anytime	nanoseconds	NULL	Set poll interval
`SET_EPOLL_TIMEOUT`	Anytime	milliseconds	NULL	Set epoll timeout
`SET_MAX_RETRY_COUNT`	Anytime	count	NULL	Set retry limit
`GET_NUM_CRYPTO_INSTANCES`	After init	0	int*	Get instance count
`GET_EXTERNAL_POLLING_FD`	After init	instance	int*	Get polling fd
`SET_INSTANCE_FOR_THREAD`	After creation	instance	NULL	Bind thread to instance
`GET_NUM_REQUESTS_IN_FLIGHT`	After init	type	int**	Get in-flight counter address
`GET_NUM_OP_RETRIES`	After init	0	unsigned int*	Get retry count
`INIT_ENGINE`	After creation	0	NULL	Manually initialize
`SET_CONFIGURATION_SECTION_NAME`	Before init	0	char*	Set config section
`ENABLE_SW_FALLBACK`	Before init	0	NULL	Enable software fallback
`HEARTBEAT_POLL`	After init	0	int*	Check device status
`DISABLE_QAT_OFFLOAD`	After init	0	NULL	Disable HW acceleration
`SET_CRYPTO_SMALL_PACKET_OFFLOAD_THRESHOLD`	Anytime	0	char*	Set size thresholds
`HW_ALGO_BITMAP`	After init	0	unsigned long*	Set HW algorithm bitmap
`SW_ALGO_BITMAP`	After init	0	unsigned long*	Set SW algorithm bitmap

Get Started

Installation

Core Concepts

Configuration

Advanced Features

Integration

Troubleshooting

​Overview

​Using Engine Control Messages

​Parameters

​Polling Mode Messages

​ENABLE_EXTERNAL_POLLING

​POLL

​ENABLE_EVENT_DRIVEN_POLLING_MODE

​DISABLE_EVENT_DRIVEN_POLLING_MODE

​ENABLE_INLINE_POLLING

​ENABLE_HEURISTIC_POLLING

​Polling Configuration Messages

​SET_INTERNAL_POLL_INTERVAL

​SET_EPOLL_TIMEOUT

​SET_MAX_RETRY_COUNT

​Instance and Thread Management

​GET_NUM_CRYPTO_INSTANCES

​GET_EXTERNAL_POLLING_FD

​SET_INSTANCE_FOR_THREAD

​Monitoring and Statistics

​GET_NUM_REQUESTS_IN_FLIGHT

​GET_NUM_OP_RETRIES

​Engine Initialization and Lifecycle

​INIT_ENGINE

​SET_CONFIGURATION_SECTION_NAME

​Fallback and Offload Control

​ENABLE_SW_FALLBACK

​HEARTBEAT_POLL

​DISABLE_QAT_OFFLOAD

​Algorithm Control

​SET_CRYPTO_SMALL_PACKET_OFFLOAD_THRESHOLD

​HW_ALGO_BITMAP

​SW_ALGO_BITMAP

​Quick Reference Table

​Additional Resources

Build docs developers (and LLMs) love

Overview

Using Engine Control Messages

Parameters

Polling Mode Messages

ENABLE_EXTERNAL_POLLING

POLL

ENABLE_EVENT_DRIVEN_POLLING_MODE

DISABLE_EVENT_DRIVEN_POLLING_MODE

ENABLE_INLINE_POLLING

ENABLE_HEURISTIC_POLLING

Polling Configuration Messages

SET_INTERNAL_POLL_INTERVAL

SET_EPOLL_TIMEOUT

SET_MAX_RETRY_COUNT

Instance and Thread Management

GET_NUM_CRYPTO_INSTANCES

GET_EXTERNAL_POLLING_FD

SET_INSTANCE_FOR_THREAD

Monitoring and Statistics

GET_NUM_REQUESTS_IN_FLIGHT

GET_NUM_OP_RETRIES

Engine Initialization and Lifecycle

INIT_ENGINE

SET_CONFIGURATION_SECTION_NAME

Fallback and Offload Control

ENABLE_SW_FALLBACK

HEARTBEAT_POLL

DISABLE_QAT_OFFLOAD

Algorithm Control

SET_CRYPTO_SMALL_PACKET_OFFLOAD_THRESHOLD

HW_ALGO_BITMAP

SW_ALGO_BITMAP

Quick Reference Table

Additional Resources