QNN (Qualcomm AI Engine Direct) Backend
Slash command argument routing
When this skill is invoked with arguments (e.g. /qualcomm <args>), classify the args FIRST and route before doing anything else:
| If args contain any of… |
Route to |
buck-fix, buck-cmake, buck cmake, buck-parity, buck parity, buck ci, qnn buck, fix qnn ci, test-qnn-buck-build-linux, or any natural-language request to fix QNN buck CI / catch buck-cmake drift |
Read buck_parity.md and follow it end-to-end. Default mode: full iterative-fix loop. If the args also contain check or diagnose, run buck once and report only — do not apply fixes. |
| (no args) or any other args |
Stay in this file; treat as a normal /qualcomm discovery request and use the Advanced Topics table below. |
Advanced Topics
When the user's request falls into one of these areas, read the corresponding file before proceeding:
| Topic |
File |
When to read |
| Export / lowering / quantization options / pass pipelines |
lowering_export.md |
User asks about exporting, lowering, quantization config, QuantDtype, QuantRecipe, pass pipelines |
| New op development |
new_op_development.md |
User asks to add/implement a new op or op builder |
| Model enablement |
model_enablement.md |
User asks to enable a new model end-to-end |
| Buck vs CMake parity (pre-PR or fix red CI) |
buck_parity.md |
User changed BUCK / TARGETS / targets.bzl or CMakeLists.txt under backends/qualcomm/, added new .cpp / .h / #include there, is preparing to push a PR that touches QNN, or the test-qnn-buck-build-linux CI check on their PR is red and they want to fix it locally. Direct trigger: /qualcomm buck-fix. |
| Profiling & debugging |
profiling.md |
User asks about profiling, optrace, QHAS, QAIRT Visualizer (file TBD) |
Building
Use backends/qualcomm/scripts/build.sh. Linux only (macOS not supported).
Environment variables:
QNN_SDK_ROOT — path to QNN SDK (auto-downloaded if not set)ANDROID_NDK_ROOT — path to Android NDK (auto-downloaded if not set)
Build targets:
| Target |
Default |
Build dir |
| x86_64 (Python interface + host tools) |
enabled |
build-x86/ |
| Android arm64-v8a (device runner) |
enabled |
build-android/ |
| Direct mode (LPAI ADSP or Hexagon CDSP) |
disabled |
build-direct/ |
| OE Linux embedded |
disabled |
build-oe-linux/ |
Common build commands:
# Full build (x86_64 + Android)
./backends/qualcomm/scripts/build.sh
# x86_64 only (faster, for Python interface development)
./backends/qualcomm/scripts/build.sh --skip_linux_android
# Android only (skip x86_64)
./backends/qualcomm/scripts/build.sh --skip_x86_64
# Incremental build (skip clean)
./backends/qualcomm/scripts/build.sh --no_clean
# Enable Hexagon DSP direct mode (requires HEXAGON_SDK_ROOT, HEXAGON_TOOLS_ROOT, DSP_VERSION)
./backends/qualcomm/scripts/build.sh --enable_hexagon
# OE Linux embedded target (requires TOOLCHAIN_ROOT_HOST, TOOLCHAIN_ROOT_TARGET)
./backends/qualcomm/scripts/build.sh --enable_linux_embedded
# Release build
./backends/qualcomm/scripts/build.sh --release
# Control parallelism
./backends/qualcomm/scripts/build.sh --job_number 8
After x86_64 build, the Python interface .so files are copied to backends/qualcomm/python/ automatically.
Testing
QNN_SDK_ROOT=/path/to/qnn_sdk \
ANDROID_NDK_ROOT=/path/to/android_ndk \
LD_LIBRARY_PATH=/path/to/executorch/build-x86/lib:/path/to/qnn_sdk/lib/x86_64-linux-clang \
PYTHONPATH=$(dirname $EXECUTORCH_ROOT) \
python backends/qualcomm/tests/test_qnn_delegate.py \
TestQNNFloatingPointOperator.test_qnn_backend_abs \
-H $HOST -s $DEVICE_SERIAL -m SM8850 -b build-android -a /path/to/artifacts
Note (build from source): Set PYTHONPATH to the parent directory of the executorch repo root. Required because executorch.examples.qualcomm lives in the source tree and is not installed into site-packages.
Required flags: -m (SoC model), -b (Android build dir). Optional: -s (device serial), -H (host), -a (artifact dir), -c (compile only), -x (run on x86_64).
Test classes:
| Class |
Description |
TestQNNFloatingPointOperator |
FP16 operator tests |
TestQNNQuantizedOperator |
Quantized operator tests |
TestQNNFloatingPointModel |
FP16 model-level tests |
TestQNNQuantizedModel |
Quantized model-level tests |
TestQNNFloatingPointUtils |
FP16 utility tests |
TestQNNQuantizedUtils |
Quantized utility tests |
TestExampleLLMScript |
LLM script tests |
TestExampleMultimodalityScript |
Multimodality script tests |
TestExampleOssScript |
OSS model script tests |
TestExampleScript |
General example script tests |
TestUtilsScript |
Utility script tests |
1---2name: qualcomm3description: Build, test, or develop the QNN (Qualcomm AI Engine Direct) backend. Use when working on backends/qualcomm/, building QNN (use backends/qualcomm/scripts/build.sh), adding new ops or passes, running QNN delegate tests, or exporting models for Qualcomm HTP/GPU targets. Also exposes a Buck-vs-CMake parity workflow — invoke as `/qualcomm buck-fix`, `/qualcomm buck-cmake fix`, `/qualcomm buck-parity`, or any user request to fix `test-qnn-buck-build-linux` CI failures or check buck/cmake drift in backends/qualcomm/.4---56# QNN (Qualcomm AI Engine Direct) Backend78## Slash command argument routing910When this skill is invoked with arguments (e.g. `/qualcomm <args>`), classify the args FIRST and route before doing anything else:1112| If args contain any of… | Route to |13|---|---|14| `buck-fix`, `buck-cmake`, `buck cmake`, `buck-parity`, `buck parity`, `buck ci`, `qnn buck`, `fix qnn ci`, `test-qnn-buck-build-linux`, or any natural-language request to fix QNN buck CI / catch buck-cmake drift | Read `buck_parity.md` and follow it end-to-end. Default mode: full iterative-fix loop. If the args also contain `check` or `diagnose`, run buck once and report only — do not apply fixes. |15| (no args) or any other args | Stay in this file; treat as a normal `/qualcomm` discovery request and use the Advanced Topics table below. |1617## Advanced Topics1819When the user's request falls into one of these areas, read the corresponding file before proceeding:2021| Topic | File | When to read |22|---|---|---|23| Export / lowering / quantization options / pass pipelines | `lowering_export.md` | User asks about exporting, lowering, quantization config, QuantDtype, QuantRecipe, pass pipelines |24| New op development | `new_op_development.md` | User asks to add/implement a new op or op builder |25| Model enablement | `model_enablement.md` | User asks to enable a new model end-to-end |26| Buck vs CMake parity (pre-PR or fix red CI) | `buck_parity.md` | User changed BUCK / TARGETS / `targets.bzl` or `CMakeLists.txt` under `backends/qualcomm/`, added new `.cpp` / `.h` / `#include` there, is preparing to push a PR that touches QNN, **or** the `test-qnn-buck-build-linux` CI check on their PR is red and they want to fix it locally. Direct trigger: `/qualcomm buck-fix`. |27| Profiling & debugging | `profiling.md` | User asks about profiling, optrace, QHAS, QAIRT Visualizer *(file TBD)* |2829## Building3031Use `backends/qualcomm/scripts/build.sh`. Linux only (macOS not supported).3233**Environment variables:**34- `QNN_SDK_ROOT` — path to QNN SDK (auto-downloaded if not set)35- `ANDROID_NDK_ROOT` — path to Android NDK (auto-downloaded if not set)3637**Build targets:**3839| Target | Default | Build dir |40|---|---|---|41| x86_64 (Python interface + host tools) | enabled | `build-x86/` |42| Android arm64-v8a (device runner) | enabled | `build-android/` |43| Direct mode (LPAI ADSP or Hexagon CDSP) | disabled | `build-direct/` |44| OE Linux embedded | disabled | `build-oe-linux/` |4546**Common build commands:**4748```bash49# Full build (x86_64 + Android)50./backends/qualcomm/scripts/build.sh5152# x86_64 only (faster, for Python interface development)53./backends/qualcomm/scripts/build.sh --skip_linux_android5455# Android only (skip x86_64)56./backends/qualcomm/scripts/build.sh --skip_x86_645758# Incremental build (skip clean)59./backends/qualcomm/scripts/build.sh --no_clean6061# Enable Hexagon DSP direct mode (requires HEXAGON_SDK_ROOT, HEXAGON_TOOLS_ROOT, DSP_VERSION)62./backends/qualcomm/scripts/build.sh --enable_hexagon6364# OE Linux embedded target (requires TOOLCHAIN_ROOT_HOST, TOOLCHAIN_ROOT_TARGET)65./backends/qualcomm/scripts/build.sh --enable_linux_embedded6667# Release build68./backends/qualcomm/scripts/build.sh --release6970# Control parallelism71./backends/qualcomm/scripts/build.sh --job_number 872```7374**After x86_64 build**, the Python interface `.so` files are copied to `backends/qualcomm/python/` automatically.7576## Testing7778```bash79QNN_SDK_ROOT=/path/to/qnn_sdk \80ANDROID_NDK_ROOT=/path/to/android_ndk \81LD_LIBRARY_PATH=/path/to/executorch/build-x86/lib:/path/to/qnn_sdk/lib/x86_64-linux-clang \82PYTHONPATH=$(dirname $EXECUTORCH_ROOT) \83python backends/qualcomm/tests/test_qnn_delegate.py \84 TestQNNFloatingPointOperator.test_qnn_backend_abs \85 -H $HOST -s $DEVICE_SERIAL -m SM8850 -b build-android -a /path/to/artifacts86```8788> **Note (build from source):** Set `PYTHONPATH` to the parent directory of the executorch repo root. Required because `executorch.examples.qualcomm` lives in the source tree and is not installed into site-packages.8990Required flags: `-m` (SoC model), `-b` (Android build dir). Optional: `-s` (device serial), `-H` (host), `-a` (artifact dir), `-c` (compile only), `-x` (run on x86_64).9192**Test classes:**9394| Class | Description |95|---|---|96| `TestQNNFloatingPointOperator` | FP16 operator tests |97| `TestQNNQuantizedOperator` | Quantized operator tests |98| `TestQNNFloatingPointModel` | FP16 model-level tests |99| `TestQNNQuantizedModel` | Quantized model-level tests |100| `TestQNNFloatingPointUtils` | FP16 utility tests |101| `TestQNNQuantizedUtils` | Quantized utility tests |102| `TestExampleLLMScript` | LLM script tests |103| `TestExampleMultimodalityScript` | Multimodality script tests |104| `TestExampleOssScript` | OSS model script tests |105| `TestExampleScript` | General example script tests |106| `TestUtilsScript` | Utility script tests |
software-mansion-labs