Files
UniXNU/docs/zh/guide/userdata.md
UniXNU Docs 1446f449b6 docs(porting): cover the macOS path
The porting flow covers the macos-27.3-26C5035r profile from profile
selection to the porting record: the macOS profile page lists the profile
contents, host inputs, board.toml override, Data seed, build commands,
driver adaptations and boot checkpoints, and the steps, arm64e, packaging,
records, bring-up, building, requirements and reference pages point to it.
The iPadOS instructions are unchanged.

Porting pages link porting pages for driver topics: Develop a driver and
Brightness interface are porting pages, and component names in porting
pages are plain text. English and Chinese pages.
2026-11-10 19:26:10 +08:00

126 lines
4.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# userdata 镜像
userdata 镜像为 XNU 提供根文件系统。它保存目标 IPSW 中未修改的 `OS` 和 `Cryptex1,SystemOS` 磁盘镜像,并在前面加一个 manifest。
准备选定的 IPSW 及设备 GPT 数据。Linux 上安装提供 `lzfse` 的 [Linux 工具链](/zh/guide/requirements#linux)。扩大 Data 种子(第 4 步)需要 macOS 的 `hdiutil` 和 `diskutil`。AEA 加密的镜像(如 iOS 与 iPadOS 27)需要 macOS 的 `aea` 和 `ipsw` 工具。先在[构建流程](/zh/building)中选定设备并保存本地输入。
## 1. 核对分区 {#分区}
`board.toml` 描述 GPT 条目:
```toml
[userdata]
first_lba = 0x2f3840
last_lba = 0x3d0abfa
lba_bytes = 4096
```
`first_lba` 和 `last_lba` 来自设备上名为 `userdata` 的 GPT 条目,`lba_bytes` 是分区逻辑块大小。
OS 配置列出磁盘镜像:
```toml
[userdata]
windows = [
{ name = "OS", component = "OS" },
{ name = "SystemOS", component = "Cryptex1,SystemOS", optional = true },
]
```
IPSW 没有某个 `optional = true` 的窗口时跳过它。macOS profile 还列出第三个窗口 `App`(`Cryptex1,AppOS`)。
镜像大小为各窗口按 1 MiB 对齐后的总和,加上 1 MiB 头部区域。步骤拒绝超过分区容量的镜像。
## 2. 预检并构建镜像 {#构建}
```sh
./unixnu build userdata --ipsw /path/to/restore.ipsw --dry-run
./unixnu build userdata --ipsw /path/to/restore.ipsw
```
步骤按 `[userdata] windows` 提取 IPSW 组件,在 macOS 上解密 AEA 镜像,在 macOS 上用 `hdiutil`、在 Linux 上用 `scripts/unixnu/udif.py` 读取每个磁盘镜像,写出原始镜像到 `out/<device>/<os_profile>/<config>/userdata/userdata-root.img`。
报告 `userdata-root.json` 记录窗口偏移、大小、哈希、分区容量和刷写命令。
先检查 dry-run 的分区容量和窗口布局,确认输入正确后再运行第二条命令。完成后应得到镜像及报告。
## 3. 设置根卷 UUID {#根卷选择}
内核按 UUID 挂载根卷:
```toml
[payload.adt]
root_match_volume_uuid = "REQUIRED_ROOT_VOLUME_UUID"
```
从所选 OS 镜像取得 APFS 根卷 UUID。在 macOS 连接镜像后用 `diskutil apfs list` 检查,确认根卷所属镜像容器并复制其 Volume UUID。修改后重建 payload 和启动镜像。
ADT 生成器写入 `/chosen/root-matching`,包含 `IOProviderClass = IOMedia` 和该 UUID。原生块驱动发布 userdata 分区,分区方案发布卷,XNU 选择 UUID 匹配的 IOMedia。
## 4. 准备 Data 卷 {#data-卷}
可写 Data 卷来自负载中的 Data ramdisk 种子:
```sh
./unixnu build payload --data-ramdisk data.img
```
在 macOS 上按目标持久存储布局调整 seed 大小:
```sh
python3 scripts/seed-data-grow.py --gib 8 /path/to/data.dbr /path/to/data-grow.dbr
```
按目标 Data 分配范围选择大小,预留根卷窗口、存储元数据和日志区域。
工具通过 `hdiutil` 连接原始镜像,使用 `diskutil` 调整 APFS,生成新的 packed seed。
接受范围为 3 至 1024 GiB。
`--auto` 还读取脚本树中的 `build/userdata-root/userdata-root.json`(或 `.img`),
并通过 fastboot 查询 userdata 容量。使用前在该位置提供同一目标的报告。
`--userdata-bytes BYTES` 替代容量查询,`--reserve-mib` 指定日志保留区,默认 1024 MiB。
卷 UUID 保留,seed 大小变化会改变持久化身份并初始化新的 Data store。
随镜像记录所选大小和根卷报告。其他设备先适配并验证 [UFS 指南](/zh/porting/ufs)中的存储分配。
`--skip-setup` 在种子副本中把 Setup 标记为完成。负载报告记录种子哈希和结果镜像哈希。偏好改动见[跳过 Setup](/zh/guide/skip-setup)。
## 5. 刷写并启动 {#刷写}
刷写 `userdata` 会覆盖该分区。执行前确认目标设备、分区布局和报告中的镜像路径,并保存需要保留的分区数据。
```sh
fastboot devices
fastboot flash userdata out/<device>/<os_profile>/<config>/userdata/userdata-root.img
```
刷写成功后,按[启动镜像](/zh/guide/boot#启动)启动匹配的 boot image,记录根卷挂载结果。
驱动把命令写入报告。设备仓库可以提供封装脚本,在刷写前检查镜像和分区。
## 布局
```
0x000000 SHNGROOT manifest,4096 字节,零填充到 1 MiB
0x100000 OS 窗口,完整磁盘镜像
.... SystemOS 窗口,完整磁盘镜像
```
manifest 为小端:
| 偏移 | 字段 |
| --- | --- |
| 0 | `SHNGROOT` |
| 8 | 版本,32 位,值 1 |
| 12 | 窗口数,32 位 |
| 16 | 镜像大小,64 位 |
| 24 | 窗口条目,每条 128 字节 |
| 4064 | 字节 0 到 4063 的 SHA-256 |
每个窗口条目包含 32 字节名称、64 位偏移、64 位大小、32 位块大小、32 位标志、32 字节 SHA-256 和 40 字节保留。
## 下一步
- [userdata 布局](/zh/concepts/userdata)
- [启动镜像](/zh/guide/boot)
- [设备配置](/zh/reference/configuration)