Skip to main content

​
Overview

The Intel QAT OpenSSL Engine’s software fallback feature provides continuity of cryptographic operations when acceleration devices become unresponsive or undergo reset. This is achieved through the Intel QuickAssist Heartbeat feature.

​
Heartbeat Feature

The Intel QuickAssist Heartbeat feature provides:
  • Device Health Monitoring: Detects unresponsive acceleration devices
  • Reset Notifications: Notifies the engine when device reset starts and ends
  • Instance Management: Suspends QAT instances during device reset
Software fallback requires an application utility or daemon that periodically checks device health as part of the heartbeat functionality.

​
Automatic Fallback Behavior

When software fallback is enabled, the engine exhibits the following behavior:

​
During Device Reset

  1. In-Flight Requests: Requests already submitted to the failed device that haven’t completed are handled on-core and will complete successfully
  2. New Requests: Incoming requests while the device is offline are either:
    • Submitted to other available acceleration devices (if any)
    • Handled on-core if no devices are available
  3. Device Recovery: Once the device comes back online, new requests can use instances from that device again
The fallback process is transparent to applications. The only noticeable effect is potential performance degradation until the acceleration device recovers.

​
Requirements

​
Supported Hardware

The Heartbeat feature is supported on:

​
Supported Drivers

  • Linux Hardware v1.7
  • Linux Hardware v1.8
  • Linux Hardware v2.0 (qatlib intree)
  • FreeBSD Hardware v2.0 (OOT package)

​
Supported Algorithms

The following algorithm types support software fallback:
  • Asymmetric PKE: All asymmetric algorithms supported by QAT Engine/Provider
  • Key Derivation: All key derivation algorithms
  • Symmetric Ciphers:
    • AES-GCM
    • AES-CCM
    • ChaCha20-Poly1305
    • AES-CBC chained ciphers
Hash algorithms (SHA family) and SMx algorithms do not support software fallback.
Software fallback for symmetric algorithms is only supported on FreeBSD platforms.

​
Configuration

​
Driver Configuration

Enable automatic reset on error in the device configuration file /etc/<device>.conf: 
[GENERAL]
AutomaticResetOnError = 1
The AutomaticResetOnError = 1 setting is required for software fallback to function properly.

​
Engine Configuration

Enable software fallback in your application using engine control messages, or manually set: 
enable_sw_fallback = 1
This can be set at runtime through Engine Control messages from the application.

​
Testing Software Fallback

​
Prerequisites

  1. Build QAT Driver with Heartbeat Simulation: 
    ./configure --enable-icp-hb-fail-sim
make && make install
  2. Configure Device for Auto-Reset: Edit /etc/<device>.conf to include: 
    AutomaticResetOnError = 1
  3. OpenSSL Version Compatibility: The driver must be built with the same version of OpenSSL as the application. Set these environment variables if needed: 
    export LDFLAGS="-L<installed OpenSSL path>/lib"
export CPPFLAGS="-I<installed OpenSSL path>/include"

​
Test Procedure

  1. Enable Software Fallback: Set enable_sw_fallback = 1 in e_qat.c or enable via Engine Control messages at runtime.
  2. Build QAT Engine: Follow the standard build instructions.
  3. Run OpenSSL Speed Test: 
    openssl speed -engine qatengine -elapsed rsa2048
  4. Inject Device Failure: 
    sysctl dev.qat.0.heartbeat_sim_fail=1
  5. Check Device Status: 
    sysctl dev.qat.0.heartbeat
    • 0 = device failure
    • 1 = device active
  6. Verify Success: On successful software fallback, the OpenSSL speed test continues without errors despite the device failure.

​
Expected Results

  • The test continues running after device failure injection
  • Performance may decrease while the device is offline
  • No cryptographic operation errors occur
  • Operations resume normal performance after device recovery

​
Additional Resources

For more information on the Heartbeat feature, refer to:

Build docs developers (and LLMs) love

Get started for freeTalk to us