0%

OrangePi-3B 适配 AOSP —— 移植 Kernel

OrangePi-3B 适配 AOSP 系列笔记:

温馨提示:

  1. OrangePi-3B 硬件版本 V1.1.1 的板子出现过有线网卡“无故”失灵的故障, 所以在进行操作前请确认开发板工作良好(修复这个问题需要更换 RK3566 芯片).
    https://www.bilibili.com/read/cv33224126
  2. 香橙派目前已经推出了硬件版本为 V2.1 的 OrangePi-3B, 有线网卡供应商更换为 RTL. 本系列文章没有针对 V2.1 的板子做过适配, 请根据实际情况操作(同时强烈谴责此种不负责任的行为, 如考虑购买此型号板子商用, 建议换个型号避坑).
  3. 本系列文章最后更新时间: 2026年11月20日, 实现了初始化 TEE 环境, 填了一个 ATF 关于GPU的坑.

编译环境

  • 主板: OrangePi-3b_V1.1.1
  • 芯片: RK3566
  • 环境: Debian:13_x86_64(Docker)

内容说明

OrangePi 3B(RK3566)适配 Android 17 GKI(android17-6.18)内核,采用 mixed build(GKI 共享内核 + 板级模块)模式,与 AOSP 手机厂商(高通 db845c、MTK wonder 等)的做法对齐。

  • 板级提交:common 仓库 ci: add OrangePi 3B(分支 orangepi-3b)
  • 产物:GKI 110 个模块 + 板级 59 个模块 + 2 个 dtb(持续变更中)

移植

克隆代码

# Android-17-6.18
mkdir -p ~/projects/android/kernel_android-17-6.18/
cd ~/projects/android/kernel_android-17-6.18/
repo init -u https://android.googlesource.com/kernel/manifest -b common-android17-6.18
  1. 核心项目是: https://android.googlesource.com/kernel/common
  2. 也可以使用纯 Git 的项目(使用 submodule 依赖): https://android.googlesource.com/kernel/superproject
  3. 分支 common-android12-5.10 是最后一个使用 Makefile 作为构建工具的版本
  4. 注意区分两个版本号:repo init -b 填的是 manifest 仓库的分支(common-android17-6.18),而 common/ 子仓库的实际 revision 是 android17-6.18(无 common- 前缀)

启动容器

docker run -ti --rm --privileged -v ~/projects/:/projects/ build-android bash -l

容器中提前预装了软件:

sudo apt install \
# toolchain
make gcc g++ gcc-arm-linux-gnueabi g++-arm-linux-gnueabi gcc-aarch64-linux-gnu g++-aarch64-linux-gnu clang \
# bazel
perl rsync \
# kernel
bc binutils bison dwarves flex gcc git make openssl pahole perl-base libssl-dev libelf-dev

https://docs.kernel.org/admin-guide/quickly-build-trimmed-linux.html#install-build-requirements

  1. kleaf 使用 AOSP 预编译 clang 工具链(prebuilts/clang/host/linux-x86),不走 CROSS_COMPILE=aarch64-linux-gnu-,所以 gcc-arm-linux-gnueabi / gcc-aarch64-linux-gnu 装了也用不上
  2. kleaf 不识别 USE_CCACHE 环境变量(全仓无匹配),加速请用 --config=fast,详见 https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/docs/fast.md

代码修改

详情前往 Github: https://github.com/lx0758/android-kernel/commits/orangepi-3b/

本次改动共 8 个文件、1938 行插入,核心是把 OrangePi 3B 从"独立板级内核"改造成 mixed build。

  1. 最初的配置是抄的 rockpi4 的配置,只是一块基于 rk3399 的开发板。
  2. 其中 _ORANGEPI3B_MODULE_OUTS 可以先留空,编译过程中编译系统会报错,打印生成的 ko 文件,让添加到构建产物列表当中:
ERROR: The following kernel modules are built but not copied. Add these lines to the module_outs attribute of @@//common:orangepi3b:
  "drivers/regulator/tps65132-regulator.ko",
  "drivers/net/usb/kalmia.ko",
  "drivers/phy/rockchip/phy-rockchip-inno-dsidphy.ko",
  ...

https://source.android.com/docs/core/architecture/kernel/howto-abi-monitor?hl=zh-cn

改动清单

文件 作用
BUILD.bazel orangepi3b 目标改造为 mixed build;新增 _ORANGEPI3B_MODULE_OUTS
arch/arm64/configs/gki_defconfig GKI 共享配置,+3 行 Rockchip
arch/arm64/configs/orangepi3b_gki.fragment 板级配置(新建)
arch/arm64/boot/dts/rockchip/rk3566-orangepi-3b.dtsi 板级 DTS,OP-TEE / reboot-mode / USB otg
arch/arm64/boot/dts/rockchip/rk3566-orangepi-3b-v1.1.dts v1.1 板型 DTS(新建)
gki/aarch64/symbols/6xyun 板级 KMI 符号列表(新建,1156 个符号)
gki/aarch64/abi.stg GKI ABI 基线(+367 行)
init/main.c 打印 bootconfig 内容,便于调试

1. GKI 侧:3 行配置

arch/arm64/configs/gki_defconfig:

+CONFIG_ARCH_ROCKCHIP=y
+CONFIG_PCIE_ROCKCHIP_DW_HOST=y
+CONFIG_ROCKCHIP_IOMMU=y
  1. Rockchip 的 SoC 支持必须住在共享 GKI 的 vmlinux 里(mixed build 下板级没有 vmlinux 承载它们)
  2. CONFIG_ROCKCHIP_PM_DOMAINS 不需要显式写 —— 它是 bool + default ARCH_ROCKCHIP,随 CONFIG_ARCH_ROCKCHIP=y 自动生效
  3. 实测 GKI 模块数 110 → 110,清单逐字节一致(Rockchip 支持全进 vmlinux,0 个变成 .ko)

2. 板级 fragment:tristate 一律 =m

arch/arm64/configs/orangepi3b_gki.fragment(新建):

CONFIG_COMMON_CLK_RK808=m
CONFIG_CPUFREQ_DT=m
CONFIG_MFD_RK8XX=m
...
CONFIG_TEE=m
CONFIG_OPTEE=m

⚠️ 三条关键规则:

# 规则 原因
R1 板级 fragment 里所有 tristate 符号必须 =m mixed build 下板级没有 vmlinux,scripts/Makefile.build:78-81 会把 obj-y 静默丢弃 → 写 =y 会无声消失
R2 复合模块的成员保留 =y ROCKCHIP_VOP2 / ROCKCHIP_ANALOGIX_DP / ROCKCHIP_DW_HDMI / ROCKCHIP_DW_MIPI_DSI 会合并成单个 .ko,写 =m 会拆散
R3 板级模块引用的 GKI 符号必须在 6xyun 列表里 GKI 的 CONFIG_TRIM_UNUSED_KSYMS=y 会裁掉不在白名单的导出符号 → 板级 modpost 报 undefined

同时删除了以下无用/已失效的符号:

符号 原因
PCIE_ROCKCHIP_HOST 只匹配 rk3399,RK3566 用不上
POWER_RESET_SYSCON_POWEROFF 死符号
REGULATOR_GPIO 死符号
CONFIG_SND_SOC_ROCKCHIP 当前内核树已无此聚合符号,只剩 _I2S/_PDM/_SPDIF 等子符号

3. BUILD.bazel:mixed build 改造

kernel_build(
    name = "orangepi3b",
    srcs = [":kernel_aarch64_sources"],
    outs = [
        "arch/arm64/boot/dts/rockchip/rk3566-orangepi-3b-v1.1.dtb",
        "arch/arm64/boot/dts/rockchip/rk3566-orangepi-3b-v2.1.dtb",
    ],
    arch = "arm64",
    # Enable mixed build.
    base_kernel = ":kernel_aarch64",                 # ← mixed build 的开关
    collect_unstripped_modules = True,
    defconfig = "arch/arm64/configs/gki_defconfig",
    generate_out_targets = False,
    kmi_symbol_list = "gki/aarch64/symbols/6xyun",   # ← 板级 KMI 列表
    make_goals = [
        "modules",
        "rockchip/rk3566-orangepi-3b-v1.1.dtb",
        "rockchip/rk3566-orangepi-3b-v2.1.dtb",
    ],
    makefile = ":Makefile",
    module_outs = _ORANGEPI3B_MODULE_OUTS + select({
        "//build/kernel/kleaf:kgdb_is_true": [],
        "//conditions:default": _ORANGEPI3B_WATCHDOG_MODULE_OUTS,
    }),
    pre_defconfig_fragments = ["arch/arm64/configs/orangepi3b_gki.fragment"],
    strip_modules = select({
        "//build/kernel/kleaf:debug_is_true": False,
        "//conditions:default": True,
    }),
)

kernel_abi(
    name = "orangepi3b_abi",
    kernel_build = ":orangepi3b",
    kmi_symbol_list_add_only = True,
)

对照 rockpi4(改造前,抄的那份)逐项列出差异:

属性 rockpi4(改造前) orangepi3b(改造后)
base_kernel 无 新增 ":kernel_aarch64"
outs Image/System.map/vmlinux/modules.builtin* 只留 2 个 dtb
make_goals 含 "Image" 去掉 "Image"
module_outs get_gki_modules_list() + get_kunit_modules_list() + 板级 只留板级(_ORANGEPI3B_MODULE_OUTS)
kmi_symbol_list 无 "gki/aarch64/symbols/6xyun"
kmi_symbol_list_strict_mode False 删除(板级不需要 1-1 严格匹配)
trim_nonlisted_kmi False 删除(与 db845c 一致,默认不 trim)

不变式:板级 module_outs ∩ GKI 模块列表 = ∅(实测 0)。

  1. _ORANGEPI3B_MODULE_OUTS 共 58 条,另有 1 条 watchdog(drivers/watchdog/dw_wdt.ko)在 select() 里,合计 59 个
  2. module_outs 声明的模块必须和实际产出完全一致,多一个少一个都会失败

4. 6xyun 符号列表:解决 modpost undefined

问题:GKI 的 CONFIG_TRIM_UNUSED_KSYMS=y 会把 vmlinux.symvers 裁剪成只剩 KMI 白名单里的符号。板级 modpost 通过 scripts/Makefile.modpost:137 的 -i vmlinux.symvers 引用 GKI 符号表 → 白名单外的符号解析不到 → 23 个 undefined。

解法:新建 gki/aarch64/symbols/6xyun(1156 个符号),并加入 GKI 的 additional_kmi_symbol_lists:

filegroup(
    name = "aarch64_additional_kmi_symbol_lists",
    srcs = [
        # keep sorted
        "gki/aarch64/symbols/6xyun",
        "gki/aarch64/symbols/allwinner",
        ...
    ],
)

其中有 22 个符号是 GKI 新导出(原先被 trim 掉),逐个在源码确认了 EXPORT_SYMBOL:

__sdhci_execute_tuning  _bcd2bin  _bin2bcd  clk_get_phase  clk_set_phase
clk_unregister  component_master_is_bound  dev_pm_genpd_rpm_always_on
dev_warn_probe  drm_dev_set_dma_dev  drm_format_info_min_pitch
drm_gem_fb_afbc_init  drm_gem_fb_init_with_funcs  of_usb_get_dr_mode_by_phy
phy_mipi_dphy_config_validate  pwm_adjust_config  regulator_find_closest_bigger
sdhci_end_tuning  sdhci_pltfm_remove  sdhci_set_power_and_bus_voltage
sdhci_start_tuning  v4l2_fill_pixfmt_mp

维护方式(用官方工具,不要手工维护):

cd /projects/android/kernel_android-17-6.18/

tools/bazel run //common:orangepi3b_abi_update_symbol_list

工具从最终 .ko 提取符号,自动处理 module_layout / __versions / tracepoint 孪生。

  1. ⚠️ __tracepoint_X 必须与 __traceiter_X 成对出现,否则 build/kernel/abi/process_symbols.py:29 报 Missing symbols: ['__traceiter_*'] in 6xyun
  2. ⚠️ 板级没有 ABI 基线,//common:orangepi3b_abi_update 是 fail_rule(板级的 kernel_abi() 未提供 abi_definition_stg),跑它会直接报错。板级只有 _update_symbol_list 和 _extracted_symbols 两个可用目标

5. DTS 改动

+#include <dt-bindings/soc/rockchip,boot-mode.h>

+	firmware {
+		optee {
+			compatible = "linaro,optee-tz";
+			method = "smc";
+		};
+	};
+
+	reserved-memory {
+		#address-cells = <2>;
+		#size-cells = <2>;
+		ranges;
+
+		secure_ddr: optee@8400000 {
+			reg = <0x0 0x08400000 0x0 0x02000000>;
+			no-map;
+		};
+	};

+&i2c2 {
+	pinctrl-0 = <&i2c2m1_xfer>;
+	status = "okay";
+};

-	dr_mode = "host";
+	dr_mode = "otg";

+&pmugrf {
+	reboot-mode {
+		compatible = "syscon-reboot-mode";
+		offset = <0x200>;
+		mode-normal = <BOOT_NORMAL>;
+		mode-loader = <BOOT_BL_DOWNLOAD>;
+		mode-recovery = <BOOT_RECOVERY>;
+		mode-bootloader = <BOOT_FASTBOOT>;
+	};
+};

v1.1 板型(rk3566-orangepi-3b-v1.1.dts)额外包含 sprd-mtty / uwe-bsp 节点、&sdhci 150 MHz、&gmac1 + RGMII PHY。

启动编译

cd /projects/android/kernel_android-17-6.18/

# 场景:改驱动 / 配置 / DTS,要出包烧机
# 产物在 `out/orangepi3b/dist`;只构建不安装时把 `run` 换成 `build`。
tools/bazel run --config=fast --jobs=$(nproc) --keep_going \
  --make_jobs=$(nproc) --make_keep_going //common:orangepi3b_dist

# 场景:只想确认板级能编过,不打 dist
# 只验证内核与模块能编译,不产出 dist。
tools/bazel build --config=fast //common:orangepi3b

# 场景:改了 GKI 或公共内核代码
# 板级是 mixed build,Bazel 会自动带 GKI;先编 GKI 只是为了先看到它的报错。
tools/bazel build --config=fast //common:kernel_aarch64
tools/bazel run   --config=fast //common:orangepi3b_dist

# 场景:改了设备符号列表 gki/aarch64/symbols/6xyun
# 改 `6xyun` 就是改 GKI 的 KMI 白名单,GKI 必须重建,否则新符号不会真正导出。
tools/bazel run   --config=fast //common:orangepi3b_abi_update_symbol_list
tools/bazel build --config=fast //common:kernel_aarch64
tools/bazel run   --config=fast //common:orangepi3b_dist

# 场景:ABI 检查 / 刷新 abi.stg
# 退出码 4 = 检测到 ABI 差异,属正常语义;0 = 零差异。
tools/bazel run --config=fast //common:kernel_aarch64_abi_update

目标 orangepi3b_dist 产物路径是 out/orangepi3b/dist,目标 kernel_aarch64_abi_dist 产物路径是 out_abi/kernel_aarch64/dist。
参数 --make_jobs 作用是设置编译线程数量;参数 --keep_going、--make_keep_going 作用是遇到错误继续;这两个参数只有 tools/bazel 认,直接用 bazel 会报未知参数。
参数 --config=fast 是 Kleaf 的开发加速配置(等价 --config=local),不加则每次全量构建;切换前后各跑一次 tools/bazel clean;具体参见 build/kernel/kleaf/docs/sandbox.md。
修改输出路径可以用 --destdir,需要清空目标目录时可以用 --wipe_destdir,但注意需要用 -- 隔开,比如:tools/bazel run --config=fast //common:kernel_aarch64_abi_dist -- --destdir=out/dist。
不要跑 //common:kernel_aarch64_abi_update_symbol_list:它会覆盖 GKI 的 KMI 基线 gki/aarch64/symbols/base,设备符号只加到 6xyun。

https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/docs/fast.md
https://ci.android.com/builds/branches/aosp_kernel-common-android15-6.6/grid?legacy=1

如果编译出错,可以添加 --sandbox_debug 参数打印过程脚本。一些编译过程文件在这:

out/bazel/output_user_root/<hash>/command.log
out/bazel/output_user_root/<hash>/execroot/_main/bazel-out/_tmp/actions/stderr-x

⚠️ 从失败构建里捞中间产物(调试 modpost undefined 的关键技巧):

cd /projects/android/kernel_android-17-6.18/

# modpost 是 make modules 的最后一步,失败时 .ko 还没链接,
# 但中间的 .o 已经在 sandbox 里编译好了,符号表完整
find out/bazel/output_user_root/*/sandbox/sandbox_stash/KernelBuild/*/ -name "*.o"

# 提取板级模块的完整 undefined 符号集
nm -u <module>.o | awk 'NF==3 && $2=="U" {print $3}'

modpost 最多只报 10 条(scripts/mod/modpost.c:73 的 MAX_UNRESOLVED_REPORTS = 10),必须用上面的方法拿到完整列表

正规调配置的方式(比手工 make menuconfig 好,kleaf 会自动把差异写回 fragment):

cd /projects/android/kernel_android-17-6.18/

tools/bazel run //common:orangepi3b_config -- menuconfig

https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/docs/kernel_config.md

问题

Q1: 板级 fragment 里写 =y 的符号不报错,但功能就是没有

根因:mixed build 下板级没有自己的 vmlinux。scripts/Makefile.build:78-81 在 mixed build 时会把 obj-y 条目静默丢弃 —— 写 =y 既不报错也不生效。

解法:板级 fragment 里所有 tristate 符号一律改 =m;只有复合模块成员(ROCKCHIP_VOP2 / ROCKCHIP_ANALOGIX_DP / ROCKCHIP_DW_HDMI / ROCKCHIP_DW_MIPI_DSI)保留 =y。

Q2: ERROR: modpost: "xxx" [xxx.ko] undefined!

根因:GKI 的 CONFIG_TRIM_UNUSED_KSYMS=y 把 vmlinux.symvers 裁剪成只剩 KMI 白名单(abi_symbollist.raw)里的符号。板级 modpost 通过 scripts/Makefile.modpost:137 的 -i vmlinux.symvers 引用它 → 白名单外的符号解析不到。

实测数据:

指标 数量
GKI vmlinux.symvers(trim 后) 9542
板级 undefined 符号总数 1243
板级自身导出(自供) 748
板级需外部提供 1146
├ 已在 GKI 白名单里 1124
└ 被 trim 掉、需新增导出 22
GKI 完全无法提供的 0

解法:把符号加进 gki/aarch64/symbols/6xyun,并确保它在 GKI 的 aarch64_additional_kmi_symbol_lists 里,然后重建 GKI。

Q3: --debug_modpost_warn=true 不起作用

根因:build/kernel/kleaf/impl/debug.bzl:67 的 _modpost_warn 只在 kernel_module.bzl(外部模块 DDK)里被调用,kernel_build.bzl(in-tree 内核构建)根本没调用它。

解法:换方案 —— 用 --sandbox_debug 从失败构建的 sandbox 里捞出已编译好的 .o,用 nm -u 手工提取完整 undefined 符号集。

Q4: ERROR: Missing symbols: ['__traceiter_*'] in 6xyun

根因:build/kernel/abi/process_symbols.py:29 的 _validate_symbols 要求 __tracepoint_X 与 __traceiter_X 成对出现。

解法:补齐对应的 __traceiter_* 孪生符号(本项目补了 7 个)。更好的做法是用官方工具 tools/bazel run //common:orangepi3b_abi_update_symbol_list 重新生成。

Q5: nm -u 提取的符号比官方工具少 3 个

根因:module_layout 在 __versions 段,nm -u 对未链接的 .o 看不到它(modpost 链接时才校验)。

解法:以官方工具从最终 .ko 的提取结果为准。差异的 3 个符号是 module_layout、__put_task_struct、utf8_data_table(后者来自 build/kernel/abi/extract_symbols.py:31-35 的 _ALWAYS_INCLUDED)。

Q6: bazel run ..._abi_dist -- --dist_dir=out/dist 报 unrecognized arguments

根因:dist 目标底层是 rules_pkg 的 pkg_install,其命令行参数只有 --destdir 和 --wipe_destdir(external/rules_pkg+/pkg/private/install.py.tpl:249-258)。

注意:kleaf 自己的 docs/bug_template.md:36 里也写的 --dist_dir —— 那是上游文档的笔误,docs/abi.md:8 的 --destdir 才对。

解法:改用 --destdir=out/dist。

Q7: tools/bazel run //common:orangepi3b_abi_update 直接报错

报错:Error in fail: In orangepi3b_abi 'define_abi_targets' is True but 'abi_definition_stg' was not provided.

根因:板级的 kernel_abi() 没有提供 abi_definition_stg(板级不共享 GKI 的 abi.stg),kleaf 走 build/kernel/kleaf/impl/abi/kernel_abi.bzl:332 的另一分支,把 update 生成为 fail_rule。

解法:板级只用 //common:orangepi3b_abi_update_symbol_list(维护 6xyun)和 //common:orangepi3b_abi_extracted_symbols(只提取不覆盖)。

Q8: kernel_aarch64_abi_update_symbol_list 触发无谓的 GKI 重建

根因:该目标的语义是用 extracted_symbols 覆盖 gki/aarch64/symbols/base(kernel_abi.bzl:290-295 的 dst = name + "_src_kmi_symbol_list")。

解法:本项目跳过这一步。只有真正修改了 GKI 导出符号时才需要动 base。

Q9: 报错信息里的 //common:orangepi3b_no_kgdb 找不到

根因:上游提交 23d421754c87 "ANDROID: simplify kgdb targets." 删除了 db845c_no_kgdb / rockpi4_no_kgdb / yukawa_no_kgdb 这类副本目标,改为在 module_outs 里直接用 select():

module_outs = _ORANGEPI3B_MODULE_OUTS + select({
    "//build/kernel/kleaf:kgdb_is_true": [],
    "//conditions:default": _ORANGEPI3B_WATCHDOG_MODULE_OUTS,
}),

解法:目标名就是 //common:orangepi3b,不需要 _no_kgdb 副本。

Q10: 干跑 module_outs 少 3 个 .ko

根因:静态分析漏了连带 select:SYSCON_REBOOT_MODE → REBOOT_MODE、HW_RANDOM_OPTEE depends on OPTEE、ARM_SCMI_TRANSPORT_OPTEE depends on OPTEE。

解法:以实际构建报错为准(kleaf 会打印所有未声明的 .ko),或用 buildozer 'add module_outs ...' 一键补全。

Q11: export USE_CCACHE=1 没有效果

根因:kleaf 全仓不识别该环境变量(grep -rn 'USE_CCACHE' 无匹配)。容器里虽然装了 ccache 4.11.2,但 kleaf 不调用它。

解法:用 --config=fast(build/kernel/kleaf/docs/fast.md),或依赖 bazel 自身的 action cache。

Q12: make X_defconfig 会消耗掉源 defconfig 文件

根因:Kbuild 的 savedefconfig 行为 —— 它会覆写源 defconfig。

解法:每次做实验前重新拷贝一份;或直接用 tools/bazel run //common:orangepi3b_config -- menuconfig,kleaf 会把差异正确地写回 pre_defconfig_fragments。

Q13: savedefconfig does not match common/arch/arm64/configs/gki_defconfig 报错

根因:修改了 gki_defconfig 导致。并且 gki_defconfig 里面不能出现一些注释,不然对比验证必然不过。

解法:有注释移除注释,重编一次。

参考