0%

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

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)

内容说明

移植

克隆代码

克隆 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
  1. 关于 lunch 的介绍可参考后面的专题。
  2. 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.

容器环境缺少权限导致.

https://blog.csdn.net/yyzsyx/article/details/117963081

解决办法: 运行容器加上 --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)的季度列车式发布配置,另一条线。
  1. AOSP 自带配置由 Google 定义,不接受修改;需要自定义开关组合请在自己分支新增 release config。
  2. 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

参考