Android HAL 开发（SMDT 双 SDK 联编）

1. 概述

1.1 功能简介

HAL（Hardware Abstraction Layer，硬件抽象层）是 Android Framework 与内核驱动之间的中间层。本文按 SMDT RK3588 3588A V3.1 双 SDK 项目的实际开发情况编写。双 SDK 联编指 A16 框架树与 A14 厂商树两套 SDK 分别构建、再合并出最终镜像。本文覆盖两条开发主线：

  • KO 驱动模块开发（GKI 架构。KO 指以 .ko 文件形式装载的内核模块；GKI 即 Generic Kernel Image，把通用内核与厂商模块分开的构建方式）：SMDT 外设驱动（nca9555/smdt_io 等 8 个模块）的标准开发流程、模块装载管线、快速迭代路径；
  • HAL 服务集成（GRF 双树规则。GRF 即 Generic Root Filesystem，双树指 A16/A14 两棵源码树）：HAL 库分布、VINTF 兼容矩阵、AIDL/HIDL 迁移注意事项。

1.2 应用场景

  • 新增/修改板级外设驱动（KO 模块）
  • HAL 服务接入并通过兼容矩阵检查
  • 模块装载问题排查（Unknown symbol / 顺序 / 旧模块不更新）
  • 板上 HAL 与驱动联调

1.3 工作原理

本产线真实分层：

Framework (Java/AOSP, A16)
    │  AIDL / HIDL（Binder）
HAL Service / 实现（A14 vendor 侧，编进 vendor 分区）
    │  ioctl / sysfs / /dev
KO 内核模块（A14 kernel-6.1，GKI 方式装载）
    │
RK3588 硬件

模块装载三通道（详见 ch03 §4.4）：
vendor_boot.img first_stage（ramdisk 模块：pcie-rkep 等）
vendor_dlkm second_stage（smdt 家族，insmod）
kernel/prebuilts modules.load（Rockchip 内核流程兜底）

三通道的含义：first_stage 指开机第一阶段直接从 vendor_boot 的 ramdisk 装载；second_stage 指随后从 vendor_dlkm 分区用 insmod 装载；最后一项是 Rockchip 内核流程的后备。

GKI 现状：kernel 6.1.172（A14 树），配置链 gki_defconfig rockchip_gki.config valhall_gpu_gki.config；板级驱动全部以 .ko 形式装载；dtb 打进 vendor_boot.img（不单独烧 kernel.img/resource.img）。

2. 硬件准备

设备型号/规格数量说明
开发主机x86_64 Linux（Ubuntu 22.04）1编译（要求见 ch01 §2）
目标板SMDT RK3588 3588A V3.11板上无 MCU、无 rk628（见 ch03 §2）
USB 转 TTL3.3V1串口 1500000 8N1
USB Type-C数据线1adb（USB-C OTG 口，peripheral 模式）

3. 软件准备

  • 双 SDK 树就位且一次全量编译通过（ch01 §4.2）
  • 熟悉 ch02 §4.2 增量出包路径表（本文所有编译命令引自该表）
  • 板载调试工具已在固件内：rknn-smi、lspci_vendor、modinfo、getevent 等（userdebug 版）

4. 操作步骤

4.1 GKI / KO 架构现状（本产线实测）

项现状
内核A14 kernel-6.1（6.1.172），in-tree 构建
GKI 配置链gki_defconfig rockchip_gki.config valhall_gpu_gki.config（config.json 权威）
u-boot 配置rk3588_defconfig gki.config
模块装载三通道（first_stage ramdisk / vendor_dlkm second_stage / 内核流程后备），清单文件见 ch03 §4.4
dtb打进 vendor_boot.img（GRF 模式）
分区vendor_boot、vendor_dlkm、init_boot 等动态分区，A/B 双槽（分区各保留两份，升级失败可回退）

「关闭 GKI」（BOARD_BUILD_GKI := false）是单 SDK 流程的选项，GRF 双 SDK 联编不适用。

4.2 新增/修改 KO 驱动模块（SMDT 驱动开发模式，标准流程）

以 SMDT 外设驱动为模板（8 个模块的完整流程都已验证）：

  1. 源码放 A16 板卡资产（唯一源码位置）：device/rockchip/rockchip_generic/board/rk3588_smdt_3588a_v31/drivers_smdt/，同目录 Makefile 写 obj-m += xxx.o；
  2. 头文件依赖放 include_smdt/（slog.h；缺了它编译必然失败，历史上漏部署过一次）；
  3. 部署：执行 bash deploy_board.sh，把源码推到 A14 kernel-6.1/drivers/smdt/，并在 drivers/Makefile 挂上 obj-m += smdt/；
  4. 配置开关：需要 Kconfig 的驱动在 A14 arch/arm64/configs/rockchip_gki.config 加 CONFIG_XXX=m（模块清单与 .config 不一致会让 vendor 阶段编译失败，见 ch02 §6.2）；
  5. 装载清单：按装载通道在对应 .load 文件加一行，注意按依赖顺序排列，且不能写注释、不能有空行。smdt 系列模块只走 vendor_modules.load 的 second_stage，因为 first_stage 阶段 i2c6/nca9555 还没就绪；
  6. 编译：改了 dts 先执行 bash build_ssi16.sh dts 快速验证，正式出包用 bash build_ssi16.sh all vendor；
  7. 验证链（每步都要通过）：模块池（集中存放待打包 .ko 的目录，位置见 §5.1）里的 .ko 用 strings 查标记 → staging 目录 md5 一致 → 板上 modinfo 看 depends → lsmod → sysfs/功能实测。

4.3 模块快速迭代（只改 .c，不动 dts）

实测路径：

# 1. 改 A16 资产端 .c → bash deploy_board.sh
# 2. A14 kernel-6.1 内重编该模块（make CC=clang ...）
# 3. strip-debug 进模块池（BOARD_VENDOR_KERNEL_MODULES 本体）
llvm-objcopy --strip-debug <新.ko> $A14/mkcombinedroot/vendor_ramdisk/lib/modules/xxx.ko
# 4. 坑16：ninja 不跟踪模块池 mtime，必须手动清 staging + 触发清单重展开
rm $A14/out/target/product/rk3588_u/vendor_dlkm/lib/modules/smdt_*.ko
touch $A14/mkcombinedroot/res/vendor_modules.load
# 5. 重编 vendor（bash build_ssi16.sh vendor）

其中第 4 步注释里的「坑16」是排查记录中的一个编号问题，内容是：构建系统不会检测模块池文件的时间戳变化，所以改完 .ko 必须手动清掉 staging 里的旧文件并 touch 清单文件，否则打进镜像的还是旧模块。

需要把模块更新进 vendor_boot.img（first_stage 通道）时，走 ch02 §4.4 的高级路径（target-files 暂存区 + zip 成员刷新 + mkupdate）。

RK 原厂的单模块重打包工具 mkgki4.sh 在 A14 mkcombinedroot/ 下存在，但本项目没有验证过；验证过的是上面这条流程。

4.4 HAL 服务开发与集成（GRF 双树规则）

4.4.1 HAL 库分布（路径已逐一核实，全在 A14 树）

功能路径（A14）
显示合成 hwc3hardware/rockchip/hwcomposer/（drmhwc2）
hw_output 管理hardware/rockchip/hw_output/、hwc_proxy_service/
音频 HALhardware/rockchip/audio/
相机 HALhardware/rockchip/camera/、camera_aidl/、camera_engine_rkisp/、rvcam/
outputmanagervendor/rockchip/hardware/interfaces/outputmanager/（AIDL）
rockit 多媒体vendor/rockchip/hardware/interfaces/{rockit,codec2,hdmi,tv...}
NPU / RKNNhardware/rockchip/{rknn-toolkit2,rknpu2,rk1820}、rvinfer/
图形/媒体加速libgralloc/、librga/、libiep/、libhwjpeg/、libvdpp/
外设类sensor/、thermal/、usb/、wifi/、keymaster4/、gnss/ 等

A16 侧 vendor/rockchip/{common,hardware,platform,prebuilts} 主要承载 apps（RkAi 三件套）、jq 等预编译件与接口对接。

4.4.2 GRF 双树集成规则

  1. framework 兼容矩阵在 A16：新增 HAL 要在 A16 rockchip_generic/manifests/ 的 FCM（framework 兼容矩阵）加条目，否则合并阶段报 Incompatible VINTF。同时注意接口代际（HAL 接口定义语言分 HIDL、AIDL 两代）：新版 GRF 已把 rockchip.hardware.outputmanager 从 HIDL 迁到 AIDL，条目要写 <hal format="aidl">（实际案例）；
  2. 装到 SYSTEM 分区的内容必须在 A16 打包：A14 的 PRODUCT_PACKAGES 进 SYSTEM 的部分在合并时被静默丢弃、不报错（AI 三件套实际案例，见 ch03 §4.7）；
  3. 可选 HAL 用 optional 条目：rknnsmi/rknnmodeltest 走 configs/vintf.mk + ssi_16_arm64/vintf/*.xml 的 optional AIDL 条目（实际案例）。

另外两点经验：A16 编译对 A14 拷来的 mk 文件比较敏感，$(TARGET_BOARD_PLATFORM) 在 SSI 产品为空，需要硬编码 rk3588（RkAiService 的 Android.mk 实际案例）；缺头文件时可用符号链接补齐（RockitMetadataRetriever.h 链接到同目录 Comm 版本，实际案例）。

2026-10-22 实机确认：三个 HAL 服务均在运行，分别是 android.hardware.graphics.composer3-service.rockchip、rockchip.hardware.outputmanager-service（AIDL）、rockchip.hardware.rockit.hw@1.0-service（HIDL 1.0），与上面 outputmanager 用 AIDL、rockit 用 HIDL 的代际描述一致；AI 三件套（com.rockchip.ailauncher / com.rockchip.aiservice / com.rockchip.aiasst）确认装在 SYSTEM 分区。

4.5 板级 DTS 与驱动匹配

本项目的板级差异用独立完整 dts（rk3588_smdt_3588a_v31.dts）表达，不用 DTBO overlay（在基础设备树上叠加补丁的机制）。驱动靠 compatible 字符串匹配（实际案例：smdt,smdtio 由 smdt_io.ko probe）。dts 修改流程、/delete-node/ 规则、功能块完整清单见 ch03 §4.2。

4.6 板上调试工具箱（全部实测）

| 目的 | 命令 | 备注 / 常见问题 | | ----------- | --------------------------------------------- | -------------------------------------------------------------------- | --------------------------------- | | 模块清单 | lsmod | 看模块在不在、依赖谁 | | 模块依赖 | modinfo xxx.ko | 看 depends 字段（smdt_io 曾带 smdt_mcu 残留导致 insmod 失败） | | 缺符号定位 | nm -u xxx.ko | Undefined 符号 = 缺依赖/白名单外符号 | | 内核日志 | dmesg / dmesg | grep -E "fe190000\|182a" | 串口 1500000 8N1 同步看 boot 全程 | | NPU | rknn-smi info、/vendor/bin/lspci_vendor | RK1828 Online 说明整条链路已通 | | GPIO / 灯 | cat /sys/class/gpio_sw/red_led/data（0=灭） | blue_led/data 应为 1；red_led 本体是目录，直接 cat 报 Is a directory | | input 事件 | getevent | 输出格式随参数变（带节点无前缀 / 全局有前缀），写脚本先实测 | | 进程确认 | ps -A \| grep xxx | grep -x 整行匹配必误判，用 grep 子串 | | sysfs input | cat /sys/class/input/*/name | shell 域读 sysfs input 不通，注意 SELinux/域 | | 系统属性 | getprop / getprop \| grep xx | — | | 日志 | logcat -b all | hwc3/SF/zygote 重启循环看这里 | | 连接 | adb（USB-C peripheral 口） | 无 husb311 PD 芯片，固定 peripheral 模式 |

板上实测：

  • lsmod：smdt_io / smdt_info / smdt_param / smdt_mouse / smdt_serial / smdt_nca9555 / smdt_sys_serial_shim + rockchip_disable_unused 全部在载；bcmdhd（WiFi）在载
  • PCIe：pcie_rkep 与宿主控制器 pcie_dw_rockchip 均在载（pcie-rkep 由 init 在 0.71s 从 vendor_ramdisk /lib/modules 装载，即 first_stage 通道；dmesg 实测 pcie-rkep 0004:41:00.0: success to request irq）
  • rknn-smi info（v1.3.0）：RK1828 Online，Bus-Id 0004:41:00.0，Temp 46°C，Memory 32/5120 MB
  • dmesg | grep -E "fe190000|182a" 可用（实测输出 rk-pcie fe190000.pcie: invalid prsnt-gpios property in node 等）
  • LED 实测：red_led/data=0（灭）、blue_led/data=1；getprop sys.usb.config → adb

4.7 开机链路日志确认（基线）

阶段确认点
Loader/U-Boot串口可见；rockchip_dw_hdmi_qp_probe: can't get link_clk 是 loader 自身无害报错
kerneldisplay 链 bound（Initialized rockchip on minor 0）；无 RCU stall / SError
init/模块lsmod 见 smdt 家族 + pcie-rkep + rknpu（2026-10-22 实测均在载）；/sys/class/gpio_sw/ 出 red/blue_led
HAL/系统boot completed ~14s 基线；SF/hwc3 无重启循环
灯red_led/data=0、blue_led/data=1（开机红灯灭绿灯亮）

排查案例索引：

现象根因出处
hwc3 Check failed: halImpl != nullptr abort 循环黑屏kernel display 链未通（fw_devlink 依赖环致 DRM card 不注册），不是 HAL 本身问题handoff / README
GPU 访问即 async SErrorSCMI 固件域调频/下电链路问题，通过 GPU 冻结补丁加 OPP 单档解决handoff
usbdp_phy 永久 defer、USB 口不在线modules.load 里 inno-usb2 与 usbdp 顺序反了README §二C
PCIe 设备不枚举（LTSSM 0x1）combphy0 被 sata0 先锁 / 拓扑搞错（先用 lspci 确认实际拓扑再改 dts）README §八
模块 insmod Unknown symbolGKI 符号白名单（ch341 tty_put_char）/ extern 依赖（SUPPORT_MCU）README

4.8 RK 官方通用方法速查

项内容状态
mkgki4.sh 单独重打包 vendor_bootA14 mkcombinedroot/mkgki4.sh（RK 官方）未验证过，用 ch02 §4.4 路径
BOOT_IMG=... rk3588-evb1-lp4-v10.img 单编 boot.img单 SDK GKI 验证法不适用（GRF 模式下走 vendor 阶段）
关闭 GKI（BOARD_BUILD_GKI := false）单 SDK 选项不适用
DTBO overlay 多产品兼容dt-overlay.in（存在）未使用（独立 dts 方案）
EVB 参考板 dts 表rk3588-evb1/evb7 等仅作 dtsi 参考来源

5. 代码详解

5.1 模块管线关键路径（源 → 板）

从源码到板上，模块要经过下面这些环节：

环节路径（A14）
源码（部署目标）kernel-6.1/drivers/smdt/（资产源在 A16 board 目录）
构建产物kernel-6.1/drivers/smdt/*.ko
模块池mkcombinedroot/vendor_ramdisk/lib/modules/（BOARD_VENDOR_KERNEL_MODULES 本体，strip-debug 生成）
装载清单mkcombinedroot/res/{vendor_modules,vendor_ramdisk_modules}.load、kernel/prebuilts/6.1/arm64/modules.load
暂存区out/target/product/rk3588_u/obj/PACKAGING/target_files_intermediates/.../VENDOR_BOOT/RAMDISK/lib/modules/
镜像vendor_boot.img（first_stage）/ vendor_dlkm.img（second_stage）
验证点板上 lsmod / modinfo / sysfs

5.2 HAL 侧关键路径

见 §4.4.1 表；A16 侧对接点：manifests/frameworks_compatibility_matrix.xml、configs/vintf.mk、ssi_16_arm64/device.mk（预装）、vendor/rockchip/common/apps/（APK 本体）。

5.3 GKI 配置链

// config.json（权威）
"kernel_config": "gki_defconfig rockchip_gki.config valhall_gpu_gki.config",
"uboot_config":  "rk3588_defconfig gki.config"

驱动挂载两种方式：Kconfig 型走 rockchip_gki.config 的 CONFIG_XXX=m；smdt 家族走 drivers/Makefile 的 obj-m += smdt/ 直接挂载（不依赖 Kconfig）。

6. 常见问题

6.1 模块 insmod 报 Unknown symbol

两类根本原因（都有实际案例）：

  1. 符号不在 GKI 白名单内（GKI 只允许模块引用白名单里的内核符号）：如 ch341 的 tty_put_char，删掉该调用（保留注释）即可通过；
  2. extern 链接依赖：smdt_io 引用 mcu_get_version（板上没有 MCU），用 #define SUPPORT_MCU 0 切断依赖。

定位方法： nm -u xxx.ko 列出 undefined 符号，对照上面两类处置；板上先 modinfo xxx.ko 看 depends 是否符合预期。

6.2 模块加载了但功能不对 / 顺序问题

排查： modinfo 看 depends，对照 .load 清单顺序。实际案例：phy-rockchip-inno-usb2 必须排在 phy-rockchip-usbdp 之前（前者提供 usb480m_phy1 时钟），顺序反了 usbdp 会永久 defer、USB 口不可用。smdt 家族只走 second_stage（first_stage 时 i2c6 未就绪）。

6.3 改了驱动，板上还是旧模块

**根本原因：**构建系统不会检测模块池文件的时间戳变化（即 §4.3 提到的坑16），staging 目录里还是旧 .ko。

**处置：**按 §4.3 完整链条（strip-debug 进池 → 删 staging → touch .load → rkbuild_build vendor）；刷机后在板上用 modinfo/strings 查新加的标记字符串，确认新模块真的进了镜像。

6.4 新 HAL 接入后 merge 失败 Incompatible VINTF

**根本原因：**framework 矩阵在 A16，HAL 实现在 A14。device manifest 声明的 HAL 必须在 A16 的 FCM 有条目；HIDL→AIDL 迁移的接口要写 format="aidl"。

**处置：**见 ch03 §4.8 两个实际案例。

6.5 显示黑屏 / hwc3 反复重启

**经验：**本项目三次黑屏的根本原因全在 kernel 侧（fw_devlink 依赖环、rk628 桥死链、GPU SError），先查 dmesg 的 display 链，再怀疑 HAL。确认 Initialized rockchip on minor 0 出现、SF/zygote 没有 5 秒一次的重启循环之后，再往下查 HAL 层。

6.6 vendor 阶段报 ninja: ... vendor_ramdisk/lib/modules/xxx.ko no known rule

原因是模块清单与 .config 不一致。处置见 ch02 §6.2（A14 make installclean 后重跑）。

6.7 调试命令的常见问题

getevent 输出格式随参数变（写脚本前先实际跑一遍确认格式）；ps | grep -x 整行匹配必然误判（用子串 grep）；shell 域读不到 sysfs input 信息。详见 §4.6 表备注。

7. 相关文档

文档说明
ch01-android-sdk-build.md双 SDK 联编主流程
ch02-android-build-system-incremental-build.md模块定向更新、断层点
ch03-Android系统定制.md板卡资产、dts、模块装载三通道
README_SMDT_MODIFICATIONS.md（A16 顶层）权威净改动清单（HAL/驱动明细）
handoff_2026-09-21.md（A16 顶层）display/GPU 排查实录、验证脚本
Android/ai-npu/ch01-android-npu-guide.mdNPU 与 AI 推理
Debian-Ubuntu/peripheral-drivers/Linux 驱动参考