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)
内容说明
移植
克隆代码
克隆 AOSP 代码
mkdir -p ~/projects/android/android_17/
cd ~/projects/android/android_17/
repo init --partial-clone -u https://android.googlesource.com/platform/manifest -b android17-release
引用设备代码
为了方便管理源码, 我在 .repo/local_manifests/6xyun.xml 加了一些自定义的 repo 仓库:
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<remote name="github" fetch="ssh://git@github.com" />
<project path="device/6xyun" remote="github" name="lx0758-android/device_6xyun" revision="android17-release">
<!-- AGENTS -->
<linkfile src=".root/AGENTS.md" dest="AGENTS.md" />
<linkfile src=".root/.agents" dest=".agents" />
<linkfile src=".root/openspec" dest="openspec" />
<!-- VENDOR -->
<linkfile src=".root/vendor_6xyun" dest="vendor/6xyun" />
</project>
<repo-hooks enabled-list="post-sync" in-project="lx0758-android/device_6xyun" />
</manifest>
上面的 hook 会额外创建两个软连接, 指向 U-Boot 和 GKI Kernel 仓库路径, 效果等同于:
ln -s ../../bootloader/u-boot b-boot
ln -s ../kernel_android-17-6.18 kernel-6.18
启动容器
docker run -ti --rm --privileged -v ~/projects/:/projects/ build-android bash -l
容器中提前预装了软件:
sudo apt install \
# android
git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip procps
https://source.android.com/docs/setup/initializing?hl=zh-cn#installing-required-packages-ubuntu-1404
代码修改
分区规划
https://source.android.com/docs/core/architecture/partitions?hl=zh-cn
https://source.android.com/docs/core/architecture/bootloader/partitions/generic-boot?hl=zh-cn
启动构建
可选启用 ccache 加速,记得映射工作目录:
export USE_CCACHE=1
默认工作目录:
~/.cache/ccache/。
cd /projects/android/android_17/
# 导入环境变量
source build/envsetup.sh
# 选择构建配置(新写法, 等价 lunch orangepi_3b-cp2a-userdebug)
lunch orangepi_3b cp2a userdebug
# 开始构建
m
- 关于
lunch的介绍可参考后面的专题。m命令默认会全开线程,编译过程中对内存峰值要求比较高。
问题
执行 lunch 命令报错
$ lunch
No target specified. See lunch --help
据说是 Google 对 Android 14.0.0-r50 开始的构建过程和配置进行了更改。
解决办法: 旧的交互式菜单和硬编码的"精选目标列表"已经被移除了。所以你以前 lunch 一下出现一堆编号选项的体验没有了,现在必须自己查、自己拼。使用三段式命令制定构建产品 lunch <product_name> <release_config> <build_variant> 或 lunch <product_name>-<release_config>-<build_variant>。
报错:Build sandboxing disabled due to nsjail error.
$ m
Build sandboxing disabled due to nsjail error.
容器环境缺少权限导致.
解决办法: 运行容器加上 --privileged 参数.
报错:error code 137
FAILED: //packages/modules/Wifi/service:service-wifi r8[common apex31]
Outputs: ...
Error: exited with code: 137
Command: ...
Output:
stderr:
Killed
error: ninja:
2h17m49.17s Build Failure: 137088 done, 1 failed, 38195 remaining - 16.58/s
1 steps failed: exit=137 # signal:killed
一般是内存不够导致的, 而且一定要有 swap, 前不久我用 64G 物理内存但没有 swap 的环境来编译, 也报错了.
编译核心数开得越多, 需要的峰值内存也越大.
内核打印不停干扰调试
驱动没有完全就绪的时候, 串口可能会因为系统循环重启而一直打印日志, 无法进行串口调试. 可以通过下面的命令静音:
dmesg -n 1
dmesg -n 1 的作用是:把内核输出到控制台的日志级别设为 1,也就是只允许 KERN_ALERT 及更紧急的消息出现在控制台。
内核日志级别从 0 到 7,数字越小越紧急:
| 级别 | 含义 |
|---|---|
| 0 | KERN_EMERG,系统不可用 |
| 1 | KERN_ALERT,需要立即处理 |
| 2 | KERN_CRIT,严重错误 |
| 3 | KERN_ERR,错误 |
| 4 | KERN_WARNING,警告 |
| 5 | KERN_NOTICE,正常但重要 |
| 6 | KERN_INFO,普通信息 |
| 7 | KERN_DEBUG,调试信息 |
dmesg -n 改的是 console_loglevel,也就是“哪些内核消息会打印到当前控制台/串口”。它不会清除内核环形缓冲区,也不影响 dmesg 命令本身读取日志。 |
AOSP lunch 目标速查
lunch 目标格式:lunch <product_name> <release_config> <build_variant> 或 lunch <product_name>-<release_config>-<build_variant>
例:lunch aosp_cf_x86_64_phone cp2a userdebug(新版 AOSP 已移除交互式菜单,需自己拼串)
release_config —— 决定「开哪些功能」
build/release/release_configs/ 下每个 .textproto 对应一个可选配置,本质是build/release/aconfig/<config_name>/ 目录,存放该版本所有功能启动标记(flag)的取值。
trunk_staging/eng:开发类。正式发布前测试功能用,flag 多为READ_WRITE,可运行时启停,便于调试但行为可变。ap2aap4a、bp1abp4a、cp1a、cp2a:发布类。flag 多为READ_ONLY,反映该版本最终启用的全部代码;只读标记是运行时不可改的布尔常量,编译器还可能把未执行的代码从构建里直接排除。行为固定、可复现。mainline_2026_01~04:Mainline 模块(APEX,如 ART/Media)的季度列车式发布配置,另一条线。
- AOSP 自带配置由 Google 定义,不接受修改;需要自定义开关组合请在自己分支新增 release config。
xpxa代号怎么读:它就是 Build ID 里的BB段——Google 用来识别 build 所属确切代码分支的代码。首字母 a/b/c = 第几轮年度发布序列;中间数字 1~4 = 该序列内第几个季度快照;末尾 a = 该快照的初始修订。所以bp3a= b 系列 Q3 快照。它标识的是代码分支,不是成熟度等级:bp1a→bp3a的差异是「这个季度哪些 flag 被正式打开了」,而非「新塞了一批代码」——代码早在同一份源码树里,只是被 flag 隔离。
build_variant —— 决定「怎么构建」
只有三个取值,影响权限、调试能力与性能取向:
eng:构建更快,适合不在意性能功耗的日常开发。ro.secure=0、ro.debuggable=1,默认开 adb。userdebug:用于分析开发中版本的性能/功耗;与 user 同,但额外装 debug 模块、ro.debuggable=1、默认开 adb。user:安全访问权限有限,生产环境。ro.secure=1、ro.debuggable=0,默认关 adb。
两者可自由组合,如 trunk_staging-userdebug、cp2a-user。
BUILD_ID —— 这次构建的版本标识
写入 /system/build.prop 的 ro.build.id(即 Build.ID),格式 PVBB.YYMMDD.bbb[.Cn]:
| 段 | 含义 | 示例 CP2A.260605.016 |
|---|---|---|
| P | 平台版本代号首字母 | C(本轮大版本) |
| V | 支持的类别(P = 主要平台分支) | P |
| BB | 分支代码 = release_config 代号 | 2A → cp2a |
| YYMMDD | 切出/与开发分支同步日期(非真实构建日期) | 260605 |
| bbb | 同一日期代码下的第几个版本,从 001 起 | 016 |
| Cn | 可选,在其之上打的修补程序 | 无 |
关键:lunch 里的 release_config 取的就是 BUILD_ID 前四位的分支代码,两者必须对得上,
否则构建出的 flag 组合与你要复现的版本不一致。lunch 之后终端输出里就有 BUILD_ID 字段可直接核对。
选取策略
- 日常开发、调试新功能 →
trunk_staging - 复现某个已发布版本 → 用与该版本 Build ID 完全一致的代号(如
cp2a对CP2A.xxxxxx.xxx) - 追求稳定、可复现的构建 → 任选发布类配置,优先取最新的
- 调试 APEX 独立更新 →
mainline_2026_xx
常用命令
source build/envsetup.sh # 每个新 shell 都要先执行
list_products # 列出当前源码树所有可用产品
list_releases [product] # 列出 release config(带产品名看该产品支持的)
list_variants # 列出可用 variant