Qualcomm Hexagon (QHexRT) Engine

Relevant source files

The following files were used as context for generating this wiki page:

• engines/AGENTS.md
• AGENTS.md
• bindings/kotlin/AGENTS.md
• bindings/react-native/AGENTS.md
• core/README.md

Qualcomm Hexagon (QHexRT) Engine provides hardware-accelerated AI inference on Snapdragon processors. It interfaces with the Qualcomm Hexagon NPU (Neural Processing Unit) to serve multiple AI modalities, including large language models (LLM), vision-language models (VLM), and speech processing. The engine operates as a plugin within the RunAnywhere SDK ecosystem, registering itself into the core C++ registry to be used when compatible hardware is detected.

The engine specifically targets arm64-v8a Android devices and Windows ARM64 hardware. It is packaged as a private, prebuilt archive due to its dependence on proprietary Qualcomm QAIRT (Qualcomm AI Stack) and QNN (Qualcomm Neural Network) host libraries.

Sources: engines/AGENTS.md, core/README.md, bindings/kotlin/AGENTS.md

Architecture and Integration

QHexRT follows the RunAnywhere Engine Pattern 1, meaning it bundles or links its own runtime context. It uses QNN-context bundles to execute optimized AI graphs on the Hexagon HTP (Hexagon Tensor Processor).

Plugin Manifest and Priority

The engine declares a rac_engine_manifest_t that defines its capabilities and routing priority. When hardware support is confirmed, QHexRT is assigned a priority of 150, making it the preferred engine for served primitives over LlamaCPP (priority 100) and ONNX (priority 50).

Supported Modalities

QHexRT is one of the most comprehensive engines in the roster, serving six primary primitives:

Primitive	Functionality
LLM	Text generation via QNN-context models
VLM	Image understanding and vision tasks
STT	Speech-to-Text transcription
TTS	Text-to-Speech synthesis
EMBED	Vector embedding generation
DIFFUSION	Inpainting (LaMa) and Text-to-Image (Cosmos3-Edge)

Sources: engines/AGENTS.md, core/README.md

Registration Flow

The engine uses a two-phase initialization and a ROUTABLE-vs-STUB shell pattern. In public builds where the private Qualcomm binaries are absent, the engine remains in a "STUB" state. Registration is refused if the capability_check fails to find the necessary hardware or implementation.

Platform Specifics

Android (Kotlin SDK)

In the Kotlin SDK, QHexRT is packaged as an optional sub-module. It requires the QHexRTSkelInstaller to extract per-architecture DSP "skels" (V75, V79, or V81) at install time.

• JNI Bridge: All entry points guard on QHexRTBridge.ensureNativeLibraryLoaded().
• Packaging: Uses packaging.jniLibs.useLegacyPackaging = true because the Hexagon FastRPC mechanism must fopen() the skel .so files from the filesystem.
• 16KB Pages: The engine is compliant with Android 15+ 16KB page-size requirements.

Sources: bindings/kotlin/AGENTS.md, bindings/react-native/example/README.md

Windows and Electron

On Windows ARM64, the engine relies on the ADSP_LIBRARY_PATH environment variable to resolve FastRPC skels. The Electron binding uses a bridge.ts helper to add sidecar directories to the DLL and DSP search paths to ensure the NPU can load the necessary ternary decoders (e.g., Bonsai/Maple).

Sources: AGENTS.md, bindings/electron/AGENTS.md

Model Lifecycle and Execution

QHexRT adheres to the uniform model lifecycle defined for all RunAnywhere engines.

1. Create: Allocates the engine implementation based on a model ID and configuration JSON.
2. Initialize: Loads QNN-context weights and graphs from the filesystem.
3. Use: Executes inference (transcribe, synthesize, generate, etc.).
4. Cleanup: Unloads weights while keeping the implementation shell alive.
5. Destroy: Frees the implementation and native resources.

FastRPC and Session Management

For specific models like ternary decoders, the engine manages a direct FastRPC session to the cDSP. This session must be handled carefully to avoid contention with the standard QNN HTP device path.

Technical Summary

The Qualcomm Hexagon (QHexRT) Engine is the high-performance path for Snapdragon-based devices within the RunAnywhere ecosystem. By leveraging the Hexagon NPU via QNN contexts, it provides significantly higher priority and performance than CPU-based fallbacks. Its integration is complex due to proprietary dependencies, requiring specific environment configurations (like ADSP_LIBRARY_PATH) and legacy APK packaging to allow the hardware to access on-disk DSP libraries.

Sources: engines/AGENTS.md, bindings/react-native/example/README.md, bindings/electron/AGENTS.md