Troubleshooting for QNN LPAI Backends (x86 Simulator, ARM & aDSP)

This paragraph provides a comprehensive guide for executing and troubleshooting QNN LPAI backends across x86 (simulator), ARM (Android), and native aDSP targets.

Environment Variable Export Commands

ARM Target (Android)

export QNN_TARGET_ARCH=aarch64-android
export HW_VER=v6

aDSP Target (Hexagon DSP)

export QNN_TARGET_ARCH=aarch64-android
export DSP_ARCH=hexagon-v81
export DSP_VER=V81
export HW_VER=v6

x86 Simulator (Linux)

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${QNN_SDK_ROOT}/lib/x86_64-linux-clang

x86 Simulator (Windows)

set PATH=%PATH%;%QNN_SDK_ROOT%\lib\x86_64-windows-msvc

Execution Examples

x86 Simulator (Linux)

From Quantized Model:

cd ${QNN_SDK_ROOT}/examples/QNN/converter/models
${QNN_SDK_ROOT}/bin/x86_64-linux-clang/qnn-net-run \
  --backend ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpai.so \
  --model ${QNN_SDK_ROOT}/examples/QNN/example_libs/x86_64-linux-clang/libQnnModel.so \
  --input_list input_list_float.txt \
  --config_file /path/to/config.json

From Serialized Buffer:

${QNN_SDK_ROOT}/bin/x86_64-linux-clang/qnn-net-run \
  --backend ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpai.so \
  --retrieve_context qnn_model_8bit_quantized.serialized.bin \
  --input_list input_list_float.txt \
  --config_file /path/to/config.json

x86 Simulator (Windows)

cd %QNN_SDK_ROOT%\examples\QNN\converter\models
%QNN_SDK_ROOT%\bin\x86_64-windows-msvc\qnn-net-run.exe
  --backend %QNN_SDK_ROOT%\lib\x86_64-windows-msvc\QnnLpai.dll
  --model %QNN_SDK_ROOT%\examples\QNN\example_libs\x86_64-windows-msvc\QnnModel.dll
  --input_list input_list_float.txt
  --config_file C:\path\to\config.json

ARM Target (Android)

adb shell mkdir -p /data/local/tmp/LPAI/adsp
adb push ./output/qnn_model_8bit_quantized.serialized.bin /data/local/tmp/LPAI
adb push ${QNN_SDK_ROOT}/lib/${QNN_TARGET_ARCH}/libQnnLpai.so /data/local/tmp/LPAI
adb push ${QNN_SDK_ROOT}/lib/${QNN_TARGET_ARCH}/libQnnLpaiStub.so /data/local/tmp/LPAI
adb push ${QNN_SDK_ROOT}/lib/${QNN_TARGET_ARCH}/libQnnLpaiNetRunExtensions.so /data/local/tmp/LPAI
adb push ${QNN_SDK_ROOT}/lib/lpai-${HW_VER}/unsigned/libQnnLpaiSkel.so /data/local/tmp/LPAI/adsp
adb push ${QNN_SDK_ROOT}/examples/QNN/converter/models/input_data_float /data/local/tmp/LPAI
adb push ${QNN_SDK_ROOT}/examples/QNN/converter/models/input_list_float.txt /data/local/tmp/LPAI
adb push ${QNN_SDK_ROOT}/bin/aarch64-android/qnn-net-run /data/local/tmp/LPAI

adb shell
cd /data/local/tmp/LPAI
export LD_LIBRARY_PATH=/data/local/tmp/LPAI:/data/local/tmp/LPAI/adsp
export ADSP_LIBRARY_PATH="/data/local/tmp/LPAI/adsp"

./qnn-net-run --backend ./libQnnLpai.so --device_options device_id:0 \
  --retrieve_context ./qnn_model_8bit_quantized.serialized.bin \
  --input_list ./input_list_float.txt

aDSP Target (Hexagon DSP)

adb push ${QNN_SDK_ROOT}/lib/lpai-${HW_VER}/unsigned/libQnnLpai.so /data/local/tmp/LPAI/adsp
adb push ${QNN_SDK_ROOT}/lib/lpai-${HW_VER}/unsigned/libQnnLpaiNetRunExtensions.so /data/local/tmp/LPAI/adsp
adb push ${QNN_SDK_ROOT}/lib/${DSP_ARCH}/unsigned/libQnnHexagonSkel_App.so /data/local/tmp/LPAI/adsp
adb push ${QNN_SDK_ROOT}/lib/${DSP_ARCH}/unsigned/libQnnNetRunDirect${DSP_VER}Skel.so /data/local/tmp/LPAI/adsp
adb push ${QNN_SDK_ROOT}/lib/${QNN_TARGET_ARCH}/libQnnNetRunDirect${DSP_VER}Stub.so /data/local/tmp/LPAI

export LD_LIBRARY_PATH=/data/local/tmp/LPAI:/data/local/tmp/LPAI/adsp
export ADSP_LIBRARY_PATH="/data/local/tmp/LPAI/adsp"

Example config.json

The table below shows the differences in config.json for each supported backend type:

Target

shared_library_path

config_file_path

context_configs

Simulator (x86)

${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiNetRunExtensions.so

./lpaiParams.conf

“is_persistent_binary”: false

aDSP (Hexagon)

/data/local/tmp/LPAI/adsp/libQnnLpaiNetRunExtensions.so

./lpaiParams.conf

“is_persistent_binary”: true

ARM Android

/data/local/tmp/LPAI/libQnnLpaiNetRunExtensions.so

./lpaiParams.conf

“is_persistent_binary”: false

Each configuration should be wrapped in the following structure:

{
  "backend_extensions": {
    "shared_library_path": "<appropriate path>",
    "config_file_path": "./lpaiParams.conf"
  },
  "context_configs": {
    "is_persistent_binary": true
  }
}

Troubleshooting Table

Issue Category

Symptoms

Resolution & Debugging Commands

Library Not Found or Load Errors

  • cannot locate shared object file

  • undefined symbol

  • library not found

  • Ensure all required .so or .dll files are present in the correct paths.

  • Verify that LD_LIBRARY_PATH (Linux) or PATH (Windows) includes the correct directories.

  • Use ldd (Linux) or Dependency Walker (Windows) to inspect missing dependencies.

    • x86 Linux For model generation and Simulatiion:

      • ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpai.so

      • ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiNetRunExtensions.so

      • ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiPrepare_${HW_VER}.so

      • ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiSim_${HW_VER}.so

    • x86 Windows For model generation and Simulatiion:

      • ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpai.dll

      • ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpaiNetRunExtensions.dll

      • ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpaiPrepare_${HW_VER}.dll

      • ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpaiSim_${HW_VER}.dll

    • ARM FastRpc Path:

      • /data/local/tmp/LPAI/libQnnLpai.so

      • /data/local/tmp/LPAI/libQnnLpaiStub.so

      • /data/local/tmp/LPAI/libQnnLpaiNetRunExtensions

      • /data/local/tmp/LPAI/adsp/libQnnLpaiSkel.so

    • aDSP for LPAI and Hexagon libraries:

      • /data/local/tmp/LPAI/adsp/libQnnLpai.so

      • /data/local/tmp/LPAI/adsp/libQnnLpaiNetRunExtensions.so

      • /data/local/tmp/LPAI/adsp/libQnnHexagonSkel_App.so

      • /data/local/tmp/LPAI/adsp/libQnnNetRunDirect${DSP_VER}Skel.so

      • /data/local/tmp/LPAI/adsp/libQnnNetRunDirect${DSP_VER}Stub.so

  • Set environment variables:

    • Linux: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${QNN_SDK_ROOT}/lib/x86_64-linux-clang

    • Windows: set PATH=%PATH%;%QNN_SDK_ROOT%/lib/x86_64-windows-msvc

    • Android: export LD_LIBRARY_PATH=/data/local/tmp/LPAI:/data/local/tmp/LPAI/adsp

    • Android: export ADSP_LIBRARY_PATH="/data/local/tmp/LPAI/adsp"

  • Debug commands:

    • ldd qnn-net-run (Linux)

    • Dependency Walker (Windows)

    • adb shell ls /data/local/tmp/LPAI

    • adb shell ls /data/local/tmp/LPAI/adsp

    • readelf -d libQnnLpai.so

Context Binary Generator Setup Failure

  • qnn-context-binary-generator fails to start

  • missing backend or model path

  • missing LPAI Prepare library

  • Verify qnn-context-binary-generator binary exists:

    • Linux: ${QNN_SDK_ROOT}/bin/x86_64-linux-clang/qnn-context-binary-generator

    • Windows: ${QNN_SDK_ROOT}/bin/x86_64-windows-msvc/qnn-context-binary-generator.exe

  • Verify Prepare library exists:

    • Linux: ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiPrepare_${HW_VER}.so

    • Windows: ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpaiPrepare_${HW_VER}.so

  • Check backend and model paths are correct

  • Debug commands:

    • which qnn-context-binary-generator

    • ls -l ${QNN_SDK_ROOT}/bin/x86_64-linux-clang/

    • ls -l ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/

Simulator Setup Failure

  • qnn-net-run fails to start

  • missing backend or model path

  • missing LPAI Simulation library

  • Verify qnn-net-run binary exists:

    • Linux: ${QNN_SDK_ROOT}/bin/x86_64-linux-clang/qnn-net-run

    • Windows: ${QNN_SDK_ROOT}/bin/x86_64-windows-msvc/qnn-net-run.exe

  • Verify simulation library exists:

    • Linux: ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiSim_${HW_VER}.so

    • Windows: ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpaiSim_${HW_VER}.so

  • Check backend and model paths are correct

  • Debug commands:

    • which qnn-net-run

    • ls -l ${QNN_SDK_ROOT}/bin/x86_64-linux-clang/

    • ls -l ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/

Incorrect Environment Variables

  • backend fails to load

  • ADSP libraries not found

  • Ensure correct exports are set, see example for v5 (see Supported Platform for more info):

    • export QNN_TARGET_ARCH=aarch64-android

    • export DSP_ARCH=hexagon-v79

    • export DSP_VER=V79

    • export HW_VER=v5

  • Debug commands:

    • echo $QNN_TARGET_ARCH

    • env | grep DSP

ELF Format or Architecture Mismatch

  • Exec format error

  • wrong ELF class

  • no such file (even though the file exists)

  • Use file <binary> to inspect architecture compatibility.

    • file libQnnLpai.so → should show correct ELF type for target platform

  • Ensure binaries match target architecture:

    • Simulator (x86 Linux): ELF 64-bit LSB shared object, x86-64

      • ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpai.so

      • ${QNN_SDK_ROOT}/lib/x86_64-linux-clang/libQnnLpaiNetRunExtensions.so

      • ${QNN_SDK_ROOT}/bin/x86_64-linux-clang/qnn-net-run

    • Simulator (x86 Windows): PE32/PE32+ DLLs and EXEs

      • ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/QnnLpai.dll

      • ${QNN_SDK_ROOT}/lib/x86_64-windows-msvc/libQnnLpaiNetRunExtensions.dll

      • ${QNN_SDK_ROOT}/bin/x86_64-windows-msvc/qnn-net-run.exe

    • ARM (Android): ELF 64-bit LSB shared object, ARM aarch64

      • /data/local/tmp/LPAI/libQnnLpai.so

      • /data/local/tmp/LPAI/libQnnLpaiNetRunExtensions.so

      • /data/local/tmp/LPAI/qnn-net-run

    • aDSP (Hexagon): ELF 32-bit LSB shared object, Hexagon

      • /data/local/tmp/LPAI/adsp/libQnnLpai.so

      • /data/local/tmp/LPAI/adsp/libQnnLpaiNetRunExtensions.so

  • Debug commands:

    • readelf -h libQnnLpai.so

Unsigned or Improperly Signed Libraries

  • backend fails silently

  • model fails to execute

  • Use Qualcomm signing tools (sectools, sign_hexagon.py) to sign required libraries.

  • Ensure signed libraries are pushed to /data/local/tmp/LPAI/adsp.

  • Sign required libraries using Qualcomm tools:

    • Tools: sectools, sign_hexagon.py

  • For ARM (Android):

    • Sign and push to /data/local/tmp/LPAI/adsp/:

      • ${QNN_SDK_ROOT}/lib/lpai-${HW_VER}/unsigned/libQnnLpaiSkel.so

  • For aDSP (native DSP):

    • Sign and push to /data/local/tmp/LPAI/adsp/:

      • ${QNN_SDK_ROOT}/lib/lpai-${HW_VER}/unsigned/libQnnLpai.so

      • ${QNN_SDK_ROOT}/lib/lpai-${HW_VER}/unsigned/libQnnLpaiNetRunExtensions.so

      • ${QNN_SDK_ROOT}/lib/${DSP_ARCH}/unsigned/libQnnHexagonSkel_App.so

      • ${QNN_SDK_ROOT}/lib/${DSP_ARCH}/unsigned/libQnnNetRunDirect${DSP_VER}Skel.so

  • Debug commands:

    • adb shell ls -l /data/local/tmp/LPAI/adsp/

Invalid or Missing Configuration

  • config.json not found

  • backend extension fails

  • Ensure config.json and lpaiParams.conf are present and valid.

  • Validate JSON syntax and required fields

    (shared_library_path, config_file_path, is_persistent_binary).

    • Example config.json:

{
  "backend_extensions": {
    "shared_library_path": "/data/local/tmp/LPAI/adsp/libQnnLpaiNetRunExtensions.so",
    "config_file_path": "./lpaiParams.conf"
  }
}

Model Execution Fails or Incorrect Output

  • model crashes

  • Output is incorrect or empty

  • Verify QNN model was quantized and serialized correctly

  • Ensure input data matches expected format and dimensions.

  • Check for version mismatches between model and runtime.

  • Confirm you dont see message like: version 4.xx is not supported on runtime 5.xx

  • Debug commands:

    • qnn-net-run --log_level debug <add your other previous options here>

    • adb logcat | grep supported

Root Permissions

  • permission denied errors

  • cannot access /data/local/tmp

  • Ensure commands are run with root privileges:

    • Use adb root and adb remount before pushing files

    • Use su or sudo where applicable

  • Debug commands:

    • adb shell whoami

    • ls -l /data/local/tmp