HackIOS的APFS文件系统实现:iOS根卷如何在手机UFS闪存上生存并跨重启持久化
HackIOS的APFS文件系统实现:iOS根卷如何在手机UFS闪存上生存并跨重启持久化
HackIOS 在安卓手机(POCO X5 Pro 5G,骁龙 778G)上启动苹果开源的 XNU 内核,运行未经修改的 iOS 16.5。这个仓库的核心难题之一,就是它自写的 APFS 文件系统驱动:iOS 的系统根卷以只读方式从手机 UFS 闪存上挂载,而用户数据要能跨重启存活。本文带你走一遍这套 APFS 实现的完整思路:只读根卷、双槽持久化、原地写入的三重护栏,以及断电安全的设计。💾
一、先看懂 HackIOS 在做什么 📱
HackIOS 把 iOS 16.5 的 launchd → SpringBoard → 应用,原封不动地跑在安卓硬件上:
- 系统卷(
System)从苹果的 IPSW 解包而来,是密封卷(sealed volume),只读; - 内核是 XNU 开源版打了补丁(xnu/redwood.patch),在 Linux 上用 clang 构建(xnu/README.md);
- 整个系统装在 RAM 里,会话结束手机回到 Android,不刷任何东西。
问题来了:iOS 用户态会不停往 /private/var 写数据(设置、缓存、照片库元数据……)。如果这些数据只在 RAM 里,重启即失。HackIOS 的答案分两半:根卷只读,数据卷落在闪存——由自研 APFS 驱动负责读取,再由一个"双槽存档"机制负责写入。
二、只读的 APFS 驱动:系统卷像光盘一样挂载
整套驱动位于 xnu/files/bsd/miscfs/apfs/,刻意分成三层,各管各的事:
| 层 | 文件 | 职责 |
|---|---|---|
| 格式解析 | apfs_lib.c、apfs_format.h | 懂 APFS 磁盘格式,完全不懂 vnode;同一份代码同时编译进内核和构建机上的测试工具 |
| VFS 层 | apfs_vfsops.c、apfs_vnops.c、apfs.h | 挂载、每个对象一个 vnode、单锁并发控制 |
| 设备抽象 | apfs_lib.h 的 struct apfs_dev |
读(内核里是块设备,工具里是镜像文件);写指针只对 apfs_write.c 开放 |
2.1 每个元数据块先过 Fletcher-64 校验
APFS 的每个块自带 Fletcher-64 校验和(apfs_lib.c)。驱动对每个块、每个 B-tree 节点内偏移、每条记录长度都做越界校验:损坏的或来路不明的镜像只会得到 EIO,绝不变成野指针。密封卷的 B-tree 节点还带 SHA-256 哈希,驱动会沿树逐层核对。
2.2 为闪存调过的读取路径
手机闪存的随机 4 KB 读约 113 微秒,所以 apfs_lib.h 用 8 MB 元数据块缓存(2048 块)、成簇预读邻居块;decmpfs 压缩文件按 64 KB 分片,多核并行解压,顺序读还会预解压后续 7 片——解压器用的是 libdeflate 和 libzbitmap。
三、跨重启持久化:iOS 写的数据去哪了
3.1 根卷只读,可变数据放 RAM
/private/var 和 /tmp 是内存文件系统 ramfs.c,每次启动重建为空。要活过重启的东西,必须打包后写到闪存上一个"不是文件系统"的地方。
3.2 最初的方案:裸偏移魔术数字
早期做法是把数据卷打成归档,写到 darwin 分区字节 8589934592 处的两个 2 GB 槽——位置只存在于代码注释里的常量。它有效,但没有任何介质上的东西能说明"这些字节是存档、槽有多长"。
3.3 RedwoodStore:把存档变成 APFS 卷上的两个具名文件
现在的方案(apfs_store.c、apfs_store.h)是:
- 在构建机上用
mkapfs类工具造一个名为RedwoodStore的 APFS 卷,卷根目录下放两个等长普通文件slot0、slot1; - 这个卷被一次性写进手机闪存的空闲空间,结构从此不再变化;
- 之后所有保存只在槽文件内部原地覆写字节——卷的任何记录都不被改写,于是根本不需要 APFS 的事务机制。
每个槽的第一块是 64 字节头部(apfs_store.h):魔数 RDWSTOR、代数 generation、载荷长度、时间戳、载荷的 FNV-1a 64 位和,以及头部自身的校验和。
3.4 为什么断电也坏不了 ⚡
保存流程刻意安排成三步:
- 写入不持有最新有效头部的那个槽,先把它头部清零——从这一刻起到提交前,该槽"什么都不说",读者只会取另一个槽;
- 依次写载荷,边写边算 FNV-1a 和;
- 最后写头部(单独一块,带新的代数与校验和),一次性使之生效。
头部和载荷起始分属相邻两块,任何一次写入都不同时碰两者。所以保存中途断电,最坏结果只是丢了自己这一次:代数高但校验不过的槽被跳过,读者退回上一代完好的槽。不需要回滚,不需要事务,这就是它全部的断电安全。
四、原地写入:apfs_write_in_place 的三重护栏 🔒
apfs_write.c 是这个移植里第一个"写"能力,但写得极其保守:只允许替换已存在文件的内容,不改长度、不改任何元数据结构。写之前逐项检查(apfs_write_volume_ok):
- 设备不带写回调 → 拒绝(绝大多数挂载都是只读设备);
- 密封卷、带完整性元数据(内容被哈希锁定)→ 拒绝;
- 有快照 → 拒绝(快照共享这些块);
- iOS 自己的 system / preboot 卷 → 拒绝("不是我们的,不动");
- 无 extent-reference 树 → 拒绝(没有它无法证明块不共享)。
块级还有三重护栏,层层独立:
- 文件自己的 extent 记录说这些块是它的内容;
- extent-reference 树说这些块归这个流独占、引用计数为 1(不是克隆、不是快照);
- 纯区间检查:即使两棵树全读错了,落在块 0、检查点环或容器对象映射上的写入照样被拒。
每个块写出后还要读回比对,不一致即报 EIO。失败时卷的结构与之前逐字节相同——所有树和校验和都还成立,其他文件毫发无损。
五、UFS 闪存与 UEFI 加载器:唯一的写之门
手机闪存由 redwood_ufs.c 驱动。巧妙之处在于内核里没有 UFS 驱动:Qualcomm 的 UEFI UFS 驱动(UFSDxe)常驻,加载器 loader.c 留在 0 号核上替内核代发读写请求。
- 块设备(
/dev/ufs_*)永远只读,策略例程直接拒绝写; - 只有字符设备
/dev/rufs_darwin在启动参数ufs_write=1时接受写,且仅限 UFS_WRITE_FIRST 之后的整块——那正是darwin分区里 iOS 根卷和两个 cryptex 之后的空闲区,与加载器侧的BLOCK_WRITE_FIRST边界一致; - 加载器侧还会把每个写读回验证后才应答。
会话结束走正常路径时,内核通过 sysctl kern.redwood.var_save 与用户态存档程序握手(IDLE → WANTED → DONE),kern.redwood.var_busy 保证同一时刻只有一个写者——两个存档程序不会交错写进同一个槽。这就是 var_store=1 ufs_write=1 之后,"iOS 写的数据能活过重启"的完整闭环。
六、如何验证内核没读错、没写错
redwood_apfs_check.c 提供 apfs_check=1~8 八种自检模式:
- 模式 1/2:整卷遍历,把 318098 条目的路径、权限、大小、内容哈希逐条折算成一个和,与构建机上同镜像的宿主工具对比——两个和一致,说明内核与宿主读到的每个字节都一致;
- 模式 4:真机路径。手机没有自己的存储驱动,根设备其实是 RAM 盘,
apfs_check=4直接遍历"根"; - 模式 7:真写测试——
apfs_write_in_place原地改写一个文件,再从零重新打开容器读回验证; - 模式 8:RedwoodStore 全流程测试——存档、重开容器、取回最新有效槽。
配套主机侧工具在 tools/ufs-super.py、tools/ufs-survey.py、tools/darwin-write.py。
七、关键路径速查
| 路径 | 说明 |
|---|---|
| xnu/files/bsd/miscfs/apfs/apfs_lib.c | APFS 格式解析(内核与宿主工具共用) |
| xnu/files/bsd/miscfs/apfs/apfs_format.h | APFS 磁盘布局定义 |
| xnu/files/bsd/miscfs/apfs/apfs_write.c | 原地写入 + 三重护栏 |
| xnu/files/bsd/miscfs/apfs/apfs_store.c | RedwoodStore 双槽存档 |
| xnu/files/bsd/dev/redwood_ufs.c | UFS 分区设备与写允许边界 |
| xnu/files/bsd/dev/redwood_apfs_check.c | 内核自检(读比对 + 写验证) |
| xnu/files/bsd/miscfs/ramfs/ramfs.c | /private/var、/tmp 内存文件系统 |
| xnuloader/loader.c | 常驻加载器:块设备请求代理、写边界 |
八、小结
HackIOS 的 APFS 实现是一个漂亮的"约束即设计"案例:根卷密封只读,所以系统卷像光盘;没有完整可写 APFS(空间管理器、检查点环、事务那套工作量太大),所以把"可写"压缩成原地覆写预建槽文件这一种动作;断电安全不靠原子性,靠双槽 + 代数 + 最后写头部的朴素协议。最终结果:iOS 用户态一行未改,它写下的数据却真实地落在了手机的 UFS 闪存里,重启之后还在。🚀

