系列第 1 / 6 篇 · 基于 Android 14(
PLATFORM_SDK_VERSION = 34)系列目录(规划):
- 总览:A/B 无缝升级架构与核心组件(本篇)
- OTA 包的构成与生成:payload.bin / metadata / otacert 与
ota_from_target_files- 升级链路:Java
UpdateEngineAPI、自研 HAL 与 MQTT(emu)三条路怎么选- update_engine 内部机制:Action 流水线、下载、校验与 postinstall
- 切槽、回滚保护与升级后首启:bootctl HAL、update_verifier、checkpoint
- 非 A/B 设备对照:传统 Recovery 升级、sideload 与现场刷机(附 A9 设备移植对照)
0. 一句话总纲
Android 14 上做系统升级,第一步不是写代码,而是先确认设备的升级形态: 设备是 A/B(无缝)升级还是传统 Recovery 升级,两者从包格式、应用方式、失败恢复到 排障入口完全是两套体系。AOSP 14 主推且本系列的主线是 A/B:
A/B 升级的本质:所有可升级分区都有两份(slot A / slot B)。升级时 update_engine 把 payload 写进"非当前"的那一份,然后只改一个引导标志位,让 bootloader 下次从新槽启动; 新槽启动失败,bootloader 自动回退老槽——全程不进 Recovery,不清 /data,也不停机。
┌─────────── 在线阶段(当前 slot 运行中)───────────┐
系统更新 App ──applyPayload──▶ update_engine(Binder 服务)
│ 1. 下载 payload.bin(边下边解)
│ 2. 校验整包 hash
│ 3. 把分区数据写入 target slot
│ 4. 跑 postinstall
▼
状态 UPDATED_NEED_REBOOT(此时系统仍在老版本运行)
└────────────────────┬───────────────────────────┘
│ 重启(bootloader 切到新 slot)
┌─────────── 重启后(已在新 slot)──────────────────┐
init ──▶ update_verifier ──按 care_map 读回校验新槽的块──▶ 一切正常
│ ▼
│ bootctl: MarkBootSuccessful
▼ ▼
校验失败 → 重启回老槽 slot 标记 successful(升级落定)
└──────────────────────────────────────────────────┘
1. 先判断你的设备是哪种升级形态
拿到一块板子,先做三件事:
# ① 有没有槽位后缀(A/B 设备非空:_a 或 _b)
adb shell getprop ro.boot.slot_suffix
# ② 有没有 update_engine 产物
adb shell ls -l /system/bin/update_engine /system/bin/update_verifier /system/bin/bootctl
# ③ build.prop 里的 A/B 标记
adb shell getprop ro.build.ab_update
| 观测结果 | 结论 |
|---|---|
ro.boot.slot_suffix 非空 + update_engine 存在 | A/B 设备,走本系列主线(update_engine 方案) |
ro.boot.slot_suffix 为空、无 update_engine | 传统 Recovery 设备(如 Android 9 的 p291_iptv/TB612),升级包交给 Recovery 安装,见系列第 6 篇 |
源码侧对应的开关只有一个变量——AB_OTA_UPDATER。以产品 raman 为例:
# device/amlogic/raman/raman.mk
AB_OTA_UPDATER ?= true
设置后 build/make/core/main.mk 会把它暴露成系统属性:
ifdef AB_OTA_UPDATER
ADDITIONAL_DEFAULT_PROPERTIES += ro.build.ab_update=$(AB_OTA_UPDATER)
配套的还有三个"产品级事实"要一起确认(可查 fstab 与产物目录):
| 事实 | 怎么看 | 对升级的影响 |
|---|---|---|
| 分区带槽位后缀 + 逻辑分区 + AVB | fstab:system ... wait,slotselect,avb=vbmeta_system,logical,first_stage_mount | payload 的写入目标全部是带 _b 后缀的逻辑/物理分区 |
| 没有独立 recovery 分区 | 产物里没有 recovery.img(只有 recovery/root 暂存目录) | OTA 不再走 Recovery;RecoverySystem API 只剩"恢复出厂/擦除"用途 |
| update_engine 常驻但默认 disabled | update_engine.rc:disabled + on property:ro.boot.slot_suffix=* enable update_engine | 非 A/B 设备上该服务永远不启动 |
2. A/B 设备上的三个核心角色
2.1 slot 模型:两个属性决定一切
每个 slot 由 bootloader + bootctl HAL 共同维护三个属性,其中两个最关键:
- active:下次开机 bootloader 尝试启动哪个槽(
setActiveBootSlot设置); - successful:这个槽完整启动成功过(由用户空间的
update_verifier在校验后标记); - bootable:槽是否可尝试启动。
一句话规则:bootloader 只从 active 且 bootable 的槽启动;只有 successful 的槽才算"活下来了", 否则重试若干次后回退到上一个 successful 槽。 这也是 A/B 设备 OTA 出问题最多表现为"回滚" 而不是"变砖"的原因。
验证槽状态的常用命令:
adb shell getprop ro.boot.slot_suffix # 当前槽:_a / _b
adb shell getprop ro.boot.slot_successful # 0=未确认(升级后首启常见) 1=已确认
adb shell bootctl get-current-slot # 数值形式 0=A / 1=B
adb shell bootctl mark-boot-successful # 手动确认(调试用)
2.2 update_engine:唯一的"应用升级"执行者
它是常驻的 root 守护进程,负责下载、校验、写分区、跑 postinstall,全部动作都只写 target slot。
它通过 init 拉起(system/update_engine/update_engine.rc,本地树已核对):
service update_engine /system/bin/update_engine --logtostderr --logtofile --foreground
class late_start
user root
group root system wakelock inet cache media_rw
task_profiles OtaProfiles
disabled
on property:ro.boot.slot_suffix=*
enable update_engine
两个值得背下来的细节:
- 服务默认
disabled,只有ro.boot.slot_suffix非空(A/B 设备)才被 enable—— 这就是"传统方案设备上没有 update_engine"的开关点; --logtostderr --logtofile:日志同时进 logcat 和文件(/data/misc/update_engine_log/)。 排障时两边都要看,设备重启后 logcat 会丢,文件里的还在。
它对上层暴露 两个 Binder 服务(同一个后端,两套 AIDL),注册点在
system/update_engine/aosp/daemon_android.cc:
auto binder_wrapper = android::BinderWrapper::Get();
// Create the Binder Service.
binder_service_ = new BinderUpdateEngineAndroidService{
daemon_state_android->service_delegate()};
if (!binder_wrapper->RegisterService(binder_service_->ServiceName(),
binder_service_)) {
LOG(ERROR) << "Failed to register binder service.";
}
daemon_state_->AddObserver(binder_service_.get());
// Create the stable binder service.
stable_binder_service_ = new BinderUpdateEngineAndroidStableService{
daemon_state_android->service_delegate()};
...
daemon_state_->StartUpdater();
| Binder 服务名 | 定义处 | 给谁用 |
|---|---|---|
android.os.UpdateEngineService | aosp/binder_service_android.h | framework 内部 API:android.os.UpdateEngine(Java) |
android.os.UpdateEngineStableService | aosp/binder_service_stable_android.h | stable API:IUpdateEngineStable(GMS / 自研升级服务 / NDK binder) |
真机验证:adb shell service list | grep update,两个服务都应该在。
2.3 bootctl HAL 与 update_verifier:切槽与验收
- bootctl HAL(
android.hardware.boot-service):slot 的读/写/确认全部最终落到这层。 update_engine 平台无关,Amlogic/MTK 等厂商各自实现 bootctl(改引导标志/分区属性)。 平台适配排障时,SetActiveBootSlot失败基本等于"HAL 没实现好或引导分区读写失败"。 - update_verifier(独立进程,源码在
bootable/recovery/update_verifier/):新槽首次开机 时由 init 拉起的"验收员"——按 payload 生成的 care_map 把新槽被覆盖的块全部读一遍 (dm-verity 校验),读失败立即重启回老槽;全部通过才调MarkBootSuccessful落定升级。 详见系列第 5 篇。
3. 一次 A/B OTA 的完整生命周期(分阶段地图)
把整个流程按"谁在哪个进程做了什么"铺开,后面几篇都会反复回到这张表:
| 阶段 | 进程 | 做什么 | 关键源码(本地树已核对) | 日志/观测锚点 |
|---|---|---|---|---|
| ① 触发 | 系统更新 App / 自研服务 | 下载或指定 payload,调 applyPayload(url, offset, size, headers) | frameworks/base/core/java/android/os/UpdateEngine.java:348 | 应用侧日志 applyPayload url= |
| ② 入口 | update_engine | Binder 收到请求 → 防御检查(已在 UPDATED_NEED_REBOOT / 非空闲则拒绝)→ 组装 InstallPlan | aosp/update_attempter_android.cc:279(source/target slot 赋值) | Using this install plan: |
| ③ 流水线 | update_engine | UpdateBootFlags → CleanupPreviousUpdate → Download → FilesystemVerifier → Postinstall 五个 Action 接力 | aosp/update_attempter_android.cc BuildUpdateActions() | 各阶段关键字,见第 4 篇对照表 |
| ④ 完成 | update_engine | 状态置 UPDATED_NEED_REBOOT,等重启;SWITCH_SLOT_ON_REBOOT=1(默认)时重启切槽 | aosp/boot_control_android.cc SetActiveBootSlot → bootctl HAL | Marking boot as...、SetActiveBootSlot |
| ⑤ 首启验收 | update_verifier | 查 slot 未 successful → 按 care_map 读回校验 → 通过则 MarkBootSuccessful | bootable/recovery/update_verifier/update_verifier.cpp:319 | Booting slot ... isSlotMarkedSuccessful=、Marked slot ... as booted successfully |
| ⑥ 落定 | bootctl HAL | slot 标记 successful;此后该槽成为"上一个 successful 槽" | bootctl HAL 实现 | getprop ro.boot.slot_successful = 1 |
最核心的一条设计约束在第 ② 阶段就已确定(update_attempter_android.cc):
install_plan_.source_slot = GetCurrentSlot();
install_plan_.target_slot = GetTargetSlot();
payload 里所有分区写操作都落在 target_slot,当前正在运行的系统一个字节都不动—— 这就是"无缝"二字的实现基础,也是为什么升级过程中设备可以照常使用、失败也不伤及现行系统。
4. Java 侧调用面:android.os.UpdateEngine 是个薄壳
framework 里的 UpdateEngine 不做任何业务逻辑,applyPayload 直接跨 Binder:
// frameworks/base/core/java/android/os/UpdateEngine.java
public void applyPayload(String url, long offset, long size, String[] headerKeyValuePairs) {
try {
mUpdateEngine.applyPayload(url, offset, size, headerKeyValuePairs);
} catch (RemoteException e) {
throw e.rethrowFromSystemServer();
}
}
参数语义先建立直觉(第 2、3 篇展开):
| 参数 | 含义 |
|---|---|
url | 指向整包 zip 的 http(s):// 或 file:// 地址,也可以直接指向 payload.bin |
offset / size | payload 在包内的偏移与大小——zip 里除了 payload 还有 metadata/otacert,用这两个数"圈出" payload |
headerKeyValuePairs | payload_properties.txt 里的校验头:FILE_HASH / FILE_SIZE / METADATA_HASH / METADATA_SIZE 等 |
另一个重载 applyPayload(AssetFileDescriptor, headers)(UpdateEngine.java)走
applyPayloadFd,本地文件就地读、不落第二份盘——自研升级服务常用这一路。
配套的回调接口是 UpdateEngineCallback,两个方法必须实现:
onStatusUpdate(status, progress):DOWNLOADING → VERIFYING → FINALIZING → UPDATED_NEED_REBOOT的状态机(枚举定义在UpdateEngine.java顶部UpdateStatus);onPayloadApplicationComplete(errorCode):0 = kSuccess;52 = kUpdatedButNotActive也算成功(写完但未切槽,配合SWITCH_SLOT_ON_REBOOT=0使用)。
调用方权限:UPDATE_ENGINE 是 @SystemApi,普通三方应用拿不到,只有特权/系统应用可用——
所以产品上的"系统更新"入口要么是预置特权 APK,要么是 root 守护进程(详见第 3 篇三条链路对比)。
5. A/B vs 传统 Recovery:一张对比表定取舍
| 维度 | 传统 Recovery 升级(A9 / p291_iptv 等) | A/B 无缝升级(A14 等) |
|---|---|---|
| 写哪里 | 覆盖正在运行的系统分区 | 写另一个 slot,当前系统照常跑 |
| /data | 升级失败可能要 wipe | 失败回滚老槽,/data 不动 |
| 升级耗时 | 关机进 Recovery,用户干等 | 后台下载+写入,重启一次完成 |
| 失败后果 | 常见变砖/卡 Recovery | bootloader 自动回退 |
| 空间代价 | 无 | 分区 ×2(动态分区可用 snapshot/VABC 省空间) |
| 包格式 | 整包 zip,由 Recovery 侧 verify_package 校验签名 | payload.bin + payload_properties.txt,由 update_engine 内校验签名与 hash |
| 关键角色 | recovery 二进制 + BCB(bootloader control block) | update_engine + bootctl HAL + update_verifier |
| 结果判定 | 重启后读 /cache/recovery/last_install | slot 是否 successful;回滚痕迹在 /data/misc/update_engine/prefs/rollback-happened |
迁移注意:从 A9 传统方案往 A14 A/B 方案搬升级逻辑时,最容易踩的坑是 "recovery 整包升级"这条在 A/B 设备上不存在——所有 OTA 都是 "写非活跃槽 → 重启切槽",A9 侧"先整包落盘再交 Recovery 安装"的代码模型需要整体重构 (对照表见第 6 篇)。
6. 排障总入口:拿到问题先看这四个地方
任何"A14 设备 OTA 有问题",按下面的顺序查,命中率最高:
# 1. 槽位状态:升级了但没切过去?还是切了没 successful?
adb shell getprop ro.boot.slot_suffix
adb shell getprop ro.boot.slot_successful
adb shell bootctl get-current-slot
# 2. update_engine 状态与日志(logcat + 文件两处都看)
adb shell logcat -d | grep -iE "update_engine|update_verifier|bootctrl"
adb shell ls /data/misc/update_engine_log/
# 3. 卡在哪个阶段:按状态关键字定位(完整对照表见第 4 篇)
adb shell logcat -d | grep -E "Downloading|Verifying|FINALIZING|postinstall|UPDATED_NEED_REBOOT"
# 4. 手动兜底/调试:update_engine_client 与 bootctl
adb shell update_engine_client --status
adb shell bootctl mark-boot-successful
本系列后续各篇都会回到这个入口,把对应阶段展开成"关键字 → 源码 → 修复动作"的三段式。
7. 本篇小结(记住这五点就够了)
- 先判形态:
ro.boot.slot_suffix非空 = A/B 设备,升级走 update_engine;为空 = 传统 Recovery。 开关是产品 mk 里的AB_OTA_UPDATER。 - slot 三属性:active(bootloader 启动谁)、successful(用户空间验收过)、bootable; 只有 successful 的槽才算升级落定。
- 两个 Binder 服务:
android.os.UpdateEngineService(framework API)与android.os.UpdateEngineStableService(stable API),同一个 update_engine 后端。 - 升级只写 target slot:
install_plan_.target_slot = GetTargetSlot(),在线升级期间 现行系统零改动,失败由 bootloader 自动回滚。 - 升级成功 ≠ 正在运行新版本:
UPDATED_NEED_REBOOT之后还要经历"重启切槽 → update_verifier 首启校验 → MarkBootSuccessful",任何一环失败都会回滚老槽。
下一篇预告
第 2 篇《OTA 包的构成与生成》将拆开一个真实的 1.4GB 升级包
(ota.zip)逐文件讲解:payload.bin 里的分区操作清单怎么读、
payload_properties.txt 的四个校验头怎么算、otacert 与签名的校验发生在哪,
以及 ota_from_target_files 从 target-files 到 OTA 包的生成过程——
并给出"用 Python 直接验证 payload 与本机镜像一致性"的实操脚本。