Migrating Applications

This section provides a practical guide for migrating an application from the Intel QuickAssist Technology (QAT) out-of-tree (OOT) software package to the in-tree Linux* driver stack and QATlib.

Use this section together with the following references:

• System Requirements for supported devices, firmware, kernel modules, and boot parameters

• Installation for distribution-based and source-based installation steps

• Configuration and Tuning for managed mode, standalone mode, POLICY, and ServicesEnabled

• In-Tree vs. Out-of-Tree for a broader platform comparison

Overview

Before installing or enabling the in-tree stack, remove the OOT software stack to avoid conflicts.

Refer to the Uninstall Acceleration Software section of the Getting Started Guide for details.

The migration from OOT to QATlib is not only a package replacement. It usually includes four areas of change:

• The kernel stack moves from a separately installed driver to the in-tree Linux kernel driver.

• User-space libraries move from legacy OOT library names to QATlib libraries.

• Platform configuration moves from per-device OOT configuration files to QATlib service management and /etc/sysconfig/qat.

• Some legacy or OOT-specific capabilities require application changes before migration is complete.

The following table summarizes the main differences that affect application migration.

Supported Devices and Migration Eligibility

Before starting the migration, verify that the target platform is supported by QATlib.

QATlib supports the following device families:

• QAT Gen 4: 4xxx, 401xx, 402xx

• QAT Gen 5: 420xx

Refer to Supported Devices for the complete list of device IDs, kernel modules, and firmware files.

Important

Applications deployed on legacy OOT-only QAT generations, i.e. before GEN4 (devices such as QAT1.7, QAT1.8, QAT1.9) cannot be migrated to QATlib without changing to a hardware platform supported by QATlib. Refer to Supported Devices.

Pre-Migration Checklist

Complete the following checks before changing the application or host configuration:

• Verify the platform uses a device listed in Supported Devices.

• Verify BIOS prerequisites such as Intel VT-d and SR-IOV.

• Verify the required firmware is present in /lib/firmware. See Firmware.

• Verify the platform and software baseline with System Requirements.

• Back up any existing OOT configuration files and deployment scripts.

• Review the application for dependencies on legacy-only behavior, custom OOT configuration sections, or unsupported features.

• Identify existing build and packaging assumptions, including include paths, linked libraries, and any OOT-specific environment variables.

If you are unsure whether the platform is currently in a migratable state, complete the verification flow in System Requirements first, then return to this page.

Step-by-Step Migration

1. Remove the OOT software stack

Before installing or enabling the in-tree stack, remove the OOT software to avoid conflicts between kernel modules, services, and configuration.

• Stop the OOT service and disable any startup logic that loads the OOT stack.

• Uninstall the OOT package from the build tree used to install it.

• Remove stale OOT configuration files if they are no longer needed.

• Unload OOT modules if they are still resident.

Refer to Uninstall Acceleration Software for the detailed uninstall procedure.

Before continuing to Step 2, confirm that OOT components remain inactive after reboot. Partial removal can cause module, service, or configuration conflicts at runtime.

2. Install the in-tree driver stack and QATlib

After the OOT package is removed, install QATlib either from distribution packages or from source.

• For distribution-based installation, follow Installation.

• For source-based installation, follow Installing from Sources.

• If managed mode is required, enable and start the qat service after installation.

3. Update platform and system configuration

Most migration problems are caused by platform configuration rather than application code.

Review and update the following areas:

• Linux boot parameters such as intel_iommu=on and vfio-pci.ids=...

• User permissions, including membership in the qat group

• Locked memory limits required for VFIO mappings

• Firmware placement and kernel module availability

Use System Requirements to verify platform prerequisites, and Installation for post-install updates such as user group membership, service enablement, and memlock configuration.

4. Update the application build

Applications built against the OOT package usually require build-system updates even when core API usage is unchanged.

At minimum, review the following items:

Build Updates Required During Migration

Build Area	Migration Action
Include paths	Use installed QATlib headers, typically with the qat include prefix, for example #include <qat/cpa.h>.
Library names	Link against libqat.so and libusdm.so instead of legacy OOT library names.
Legacy compatibility	If legacy library names are required, build QATlib with --enable-legacy-lib-names.
Packaging assumptions	Replace OOT-specific paths, install variables, and deployment logic with standard package or Autotools outputs.

See Configuration Options in the installation section for the full option list.

5. Review application code and feature usage

For many applications, the process flow remains familiar:

• Initialize user-space access at startup

• Run QAT operations

• Release resources during shutdown

In practice, this means applications typically continue to call icp_sal_userStart before invoking QAT APIs, and call icp_sal_userStop during shutdown.

For API behavior and return-code details, refer to User Space Access Configuration Functions.

6. Validate the migrated application

After the application and host have been updated, validate migration in stages:

• Confirm the application can initialize, discover instances, and run required services.

• Compare functional results and performance against the OOT baseline.

Common Migration Issues

The following issues are common when moving from OOT to the in-tree stack.

Issue	Likely Cause	Recommended Action
Library not found	New libraries installed outside the default search path	Run ldconfig or update the library search path after installation
Permission denied on VFIO	User is not in the qat group or the session has not been refreshed	Add the user to the qat group and re-login
No device found	VFs are not bound correctly, required boot parameters are missing, or service is not running	Re-check device support, VFIO binding, firmware, boot parameters, and the qat service state
RLIMIT_MEMLOCK exceeded	Locked memory limit is too low for VFIO mappings	Increase memlock limit and re-login

Migration Summary

For most applications, migration can be reduced to the following sequence:

1. Confirm the target platform is supported by QATlib.

2. Remove the OOT stack and install the in-tree driver stack with QATlib.

3. Update system prerequisites such as firmware, VFIO, boot parameters, user permissions, and memlock limits.

4. Replace OOT-specific include paths, library names, and deployment assumptions.

5. Refactor code that depends on unsupported OOT-only features.

6. Reconfigure resource allocation using /etc/sysconfig/qat and validate final application behavior.