Android HAL 开发

1. 概述

1.1 功能简介

本文档介绍 M4-R2（RK3576）Android 14 系统的 HAL（Hardware Abstraction Layer）开发方法，涵盖 GKI 架构、内核模块（KO）编译、vendor_boot 打包、板级设备树配置、HAL 库结构以及原生接口绑定等内容。

1.2 应用场景

  • 为 RK3576 平台新增或修改内核驱动模块
  • 开发 Camera、Audio、Display 等 HAL 库
  • 打包 vendor_boot 镜像
  • 集成 RKNN Toolkit2 到 Android 系统

1.3 前置条件

  • 已完成 Android SDK 编译（详见 Android_SDK编译）
  • 了解 Linux 内核驱动开发基础
  • 了解 Android 架构（App → Framework → HAL → Kernel）

2. GKI 架构

2.1 GKI 简介

参考说明：GKI（Generic Kernel Image）是 Android 通用内核镜像方案，板级驱动以 KO 模块形式加载（RK3576 SDK 默认启用 GKI，以实际 SDK 为准）。

普通内核：内核 = 通用内核 + 板级驱动（编译在一起）
GKI 内核：内核（通用） + 板级驱动（KO 模块，单独编译加载）

2.2 编译模块

# 编译整个内核
./build.sh -K

# 使用模块方式编译单个驱动
cd kernel
export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-
make modules M=drivers/gpu/drm/rockchip

说明：具体模块化的驱动列表与编译方式以 RK3576 SDK 中 kernel/ 配置为准。

3. 板级设备树（DTS）

参考说明：RK3576 板级设备树节点定义以实际发布的 RK3576 SDK 为准，以下为通用配置思路。

3.1 设备树结构

arch/arm64/boot/dts/rockchip/
├── rk3576.dtsi              # SoC 级设备树（Rockchip 官方维护）
├── rk3576-evb.dtsi          # EVB 通用板级配置
└── rk3576-shimetapi.dts     # M4-R2 板级配置（自定义）

3.2 修改设备树

在板级 DTS 中开启/配置外设节点：

&i2c3 {
    status = "okay";
    // 外设节点定义
};

&uart2 {
    status = "okay";
};

注意：具体寄存器基地址、中断号与时钟标识以 RK3576 SDK 中的 rk3576.dtsi 为准。

3.3 编译 DTBO

./build.sh -K
# 产物：rockdev/Image-rk3576_u/dtbo.img

4. vendor_boot 镜像打包

参考说明：GKI 架构下，板级 KO 模块与其他 vendor 内容打包进 vendor_boot.img（以实际 SDK 为准）。

# 编译 vendor_boot（包含 KO 模块）
./build.sh -K -p

# 产物：rockdev/Image-rk3576_u/vendor_boot.img

5. HAL 库结构

参考说明：RK3576 Android 的 HAL 库路径与 RK 平台通用结构一致（以实际 SDK 为准）。

HAL 模块路径说明
Camerahardware/rockchip/camera/摄像头 HAL
Audiohardware/rockchip/audio/音频 HAL
Displayhardware/rockchip/hwcomposer/显示合成 HAL
RKNNexternal/rknn-toolkit2/NPU 推理工具链
VPU/MPPexternal/mpp/视频编解码
RGAexternal/rga/图像处理加速

6. RKNN 集成

参考说明：RK3576 的 NPU HAL 运行时为 rknnrt（librknnrt.so），通过 API 调用 6 TOPS 单核 NPU。

6.1 系统集成

# 确认板端 RKNN 运行时库存在
adb shell ls -l /vendor/lib64/librknnrt.so

# 确认 NPU 设备节点（RK3576 单核）
adb shell ls -l /dev/rknpu0

6.2 开发集成

7. 常见问题

7.1 模块未加载

现象： 开机后自定义驱动模块未自动加载。

解决方案：

  • 确认模块已打包进 vendor_boot
  • 检查设备树中对应的 status = "okay"
  • 使用 adb shell dmesg | grep <driver> 查看加载日志
  • 确认 KO 模块与内核版本匹配（GKI 内核需匹配 GKI 编译的 KO）

7.2 设备树修改不生效

解决方案：

  • 确认修改的是正确的板级 DTS 文件
  • 重新编译并烧录 dtbo.img + boot.img
  • 反编译 DTB 确认修改生效：
adb shell cat /sys/firmware/fdt > fdt.dtb
dtc -I dtb -O dts fdt.dtb | grep -A5 "uart2"

7.3 HAL 库加载失败

解决方案：

  • 确认 HAL 库路径正确（/vendor/lib64/ 等）
  • 使用 adb shell dumpsys 检查服务状态
  • 查看 logcat 中 hal 相关错误日志

8. 相关文档