QNN介绍 on huluhuluu

QNN HTP OpPackage Softmax 源码分析

Mon, 27 Apr 2026 10:10:00 +0800

QNN HTP OpPackage Softmax 源码分析

这篇为对照源码/qairt/2.40.0.251030/examples/QNN/OpPackage/HTP/ExampleOpPackageSoftmax.cpp 学习QNN如何自定义Softmax算子。它涵盖了：

Softmax 在 HTP OpPackage 里的注册方式
Softmax 参数顺序
Softmax -> Softmax_fp 的图改写规则
普通 reference 版本
FP16 + HVX 近似版本

1. 源码分析

1.1 头文件

源码开头包含了几类 HTP core 头文件：

#include "HTP/core/constraints.h"
#include "HTP/core/op_package_feature_support.h"
#include "HTP/core/op_register_ext.h"
#include "HTP/core/optimize.h"
#include "HTP/core/simple_reg.h"

可以按职责理解：

头文件	作用
`constraints.h`	给优化规则写匹配条件，例如 dtype、scalar、常量值
`op_package_feature_support.h`	OpPackage 特性支持相关定义
`op_register_ext.h`	注册自定义 op 的宏
`optimize.h`	图优化和 pattern rewrite 的宏
`simple_reg.h`	简化注册接口

这些宏不是普通 C++ 函数调用风格，而是 HTP backend 给 OpPackage 暴露的一套 DSL。

1.2 算子定义

1.2.1 算子定义

源码第 27 行：

`1`	`BEGIN_PKG_OP_DEFINITION(PKG_Softmax);`

这行给当前源文件里的 op 定义起内部名字 PKG_Softmax。它后面要和 ExampleOpPackageInterface.cpp 里的：

`1`	`DECLARE_PKG_OPS_OPTS_LIST(PKG_Softmax)`

对应起来。即Softmax.cpp 里声明了包内容，Interface.cpp 把这个包内容挂到最终 OpPackage 接口里。

源码第 29 行：

`1`	`DEF_PACKAGE_PARAM_ORDER("Softmax", "beta", false, nullptr, "axis", false, nullptr)`

定义了 Softmax 的参数顺序。它说明 Softmax 最多关心两个参数：

beta
axis

Interface.cpp 的 validateOpConfig() 对应这个约定：Softmax 允许 numOfParams <= 2。

1.2.2 函数声明

源码第 32 到 36 行先声明两个实现：

template <typename T_Ttype>
int softmaxWithbetaWrapper(T_Ttype &out, const T_Ttype &in, const Tensor &beta);

template <typename OutTtype, typename InTtype>
int softmax_fp_impl(OutTtype &out, const InTtype &in, const Tensor &beta);

它们代表两条路径：

softmaxWithbetaWrapper()：普通模板路径，内部调用 reference 写法。
softmax_fp_impl()：FP16 快路径，内部调用 softmax_hf_approx()。

1.2.3 注册 Softmax 算子

源码第 43 到 44 行：

1
2

DEF_PACKAGE_OP(softmaxWithbetaWrapper<Tensor>, "Softmax")
DEF_PACKAGE_OP((softmaxWithbetaWrapper<QuantUint8Tensor>), "Softmax")

把函数模板实例注册成名为 Softmax 的 op 实现。

源码第 56 到 59 行：

DEF_PACKAGE_OP_AND_COST_AND_FLAGS((softmaxWithbetaWrapper<PlainFloatTensor>),
                                  "Softmax",
                                  SNAIL,
                                  Flags::RESOURCE_HVX)

也注册 Softmax，但多了两个信息：

SNAIL：成本模型里比较慢的实现。
Flags::RESOURCE_HVX：这个实现会占用 HVX 资源。

1.2.4 Tensor 属性

源码第 61 行：

`1`	`DEF_TENSOR_PROPERTIES(Op("Softmax", "in", "Beta"), Flat(""), MainMemory(""))`

定义 Softmax 的 tensor 属性：

匹配 Softmax(in, Beta) 这种形式。
Flat("*") 表示相关 tensor 使用 flat 形态。
MainMemory("*") 表示相关 tensor 在 main memory。

这里的 * 是 pattern 里的通配符，HTP graph optimizer 会拿这些属性判断某个 op 实现能不能接住当前图里的 tensor。

1.2.5 注册 Softmax_fp 算子

源码第 64 到 72 行注册了两个 Softmax_fp：

DEF_PACKAGE_OP_AND_COST_AND_FLAGS((softmax_fp_impl<PlainFloat16Tensor, PlainFloat16Tensor>),
                                  "Softmax_fp",
                                  FAST,
                                  Flags::RESOURCE_HVX)

DEF_PACKAGE_OP_AND_COST_AND_FLAGS((softmax_fp_impl<PlainFloat16Tensor_TCM, PlainFloat16Tensor_TCM>),
                                  "Softmax_fp",
                                  FAST,
                                  Flags::RESOURCE_HVX)

这两条都标成 FAST，说明作者希望真正的 float 计算最后走 Softmax_fp。

区别在 tensor 类型：

PlainFloat16Tensor：普通 FP16 tensor。
PlainFloat16Tensor_TCM：放在 TCM 里的 FP16 tensor。

TCM(Tightly Coupled Memory) 是 HTP/DSP 侧更靠近计算单元的片上存储。这里注册 TCM 版本，是为了让 optimizer 在合适的内存布局下能选更快路径。

1.3 算子优化

1.3.1 float32 -> fp16

源码第 77 到 93 行是一条关键优化规则：

DEF_PACKAGE_OPTIMIZATION_WITH_FLAGS(
    GRAPH_CLEANUP,
    relaxed_precision_flag,
    Op("Softmax", "In", "Beta", "axis"),
    AND(EQ(DTYPE_OF("In"), DType::Float32), EQ(DTYPE_OF("*"), DType::Float32)),
    ... Op("Softmax_fp", WITH_SIZE("In", Op(FROM_DEFAULT_PACKAGE("Cast"), "In")), "Beta") ...)

它做的事情是：

Softmax(float32 In, Beta, axis)
-> Cast(In -> float16)
-> Softmax_fp(float16, Beta)
-> Cast(output -> float32)

触发条件是：

输入 In 是 Float32
输出也是 Float32
启用了 relaxed_precision_flag

所以这里不是无条件把 float32 改成 fp16，而是在精度允许时，把主计算切到 HTP 更友好的 FP16 实现。

1.3.2 折叠前置乘法

源码第 95 到 110 行：

Op("Softmax_fp",
   Op(FROM_DEFAULT_PACKAGE("QNN_OP_ELEMENT_WISE_MULTIPLY"),
      "In",
      Op(FROM_DEFAULT_PACKAGE("QNN_OP_CAST"), OPCONST("MaybeScalarVal"))),
   "Beta")

它匹配这种图：

`1`	`Softmax_fp(Multiply(In, Cast(scalar)), Beta)`

如果 MaybeScalarVal 是正的 float32 scalar，就改写成：

`1`	`Softmax_fp(In, Beta * scalar)`

写成公式形式就是：

$$ \exp(\beta \cdot x') $$

其输入前面有一个正标量乘法：

$$ x' = s \cdot x $$

那就可以变成：

$$ \exp(\beta \cdot s \cdot x) $$

也就是把 s 合进 beta。

1.3.3 默认参数规整

源码第 112 到 117 行有两条更简单的 rewrite：

DEF_PACKAGE_OPTIMIZATION(QNN,
                         Op("Softmax", "In"),
                         OK,
                         Op("Softmax", "In", gen_ConstScalar_f32(1.0f)))

DEF_PACKAGE_OPTIMIZATION(QNN, Op("Softmax", "In", "Beta", "axis"), OK, Op("Softmax", "In", "Beta"))

第一条把：

`1`	`Softmax(In) -> Softmax(In, 1.0f)`

第二条把：

`1`	`Softmax(In, Beta, axis) -> Softmax(In, Beta)`

这个例子里的实现实际按最后一维做 softmax，没有使用 axis 参数。

1.3.4 `softmax_hf_approx()` 总览

源码第 119 行开始是 FP16 快路径核心：

`1`	`void softmax_hf_approx(Float16 pout, const Float16 pin, float scale, int length)`

输入含义：

pin：一段 FP16 输入。
pout：一段 FP16 输出。
scale：外部传入的缩放系数，后面由 beta 和 interface_scale() 合成。
length：最后一维长度，也就是 softmax 的归一化长度。

整体流程对应普通 softmax：

max = reduce_max(x)
y = approx_exp(scale * (x - max))
sum = reduce_sum(y)
out = y / sum

只是这里全部手写成 HVX vector intrinsic。

1.4 伪代码

算子真正执行的核心计算是：

`1`	`softmax(x) = exp(scale * (x - max(x))) / sum(exp(scale * (x - max(x))))`

这几段伪代码的调用关系是：

softmax_fp_impl()
  └── 遍历输入 tensor 的 [B, H, W, D] 外层切片[B, H, W]
      └── 对每个连续的最后一维 [D] 切片调用 softmax_hf_approx()
          ├── reduce max 计算最大值
          ├── approx_exp2() 近似计算 exp 的主体
          ├── reduce sum 求和
          └── 原地归一化输出

其中 approx_exp2() 不是源码里的真实函数名，而是为了说明第 184 到 266 行的指数近似逻辑抽出来的概念函数。源码里这些逻辑直接内联写在 softmax_hf_approx() 的主循环中。

1.4.1 `softmax_fp_impl()` 伪代码

softmax_fp_impl() 本身不直接写 HVX 算法。它负责遍历输入的外层维度，把每个最后一维切片交给 softmax_hf_approx()：

function softmax_fp_impl(out, in, beta_tensor):
    # 输出 tensor 的 shape 和输入一致。
    out.shape = in.shape

    # 示例实现按 4D tensor 处理：[B, H, W, D]。
    # D 是最后一维，也是 softmax 的归一化维度。
    B, H, W, D = in.shape

    # beta 是 softmax 指数缩放参数。
    # interface_scale 是输入 tensor 接口层的 scale，需要合进总 scale。
    scale = in.interface_scale() * beta_tensor[0]

    # 每个 [b, h, w, :] 是一段连续的 D 维 fp16 buffer。
    for b in 0 .. B-1:
      for h in 0 .. H-1:
        for w in 0 .. W-1:
            # 当前最后一维切片的输入/输出首地址。
            pin  = &in[b, h, w, 0]
            pout = &out[b, h, w, 0]

            # 对这个 D 维切片做 softmax。
            softmax_hf_approx(
                pout,
                pin,
                scale,
                length = D
            )

也就是说，这个示例实现里的归一化维度是最后一维 D。

1.4.2 `softmax_hf_approx()` 总体伪代码

softmax_hf_approx() 是真正的 FP16 + HVX 快路径。忽略向量 intrinsic 的细节，它做的是稳定版 softmax：

`1`	`out[i] = exp(scale * (in[i] - max(in))) / sum_j exp(scale * (in[j] - max(in)))`

伪代码如下：

function softmax_hf_approx(pout, pin, scale, length):
    # 换底：后面用 2^x 近似来实现 e^x。
    log2_scale = scale / ln(2)

    # 拟合 2^x 的三阶多项式系数，不是标准 Taylor 系数。
    c0 = 1.0
    c1 = 0.692850309695840
    c2 = 0.237504551482093
    c3 = 0.046751431261525

    # pass 1: 找 max，避免 exp 溢出。
    # 源码中每次读 64 个 fp16，先得到 vector 形式的部分最大值。
    xmax_vec = fp16_negative_infinity
    for block in pin split by 64 fp16 elements:
        x = load_fp16_vector(block)
        x = mask_tail_if_needed(x)
        xmax_vec = vector_max_fp16(xmax_vec, x)

    # 把 vector lane 内的最大值继续横向归约成一个标量 max。
    xmax = horizontal_max_fp16(xmax_vec)

    # pass 2: 计算未归一化 exp，并累加 sum。
    # pout 先被当成临时 buffer 保存 exp 近似值。
    sum_vec = 0
    for block in pin split by 64 fp16 elements:
        x = load_fp16_vector(block)
        x = mask_tail_if_needed(x)

        # 稳定版 softmax 的核心：先减全局 max。
        xd = x - xmax

        # fp16 扩展成两组 qf32，方便做指数近似。
        lo_qf32, hi_qf32 = widen_fp16_to_two_qf32_vectors(xd)

        # 进入 base-2 指数域。
        z_lo = lo_qf32 * log2_scale
        z_hi = hi_qf32 * log2_scale

        # 源码第 184 到 266 行内联做了这个近似。
        exp_lo = approx_exp2(z_lo)
        exp_hi = approx_exp2(z_hi)

        # 暂存未归一化 exp 到 pout。
        y_fp16 = narrow_qf32_pair_to_fp16(exp_lo, exp_hi)
        store_fp16(pout_block, y_fp16)

        # 同时累加 softmax 分母。
        sum_vec += exp_lo
        sum_vec += exp_hi

    # 把 vector 形式的部分和横向归约成标量 sum。
    sum = horizontal_sum_qf32(sum_vec)
    recip = 1.0 / sum

    # pass 3: 原地归一化。
    # pout 当前保存的是 exp 近似值，乘以 1/sum 后才是最终 softmax。
    for block in pout split by 64 fp16 elements:
        y = load_fp16_vector(block)
        lo_qf32, hi_qf32 = widen_fp16_to_two_qf32_vectors(y)

        out_lo = lo_qf32 * recip
        out_hi = hi_qf32 * recip

        out_fp16 = narrow_qf32_pair_to_fp16(out_lo, out_hi)
        store_fp16(pout_block, out_fp16)

1.4.3 `approx_exp2()` 伪代码

源码里没有单独的 approx_exp2() 函数，但第 184 到 266 行实际在做类似事情。先把自然指数换底：

$$ e^x = 2^{x / \ln 2} $$

所以 kernel 里要近似的是 2^z。抽象成伪代码：

function approx_exp2(z):
    # z 是 base-2 指数域的输入。
    # 源码先把 qf32 转成便于按 float32 bit 位拆分的形式。
    z_as_float = convert_qf32_to_float_bits(z)

    # 拆出 float32 exponent bits。
    exponent_bits = get_float_exponent_bits(z_as_float)

    # 限制 exponent，让多项式输入落在较小范围。
    exponent_limit = min(exponent_bits, 126 << 23)
    exponent_delta = exponent_bits - exponent_limit

    # 用受限 exponent 重组规格化输入。
    z_norm = replace_exponent(z_as_float, exponent_limit)

    # Horner 形式计算三阶多项式：
    # p = c0 + c1*z_norm + c2*z_norm^2 + c3*z_norm^3
    p = c3 * z_norm
    p = p + c2
    p = p * z_norm
    p = p + c1
    p = p * z_norm
    p = p + c0

    # repeated squaring：先构造多个幂次候选。
    p2  = p   * p
    p4  = p2  * p2
    p8  = p4  * p4
    p16 = p8  * p8
    p32 = p16 * p16
    p64 = p32 * p32

    # 根据 exponent_delta 选择对应幂次，恢复更大范围的指数效果。
    if exponent_delta == 1 << 23:
        return p2
    if exponent_delta == 2 << 23:
        return p4
    if exponent_delta == 3 << 23:
        return p8
    if exponent_delta == 4 << 23:
        return p16
    if exponent_delta == 5 << 23:
        return p32
    if exponent_delta > 5 << 23:
        return p64

    return p

1.5 算子实现

1.5.1 exp 近似

源码第 124 到 130 行：

scale /= float(log(2.0));
c0.f = 1.f;
c1.f = 0.692850309695840;
c2.f = 0.237504551482093;
c3.f = 0.046751431261525;

这里把自然指数换到底数 2 的指数域：

$$ e^x = 2^{x / \ln 2} $$

然后，构造类似 2^x 的多项式近似。如下，c0/c1/c2/c3 是三阶多项式系数：

$$ c0 + c1 \cdot x + c2 \cdot x^2 + c3 \cdot x^3 $$

实际上，这里会先给$x$做上下范围的限制（$x = 2^k \times r$），然后用多项式近似小范围值$2 ^ r$，最后由于$2^x = 2^{2^k \cdot r} = (2^r)^{2^k}$，所以通过 repeated squaring 的方式构造 $p^2$、$p^4$、$p^8$… 来恢复更大范围的指数效果（就是前面的${2^k}$的指数部分）。

1.5.2 找最大值

源码第 132 到 151 行完成 reduce max。

第 133 行：

`1`	`HVX_Vector xmax = Q6_Vh_vsplat_R(0xFC00);`

0xFC00 是 half precision 的负无穷。Q6_Vh_vsplat_R() 把这个 16-bit 值广播到整个 HVX vector。

第 136 到 140 行每次读 64 个 FP16，寻找当前切片的最大值：

for (int d = length; d > 63; d -= 64) {
    HVX_Vector xinval = vmemu(iptr);
    iptr++;
    xmax = Q6_Vhf_vmax_VhfVhf(xmax, xinval);
}

这里 Vhf 可以读成 vector half float。Q6_Vhf_vmax_VhfVhf 就是对两个 half-float vector 做逐元素 max。

第 141 到 145 行处理最后不足 64 个元素的情况：

if ((length & 63) != 0) {
    HVX_Vector xinval         = vmemu(iptr);
    HVX_VectorPred qfinalmask = Q6_Q_vsetq2_R(length * 2);

    // mask 外的位置填成当前 xmax，避免尾部无效数据影响 max。
    xinval = Q6_V_vmux_QVV(qfinalmask, xinval, xmax);
    xmax   = Q6_Vhf_vmax_VhfVhf(xmax, xinval);
}

第 147 到 151 行把 vector 里的多个 lane 继续横向归约成一个最大值。

// 横向归约：把 vector 内多个 lane 的最大值继续合并成一个 xmax。
int nshift = 2;
for (int i = 0; i < 6; i++) {
    HVX_VectorPair temps = Q6_W_vshuff_VVR(xmax, xmax, nshift);
    xmax = Q6_Vhf_vmax_VhfVhf(Q6_V_lo_W(temps), Q6_V_hi_W(temps));
    nshift <<= 1;
}

1.5.3. 计算未归一化 exp

源码第 154 到 285 行是 softmax_hf_approx() 的主计算部分。它做的是：

1
2

tmp_i = approx_exp(scale * (x_i - max))
sum   = sum_i tmp_i

这里的 tmp_i 会先暂存到 pout，下一节再除以 sum。

进入主循环前，源码先准备常量、系数、指针和累加器：

// zero vector，后面用于类型转换、加法归一化和清尾部 lane。
HVX_Vector vzero = Q6_V_vzero();

// fp16 的 1.0，0x3c00 是 half precision 1.0 的 bit pattern。
HVX_Vector voneh = Q6_Vh_vsplat_R(0x3c00);

// 把三阶多项式系数广播到 HVX vector。
HVX_Vector f0 = Q6_V_vsplat_R(c0.i);
HVX_Vector f1 = Q6_V_vsplat_R(c1.i);
HVX_Vector f2 = Q6_V_vsplat_R(c2.i);
HVX_Vector f3 = Q6_V_vsplat_R(c3.i);

// 这些 mask/常量用于拆 float32 的指数位和尾数部分。
HVX_Vector c7f800000 = Q6_V_vsplat_R(0x7f800000);
HVX_Vector c807fffff = Q6_V_vsplat_R(0x807fffff);

// vbeta 是已经除以 ln(2) 后的 scale：
// exp(scale_orig * x) = 2^((scale_orig / ln2) * x)
HVX_Vector vbeta = Q6_Vqf32_vadd_VsfVsf(Q6_V_vsplat_R(scaleu.i), vzero);

// 126 << 23 对应 float32 exponent field 的一个上限基准。
// 后面会用它限制/拆分指数部分，避免近似计算范围过大。
HVX_Vector c126 = Q6_V_vsplat_R(126 << 23);

// c1w, c2w, ... c5w 是指数位差值的比较常量。
// 后面根据 xexp 的大小选择 p、p^2、p^4、...、p^64。
HVX_Vector c1w = Q6_V_vsplat_R(1 << 23);
HVX_Vector c2w = Q6_Vw_vadd_VwVw(c1w, c1w);
HVX_Vector c3w = Q6_Vw_vadd_VwVw(c2w, c1w);
HVX_Vector c4w = Q6_Vw_vadd_VwVw(c3w, c1w);
HVX_Vector c5w = Q6_Vw_vadd_VwVw(c4w, c1w);

// vsumf 累加当前 softmax 切片所有未归一化 exp 的和。
HVX_Vector vsumf = Q6_V_vzero();

// optr 指向输出 buffer。此时输出 buffer 被用作 tmp buffer，
// 用来暂存未归一化的 exp 近似值。
HVX_Vector *optr = (HVX_Vector *)pout;
iptr = (HVX_Vector *)pin;

主循环每轮处理 64 个 FP16。第一步是读取输入并减最大值：

for (int d = length; d > 0; d -= 64) {
  HVX_Vector x, x0, x1, p0, p1;
  HVX_VectorPair xdiff, p10;
  HVX_VectorPred q0, q1;

  // 读取当前 64 个 fp16 输入。
  x = vmemu(iptr);
  iptr++;

  // 稳定版 softmax 的关键：
  // xd = x - max(x)
  HVX_Vector xd = Q6_Vqf16_vsub_VhfVhf(x, xmax);

  // 把 fp16 差值扩展成两组 qf32 数据。
  // 返回 HVX_VectorPair，后面分别处理 lo/hi 两半。
  xdiff = Q6_Wqf32_vmpy_Vqf16Vhf(xd, voneh);

接着乘以 vbeta，进入 2^x 的近似域：

  // x0/x1 = (x - max) * scale / ln(2)
  x0 = Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_V_lo_W(xdiff), vbeta);
  x0 = Q6_Vsf_equals_Vqf32(x0);

  x1 = Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_V_hi_W(xdiff), vbeta);
  x1 = Q6_Vsf_equals_Vqf32(x1);

后面这组 bit 操作是在拆 float32 的指数位和规格化尾数。直观理解是：把 2^x 的计算拆成“较小范围的多项式近似”和“指数缩放/幂次恢复”两部分。

  // 取出 float32 的 exponent bits。
  HVX_Vector x0exp = Q6_V_vand_VV(x0, c7f800000);
  HVX_Vector x1exp = Q6_V_vand_VV(x1, c7f800000);

  // 把 exponent 限制到 c126 以内，构造后续多项式的输入范围。
  HVX_Vector x0explimit = Q6_Vw_vmin_VwVw(x0exp, c126);
  HVX_Vector x1explimit = Q6_Vw_vmin_VwVw(x1exp, c126);

  // xexp 保存剩余的指数位差值，用于后面选择 p^2/p^4/...。
  x0exp = Q6_Vw_vsub_VwVw(x0exp, x0explimit);
  x1exp = Q6_Vw_vsub_VwVw(x1exp, x1explimit);

  // xnorm 是规格化后的多项式输入。
  HVX_Vector x0norm = Q6_V_vor_VV(Q6_V_vand_VV(c807fffff, x0), x0explimit);
  HVX_Vector x1norm = Q6_V_vor_VV(Q6_V_vand_VV(c807fffff, x1), x1explimit);

然后用 Horner 形式计算三阶多项式：

  // p0 = ((c3 * x0norm + c2) * x0norm + c1) * x0norm + c0
  // 即 p0 = c0 + c1*x + c2*x^2 + c3*x^3
  p0 = Q6_Vqf32_vmpy_VsfVsf(x0norm, f3);
  p0 = Q6_Vqf32_vadd_Vqf32Vsf(p0, f2);
  x0norm = Q6_Vqf32_vadd_VsfVsf(x0norm, vzero);
  p0 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0, x0norm);
  p0 = Q6_Vqf32_vadd_Vqf32Vsf(p0, f1);
  p0 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0, x0norm);
  p0 = Q6_Vqf32_vadd_Vqf32Vsf(p0, f0);

  // p1 对应 vector 的另一半，计算方式相同。
  p1 = Q6_Vqf32_vmpy_VsfVsf(x1norm, f3);
  p1 = Q6_Vqf32_vadd_Vqf32Vsf(p1, f2);
  x1norm = Q6_Vqf32_vadd_VsfVsf(x1norm, vzero);
  p1 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1, x1norm);
  p1 = Q6_Vqf32_vadd_Vqf32Vsf(p1, f1);
  p1 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1, x1norm);
  p1 = Q6_Vqf32_vadd_Vqf32Vsf(p1, f0);

接下来反复平方，构造 p^2 到 p^64。这一步服务于前面拆出来的 exponent 差值：指数位差值越大，就选择更高次的平方结果。

  // 构造 p0^2, p0^4, p0^8, p0^16, p0^32, p0^64。
  HVX_Vector p0_2  = Q6_Vqf32_vmpy_Vqf32Vqf32(p0, p0);
  p0_2             = Q6_Vqf32_vadd_Vqf32Vsf(p0_2, vzero);
  HVX_Vector p0_4  = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_2, p0_2);
  p0_4             = Q6_Vqf32_vadd_Vqf32Vsf(p0_4, vzero);
  HVX_Vector p0_8  = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_4, p0_4);
  p0_8             = Q6_Vqf32_vadd_Vqf32Vsf(p0_8, vzero);
  HVX_Vector p0_16 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_8, p0_8);
  p0_16            = Q6_Vqf32_vadd_Vqf32Vsf(p0_16, vzero);
  HVX_Vector p0_32 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_16, p0_16);
  p0_32            = Q6_Vqf32_vadd_Vqf32Vsf(p0_32, vzero);
  HVX_Vector p0_64 = Q6_Vqf32_vmpy_Vqf32Vqf32(p0_32, p0_32);

  // p1^2 ... p1^64 同理。
  HVX_Vector p1_2  = Q6_Vqf32_vmpy_Vqf32Vqf32(p1, p1);
  p1_2             = Q6_Vqf32_vadd_Vqf32Vsf(p1_2, vzero);
  HVX_Vector p1_4  = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_2, p1_2);
  p1_4             = Q6_Vqf32_vadd_Vqf32Vsf(p1_4, vzero);
  HVX_Vector p1_8  = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_4, p1_4);
  p1_8             = Q6_Vqf32_vadd_Vqf32Vsf(p1_8, vzero);
  HVX_Vector p1_16 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_8, p1_8);
  p1_16            = Q6_Vqf32_vadd_Vqf32Vsf(p1_16, vzero);
  HVX_Vector p1_32 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_16, p1_16);
  p1_32            = Q6_Vqf32_vadd_Vqf32Vsf(p1_32, vzero);
  HVX_Vector p1_64 = Q6_Vqf32_vmpy_Vqf32Vqf32(p1_32, p1_32);

根据 x0exp/x1exp 的值选择对应幂次：

  // 如果 xexp == 1 << 23，选择 p^2。
  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c1w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c1w);
  p0 = Q6_V_vmux_QVV(q0, p0_2, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_2, p1);

  // 如果 xexp == 2 << 23，选择 p^4。
  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c2w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c2w);
  p0 = Q6_V_vmux_QVV(q0, p0_4, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_4, p1);

  // 后面依次选择 p^8、p^16、p^32。
  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c3w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c3w);
  p0 = Q6_V_vmux_QVV(q0, p0_8, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_8, p1);

  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c4w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c4w);
  p0 = Q6_V_vmux_QVV(q0, p0_16, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_16, p1);

  q0 = Q6_Q_vcmp_eq_VwVw(x0exp, c5w);
  q1 = Q6_Q_vcmp_eq_VwVw(x1exp, c5w);
  p0 = Q6_V_vmux_QVV(q0, p0_32, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_32, p1);

  // 如果指数差值更大，选择 p^64。
  q0 = Q6_Q_vcmp_gt_VwVw(x0exp, c5w);
  q1 = Q6_Q_vcmp_gt_VwVw(x1exp, c5w);
  p0 = Q6_V_vmux_QVV(q0, p0_64, p0);
  p1 = Q6_V_vmux_QVV(q1, p1_64, p1);

最后把这一轮的未归一化 exp 写到 pout，并累加到 vsumf：

  if (d >= 64) {
    // p0/p1 合成一个 vector pair，转成 fp16 后写到 pout。
    // 注意：这里的 pout 暂时保存的是未归一化 exp，不是最终 softmax。
    p10 = Q6_W_vcombine_VV(p1, p0);
    q6op_vstu_AV(optr, Q6_Vhf_equals_Wqf32(p10));
    optr++;

    // 累加 softmax 分母。
    vsumf = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p0);
    vsumf = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p1);
  } else {
    // 尾部不足 64 个 fp16 时，用 predicate 清掉无效 lane。
    // 这里 qf32 每个 lane 是 4 字节，所以 mask 长度乘 4。
    HVX_VectorPred Q0 = Q6_Q_vsetq2_R(4 * (((d & 63) + 1) / 2));
    HVX_VectorPred Q1 = Q6_Q_vsetq2_R(4 * (((d & 63) + 0) / 2));
    p0                = Q6_V_vmux_QVV(Q0, p0, vzero);
    p1                = Q6_V_vmux_QVV(Q1, p1, vzero);

    // 只累加有效 lane。
    vsumf             = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p0);
    vsumf             = Q6_Vqf32_vadd_Vqf32Vqf32(vsumf, p1);

    // 只写回有效 fp16 元素。
    p10               = Q6_W_vcombine_VV(p1, p0);
    q6op_vstu_variable_ARV(optr, 2 * (d & 63), Q6_Vhf_equals_Wqf32(p10));
    optr++;
  }
}

1.5.4 sum 并归一化

源码第 287 到 292 行把 vsumf 横向归约，得到整段 softmax 的分母：

// vsumf 是 vector 形式的部分和。这里把 vector 内所有 lane 继续横向相加。
for (int i = 0, nshift = 4; i < 5; i++) {
  HVX_VectorPair temps = Q6_W_vshuff_VVR(vsumf, vsumf, nshift);
  vsumf                = Q6_Vqf32_vadd_Vqf32Vqf32(Q6_V_lo_W(temps), Q6_V_hi_W(temps));
  nshift <<= 1;
}

// 转成 scalar float 格式，便于从 lane 0 取出。
vsumf = Q6_Vsf_equals_Vqf32(vsumf);

第 295 到 297 行取出 sum 并求倒数：

// 横向归约后，每个 lane 都等价地携带总和；取 lane 0 即可。
sum.i = Q6_R_vextract_VR(vsumf, 0);
sum_recip.f = 1.0f / sum.f;

// 把 1/sum 广播成 vector，后面逐元素乘。
HVX_Vector vrecip = Q6_Vqf32_vadd_VsfVsf(Q6_V_vsplat_R(sum_recip.i), vzero);
HVX_Vector *ioptr = (HVX_Vector *)pout;

第 300 到 314 行第二次遍历输出 buffer，把前面暂存的 exp 乘以 1 / sum。这里的输入和输出都是 pout，相当于原地归一化：

// 处理完整的 64 个 fp16 block。
for (int d = length; d > 63; d -= 64) {
  // 从 pout 读取前一节暂存的未归一化 exp，并扩展到 qf32。
  HVX_VectorPair xx = Q6_Wqf32_vmpy_VhfVhf(vmemu(&ioptr[0]), voneh);

  // lo/hi 两半分别乘以 1/sum。
  HVX_Vector xl =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_lo_W(xx), vzero), vrecip);
  HVX_Vector xh =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_hi_W(xx), vzero), vrecip);

  // 合并并转回 fp16，写回最终 softmax 输出。
  xx = Q6_W_vcombine_VV(xh, xl);
  q6op_vstu_AV(ioptr, Q6_Vhf_equals_Wqf32(xx));
  ioptr++;
}

// 处理尾部不足 64 个 fp16 的 block。
if ((length & 63) != 0) {
  HVX_VectorPair xx = Q6_Wqf32_vmpy_VhfVhf(vmemu(&ioptr[0]), voneh);
  HVX_Vector xl =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_lo_W(xx), vzero), vrecip);
  HVX_Vector xh =
      Q6_Vqf32_vmpy_Vqf32Vqf32(Q6_Vqf32_vadd_Vqf32Vsf(Q6_V_hi_W(xx), vzero), vrecip);

  xx = Q6_W_vcombine_VV(xh, xl);

  // 只写回有效的 fp16 元素。
  q6op_vstu_variable_ARV(ioptr, (length & 63) * 2, Q6_Vhf_equals_Wqf32(xx));
}

这一步对应：

$$ out_i = \frac{\exp(scale \cdot (x_i - max))}{\sum_j \exp(scale \cdot (x_j - max))} $$

1.5.5 `softmax_fp_impl()`

源码第 318 到 333 行是 Softmax_fp 的外层调度函数。它本身不写 HVX 计算细节，只负责按 [B, H, W] 遍历，把每段最后一维切片交给 softmax_hf_approx()：

template <typename OutTtype, typename InTtype>
int softmax_fp_impl(OutTtype &out, const InTtype &in, const Tensor &beta) {
  // 输出 shape 与输入一致。
  out.set_dims(in);

  // 示例实现按 4D tensor 处理：[B, H, W, D]。
  // softmax 固定沿最后一维 D 做。
  auto [b_in, h_in, w_in, d_in] = in.dims();

  // beta 是 softmax 的指数缩放参数。
  // interface_scale 是输入 tensor 接口层的 scale，这里合进总 scale。
  float scale = in.interface_scale() * beta(0, 0, 0, 0);

  // 外层 B/H/W 逐切片遍历。
  // 每个切片是一段连续的 D 维 fp16 数据。
  for (Idx b = 0; b < b_in; b++) {
    for (Idx h = 0; h < h_in; h++) {
      for (Idx w = 0; w < w_in; w++) {
        using T                               = typename InTtype::element_type;

        // 当前 [b, h, w, :] 的输入首地址。
        const T *pin                          = &in.get_raw(b, h, w, 0);

        // 当前 [b, h, w, :] 的输出首地址。
        typename OutTtype::element_type *pout = &out.get_raw(b, h, w, 0);

        // 对最后一维做 softmax。
        softmax_hf_approx(pout, pin, scale, d_in);
      }
    }
  }
  return GraphStatus::Success;
}

也就是说，这个示例的 Softmax_fp 固定做最后一维 softmax；axis 在前面的优化规则里已经被规整掉了。

1.6 reference 版本

源码第 337 到 367 行是普通 C++ 版本：

template <typename Ttype>
int softmax_impl(Ttype &out, const Ttype &in, const float beta) {
  // debuglog("reference softmax (%s)", __PRETTY_FUNCTION__);
  out.set_dims(in);
  // 示例实现按 4D tensor 处理：[B, H, W, D]。
  auto [b_in, h_in, w_in, d_in] = in.dims();
  for (Idx b = 0; b < b_in; b++) {
    for (Idx h = 0; h < h_in; h++) {
      for (Idx w = 0; w < w_in; w++) {
        float max = in(b, h, w, 0);
        // 先找最大值，保证数值稳定。
        for (Idx d = 0; d < d_in; d++) {
          float const inval = in(b, h, w, d);
          max               = fmaxf(inval, max);
        }
        float sum = 0;
        // 计算未归一化的 exp 并且求和
        for (Idx d = 0; d < d_in; d++) {
          float const inval = in(b, h, w, d);
          sum += (out(b, h, w, d) = expf(beta * (inval - max)));
        }
        float const sum_recip = 1.0f / sum;
        // 归一化
        for (Idx d = 0; d < d_in; d++) {
          float const outval = out(b, h, w, d);
          out(b, h, w, d)    = outval * sum_recip;
        }
      }
    }
  }
  return GraphStatus::Success;
}

先找最大值
计算 exp(beta * (x - max))
求和
除以 sum

softmaxWithbetaWrapper() 只是把 Tensor beta 里的第一个 scalar 取出来，再调用这个 reference 实现。

2. `Q6_Vqf32_vmpy_Vqf32Vqf32` 等类型

这不是 QNN API，也不是 C++ 标准库函数。它是 Qualcomm Hexagon/HVX intrinsic。

可以按名字拆：

Q6_ Vqf32 _vmpy_ Vqf32 Vqf32
|   |       |      |     |
|   |       |      |     +-- 第二个输入类型：qf32 vector
|   |       |      +-------- 第一个输入类型：qf32 vector
|   |       +--------------- 操作：vector multiply
|   +----------------------- 返回类型：qf32 vector
+--------------------------- Hexagon Q6 intrinsic 前缀

这里几个缩写大致这样读：

片段	含义
`Q6`	Hexagon Q6 intrinsic 前缀
`V`	HVX vector
`W`	HVX vector pair
`R`	scalar register
`Q`	predicate/mask
`vmpy`	vector multiply
`vadd`	vector add
`Vhf`	vector half-float
`Vqf32`	vector qfloat32/内部扩展浮点表示
`Vsf`	vector single-float

所以在这份 softmax 里，Q6_Vqf32_vmpy_Vqf32Vqf32(a, b) 主要出现在三类地方：

把 (x - max) 乘以 beta 缩放。
多项式近似里做乘法。
最后把未归一化输出乘以 1 / sum。

直觉上可以把它当成：

1
2

for each lane:
  out[i] = a[i] * b[i]

但它的真实数据格式、lane 数、舍入行为、饱和行为要以 Hexagon intrinsic 文档为准。

QNN MatMul 权重静态化与输入化

Mon, 27 Apr 2026 10:00:00 +0800

QNN MatMul 权重静态化与输入化

MatMul 里，把矩阵权重做成 QNN_TENSOR_TYPE_STATIC，和把权重做成 QNN_TENSOR_TYPE_APP_WRITE的区别：

纯图拓扑几乎不变，变的是图里携带的数据和运行时绑定方式。
如果看上下文缓存、模型库或打包后的 so 体积，静态权重通常更大。
如果看 NPU 上多次重复推理的执行时间，静态权重通常更容易快。

1. 两种写法

在 QNN 环境里，MatMul 可以写成两种方式：

// 静态权重
Qnn_Tensor_t weightTensor = makeTensor("weight",
                                      QNN_TENSOR_TYPE_STATIC,
                                      QNN_DATATYPE_FLOAT_32,
                                      weightDims.data(),
                                      kTensorRank,
                                      weightData.data(),
                                      static_cast<uint32_t>(weightData.size() * sizeof(float)));

// 权重输入
Qnn_Tensor_t weightTensor = makeTensor("weight",
                                      QNN_TENSOR_TYPE_APP_WRITE,
                                      QNN_DATATYPE_FLOAT_32,
                                      weightDims.data(),
                                      kTensorRank,
                                      nullptr,
                                      0);

两种方式的异同主要体现在：

MatMul 的节点数和边数不变。
生成出来的模型库、上下文二进制、或者打包后的 so 体积，静态权重会明显更大。
运行时输入列表里，输入化权重会多一份外部输入。

计算时间： 静态权重可以让后端提前看到常量值，很多后端会在 finalize 或编译阶段做常量相关处理，比如预打包、布局转换、融合和缓存。

build/finalize 可能更慢
上下文缓存可能更大
这部分成本通常只付一次

图大小： 输入权重每次都要作为 graph input 绑定和传输，静态权重则直接复用后端已经接收和准备好的常量。所以在重复推理场景里，静态权重速度更占优：

少一次大块权重输入
少一次权重 buffer 绑定/校验
少一次 host 到 NPU 侧的数据准备机会
更容易命中后端内部的权重布局缓存

如果权重特别大，这个差距会更明显。

2. 在线构图bench

源码放在：

`1`	`blog/qnn-matmul-weight-static/weight_static_benchmark.cpp`

它在同一个进程里构建两张 MatMul 图，分别是：

static：weight 是 QNN_TENSOR_TYPE_STATIC，构图时权重数据直接挂在张量里。
app_write：weight 是 QNN_TENSOR_TYPE_APP_WRITE，构图时权重张量不带数据；每轮执行时把权重数据作为输入传进去。

两张图使用同样的 M/K/N、同样的输入数据、同样的权重数据和同一个 HTP backend。输出表里重点看这些列：

precision：本轮测试的张量精度，支持 fp32/fp16/int8/int16。
ctx_bin(MB)：QnnContext_getBinarySize() 返回的上下文缓存大小，按 1024 * 1024 转成 MB 显示。
static(MB)：注册到图里的静态权重 payload 大小，按 MB 显示。
runtime(MB)：每次执行需要从应用侧传入的输入大小，按 MB 显示。
final(ms)：QnnGraph_finalize() 耗时。
first(ms)：第一次 QnnGraph_execute() 耗时。
exec(ms)：多轮 QnnGraph_execute() 的均值和标准差。
precision_error_summary：按精度汇总所有 OK case 的误差；max_err 是该精度下最大的最大误差，avg_mean_err 是该精度下 mean_err 的平均值。

每个 precision + weight_mode 会单独跑一行。benchmark 默认测试：

`1`	`fp32,fp16,int8,int16`

如果只想跑某些精度，用：

`1`	`--precisions fp16,int8,int16`

2.1 编译

这个 benchmark 由仓库根目录的 CMakeLists.txt 统一管理, Android 交叉编译:

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28

cmake --build build --target qnn_weight_static_benchmark -j4

2.2 推送到设备

把 benchmark、HTP 后端库和 C++ runtime 推到设备：

export DEVICE_ROOT=/data/local/tmp/qnn_matmul_weight_static
adb -s 127.0.0.1:40404 shell "mkdir -p $DEVICE_ROOT"

adb -s 127.0.0.1:40404 push \
  build/qnn_weight_static_benchmark \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $DEVICE_ROOT/

如果你的 SoC 不是 v79，需要把 libQnnHtpV79Stub.so 和 lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so 换成对应架构。

在 HTP/NPU 后端（SM8750 / HTP v79 上执行：）运行：

adb -s 127.0.0.1:40404 shell "
  cd /data/local/tmp/qnn_matmul_weight_static && \
  export LD_LIBRARY_PATH=\$PWD && \
  export ADSP_LIBRARY_PATH=\$PWD && \
  ./qnn_weight_static_benchmark \
    --backend ./libQnnHtp.so \
    --m 512 --k 2048 --n 2048 \
    --warmup 3 --iters 5 \
    --precisions fp32,fp16,int8,int16
"
# --m 512 --k 2048 --n 6144 \
# --m 512 --k 6144 --n 2048 \
# --m 512 --k 2048 --n 2048 \
# --m 1 --k 151936 --n 2048 \

输出结构如下。下面这份是 SM8750 / HTP v79 上的小矩阵 smoke test；这个 runtime 接受了 fp32 的 QNN API 张量配置，但这不等价于 HTP 内部在做原生 FP32 MatMul。

QNN MatMul Weight Static Benchmark
backend_path : ./libQnnHtp.so
backend_kind : NPU
htp_soc_model: 69
htp_arch     : 79
shape        : A[512, 2048] x B[2048, 6144] -> C[512, 6144]
warmup       : 3
iterations   : 5

precision weight     status             valid       ctx(ms)     build(ms)     final(ms)     first(ms)          exec(ms)      free(ms)    ctx_bin(MB)     static(MB)    runtime(MB)       max_err      mean_err
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
fp32      static     OK                  PASS        0.0292       85.0602      545.1886       10.1046    6.0671±0.8934       24.0706         4.3086        48.0000         4.0000        0.0026        0.0007
fp32      app_write  OK                  PASS        0.0377        0.4305      396.2505       52.3059   38.2210±2.6300       36.8942         0.2852         0.0000        52.0000        0.0026        0.0007
fp16      static     OK                  PASS        0.0377       14.0695      139.9085        7.3569    4.8455±0.0422       24.6860         4.3008        24.0000         2.0000        0.0026        0.0007
fp16      app_write  OK                  PASS        0.0391        0.3680     4126.0704       28.9443   23.9732±1.2695       52.0595         0.5664         0.0000        26.0000        0.0026        0.0007
int8      static     OK                  FAIL        0.0661        9.2544     1559.6377       16.3176   18.0157±5.1124       32.5441         8.6641        12.0000         1.0000        6.7834        2.2220
int8      app_write  OK                  FAIL        0.0447        0.3903      529.9657       35.4261   26.7496±4.7284       36.0866         0.3633         0.0000        13.0000        6.7834        2.2220
int16     static     OK                  PASS        0.0375       13.8047      482.1438       25.6598   22.8528±3.7121       28.8608         4.4336        24.0000         2.0000        0.0071        0.0027
int16     app_write  OK                  PASS        0.0357        0.4098     2056.0973       99.2368 122.3321±13.6945       63.8079         1.2305         0.0000        26.0000        0.0141        0.0054

context_binary_status
  fp32      static     ok
  fp32      app_write  ok
  fp16      static     ok
  fp16      app_write  ok
  int8      static     ok
  int8      app_write  ok
  int16     static     ok
  int16     app_write  ok

precision_error_summary
precision      cases       max_err      avg_mean_err
----------------------------------------------------
fp32              2        0.0026            0.0007
fp16              2        0.0026            0.0007
int8              2        6.7834            2.2220
int16             2        0.0141            0.0041

QNN MatMul Weight Static Benchmark
backend_path : ./libQnnHtp.so
backend_kind : NPU
htp_soc_model: 69
htp_arch     : 79
shape        : A[512, 6144] x B[6144, 2048] -> C[512, 2048]
warmup       : 3
iterations   : 5

precision weight     status             valid       ctx(ms)     build(ms)     final(ms)     first(ms)          exec(ms)      free(ms)    ctx_bin(MB)     static(MB)    runtime(MB)       max_err      mean_err
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
fp32      static     OK                  PASS        0.0252       84.7228      715.4846       12.0498   11.9023±1.6982       31.6374        12.8633        48.0000        12.0000        0.0016        0.0005
fp32      app_write  OK                  PASS        0.0217        0.2437      196.9550       59.2926   39.9130±2.8257       20.9656         0.1562         0.0000        60.0000        0.0016        0.0005
fp16      static     OK                  PASS        0.0311       12.2270      196.3642       20.4973   10.8049±1.6617       26.2479        12.8047        24.0000         6.0000        0.0016        0.0005
fp16      app_write  OK                  PASS        0.0383        0.3783     2350.6353       45.8905   30.1110±6.5165       31.6772         0.2305         0.0000        30.0000        0.0016        0.0005
int8      static     OK                  PASS        0.0663        8.6619     1950.1152       32.4290   27.9270±8.7762       32.5944        12.2031        12.0000         3.0000        0.0351        0.0121
int8      app_write  OK                  PASS        0.0647        0.4667     8905.2090       39.7415   29.3041±6.1805       46.4648         0.5898         0.0000        15.0000        0.0351        0.0121
int16     static     OK                  PASS        0.0379       16.8233     1472.6296       45.7644   73.8026±4.9664       46.2043        13.2148        24.0000         6.0000        0.0071        0.0028
int16     app_write  OK                  PASS        0.0384        0.3794    16282.6409      247.3371 263.2424±21.9484      168.4643         7.4531         0.0000        30.0000        0.0140        0.0055

context_binary_status
  fp32      static     ok
  fp32      app_write  ok
  fp16      static     ok
  fp16      app_write  ok
  int8      static     ok
  int8      app_write  ok
  int16     static     ok
  int16     app_write  ok

precision_error_summary
precision      cases       max_err      avg_mean_err
----------------------------------------------------
fp32              2        0.0016            0.0005
fp16              2        0.0016            0.0005
int8              2        0.0351            0.0121
int16             2        0.0140            0.0042

3. 离线构图

前面的 benchmark 比较的是在线构图后的 STATIC 和 APP_WRITE。为了更接近部署场景，新加了一个独立程序：

`1`	`blog/qnn-matmul-weight-static/weight_switch_benchmark.cpp`

它默认尝试三种运行模式，输出里的 mode 名称简化成：

app_write：一张图，weight 是 QNN_TENSOR_TYPE_APP_WRITE；每轮执行前从磁盘读 input/weight 数据，再把当前权重作为第二个输入传给 QnnGraph_execute()。
static_load：每个权重编译一张 STATIC 图，导出 context binary 并写到磁盘；每轮执行前临时读取一个 binary，再做 contextCreateFromBinary + graphRetrieve + execute + free。
update_static(不支持暂时)：一张图，weight 是 QNN_TENSOR_TYPE_UPDATEABLE_STATIC；每轮执行前从磁盘读新权重，调用 QnnTensor_updateGraphTensors()，再 QnnGraph_finalize() 让更新生效，然后执行。

三种模式使用同样的 M/K/N、同样的输入数据、同样的权重数据和同一个 backend。程序会先为每个 shape + precision 生成公共 tensor/expected-output 文件，然后释放 fp32 参考数据和常驻权重 payload；各模式在计时路径里再按需从磁盘读取当前 input、weight、expected output 或 graph binary。这样可以避免测试时把所有权重和所有参考输出长期留在 CPU 内存里。

实际在 SM8750 / HTP v79 上测试时，update_static 的 UPDATEABLE_STATIC + updateGraphTensors + finalize 路径会被 HTP 拒绝，所以程序会把这一行标成 SKIP，并且不会因为这个已知不支持路径返回失败。输出表里重点看这些列：

precision：本轮测试的张量精度，默认是 fp16/int8/int16。
prep(ms)：模式自己的准备阶段耗时，包括构图、导出 binary 等一次性工作；公共 tensor/expected-output 文件生成在各 mode 计时前完成，不计入这一列，且不包含单独列出的 final(ms)。
ssd_d(ms)：每轮从磁盘读取 input/weight 数据的时间。
ssd_g(ms)：每轮从磁盘读取 graph binary 的时间；只有 static_load 会有这一列。
htp_w(ms)：把图或权重真正写入 backend 的时间；static_load 里是 contextCreateFromBinary + graphRetrieve，update_static 里是 updateGraphTensors + finalize。
final(ms)：构图后的首次 QnnGraph_finalize() 总耗时。
first(ms)：第一轮完整路径耗时。
exec(ms)：纯 QnnGraph_execute() 的均值和标准差。
binary(B)：导出的 context binary 总大小。
static(B)：静态权重占用的 payload 字节数。
runtime(B)：每轮执行时应用侧需要准备的输入字节数。
--m 512 --k 2048 --n 6144: 测试shape

3.1 编译

这个 benchmark 也由仓库根目录的 CMakeLists.txt 统一管理，Android 交叉编译：

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-28

cmake --build build --target qnn_weight_switch_benchmark -j4

3.2 推送到设备

把 benchmark、HTP 后端库和 C++ runtime 推到设备：

export DEVICE_ROOT=/data/local/tmp/qnn_static_binary_switch
adb -s 127.0.0.1:40404 shell "mkdir -p $DEVICE_ROOT"

adb -s 127.0.0.1:40404 push \
  build/qnn_weight_switch_benchmark \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $DEVICE_ROOT/

如果你的 SoC 不是 v79，需要把 libQnnHtpV79Stub.so 和 lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so 换成对应架构。

在 HTP/NPU 后端运行：

adb -s 127.0.0.1:40404 shell "
  cd /data/local/tmp/qnn_static_binary_switch && \
  export LD_LIBRARY_PATH=\$PWD && \
  export ADSP_LIBRARY_PATH=\$PWD && \
  ./qnn_weight_switch_benchmark \
    --backend ./libQnnHtp.so \
    --precisions fp16,int8,int16
"

这个程序默认只把结果打印到 stdout，不会额外写日志文件。只有显式传 --log <path> 时才会把同样的结果落盘。

程序运行过程中会为了测量切换开销，临时写出 input / weight / expected-output / static graph binary 等中间文件；正常退出或异常退出时都会自动清理这些本地临时文件，不会在当前目录长期残留。

QNN 文档

Fri, 17 Apr 2026 14:10:00 +0800

QNN 文档阅读

QNN SDK 的核心文档在目录 $QNN_SDK_ROOT/docs/QNN/ 下, 这里的 api-rst 和 OpDef 的核心文档在官网上没有。

OpDef： “算子定义和后端支持” 文档，包括 Op 在不同设备的支持性、约束等信息。
api-rst： “API 参考” 文档，包括各个 api 的参数、功能、返回值等细节。

1. OpDef

下面以 MatMul，介绍一下 OpDef 里都有什么内容，在主文档 $QNN_SDK_ROOT/docs/QNN/OpDef/MasterOpDef.html?highlight=matmul#matmul 中可以看到算子 MatMul 的定义和输入输出参数等信息，如下图。可以看到算子定义矩阵乘法为$C = A \times B + b$, 有额外参数 transpose_in0 和 transpose_in1，控制输入矩阵的转置方式，从而影响计算结果。

这里的输入参数的数据类型是后端特定的，而不同后端又有自己特定的文档描述算子的支持情况和约束条件，例如 HTP 后端的 MatMul 算子定义和约束条件可以在 $QNN_SDK_ROOT/docs/QNN/OpDef/HtpOpDefSupplement.html?highlight=matmul#matmul 看到。

1.1 数据结构

首先是输入输出的数据结构，如下图, 当前 HTP 后端支持的数据格式是 FP16/INT16/INT8，

1.2 约束说明

HTP 后端对 MatMul 计算的数据维度不超过5维，另外对于各个精度的输入输出也有不同的约束，具体可以看下图。

这里针对不同的输入有不同的量化限制

2. api-rst

以 QnnGraph_addNode 接口为例展开，可以通过搜索直接搜索 api 接口，如下接下来查看 QnnGraph_addNode 接口的定义，可以看到该接口的参数和返回值等信息，如下图, 其输入参数为图句柄 Qnn_GraphHandle_t 和节点信息结构体 Qnn_OpConfig_t，返回值为状态码 Qnn_ErrorHandle_t。可以继续深入，点击 Qnn_OpConfig_t 可以跳转到对应的结构体的定义，查看其字段信息，如下图, 该结构体包含了节点的版本和对应版本的结构体，当前只有 Qnn_OpConfig_v1_t 版本的字段信息。继续点击查看 Qnn_OpConfig_v1_t 结构体的定义，可以看到该结构体包含了节点的名称、算子名称、额外输入参数数量、额外输入参数信息(上面提到的 transpose_in0 和 transpose_in1 就是这个参数)、输入张量指针、输出张量指针等字段信息，如下图。可以继续向下追溯张量结构体的结构。

3. 量化

在算子定义中看到了量化方法的约束，接下来顺着 Qnn_TensorV1_t 张量分析量化方式，从下面入口查看 Qnn_QuantizeParams_t 量化参数的定义结构体包括定义方式、量化方式、量化参数，共有8中量化方式，包括缩放量化(Qnn_ScaleOffset_t)、零点量化(Qnn_AxisScaleOffset_t)等, 具体可以继续深入查看，例如 Qnn_AxisScaleOffset_t 结构体的定义如下图, 该结构体包含了量化轴、量化参数数量、缩放值与零点值等字段信息。继续深入可以看到量化公式$floatValue = (quantizedValue + offset) * scale$，如下图,

4. 数据类型

在算子定义中看到了数据类型的约束，但是查文档只能查到粗糙的枚举类型，没有具体刻画各个数据类型的细节，如下图

话又说回来了，这么大文档直接喂给 codex 查更方便，

Qnn_DataType_t 的分类定义在 /root/qairt/2.40.0.251030/include/QNN/QnnTypes.h:103：

INT_*: 有符号整数，精确整数语义

UINT_*: 无符号整数，精确整数语义

FLOAT_*: 浮点

SFIXED_POINT_*: 有符号定点/量化类型

UFIXED_POINT_*: 无符号定点/量化类型

BOOL_8

STRING

QNN 环境准备与 python实例

Wed, 01 Apr 2026 15:30:00 +0800

QNN 环境准备与 MatMul 端侧实例

这篇把 QNN 介绍和QNN实例里的在线构图执行方式通过QNN 提供的python工具链实现

执行环境如下
- 宿主机：Ubuntu 22.04 x86_64
- QNN SDK：2.40.0.251030, python 3.10 ABI
- Android NDK：android-ndk-r29
- SoC：SnapDragon 8 elite, Chip: SM8750, Hexagon Arch: v79
- Backend：CPU/GPU/HTP

1. 环境配置

使用 QNN 的 python 工具链，执行

cd /root/qairt/2.40.0.251030/bin # 根据实际路径修改
source envsetup.sh 

# 这会设置python环境变量，确保后续命令能找到正确的python依赖
➜  ✗ echo $PYTHONPATH    
/root/qairt/2.40.0.251030/lib/python/:/root/qairt/2.40.0.251030/benchmarks/QNN/

接下来的操作依赖pytorch包，通过脚本检查环境：

# 查看环境检查结果
➜  ✗ ${QAIRT_SDK_ROOT}/bin/envcheck -a
Checking Android NDK Environment
--------------------------------------------------------------
[INFO] Found ndk-build at /root/android-ndk/android-ndk-r29/ndk-build and ANDROID_NDK_ROOT is also set.
--------------------------------------------------------------

Checking Clang Environment
--------------------------------------------------------------
[INFO] Found clang++ at /usr/bin/clang++
--------------------------------------------------------------

Checking TensorFlow Environment
--------------------------------------------------------------
[ERROR] Unable to import tensorflow using python3.
--------------------------------------------------------------

Checking TFLite Environment
--------------------------------------------------------------
[ERROR] Unable to import tflite using python3.
--------------------------------------------------------------

Checking ONNX Environment
--------------------------------------------------------------
[ERROR] Unable to import onnx using python3.
--------------------------------------------------------------

Checking PyTorch Environment
--------------------------------------------------------------
PyTorch is set-up successfully
--------------------------------------------------------------

可以通过python虚拟环境管理包，依赖版本在官方文档标出

conda create -n qnn python=3.10 -y  # 创建python3.10的虚拟环境
conda activate qnn  # 激活虚拟环境
export UV_INDEX_URL=https://pypi.mirrors.ustc.edu.cn/simple/ # 设置国内镜像源
uv pip install torch==1.13.1

2. 执行流程

QNN 提供了从模型转换到设备执行的python全链路工具，流程如下：

宿主机环境
-> 生成 MatMul 计算图
-> 转成 QNN model.cpp/.bin
-> 生成 aarch64-android 模型库
-> 推到 Android 设备
-> 用 qnn-net-run 执行
-> 回拉输出并和 NumPy 基线对比

2.1 生成 MatMul 计算图

目前计算图最常用的是 ONNX 格式，下面的脚本使用pytorch生成一个最小的 MatMul 计算图并且导出。

from pathlib import Path

import numpy as np
import torch

root = Path("matmul-demo/model")
root.mkdir(parents=True, exist_ok=True)

# 设置随机数种子，确保每次生成的输入和权重都一样
rng = np.random.default_rng(0)
A = rng.normal(size=(1, 128)).astype(np.float32)
B = rng.normal(size=(128, 64)).astype(np.float32)
bias = rng.normal(size=(64,)).astype(np.float32)

# 定义 MatMul 模型
class MatMulModel(torch.nn.Module):
    def __init__(self, weight: np.ndarray, bias_value: np.ndarray):
        super().__init__()
        self.register_buffer("weight", torch.from_numpy(weight))
        self.register_buffer("bias", torch.from_numpy(bias_value))

    def forward(self, x):
        return torch.matmul(x, self.weight) + self.bias

model = MatMulModel(B, bias).eval()
input_tensor = torch.from_numpy(A)

with torch.no_grad():
    Y = model(input_tensor).cpu().numpy()
# 导出 ONNX 模型
torch.onnx.export(
    model,
    input_tensor,
    str(root / "matmul.onnx"),
    input_names=["A"],
    output_names=["Y"],
    opset_version=13,
    do_constant_folding=False,
)
# 保存输入和参考输出
A.tofile(root / "input.raw")
np.save(root / "reference.npy", Y)
(root / "input_list.txt").write_text(str((root / "input.raw").resolve()) + "\n")

2.2 转成 QNN 计算图格式

1
2
3

$QNN_SDK_ROOT/bin/x86_64-linux-clang/qnn-onnx-converter \
  --input_network matmul-demo/model/matmul.onnx \
  --output_path matmul-demo/build/fp32/matmul_fp32.cpp

2.3 编译

$QNN_SDK_ROOT/bin/x86_64-linux-clang/qnn-model-lib-generator \
  -c matmul-demo/build/fp32/matmul_fp32.cpp \
  -b matmul-demo/build/fp32/matmul_fp32.bin \
  -t aarch64-android \
  -o matmul-demo/build/fp32/model_libs

2.4 执行

下面统一测试 fp32 精度，并分别在 CPU/GPU/NPU 三个后端执行。

首先推送需要的动态库、执行文件、模型库和输入数据到设备：

export DEVICE_ROOT=/data/local/tmp/qnn_matmul
adb -s 127.0.0.1:40404 shell "mkdir -p $DEVICE_ROOT/cpu $DEVICE_ROOT/gpu $DEVICE_ROOT/npu"

adb -s 127.0.0.1:40404 push \
  $QNN_SDK_ROOT/bin/aarch64-android/qnn-net-run \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnCpu.so \
  matmul-demo/build/fp32/model_libs/aarch64-android/libmatmul_fp32.so \
  matmul-demo/model/input.raw \
  $DEVICE_ROOT/cpu/

adb -s 127.0.0.1:40404 push \
  $QNN_SDK_ROOT/bin/aarch64-android/qnn-net-run \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnGpu.so \
  matmul-demo/build/fp32/model_libs/aarch64-android/libmatmul_fp32.so \
  matmul-demo/model/input.raw \
  $DEVICE_ROOT/gpu/

adb -s 127.0.0.1:40404 push \
  $QNN_SDK_ROOT/bin/aarch64-android/qnn-net-run \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  matmul-demo/build/fp32/model_libs/aarch64-android/libmatmul_fp32.so \
  matmul-demo/model/input.raw \
  $DEVICE_ROOT/npu/

# 准备输入列表
adb -s 127.0.0.1:40404 shell "cd $DEVICE_ROOT/cpu && printf '%s\n' input.raw > input_list.txt"
adb -s 127.0.0.1:40404 shell "cd $DEVICE_ROOT/gpu && printf '%s\n' input.raw > input_list.txt"
adb -s 127.0.0.1:40404 shell "cd $DEVICE_ROOT/npu && printf '%s\n' input.raw > input_list.txt"

然后分别执行三组测试。

CPU：

adb -s 127.0.0.1:40404 shell "
  cd $DEVICE_ROOT/cpu && \
  export LD_LIBRARY_PATH=$DEVICE_ROOT/cpu && \
  ./qnn-net-run \
    --model libmatmul_fp32.so \
    --backend libQnnCpu.so \
    --input_list input_list.txt \
    --output_dir output
"

GPU：

adb -s 127.0.0.1:40404 shell "
  cd $DEVICE_ROOT/gpu && \
  export LD_LIBRARY_PATH=$DEVICE_ROOT/gpu && \
  ./qnn-net-run \
    --model libmatmul_fp32.so \
    --backend libQnnGpu.so \
    --input_list input_list.txt \
    --output_dir output
"

NPU：

adb -s 127.0.0.1:40404 shell "
  cd $DEVICE_ROOT/npu && \
  export LD_LIBRARY_PATH=$DEVICE_ROOT/npu && \
  export ADSP_LIBRARY_PATH=$DEVICE_ROOT/npu && \
  ./qnn-net-run \
    --model libmatmul_fp32.so \
    --backend libQnnHtp.so \
    --input_list input_list.txt \
    --output_dir output
"

2.5. 验证输出

分别回拉 CPU/GPU/NPU 三组输出：

mkdir -p matmul-demo/device/{cpu,gpu,npu}
adb -s 127.0.0.1:40404 pull $DEVICE_ROOT/cpu/output matmul-demo/device/cpu
adb -s 127.0.0.1:40404 pull $DEVICE_ROOT/gpu/output matmul-demo/device/gpu
adb -s 127.0.0.1:40404 pull $DEVICE_ROOT/npu/output matmul-demo/device/npu

然后做一个简单对比：

from pathlib import Path
import numpy as np

ref = np.load("matmul-demo/model/reference.npy").reshape(-1)

for name, atol in [("cpu", 1e-6), ("gpu", 1e-5), ("npu", 1e-4)]:
    out_path = next(Path(f"matmul-demo/device/{name}/output").rglob("*.raw"))
    out = np.fromfile(out_path, dtype=np.float32).reshape(-1)
    max_abs_err = np.max(np.abs(out - ref))
    mean_abs_err = np.mean(np.abs(out - ref))
    is_close = np.allclose(out, ref, atol=atol, rtol=0.0)
    print(
        name,
        "pass=",
        is_close,
        "atol=",
        atol,
        "max_abs_err=",
        max_abs_err,
        "mean_abs_err=",
        mean_abs_err,
    )

测试结果如下，误差npu最大：

1
2
3

cpu pass= False atol= 1e-06 max_abs_err= 4.7683716e-06 mean_abs_err= 1.2996607e-06
gpu pass= True atol= 1e-05 max_abs_err= 5.722046e-06 mean_abs_err= 1.6018748e-06
npu pass= False atol= 0.0001 max_abs_err= 0.009534836 mean_abs_err= 0.0027581714

通过该工具链可以把torch模型导出onnx算子图，转换编译并使用qnn-net-run在端侧npu上使用，缺点是灵活度不够

QNN 环境准备与实例

Wed, 01 Apr 2026 15:30:00 +0800

QNN 环境准备与在线构图 MatMul 示例

这篇把 QNN 介绍里的在线构图执行方式整理成一个最小 C++ 示例，并且把同一份代码在CPU、 GPU、HTP 上跑通。

执行环境如下
- 宿主机：Ubuntu 22.04 x86_64
- QNN SDK：2.40.0.251030
- Android NDK：android-ndk-r29
- SoC：SnapDragon 8 elite, Chip: SM8750, Hexagon Arch: v79
- Backend：CPU/GPU/HTP

1. 环境配置

QNN 开发需要在有 QNN SDK 的宿主机（Host Device）开发，编译等完成后推送到有高通硬件的目标机器（Target Device）上运行，大致如下图。

图 1. QNN 宿主机与目标设备开发流程。

1.1 QNN 环境配置

方式一: 下载解压QNN SDK：在 QNN SDK 网站可以直接通过 Get Software 下载最新版的 QNN SDK。如果需要旧版本，需要注册高通账号，在 Qualcomm® software center 中找对应版本下载。 图 2. QNN SDK 下载页面。 部分受限的高通软件/工具需要向高通销售团队 申请访问权限。
- 找个路径解压 SDK, 获得一个类似 /root/qairt/2.40.0.251030 的路径
- 配置环境变量：cd /root/qairt/2.40.0.251030/bin && source envsetup.sh 包括了 QNN_SDK_ROOT 环境变量和一些工具链路径，配置在 ~/.bashrc 或者 ~/.zshrc 里会更方便一些。
- 安装依赖：sudo /root/qairt/2.40.0.251030/bin/check-linux-dependency.sh
- 检查环境：/root/qairt/2.40.0.251030/bin/envcheck -c
- 后续 python 需要使用给定的依赖版本

方式二: qsc安装:Qualcomm Software Center有cli版本供linux环境安装,

# 下载安装
➜ curl -L https://softwarecenter.qualcomm.com/api/download/software/tools/Qualcomm_Software_Center/Linux/Debian/latest.deb -o qsc_installer.deb
➜ sudo apt install ./qsc_installer.deb

# 登录
➜ qsc-cli login -u <your username>
➜ qsc-cli sdk --help
Usage: qsc-cli sdk [options] [command]

Sdk workflows

Options:
  -h,--help            Display help for this command

Commands:
  license              Activate, deactivate, or list sdk licenses
  download [options]   Download a sdk or its release notes
  install [options]    Install a sdk
  uninstall [options]  Uninstall the currently installed sdk
  info [options]       Show information for available or installed sdks

Refer to "qsc-cli sdk <command> --help" for more details and sample usage

➜ qsc-cli sdk info # 查看可用的SDK列表
[Info]: Starting qsc-cli version 1.26.6...
Audio1.x
HexagonSDK4.x
HexagonSDK5.x
HexagonSDK6.x
LPAI
qualcomm_ai_engine_direct
Qualcomm_AI_Runtime_Community
Qualcomm_AI_Runtime_SDK
Qualcomm_Aware_Location_Android_LocationProvider
Qualcomm_Aware_Location_Android_SDK
Qualcomm_Aware_Location_Embedded_Client
Qualcomm_Aware_Location_Evaluation_Tools
Qualcomm_Aware_Location_Native_SDK
Qualcomm_IRF_SDK
Qualcomm_IRP_SDK
qualcomm_neural_processing_sdk
qualcomm_neural_processing_sdk_public
QualcommSimulationPlatformSDK

# 查看sdk使用命令 
➜  ~ qsc-cli sdk info --help
Usage: qsc-cli sdk info [options]

Show information for available or installed sdks

Options:
  -n, --name <string>  Name of the sdk
  -c, --components     Display components information
  --json               Display information in JSON format
  --installed          Display only installed sdks information
  --latest-version     Display only latest available version
  -h,--help            Display help for this command

Example command to display all sdks: qsc-cli sdk info

Example command: qsc-cli sdk info --name <string> --latest-version

Example command: qsc-cli sdk info --name <string> --components --installed --json

➜  ~ qsc-cli sdk info -n Qualcomm_AI_Runtime_SDK # 查看可安装版本
[Info]: Starting qsc-cli version 1.26.6...


Name                   : Qualcomm_AI_Runtime_SDK
Installed version      : None
Available version(s)   : 2.45.40.260406
                        2.45.1.260416
                        2.45.0.260326
                        2.44.0.260225
                        2.43.1.260218
                        2.43.0.260128
                        2.42.0.251225
                        2.41.0.251128
                        2.40.1.251119
                        2.40.0.251030
                        2.39.3.251009
                        2.39.0.250926
                        2.38.1.251113
                        2.38.0.250901
                        2.37.1.250807
                        2.37.0.250724
                        2.36.4.250725
                        2.36.3.250722
                        2.36.1.250708
                        2.36.0.250627
                        2.35.6.250717
                        2.35.3.250617
                        2.35.0.250530
                        2.34.2.250528
                        2.34.1.250516
                        2.34.0.250424
                        2.33.2.250410
                        2.33.0.250327
                        2.32.6.250402
                        2.32.0.250228

➜ qsc-cli sdk install --help # 查看安装SDK的命令和参数
Usage: qsc-cli sdk install [options]

Install a sdk

Options:
  -n, --name <string>               Name of the sdk
  --activate-default-license        Activate default license before installation
  -rv, --required-version <string>  Preferred version
  --config <string>                 Configuration file or settings to use during install
  --path <path>                     Preferred install path
  -f, --force                       Force installation despite script or add-on errors
  -s, --silent                      Install sdk silently without any user prompts
  -h,--help                         Display help for this command

Example command: qsc-cli sdk install --name <string> --required-version <string> --config <string> --silent --force --activate-default-license

➜ qsc-cli sdk install -n Qualcomm_AI_Runtime_SDK --path /root/QNN -rv 2.40.0.251030 # 安装指定版本的QNN SDK到/root/QNN目录
[Info]: Starting qsc-cli version 1.26.6...
[Info] : Downloading package file for product Qualcomm_AI_Runtime_SDK for version 2.40.0.251030
[Info] : Downloading... 100%
[Info] : Downloaded package file to /tmp/QIKCache/88f4a6db-ddff-11ef-9172-02ddcb07e973/8f369776-b87d-11f0-ae67-064291a33d05/Qualcomm_AI_Runtime_SDK.2.40.0.251030.Linux-AnyCPU.qik

Access to and use of tools managed by the Qualcomm Package Manager are subject to the terms and conditions of the corresponding agreement(s) in place with Qualcomm Technologies, Inc. or its affiliates.
Unauthorized access or use is prohibited. Information such as tool version, operating system, user ID, company ID, IP address, computer mac address, date, timestamp, or features and functions of our tools that you use may be collected for internal business purposes or tool improvements and is subject to the Qualcomm Privacy Policy [http://www.qualcomm.com/site/privacy].
By accessing or using this tool, you agree to the foregoing.
Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. All rights reserved.


Accept and continue with installation [y/n] : y

[Warning] : Qualcomm_AI_Runtime_SDK is of the ExtractOnly type. The install command will automatically perform the extraction
[Info] : Step 1 of 7: Checking environment
[Info] : Step 2 of 7: Checking previous version
[Info] : Step 3 of 7: Checking dependencies
[Info] : Step 4 of 7: Preparing system
[Info] : Step 5 of 7: Extracting files
[Info] : Step 6 of 7: Configuring system
[Info] : Step 7 of 7: Finishing installation
[Info] : SUCCESS: Installed Qualcomm_AI_Runtime_SDK.Core at /root/QNN
[Info] : Log File Location: file:///var/tmp/qcom/qik/logs/462d10c5-b37e-4089-9e16-5056800f0869/qiktool.20260428.1.log

通过这个方式安装也需要自己设置环境变量，目录在/root/QNN/bin/envsetup.sh 这个路径是因为安装时指定了路径，这样激活的环境变量和前面略有不同，使用起来要注意，也可以自己设置相同名称的环境变量。

1.2 Android 交叉编译环境配置

步骤1：下载最新版软件包，获取地址（选择对应平台最新稳定版，点击后出现 “Android 软件开发套件许可协议”，勾选后鼠标右键下载按钮可以复制下载链接）

# 服务器端运行
# 到指定目录下载并解压 `android_ndk`
cd ~ && mkdir android_ndk && cd ~/android_ndk
wget https://googledownloads.cn/android/repository/android-ndk-r29-linux.zip
unzip android-ndk-r29-linux.zip # 这个文件名和下载的版本有关
# 删除压缩包
rm android-ndk-r29-linux.zip # 这个文件名和下载的版本有关

# 进入并记住解压后的目录
# 在目录里用 `pwd` 命令可以获取绝对路径
cd android-ndk-r29 # 这个目录和下载的版本有关，可以通过 `ls -lah` 显示目录

步骤2：配置环境变量

# 服务器端运行
# 通常会配置 `ANDROID_NDK_ROOT` 环境变量
# 但 `MNN` 中在 `project/android/build_64.sh` 使用的是 `$ANDROID_NDK` 环境变量，所以都设置一下
➜ export ANDROID_NDK="$HOME/android_ndk/android-ndk-r29" # 环境变量
➜ $ANDROID_NDK/ndk-build --version  # 验证环境变量
GNU Make 4.3
Built for x86_64-pc-linux-gnu
Copyright (C) 1988-2020 Free Software Foundation,  Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY,  to the extent permitted by law.

# 在命令行单次export只会在当前命令行有效 新开的终端不生效
# 需要把环境变量写到 `shell` 的配置文件中，`bash` 对应 `~/.bashrc`，`zsh` 对应 `~/.zshrc`
# !!注意这里重定向是重定向文件末尾 '>>' 符号
echo 'export ANDROID_NDK="$HOME/android_ndk/android-ndk-r29"' >> ~/.zshrc # 环境变量
echo 'export ANDROID_NDK_ROOT="$HOME/android_ndk/android-ndk-r29"'  >> ~/.zshrc # 环境变量
echo 'export PATH="$ANDROID_NDK:$PATH"' >> ~/.zshrc
# 验证
➜  ndk-build
Android NDK: Could not find application project directory !
Android NDK: Please define the NDK_PROJECT_PATH variable to point to it.
/root/android_ndk/android-ndk-r29/build/core/build-local.mk:151: *** Android NDK: Aborting    .  Stop.

2. 执行流程

下面的示例是计算$C = A \times B$，对应的执行链如下：

动态加载 `backend` 动态库
-> QnnInterface_getProviders()
-> QnnBackend_create()
-> QnnContext_create()
-> QnnGraph_create()
-> QnnTensor_createGraphTensor()
-> QnnGraph_addNode()
-> QnnGraph_finalize()
-> QnnGraph_execute()
-> 校验输出

对照执行流程图为： 图 3. QNN 在线构图执行流程。

2.1 初始化

下面例子调用的内置 MatMul 算子，无需注册自定义算子，所以初始化阶段相对简单，主要是创建上下文、设备、图等资源：

qnnInterface.logCreate(qnnLogCallback, logLevel, &logger);          // 注册log
qnnInterface.backendCreate(logger, nullptr, &backend);              // 创建backend
qnnInterface.deviceCreate(logger, configs, &device);                // 创建设备
qnnInterface.contextCreate(backend, device, nullptr, &context);     // 创建上下文
qnnInterface.graphCreate(context, "matmul_graph", nullptr, &graph); // 创建图

2.2 图构建

2.2.1 创建张量

在 QNN 图里，这三个张量分别对应：

A：QNN_TENSOR_TYPE_APP_WRITE
B：QNN_TENSOR_TYPE_STATIC
C：QNN_TENSOR_TYPE_APP_READ

    
// 构建测试数据和张量描述
constexpr uint32_t kRows      = 32;
constexpr uint32_t kInner     = 128;
constexpr uint32_t kCols      = 64;
constexpr uint32_t kTensorRank = 2;
std::vector<float> inputData  = makeInputData(kRows * kInner, 23, 11.0f);
std::vector<float> weightData = makeInputData(kInner * kCols, 17, 9.0f);
std::vector<float> outputData(kRows * kCols, std::numeric_limits<float>::quiet_NaN());

std::array<uint32_t, kTensorRank> inputDims  = {kRows, kInner};
std::array<uint32_t, kTensorRank> weightDims = {kInner, kCols};
std::array<uint32_t, kTensorRank> outputDims = {kRows, kCols};

// 创建tensor描述
Qnn_Tensor_t inputTensor = makeTensor("input",
                                      QNN_TENSOR_TYPE_APP_WRITE,
                                      QNN_DATATYPE_FLOAT_32,
                                      inputDims.data(),
                                      kTensorRank,
                                      nullptr,
                                      0);
Qnn_Tensor_t weightTensor = makeTensor("weight",
                                        QNN_TENSOR_TYPE_STATIC,
                                        QNN_DATATYPE_FLOAT_32,
                                        weightDims.data(),
                                        kTensorRank,
                                        weightData.data(),
                                        static_cast<uint32_t>(weightData.size() * sizeof(float)));
Qnn_Tensor_t outputTensor = makeTensor("output",
                                        QNN_TENSOR_TYPE_APP_READ,
                                        QNN_DATATYPE_FLOAT_32,
                                        outputDims.data(),
                                        kTensorRank,
                                        nullptr,
                                        0);

/* Tensor构造函数需要绑定多个config信息
  Qnn_Tensor_t makeTensor(const char* name,
                      Qnn_TensorType_t type,
                      Qnn_DataType_t dataType,
                      uint32_t* dimensions,
                      uint32_t rank,
                      void* data,
                      uint32_t dataSize) {
    Qnn_Tensor_t tensor = QNN_TENSOR_INIT;
    tensor.version      = QNN_TENSOR_VERSION_1; // 张量版本
    tensor.v1.name      = name;
    tensor.v1.type      = type;
    tensor.v1.dataFormat = QNN_TENSOR_DATA_FORMAT_FLAT_BUFFER; // 内存类型
    tensor.v1.dataType   = dataType;
    tensor.v1.rank       = rank; // 张量维度数量
    tensor.v1.dimensions = dimensions; // 张量维度信息
    tensor.v1.memType    = QNN_TENSORMEMTYPE_RAW; // 内存分配方式
    tensor.v1.clientBuf.data = data; // 这里的data是一个指针，指向实际的数据buffer
    tensor.v1.clientBuf.dataSize = dataSize; // buffer的大小，单位是字节
    return tensor;
  }
*/

// 把张量注册到图里
qnnInterface.tensorCreateGraphTensor(graph, &inputTensor);
qnnInterface.tensorCreateGraphTensor(graph, &weightTensor);
qnnInterface.tensorCreateGraphTensor(graph, &outputTensor);

Qnn_Tensor_t 是一个 union，底层可以使用 Qnn_TensorV1_t 或者 Qnn_TensorV2_t 两种版本的结构体来描述张量信息。
Qnn_TensorMemType_t 共有三种方式，QNN_TENSORMEMTYPE_RAW 提供原始指针，QNN_TENSORMEMTYPE_MEMHANDLE 提供内存对象，可以在 QNN 设备间内存共享，QNN_TENSORMEMTYPE_RETRIEVE_RAW 通过回调函数提供原始指针。
clientBuf 字段也是一个 union，还可以使用 memHandle 对应上面的内存对象。这里的 weight 张量是静态的，所以在注册的时候就把 data buffer 绑定上了；而 input 和 output 张量是动态的，可以先注册一个不带 data buffer 的描述，等到执行阶段再绑定真正的 buffer。

2.2.2 创建节点

节点定义也需要绑定很多信息：

// 目前只有v1版本
Qnn_OpConfig_t opConfig = QNN_OPCONFIG_INIT; 
opConfig.v1.name          = "matmul_0";
opConfig.v1.packageName   = QNN_OP_PACKAGE_NAME_QTI_AISW;
opConfig.v1.typeName      = QNN_OP_MAT_MUL;
opConfig.v1.numOfParams   = 0;       // 额外参数数量
opConfig.v1.params        = nullptr; // 额外参数数据
// 绑定输入输出张量
opConfig.v1.numOfInputs   = static_cast<uint32_t>(nodeInputs.size()); 
opConfig.v1.inputTensors  = nodeInputs.data();
opConfig.v1.numOfOutputs  = static_cast<uint32_t>(nodeOutputs.size());
opConfig.v1.outputTensors = nodeOutputs.data();

// 把节点加入图中
qnnInterface.graphAddNode(graph, opConfig);

2.4 完成构图并执行

完成构图后就可以执行图计算：

// 图构建完成后，调用 finalize 把图定型
qnnInterface.graphFinalize(graph, nullptr, nullptr);

// 构建执行张量，绑定真正的输入输出 buffer
Qnn_Tensor_t executeInput = makeExecuteTensor(
    inputTensor, inputData.data(), inputData.size() * sizeof(float));
Qnn_Tensor_t executeOutput = makeExecuteTensor(
    outputTensor, outputData.data(), outputData.size() * sizeof(float));

// 执行图计算
qnnInterface.graphExecute(graph,
                          &executeInput,
                          1,
                          &executeOutput,
                          1,
                          nullptr,
                          nullptr);

QnnTensor_createGraphTensor() 注册的是图里的张量元信息，不是这次执行的 I/O buffer。
真正的数据 buffer 是在 makeExecuteTensor() 之后、QnnGraph_execute() 之前才绑定进去的。

2.5 资源释放

逐步释放上下文等资源

qnnInterface.contextFree(context, nullptr);
qnnInterface.deviceFree(device);
qnnInterface.deviceFreePlatformInfo(logger, platformInfo);
qnnInterface.backendFree(backend);
qnnInterface.logFree(logger);

3. 构建

📦 先准备环境变量，通常只需要把 QNN_SDK_ROOT 指向 QNN SDK 路径就行了, 或者使用前面的 cd /root/qairt/2.40.0.251030/bin && source envsetup.sh 来加载一系列环境变量。保证echo $QNN_SDK_ROOT && echo ANDROID_NDK_ROOT能正确输出 SDK和NDK 路径。
🛠️ 交叉编译, 这里同时使用了 QNN SDK 和 Android NDK 的工具链文件。
📱 这里统一使用根目录 build/。host 和 Android 交叉编译都走这个目录，但切换 toolchain 前需要先清理旧缓存。

⚠️ shell 续行的反斜杠 \ 后面不要直接跟注释，否则后续 -D... 参数会被 shell 当成单独命令执行。

# 确保环境变量正常
# export QNN_SDK_ROOT=/root/qairt/2.40.0.251030
# export ANDROID_NDK_ROOT=/root/android-ndk/android-ndk-r29

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-31 \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

cmake --build build -j4 --target qnn_online_matmul

✅ 推送到手机的可执行文件应该来自当前 Android 配置的 build/，不能把宿主机 x86_64 产物直接推到 Android 设备上。
✅ 如果刚刚把 build/ 配成 host，再切到 Android，先删掉 build/CMakeCache.txt 或整个 build/ 再重新配置。

4. 目标设备运行

把依赖的动态库等文件推送给 adb 设备
运行时需要设置环境变量 LD_LIBRARY_PATH 指向动态库所在目录，ADSP_LIBRARY_PATH 指向 HTP 相关库所在目录（如果需要跑 HTP 的话），以保证动态库能被正确加载到内存里。

4.1 GPU 测试

QNN 默认的 GPU 后端是 Opencl，依赖部分动态库，需要推送 GPU 运行所需文件：

export GPU_DIR=/data/local/tmp/qnn_online_matmul_gpu # 设备侧的目录，可以根据需要修改
adb -s 127.0.0.1:40404 shell "mkdir -p $GPU_DIR"     # 这里的adb命令需要根据实际情况修改，确保能连接到目标设备

adb -s 127.0.0.1:40404 push \
  build/qnn_online_matmul \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnGpu.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $GPU_DIR/

执行设备侧的 GPU 测试：

> adb -s 127.0.0.1:40404 shell "
  cd $GPU_DIR && \
  export LD_LIBRARY_PATH=$GPU_DIR && \
  ./qnn_online_matmul ./libQnnGpu.so --dump-backend-info
"

Backend Info
backend_path  : ./libQnnGpu.so
backend_kind  : GPU
provider_count: 1
provider[0]
  backend_id        : 4 (GPU)
  provider_name     : GPU_QTI_AISW
  core_api_version  : 2.30.0
  backend_api_ver   : 3.12.0
  selected          : yes
selected_core_api   : 2.30.0
selected_backend_api: 3.12.0
backend_build_id: v2.40.0.251030114326_189385
api_entries
  propertyHasCapability             yes
  backendGetApiVersion              yes
  backendGetBuildId                 yes
  deviceCreate                      yes
  deviceGetPlatformInfo             yes
  contextCreate                     yes
  graphCreate                       yes
  tensorCreateGraphTensor           yes
  graphFinalize                     yes
  graphExecute                      yes
capabilities
  device_api_group                  supported
  backend_support_op_package        supported
  backend_support_composition       supported
  context_support_caching           supported
  graph_support_execute             supported
  graph_support_async_execution     not_supported
  graph_support_online_prepare      supported
  tensor_support_context_tensors    supported
  tensor_support_dynamic_dimensions not_supported
QNN online MatMul example
backend_path : ./libQnnGpu.so
backend_kind : GPU
tolerance    : 0.0001
shape        : A[32, 128] x B[128, 64] -> C[32, 64]
max_abs_err  : 0.00000119
mean_abs_err : 0.00000028
validation   : PASS
output[0:8]  : -1.58585858 1.19191921 0.87878758 -2.18181872 0.25252536 1.82828355 0.31313074 -0.17171730

Time Breakdown
stage                           time(us)
----------------------------------------
load_backend_library               15900
resolve_qnn_interface                  5
backend_create                     48781
dump_backend_info                     63
device_create                        268
context_create                        19
graph_create                          17
tensor_create                       2360
graph_add_node                        18
graph_finalize                    331536
graph_execute                        571
result_validate                       25

4.2 HTP 测试

推送 HTP 运行所需文件：

export HTP_DIR=/data/local/tmp/qnn_online_matmul_htp
adb -s 127.0.0.1:40404 shell "mkdir -p $HTP_DIR"

adb -s 127.0.0.1:40404 push \
  build/qnn_online_matmul \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $HTP_DIR/

执行设备侧的 HTP 测试：

adb -s 127.0.0.1:40404 shell "
  cd $HTP_DIR && \
  export LD_LIBRARY_PATH=$HTP_DIR && \
  export ADSP_LIBRARY_PATH=$HTP_DIR && \
  ./qnn_online_matmul ./libQnnHtp.so --dump-backend-info
"

Backend Info
backend_path  : ./libQnnHtp.so
backend_kind  : NPU
provider_count: 1
provider[0]
  backend_id        : 6 (HTP)
  provider_name     : HTP_QTI_AISW
  core_api_version  : 2.30.0
  backend_api_ver   : 5.40.0
  selected          : yes
selected_core_api   : 2.30.0
selected_backend_api: 5.40.0
backend_build_id: v2.40.0.251030114326_189385
api_entries
  propertyHasCapability             yes
  backendGetApiVersion              yes
  backendGetBuildId                 yes
  deviceCreate                      yes
  deviceGetPlatformInfo             yes
  contextCreate                     yes
  graphCreate                       yes
  tensorCreateGraphTensor           yes
  graphFinalize                     yes
  graphExecute                      yes
capabilities
  device_api_group                  supported
  backend_support_op_package        supported
  backend_support_composition       supported
  context_support_caching           supported
  graph_support_execute             supported
  graph_support_async_execution     not_supported
  graph_support_online_prepare      supported
  tensor_support_context_tensors    not_supported
  tensor_support_dynamic_dimensions supported
QNN online MatMul example
backend_path : ./libQnnHtp.so
backend_kind : NPU
htp_soc_model: 69
htp_arch     : 79
tolerance    : 0.005
shape        : A[32, 128] x B[128, 64] -> C[32, 64]
max_abs_err  : 0.00183558
mean_abs_err : 0.00050184
validation   : PASS
output[0:8]  : -1.58691406 1.19140625 0.87841797 -2.18164062 0.25244141 1.82910156 0.31274414 -0.17224121

Time Breakdown
stage                           time(us)
----------------------------------------
load_backend_library                 869
resolve_qnn_interface                  4
backend_create                       931
dump_backend_info                     63
device_create                     102422
context_create                        80
graph_create                      203671
tensor_create                         58
graph_add_node                        39
graph_finalize                      9320
graph_execute                       2531
result_validate                       64

如果你需要看更细的 backend 日志，可以额外加：

`1`	`export QNN_LOG_LEVEL=debug`

4.3 CPU 测试

推送 CPU 运行所需文件：

export CPU_DIR=/data/local/tmp/qnn_online_matmul_cpu
adb -s 127.0.0.1:40404 shell "mkdir -p $CPU_DIR"

adb -s 127.0.0.1:40404 push \
  build/qnn_online_matmul \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnCpu.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $CPU_DIR/

执行设备侧的 CPU 测试：

adb -s 127.0.0.1:40404 shell "
  cd $CPU_DIR && \
  export LD_LIBRARY_PATH=$CPU_DIR && \
  ./qnn_online_matmul ./libQnnCpu.so --dump-backend-info
"

Backend Info
backend_path  : ./libQnnCpu.so
backend_kind  : CPU
provider_count: 1
provider[0]
  backend_id        : 3 (CPU)
  provider_name     : CPU_QTI_AISW
  core_api_version  : 2.30.0
  backend_api_ver   : 1.1.0
  selected          : yes
selected_core_api   : 2.30.0
selected_backend_api: 1.1.0
backend_build_id: v2.40.0.251030114326_189385
api_entries
  propertyHasCapability             yes
  backendGetApiVersion              yes
  backendGetBuildId                 yes
  deviceCreate                      yes
  deviceGetPlatformInfo             yes
  contextCreate                     yes
  graphCreate                       yes
  tensorCreateGraphTensor           yes
  graphFinalize                     yes
  graphExecute                      yes
capabilities
  device_api_group                  not_supported
  backend_support_op_package        supported
  backend_support_composition       supported
  context_support_caching           supported
  graph_support_execute             supported
  graph_support_async_execution     not_supported
  graph_support_online_prepare      supported
  tensor_support_context_tensors    supported
  tensor_support_dynamic_dimensions supported
QNN online MatMul example
backend_path : ./libQnnCpu.so
backend_kind : CPU
tolerance    : 0.0001
shape        : A[32, 128] x B[128, 64] -> C[32, 64]
max_abs_err  : 0.00000000
mean_abs_err : 0.00000000
validation   : PASS
output[0:8]  : -1.58585882 1.19191945 0.87878734 -2.18181849 0.25252527 1.82828319 0.31313115 -0.17171681

Time Breakdown
stage                           time(us)
----------------------------------------
load_backend_library                2295
resolve_qnn_interface                  4
backend_create                       597
dump_backend_info                     54
device_create                          1
context_create                         7
graph_create                        1938
tensor_create                         42
graph_add_node                       117
graph_finalize                        32
graph_execute                       1066
result_validate                       47

5. `benchmark`

基于上述示例构建了一个测试不同精度/后端性能的benchmark，方便快速做端侧验证和横向对比。🧪

5.1 编译

Android 交叉编译：

# 确保环境变量正常
# export QNN_SDK_ROOT=/root/qairt/2.40.0.251030
# export ANDROID_NDK_ROOT=/root/android-ndk/android-ndk-r29

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK_ROOT/build/cmake/android.toolchain.cmake" \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-31 \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

cmake --build build -j4 --target qnn_precision_benchmark

5.2 命令行参数

qnn_precision_benchmark 支持以下参数：

--backend <path>         指定 backend 动态库路径
--dump-backend-info      打印 provider、interface、capability 信息
--m <rows>               左矩阵行数，默认 256
--k <inner>              矩阵归约维度，默认 512
--n <cols>               右矩阵列数，默认 512
--warmup <count>         预热次数，默认 3
--iters <count>          正式计时轮数，默认 10
--precisions <list>      精度列表，默认 fp32,int8,int16,fp16

如果要快速查看后端信息，也可以在运行前设置：

`1`	`export QNN_DUMP_BACKEND_INFO=1`

5.3 执行

下面的命令把可执行文件和三种后端需要的动态库一次性推到同一个目录：

export BENCH_DIR=/data/local/tmp/qnn_precision_benchmark
adb -s 127.0.0.1:40404 shell "mkdir -p $BENCH_DIR"

adb -s 127.0.0.1:40404 push \
  build/qnn_precision_benchmark \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnCpu.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnGpu.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtp.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpPrepare.so \
  $QNN_SDK_ROOT/lib/aarch64-android/libQnnHtpV79Stub.so \
  $QNN_SDK_ROOT/lib/hexagon-v79/unsigned/libQnnHtpV79Skel.so \
  $ANDROID_NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so \
  $BENCH_DIR/

5.3.1 CPU 测试

adb -s 127.0.0.1:40404 shell "
  cd $BENCH_DIR && \
  export LD_LIBRARY_PATH=$BENCH_DIR && \
  ./qnn_precision_benchmark \
    --backend ./libQnnCpu.so \
    --m 64 --k 128 --n 128 \
    --warmup 1 --iters 3
"

5.3.2 GPU 测试

adb -s 127.0.0.1:40404 shell "
  cd $BENCH_DIR && \
  export LD_LIBRARY_PATH=$BENCH_DIR && \
  ./qnn_precision_benchmark \
    --backend ./libQnnGpu.so \
    --m 64 --k 128 --n 128 \
    --warmup 1 --iters 3
"

5.3.3 HTP 测试

adb -s 127.0.0.1:40404 shell "
  cd $BENCH_DIR && \
  export LD_LIBRARY_PATH=$BENCH_DIR && \
  export ADSP_LIBRARY_PATH=$BENCH_DIR && \
  ./qnn_precision_benchmark \
    --backend ./libQnnHtp.so \
    --m 64 --k 128 --n 128 \
    --warmup 1 --iters 3
"

5.6 支持矩阵

以 MatMul 为例，当前文档和实际测试对应的支持范围如下：

✅ CPU：支持 fp32/int8，int16/fp16 会显示为 UNSUPPORTED
✅ GPU：支持 fp32/fp16，int8/int16 会显示为 UNSUPPORTED
✅ HTP：文档矩阵按 fp16/int8/int16 处理；如果 fp32 在你的设备上显示 OK，它表示 QNN runtime 接受了 QNN_DATATYPE_FLOAT_32 的图配置，不等价于 HTP 内部在做原生 FP32 MatMul

这里的 UNSUPPORTED 现在优先来自 backendValidateOpConfig() 的运行时探测；如果探测接口不可用，或者目标端 Android + HTP + int8 MatMul 会在 libQnnHtpPrepare.so 的探测路径里崩溃，就回退到文档支持矩阵，再以实际建图执行结果为准。fp32 OK 只能说明 API 层配置可执行；要判断内部实际精度，需要结合 HTP OpDef、backend profiling/log 和最终误差。⚠️

5.7 输出怎么看

输出示例如下：

QNN MatMul Precision Benchmark
backend_kind : NPU
backend_path : ./libQnnHtp.so
htp_soc_model: 69
htp_arch     : 79
shape        : A[64, 128] x B[128, 128] -> C[64, 128]
warmup       : 1
iterations   : 3

Results
precision status              init(ms)     build(ms)              exec(ms)     release(ms)     total(ms)     max_abs_err    mean_abs_err
----------------------------------------------------------------------------------------------------------------------------------------
int8      OK                  205.5645        9.0797        0.7750±0.0580         22.4316      242.4618          0.0271          0.0080
int16     OK                   35.2989       30.6419        0.8010±0.1014         20.8287       94.3954          0.0042          0.0017
fp16      OK                   28.1247       29.3391        0.7863±0.0760         21.3840       86.8039          0.0017          0.0004
fp32      OK                  175.9133       10.8606        0.7313±0.0520         22.8998      214.1842          0.0017          0.0004

GPU Results
precision status              init(ms)     build(ms)              exec(ms)     release(ms)     total(ms)     max_abs_err    mean_abs_err
----------------------------------------------------------------------------------------------------------------------------------------
fp16      OK                    5.7818      340.2971        0.2037±0.0488          2.9731      350.4211          0.0017          0.0004
fp32      OK                    6.0046      332.3594        0.3467±0.2124          2.9880      343.1908          0.0000          0.0000
CPU Results
precision status              init(ms)     build(ms)              exec(ms)     release(ms)     total(ms)     max_abs_err    mean_abs_err
----------------------------------------------------------------------------------------------------------------------------------------
int8      OK                   15.4623        0.2046        0.0167±0.0081          0.5728       17.1529          0.0398          0.0115
fp32      OK                   12.4459        0.2005        0.9967±0.0615          0.2930       17.3047          0.0000          0.0000

各列的含义如下：

init/build/release/total (ms)：初始化、建图、资源释放和总耗时
exec(ms)：多轮 QnnGraph_execute() 的平均值和标准差，格式是 mean±std
max_abs_err：输出和 float 参考值的最大绝对误差
mean_abs_err：输出和 float 参考值的平均绝对误差

QNN 介绍

Wed, 01 Apr 2026 15:00:00 +0800

QNN 介绍与 API 执行流程

1. QNN 是什么

QNN SDK 是 Qualcomm 官方提供的多设备推理开发套件，支持 Android 和 Linux 端的 CPU、GPU、HTP 等后端。如图 1 所示，它在应用和具体硬件之间提供了一层统一抽象，让上层尽量使用同一套接口。

图 1. QNN 软件架构示意。

可以把 QNN 理解成两层：

上层是一套统一的 C API。
下层是不同硬件后端的实现，最常见的是 CPU、GPU 和 HTP。

QNN 想做的是把“计算描述”和“硬件执行”拆开。应用层尽量复用同一套接口，而底层切换后端时，主要差异体现在：

加载的后端动态库不同。
计算图是否能被编译到目标硬件不同。
张量的数据类型、量化参数和内存描述要求不同。

下面列出部分支持的高通平台，详细列表可以参考官方文档。

表 1. 部分支持的 Snapdragon 平台

Snapdragon Device/Chip	Supported Toolchains	SOC Model	Hexagon Arch	LPAI Arch
SD 8 Elite Gen 5 (SM8850)	`aarch64-android`	87	V81	v6
SD 8 Elite (SM8750)	`aarch64-android`	69	V79	v5
SD 8 Gen 3 (SM8650)	`aarch64-android`	57	V75	–

2. 关键组件

QNN 文档把 API 组件分成了 Core、Utility、System 三类。
如图 2 所示，Core 负责执行主链，Utility 负责性能分析和日志，System 负责运行时配套能力。

图 2. QNN API 组件分类。

2.1 Core 组件

QnnBackend 顶层 QNN API 组件之一。大多数 QNN API 都要求先初始化后端；同时也提供 OpPackage 注册相关能力。
QnnDevice 顶层 QNN API 组件之一，用来描述设备和多核资源。一个平台可能包含多个设备，每个设备又可能包含多个核心；同时还提供性能控制能力。
QnnContext 为计算图和执行操作提供执行环境。计算图以及跨图共享的张量都创建在同一个上下文中；上下文还可以被缓存成二进制形式，供后续更快加载。
QnnGraph 提供可组合的计算图 API。计算图创建在上下文内部，由节点和张量组成；调用 finalize 之后才进入可执行状态。
QnnGlobalConfig 用于设置全局配置参数。
QnnTensor 用来表示静态常量数据，或者输入输出激活数据。张量可以具有 Context 作用域，也可以具有 Graph 作用域；同一个上下文下的多个计算图可以共享 Context 作用域张量。
QnnOpPackage 提供后端使用已注册算子包库的接口，这部分也对应自定义算子的扩展能力。

2.2 Utility 组件

QnnProfile 提供性能分析能力，用来评估计算图和操作的性能，包括时间和内存。
QnnLog 提供日志输出能力，QnnBackend 和 QnnOpPackage 都可以使用，并且它可以早于 QnnBackend 初始化。

2.3 System 组件

QnnProperty 提供能力查询接口，客户端可以在不初始化 QnnBackend 的情况下直接查询后端能力。
QnnMem 用来把外部分配的内存注册到后端。
QnnSignal 提供信号对象管理能力，用来控制其他组件的执行。

3. 执行路径

QNN 常见执行路径可以分成两类：

在线构图执行
离线缓存执行

3.1 在线构图执行

在线构图执行流程如图 3 所示。

图 3. QNN 在线构图执行流程。

3.1.1 初始化与算子包注册

运行 QNN 时，一般先创建 QnnBackend。
如果需要日志能力，可以更早初始化 QnnLog；如果需要自定义算子，则在后端创建之后注册 QnnOpPackage；随后创建 QnnContext。

3.1.2 构图与定型

在 QnnContext 中，通过 QnnGraph_create() 创建一张空计算图，随后逐步往图中添加张量和节点，最终形成完整计算图。
图构建完成之后，再调用 QnnGraph_finalize() 完成图定型，并触发后续的图优化和编译工作。

QNN 对张量类型做了明确区分：

图输入张量：QNN_TENSOR_TYPE_APP_WRITE
图输出张量：QNN_TENSOR_TYPE_APP_READ
图内部中间张量：QNN_TENSOR_TYPE_NATIVE
静态常量张量：QNN_TENSOR_TYPE_STATIC
用来连接多个计算图的上下文张量：QNN_TENSOR_TYPE_APP_READWRITE

这里有几个特别重要的约束：

张量名字在同一个上下文内必须唯一，重名属于未定义行为。
QNN 没有提供删除已注册节点或张量的 API。
往图里添加节点时，顺序应该遵守依赖顺序。

3.1.3 图执行

计算图构建完成之后，应用就可以开始执行。QNN 提供两类执行接口：

同步执行：QnnGraph_execute()
异步执行：QnnGraph_executeAsync()

异步接口会额外带上一组通知参数，用来在执行结束时通知应用。

3.1.4 资源释放

执行完成之后，应用可以通过 QnnContext_free() 销毁自己创建的上下文。
上下文被释放时，它持有的计算图也会一起销毁。

之后，再通过 QnnBackend_free() 释放后端句柄。
这一步会让整个后端相关的资源和句柄失效。

3.2 离线缓存执行

3.2.1 上下文缓存

QNN 允许应用把已经构好的计算图和上下文缓存成二进制形式，供后续复用。

图 4. QNN 上下文缓存流程。

在建图完成之后，可以通过 QnnContext_getBinary() 获取上下文的二进制形式；如果需要预估缓存大小，则可以先调用 QnnContext_getBinarySize()。
把这份二进制数据保存下来，就完成了上下文缓存。

3.2.2 缓存加载与执行

QNN 也可以直接跳过建图部分，加载前面生成好的上下文二进制数据，然后直接进入执行阶段，如图 5 所示。

图 5. QNN 缓存加载执行流程。

这条路径里最关键的几个接口是：

QnnContext_createFromBinary()：从缓存二进制恢复上下文。
QnnGraph_retrieve()：从上下文中取回已经完成定型的计算图。
QnnSystemContext_getBinaryInfo()：读取上下文二进制中的图和张量元信息。

这里还有一个容易漏掉的点：

自定义 OpPackage 不会随着上下文一起缓存。
加载缓存执行时，仍然需要手动调用 QnnBackend_registerOpPackage() 重新注册。

QNN介绍 on huluhuluu

QNN HTP OpPackage Softmax 源码分析

QNN HTP OpPackage Softmax 源码分析

1. 源码分析

1.1 头文件

1.2 算子定义

1.2.1 算子定义

1.2.2 函数声明

1.2.3 注册 Softmax 算子

1.2.4 Tensor 属性

1.2.5 注册 Softmax_fp 算子

1.3 算子优化

1.3.1 float32 -> fp16

1.3.2 折叠前置乘法

1.3.3 默认参数规整

1.3.4 softmax_hf_approx() 总览

1.4 伪代码

1.4.1 softmax_fp_impl() 伪代码

1.4.2 softmax_hf_approx() 总体伪代码

1.4.3 approx_exp2() 伪代码

1.5 算子实现

1.5.1 exp 近似

1.5.2 找最大值

1.5.3. 计算未归一化 exp

1.5.4 sum 并归一化

1.5.5 softmax_fp_impl()

1.6 reference 版本

2. Q6_Vqf32_vmpy_Vqf32Vqf32 等类型

QNN MatMul 权重静态化与输入化

QNN MatMul 权重静态化与输入化

1. 两种写法

2. 在线构图bench

2.1 编译

2.2 推送到设备

3. 离线构图

3.1 编译

3.2 推送到设备

QNN 文档

QNN 文档阅读

1. OpDef

1.1 数据结构

1.2 约束说明

2. api-rst

3. 量化

4. 数据类型

QNN 环境准备与 python实例

QNN 环境准备与 MatMul 端侧实例

1. 环境配置

2. 执行流程

2.1 生成 MatMul 计算图

2.2 转成 QNN 计算图格式

2.3 编译

2.4 执行

2.5. 验证输出

QNN 环境准备与实例

QNN 环境准备与在线构图 MatMul 示例

1. 环境配置

1.1 QNN 环境配置

1.2 Android 交叉编译环境配置

2. 执行流程

2.1 初始化

2.2 图构建

2.2.1 创建张量

2.2.2 创建节点

2.4 完成构图并执行

2.5 资源释放

3. 构建

4. 目标设备运行

4.1 GPU 测试

4.2 HTP 测试

4.3 CPU 测试

5. benchmark

5.1 编译

5.2 命令行参数

5.3 执行

5.3.1 CPU 测试

5.3.2 GPU 测试

5.3.3 HTP 测试

5.6 支持矩阵

5.7 输出怎么看

1.3.4 `softmax_hf_approx()` 总览

1.4.1 `softmax_fp_impl()` 伪代码

1.4.2 `softmax_hf_approx()` 总体伪代码

1.4.3 `approx_exp2()` 伪代码

1.5.5 `softmax_fp_impl()`

2. `Q6_Vqf32_vmpy_Vqf32Vqf32` 等类型

5. `benchmark`