OrangePi-3B 适配 AOSP 系列笔记:
- OrangePi-3B 适配 AOSP —— 介绍
- OrangePi-3B 适配 AOSP —— 准备编译环境
- OrangePi-3B 适配 AOSP —— 移植 U-Boot
- OrangePi-3B 适配 AOSP —— 移植 Kernel
- OrangePi-3B 适配 AOSP —— 移植 Android
- OrangePi-3B 适配 AOSP —— 移植 OPTEE
温馨提示:
- OrangePi-3B 硬件版本 V1.1.1 的板子出现过有线网卡“无故”失灵的故障, 所以在进行操作前请确认开发板工作良好(修复这个问题需要更换 RK3566 芯片).
https://www.bilibili.com/read/cv33224126- 香橙派目前已经推出了硬件版本为 V2.1 的 OrangePi-3B, 有线网卡供应商更换为 RTL. 本系列文章没有针对 V2.1 的板子做过适配, 请根据实际情况操作(同时强烈谴责此种不负责任的行为, 如考虑购买此型号板子商用, 建议换个型号避坑).
- 本系列文章最后更新时间: 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
- 核心项目是: https://android.googlesource.com/kernel/common
- 也可以使用纯
Git的项目(使用submodule依赖): https://android.googlesource.com/kernel/superproject- 分支
common-android12-5.10是最后一个使用Makefile作为构建工具的版本- 注意区分两个版本号:
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
- kleaf 使用 AOSP 预编译 clang 工具链(
prebuilts/clang/host/linux-x86),不走CROSS_COMPILE=aarch64-linux-gnu-,所以gcc-arm-linux-gnueabi/gcc-aarch64-linux-gnu装了也用不上- 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。
- 最初的配置是抄的
rockpi4的配置,只是一块基于rk3399的开发板。- 其中
_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
- Rockchip 的 SoC 支持必须住在共享 GKI 的 vmlinux 里(mixed build 下板级没有 vmlinux 承载它们)
CONFIG_ROCKCHIP_PM_DOMAINS不需要显式写 —— 它是bool+default ARCH_ROCKCHIP,随CONFIG_ARCH_ROCKCHIP=y自动生效- 实测 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)。
_ORANGEPI3B_MODULE_OUTS共 58 条,另有 1 条 watchdog(drivers/watchdog/dw_wdt.ko)在select()里,合计 59 个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 孪生。
- ⚠️
__tracepoint_X必须与__traceiter_X成对出现,否则build/kernel/abi/process_symbols.py:29报Missing symbols: ['__traceiter_*'] in 6xyun- ⚠️ 板级没有 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 里面不能出现一些注释,不然对比验证必然不过。
解法:有注释移除注释,重编一次。
参考
- https://source.android.com/docs/setup/build/building-kernels?hl=zh-cn
- https://source.android.com/docs/core/architecture/kernel?hl=zh-cn
- https://source.android.com/docs/devices/cuttlefish/kernel-dev?hl=zh-cn
- https://source.android.com/docs/setup/reference/bazel-support?hl=zh-cn
- https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/README.md
- https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/docs/abi.md
- https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/docs/kernel_config.md
- https://android.googlesource.com/kernel/build/+/refs/heads/main/kleaf/docs/fast.md
- https://docs.kernel.org/kbuild/llvm.html
- https://github.com/armbian/linux-rockchip