Android NPU 使用指南

1. 概述

1.1 本板 NPU

本板的 AI 推理主要在外接的 RK1828 协处理器上完成。RK1828 做在一块 M5-R2A 260Pin SO-DIMM 模组上（内存条形态的扩展卡，通过 PCIe2.1/USB3.0 与主板相连）。

项实际情况
推理主力外接 RK1828，M5-R2A 260Pin SO-DIMM 模组（PCIe2.1/USB3.0）
接入方式PCIe Gen2 x1 @ pcie2x1l2(fe190000)，经 combphy0；枚举 1d87:182a
驱动pcie-rkep.ko（PCIe endpoint 驱动）+ 卡固件（update_pcie/usb.img）
已验证应用AI 三件套（RkAiService/Launcher/Asst，LLM 应用）、rkllm3-server（实测约 118 tok/s）

1.2 应用场景

  • 板上 LLM 推理服务（rkllm3-server，监听 8090 端口）
  • AI 助手类应用（AI 三件套，基于 librockllm）
  • NPU 运行状态监测（rknn-smi）
  • 卡固件升级（update_pcie.img / update_usb.img 两个通道）

1.3 工作原理

AI 三件套 APK（A16 · SYSTEM 分区）
        │
rkllm3-server / rknn3_transfer_proxy / rknn-smi（A14 · VENDOR 分区）
        │
pcie-rkep.ko（内核模块，vendor_boot/vendor_dlkm 装载）
        │  PCIe Gen2 x1
RK1828 SO-DIMM（卡固件由 firmware_update_server 管理，update_pcie.img/update_usb.img）

卡固件指 M5-R2A 模组自身运行的固件，与 RK3588 侧的用户态程序配套。交付采用的版本组合是：1.0.4 用户态 + FAE 版 dac1f5c9 卡固件（FAE 版指芯片原厂应用工程师提供的版本）。

2. 硬件准备

设备型号/规格数量说明
目标板SMDT RK3588 3588A V3.11NPU 供电 vcc3v3_pciem1（GPIO4_B5）、复位 GPIO4_D4、clk_pwren GPIO4_B0 均已在 dts 配好
NPU 模组M5-R2A 260Pin SO-DIMM（RK1828）1升级工具识别身份：PCIe=1d87:182a，USB maskrom=2207:180b
显示器HDMI11用于验证 AI 应用界面
编译主机x86_64 Linux（Ubuntu 22.04）1双 SDK 联编（A16、A14 两套 SDK 一起编译，见 ch01）

3. 软件准备

  • 双 SDK 源码树就位，RK1828 支持代码已合入源码树（A16 提交 37a63d941bb、A14 提交 ac3cdd5d5e6；rkllm 自启问题的修复在后续提交中）
  • 完成过一次全量编译（bash build_ssi16.sh all，见 ch01 §4.2）
  • 板载工具（固件已内置）：rknn-smi、lspci_vendor、{pcie,rknn,}upgrade_tool、firmware_update_server
  • PC 端 RKNN Toolkit2（用于模型转换，位于 A14 hardware/rockchip/rknn-toolkit2/，文档在同目录 doc/ 下）

4. 操作步骤

4.1 NPU 链路确认（全实测命令）

烧录完成后，按下面的命令逐项确认 NPU 链路（这些命令都在实机上验证过）：

/vendor/bin/lspci_vendor                 # 应见 Processing accelerators 1d87:182a
dmesg | grep -E "fe190000|182a"          # Gen2 x1 link up + 枚举日志
rknn-smi info                            # 应显示 RK1828 Online
lsmod | grep -E "rkep|rknpu"             # pcie-rkep / rknpu 模块在
# rkllm 服务（五项验收基线）：
ps -A | grep rkllm                       # 进程在
netstat -tlnp | grep 8090                # 端口 LISTENING
# 真实推理 ~118 tok/s（与基线零损失）；红灯灭/绿灯亮（开机切灯）

板上实测结果：

  • 枚举：0004:41:00.0 [1d87:182a] class 0x120000（Processing accelerator）；dmesg 中可见 pcie-rkep 0004:41:00.0: success to request irq, type=1
  • rknn-smi info（v1.3.0）：RK1828 Online，Bus-Id 0004:41:00.0，Temp 46°C，Memory 32/5120 MB
  • lsmod | grep -E "rkep|rknpu"：pcie_rkep 和 rknpu 都已加载。pcie-rkep 由 init 在 0.71 秒从 vendor_ramdisk 的 /lib/modules 装载，也就是 first_stage 通道（开机第一阶段直接从 ramdisk 装载模块）；宿主控制器 pcie_dw_rockchip 同时在载
  • VENDOR/SYSTEM 分区内容：/vendor/bin/ 下有 rkllm3-server、rkllm_start.sh、rknn-smi、rknn3_transfer_proxy、{pcie,rknn}upgrade_tool；/vendor/etc/rk1820/ 下有 update_pcie.img、update_usb.img；SYSTEM 分区装有 AI 三件套三个 APK（com.rockchip.ai{service,launcher,asst}）

4.2 RK1828 支持的构建配置

RK1828 的支持分散在两棵源码树的多处配置文件中，下表列出全部改动点：

#树文件改动
1A16板卡资产 dts&pcie2x1l2 okay（reset GPIO4_D4 + vpcie3v3-supply）；根块 vcc3v3_pciem1 regulator（GPIO4_B5）；rk182x_clk_pwren（GPIO4_B0，always-on）；&sata0 disabled（combphy0 让路）；&pcie3x4/&pcie30phy disabled（空槽）
2A14kernel-6.1/arch/arm64/configs/rockchip_gki.configCONFIG_PCIE_FUNC_RKEP=m（设为 =y 时曾导致编译失败）、CONFIG_PCIE_DW_DMATEST=y
3A14mkcombinedroot/res/vendor_modules.load、vendor_ramdisk_modules.load+pcie-rkep.ko（去掉注释启用）
4A14mkcombinedroot/copy_moduls.shGKI 去重排除 smdt_*.ko/pcie-rkep.ko
5A14device/rockchip/rk3588/rk3588_u/rk3588_u.mkBOARD_RK1820_SUPPORT := true（L23，须在 inherit common/device.mk 之前）
6A14device/rockchip/common/device.mk（L248）rk182x.mk inherit + rknn_model_manager 用通配符做保护（tarball 未导入时不报错，放到位置后自动生效）；hardware/rockchip/rk1820/rk1820.mk 无条件 inherit
7A16configs/vintf.mk + ssi_16_arm64/vintf/*.xmlrknnsmi/rknnmodeltest 两条 optional AIDL 矩阵条目
8A16ssi_16_arm64/device.mkBOARD_RK1820_SUPPORT=true（可选开关，用来切换 APK 变体）+ PRODUCT_PACKAGES 三件套 + persist.sys.rkai.product=smartmonitor_RK1820
9A16vendor/rockchip/common/apps/RkAiService/Android.mk$(TARGET_BOARD_PLATFORM) → 硬编码 rk3588（SSI 产品该变量为空）
10A16vendor/rockchip/common/apps/RkAi{Service,Launcher,Asst}/从 A14 同步 rk182x 变体 APK + librockllm.so

其中第 7 项涉及 VINTF（Vendor Interface，Android 的厂商接口清单与兼容性检查框架）：device manifest 声明设备提供哪些 HAL，framework 兼容矩阵声明系统要求哪些 HAL，合并镜像时两边必须匹配。

改完之后分别编译：dts 和驱动侧执行 bash build_ssi16.sh all vendor，APK 和属性侧执行 bash build_ssi16.sh all ssi。

4.3 卡固件与用户态版本管理

交付版本组合：1.0.4 用户态 + FAE 版 dac1f5c9 卡固件。升级文件 update_pcie.img/update_usb.img 和升级工具都内置在 VENDOR 分区，firmware_update_server 服务开机后常驻，负责卡固件升级。

4.4 rkllm3-server 自启与验证

关键文件在 A14 device/rockchip/common/ 下。rkllm3-server.rc 用 /vendor/bin/sh 包装、设置 group media_rw，注意其中不写 capabilities 行，写了会被系统裁剪；rkllm_start.sh 使用 vendor bin 前缀路径，并且不带 -a 参数。

4.5 AI 三件套

AI 三件套指 RkAiService、RkAiLauncher、RkAiAsst 三个应用。APK 本体在 A16 vendor/rockchip/common/apps/RkAi{Service,Launcher,Asst}/（rk182x 变体 APK 加 librockllm.so），随 ssi 编译阶段进入 SYSTEM 分区。这里要遵守一条 GRF 规则（GRF 指用 A16 框架树和 A14 厂商树分别构建再合并的方案，详见 ch03 §4.7）：装进 SYSTEM 分区的内容必须在 A16 侧打包，A14 侧的同名包会在合并时被静默丢弃、不报错。系统属性 persist.sys.rkai.product=smartmonitor_RK1820 控制产品形态。

实机确认：com.rockchip.ailauncher / com.rockchip.aiservice / com.rockchip.aiasst 三个包都已安装在 SYSTEM 分区。

5. 代码详解

5.1 关键路径

各层关键文件的位置如下：

层路径
dts 功能块A16 板卡资产 rk3588_smdt_3588a_v31.dts L93/L106（regulators）、L888（&pcie2x1l2，注释即枚举身份）
内核驱动A14 kernel-6.1（pcie-rkep，CONFIG 见 §4.2#2）
用户态全家桶A14 hardware/rockchip/rk1820/（rk1820.mk 被 device.mk:269 无条件 inherit）
装载清单A14 mkcombinedroot/res/*.load（ch03 §4.4）
rkllm 自启A14 device/rockchip/common/{rkllm3-server.rc, rkllm_start.sh} + sepolicy .te SMDT 块
AI 应用A16 vendor/rockchip/common/apps/RkAi*、ssi_16_arm64/device.mk

5.2 镜像内实测内容

实际打开镜像确认的内容：

  • VENDOR：update_pcie.img、update_usb.img、{pcie,rknn,}upgrade_tool、init.rk1820_firmware_update_server.rc、rknn-smi、rkllm3-server、rknn3_transfer_proxy
  • SYSTEM/app：RkAiService.apk（rk182x 变体）、RkAiLauncher.apk、RkAiAsst.apk

5.3 版本基线表

组件版本说明
RK1828 用户态1.0.4交付采用（1.1.0 方案已放弃）
卡固件FAE dac1f5c9随 VENDOR 分区 update_pcie/usb.img 提供
验收镜像build#17 md5 67c70f88…（2026-09-29，经六次烧录验证通过）RK1828 Online + 灯序正常
集成提交A16 37a63d941bb / A14 ac3cdd5d5e6RK1828 完整流程合入源码树

6. 常见问题

6.1 PCIe 不枚举 / phy lock failed

按下面的顺序排查：

  1. 先确认实际拓扑：在板上执行 lspci_vendor，确认设备实际挂在哪个 PCIe 控制器下。这里曾出过一次错：把 1828 误配到没有器件的 pcie3x4 空槽，对着不存在的设备去调 phy，当然会 lock failed（fe170000 实际是 YT6801 网卡）。修改 PCIe 配置前，先对照参考 BSP 和老 SDK 的同名 dts，板卡作者预留的配置（disabled 状态加引脚定义齐全）就是正确答案。
  2. combphy 共享冲突：pcie2x1l2 与 sata0 共用 combphy0（组合 PHY，同一组 PHY 不能同时用作 PCIe 和 SATA）。若 SATA 先被 probe 并锁定了 PHY 模式，PCIe 链路会一直停在 LTSSM 0x1 状态起不来。板上没有 SATA 器件，在 dts 中禁用 sata0 即可。
  3. resource.img 里是旧的残留文件：如果烧录后运行时 FDT 里 PCIe 全是 disabled，而源 dts 明明正确，说明新 dtb 没有进入镜像（GRF 的 mkimage 步骤曾跳过拷贝，vendorsetup.sh 已补上修复）。验证 dtb 必须用 dtc -I dtb -O dts 反编译后看内容，strings | grep disabled 分不出新旧文件。

6.2 firmware_update_server 报 No PCIe device

这本质上是 6.1 的链路问题：服务和工具都在，只是 PCIe 没通。按 6.1 的顺序排查后重启，再用 rknn-smi info 验证。

6.3 rkllm3-server 起不来 / 启动 2 秒左右退出

先分清是 SELinux 问题还是应用自身问题：执行 dmesg | grep avc，如果有 denial 记录，按 §4.4 的说明检查；avc 记录清零后服务仍退出，就要查启动参数（-a 参数曾导致 SIGABRT）。最终验证以三项为准：进程存在、8090 端口在监听、实际推理正常。2026-10-22 实测注：当前 202609 固件上 rkllm3-server 未自启，如复现，先确认固件是否包含 §4.4 所述修复。

6.4 RkAiService 编译失败（librockocr.so 路径坏）

原因是 A16 的 SSI 产品中 $(TARGET_BOARD_PLATFORM) 变量为空，A14 拷来的 Android.mk 里用到该变量的地方需要硬编码成 rk3588（见 §4.2 第 9 项）。

6.5 merge 阶段 Incompatible VINTF

device manifest 声明的 HAL 必须在 framework 兼容矩阵中有条目，而矩阵在 A16 树（rknnsmi/rknnmodeltest 走 optional AIDL 条目，见 §4.2 第 7 项）。

6.6 AI 应用烧进系统后消失

原因是 GRF 合并时丢弃了 A14 树的 SYSTEM 分区内容，APK 必须在 A16 的 device.mk 打包（见 §4.5）。

7. 相关文档

文档说明
RK1828_1.1.0升级重编方案.md（A16 顶层）1.1.0 排查留档与重启路线
README_SMDT_MODIFICATIONS.md §八（A16 顶层）RK1828 完整记录 log36-45（11 条教训与验收）
ch01-04（编译/构建与增量/系统定制/HAL）本系列配套
Rockchip_RK1820_RK1828_Introduction_Android_Demo_CN.pdf（A16 顶层）RK1828 官方介绍与 Demo
Debian-Ubuntu/ai-npu-development/Linux 侧 NPU / Toolkit2 参考
application-development/ch02-android-jni-development.mdRKNN JNI 集成