15 KiB
macOS 配置
macos-27.3-26C5035r 构建面向 macOS 27.3 用户空间的内核。它属于
arm64e profile,设备必须满足 arm64e 要求。同一个设备仓库同时服务
iPadOS 和 macOS profile:macOS 的值放在 board.toml 的
[os_overrides."macos-27.3-26C5035r"] 下,iPadOS 构建不读取它们。
本页沿移植设备的顺序说明 macOS 的差异。未提到的步骤与 iPadOS 相同。
profile 提供的内容
UniXNU 的 profiles/os/macos-27.3-26C5035r/profile.toml:
| 表 | 内容 |
|---|---|
[os] |
XNU 12377.121.6,target = "macosx"。内核以 XNU_TARGET_OS_OSX 编译,机器配置、内存布局和链接地址与 iPadOS 内核相同 |
[ipsw] |
UniversalMac_27.3_26C5035r_Restore.ipsw,产品 Mac17,11。fetch 列出 kernelcache、设备树以及静态、系统和应用信任缓存 |
[kernel.prelink] |
kernelcache_sha256 固定值、macOS 启动闭包的 roots 和 early_security_init。以 ! 开头的 root 不进入闭包。该内核集合保留符号表和链接地址,因此没有 slide |
[adt] |
Mac17,11 身份、/chosen 启动卷 UUID 和 asmb 启动策略 |
[userdata] |
三个窗口:OS、SystemOS(Cryptex1,SystemOS)和 App(Cryptex1,AppOS) |
[root]、[payload.adt] |
三个窗口的卷 UUID 和镜像摘要,以及根卷 UUID |
同目录的 configs/macos.config 和 patches/xnu/series 提供内核配置和补丁序列:
Darwin 26 系统调用与内核接口、macOS 机器选项、Data firmlink、位于 Data 上的 VM 与
Hardware 卷,以及应用 cryptex 挂载。
签名文本修补按原始字节校验。代码签名检查使用有界快照,APFS 压缩块检查使用私有副本,已驻留的可执行页面保留配置的指令。
1. 检查主机和输入
macOS 构建在装有 Xcode 的 Mac 上进行。除通用前置条件外还需要:
| 输入 | 来源 |
|---|---|
| macOS SDK | Xcode。启动 shim 和使用 macOS family 头文件的设备配方通过 xcrun --sdk macosx 编译 |
| IPSW | profile 的 [ipsw] url,或 --ipsw |
| Kernelcache | 从 IPSW 提取,并按 kernelcache_sha256 校验 |
| 信任缓存 | [payload.runtime] trust_components 指定进入 owner 信任包的 IPSW 成员 |
| Data seed | 以 root 身份从系统卷制作一次,见步骤 4 |
| root 权限 | 制作 Data seed 需要 sudo,只读枚举 Metal 库需要非交互 sudo |
2. 在设备仓库加入 macOS 的值
为该 profile 添加 defconfig,在 [package.defconfig] 中映射,并把所有不同的值放进覆盖表。
sheng 的 board.toml
是完整示例。
[package.defconfig]
"macos-27.3-26C5035r" = "<device>_macos_defconfig"
[os_overrides."macos-27.3-26C5035r"]
remove = ["payload.install", "payload.skip_setup_tool", "payload.runtime.appsync"]
[os_overrides."macos-27.3-26C5035r".kernel]
defconfig = "<device>_macos_defconfig"
config_fragments = ["arch:configs/common.config", "os:configs/macos.config"]
archives = ["<macOS 内核的全部归档配方,按顺序>"]
[os_overrides."macos-27.3-26C5035r".components]
include = ["<macOS 内核的全部组件>"]
[os_overrides."macos-27.3-26C5035r".payload]
size_mib = 200
kernel_args = ["<macOS 镜像的全部内核参数>"]
[os_overrides."macos-27.3-26C5035r".payload.adt]
chip_id = "6050"
[os_overrides."macos-27.3-26C5035r".payload.runtime]
target = "macos27"
build = "26C5035r"
data_seed_tool = "scripts/make-macos-data-seed.py"
data_gib = 210
skip_setup = false
boot_shims = true
| 键 | macOS 的值 |
|---|---|
[package.defconfig] |
--os 和打包脚本为该 profile 选择的 defconfig |
kernel.config_fragments |
os:configs/macos.config |
kernel.patch_series |
板级列表使用 os: 前缀时无需覆盖:os:patches/xnu/series 解析为 macOS 序列 |
kernel.archives、components.include、payload.kernel_args |
完整列表。数组会替换板级数组 |
kernel.prelink.roots |
不设置,使用 profile 的列表。其他 profile 的板级列表应放在该 profile 的覆盖表中,因为板级值会替换 profile 列表 |
payload.size_mib |
容纳内核集合、Data seed 和 addon |
payload.adt.chip_id |
6050,Mac17,11 的芯片 |
payload.runtime.target、build |
macos27 和 26C5035r |
payload.runtime.data_seed_tool |
以 root 运行的 seed 脚本 |
payload.runtime.data_gib |
Data 卷大小。持久化 Data 存储不能与 userdata 中的根镜像重叠 |
payload.runtime.skip_setup |
true 时在 seed 命令中加入 --skip-setup |
payload.runtime.boot_shims |
把 owner apfs_boot_util 加入 addon,配合 apfs-boot-shim=1 |
payload.runtime.gpu_addon |
true 时构建 macOS 的 Metal 插件。带 gpu-addon=1 时内核把它写入 Data 上的 /Library/GPUBundles |
remove |
仅适用于 iPadOS 的板级键,例如安装入口、payload.skip_setup_tool 和 payload.runtime.appsync |
sheng 的 macOS defconfig 与 iPadOS 27 的 defconfig 只有 Data 卷 UUID 不同,构建会根据 seed 写入该值。Mac17,11 身份来自 profile。
macOS 补丁序列增加的内核参数:
| 参数 | 作用 |
|---|---|
vc-text=1 |
在启动 framebuffer 上以文本绘制内核控制台,并与串口控制台互为镜像 |
exec-log=1 |
打印每次镜像激活和每次退出及其 wait status 与原因。诊断用,默认关闭 |
apfs-boot-shim=1 |
在 launchd 的挂载启动任务中用 addon 的 apfs_boot_util 覆盖系统自带的版本。需要 boot_shims = true |
timebase-hz=24000000 |
硬件计数器频率不同时,为用户空间提供 24 MHz 时基 |
gpu-addon=1 |
把 Metal 插件写入 /Library/GPUBundles |
3. 选择 profile
--os 只对当前命令生效。macOS 构建的每条命令都要带上它;只构建 macOS 的板子可以设置
board.os_profile。macos-27 解析为 macos-27.3-26C5035r,输出目录为
out/<device>/macos-27.3-26C5035r/<config>/。
./unixnu defconfig <device>_macos_defconfig -D ../UniXNU-<device> --os macos-27
./unixnu fetch --os macos-27
./unixnu ipsw info --os macos-27
./unixnu status --json --os macos-27
ipsw info 显示 27.3 (26C5035r)。status 显示 macOS profile 根目录、合并后的覆盖值和补丁顺序。
4. 制作 Data seed
用一条命令构建内核和 payload,使内核构建绑定 seed 的卷 UUID:
./unixnu build kernel payload --os macos-27
没有 seed 时,命令在编译前停止,打印创建 seed 的命令,其中包含 OS 镜像、输出路径和
data_gib。
创建账户并跳过 Setup
在 UniXNU 仓库中执行,使用构建命令打印的路径和大小。 交互输入短用户名、显示名称和隐藏密码:
sudo python3 scripts/make-macos-data-seed.py \
"<OS image>" "<output>/runtime/data.dbr" --gib "<data_gib>" \
--skip-setup --interactive-user --auto-login
脚本创建本地管理员及其主目录,保留模板文件属主,并跳过首次开机和首次登录时的设置助理。 输出文件必须是新 seed。
提示默认使用 admin 和 Admin。sudo 验证构建主机账户的密码;
交互输入的密码用于新建的 macOS 管理员账户。
自动化时,将 --interactive-user 替换为 --user NAME:PASSWORD --real-name NAME,
或从私有 JSON 文件读取凭据:
sudo -v
sudo -n python3 scripts/make-macos-data-seed.py \
"<OS image>" "<output>/runtime/data.dbr" --gib "<data_gib>" \
--skip-setup --user-stdin --auto-login < account.json
account.json 包含字符串字段 name、password 和可选的 real_name。
--real-name 优先于 JSON 中的显示名称。提供凭据后不再显示账户输入提示。
使用该 seed 构建并打包:
./unixnu build kernel payload --os macos-27 \
--data-ramdisk "<output>/runtime/data.dbr"
./unixnu bootimg --os macos-27 \
--data-ramdisk "<output>/runtime/data.dbr"
sheng 刷入全新 userdata 后,选择 Initialize macOS Data and boot,
再确认 Initialize Data and boot。这会清空 macOS Data,并从 seed 初始化持久存储。
后续开机选择 Boot,保留 Data。账户和设置助理配置来自 seed;
--skip-setup 在制作 seed 时传入。
sheng 的 macOS 桌面配置从选定源码构建 BootShim、板级固件和 DarwinBoot。256 MiB 逻辑 payload 使用分块压缩,启动镜像上限为 193 MiB。菜单在一秒后选择 Boot。autoreset=7200 和 uefi-watchdog=1 提供固件返回计时,diag-export=7140 在期限前保存启动日志。Shader Cache 安装到应用程序目录,显示编译进度。
制作 seed 的参数:
| 参数 | 作用 |
|---|---|
--skip-setup |
把设置助理标记为已完成 |
--user NAME:PASSWORD |
添加本地管理员及其主目录 |
--real-name NAME |
设置管理员的显示名称,短用户名与 /Users/NAME 路径保持不变 |
--user-stdin |
从标准输入的 JSON 对象读取 name、password 和可选的 real_name |
--interactive-user |
交互输入账户名、显示名称和密码 |
--auto-login |
开机自动登录指定账户,供无人值守测试使用 |
--keyboard-type PRODUCT-VENDOR-COUNTRY=TYPE |
记录键盘布局类型,键盘设置助理不再询问 |
--volume-uuid UUID |
为 Data 卷指定固定 UUID,新 seed 可以替换旧 seed 而无需重新构建内核 |
该安装之后的每次构建都使用同一个 runtime/data.dbr。seed 的 UUID 与已编译配置不同时,
payload 构建会停止并要求重新构建内核。内核把 seed 挂载到 /System/Volumes/Data,并设置
/usr/share/firmlinks 中的 firmlink。
5. 构建镜像
./unixnu build kernel payload --os macos-27
./unixnu build package --os macos-27
./unixnu build firmware --os macos-27
./unixnu build userdata --os macos-27 --dry-run
./unixnu build userdata --os macos-27
./unixnu bootimg --os macos-27
打包脚本执行除 userdata 以外的相同步骤:
scripts/package.sh --os macos-27 --uefi ../uefi-<device>
sheng 先准备 LLVM 22 工具,再将安装输入写入 UniXNU 仓库的 unixnu.local.toml:
[build]
device = "../UniXNU-sheng"
uefi = "../uefi-sheng"
clang_bin = ".cache/edk2-llvm22"
data_ramdisk = "/path/to/installed-data.dbr"
unique_chip_id = "<设备平台标识>"
随后从 UniXNU 执行 ../UniXNU-sheng/scripts/package.sh --os macos-27。使用导出构建输入的主机另填内核工具路径。package.manifest.json 记录源码版本、完整启动参数和运行时输入标识。
sheng macOS 工作流使用 Xcode 26.6、Python 3.14 和 LLVM/LLD 22。仓库 secret UNIXNU_UNIQUE_CHIP_ID 提供设备标识,UNIXNU_LAB_PASSWORD 提供初始管理员密码。root_storage=true 构建三个已验证根窗口及 userdata;false 为启动镜像更新复用 profile 的签名策略。
已有 Android sparse userdata 镜像时,可从本地恢复三个根镜像:
python3 ../UniXNU-sheng/scripts/restore-macos-images.py /path/to/userdata.sparse
脚本按选定 OS profile 校验恢复内容,写入 out/ipsw/<build>/<window>.raw.dmg,构建直接使用这些镜像。提取前应预留三个镜像的合计大小及构建空间。
| 步骤 | macOS 的差异 |
|---|---|
| 内核 | XNU_TARGET_OS_OSX、macOS 补丁序列,以及针对 macOS 内核集合的预链接 |
| Payload | Mac17,11 ADT、owner 信任包和为 macos27 构建的 addon |
| Userdata | 三个窗口。按 data_gib 核对 dry-run 报告的容量 |
| Package、固件、启动镜像 | 无 |
链接 owner 根策略的板子(CONFIG_XNU_SOURCE_STORAGE=y)需要为每个窗口提供签名策略。
scripts/make-root-policies.py --tree TREE --output POLICIES --window NAME=IMAGE:VOLUME_UUID
写出 POLICIES/NAME/manifest.header.bin、trusted-key.bin 和 verification.json,
以及哈希表 TREE/build/verified-root-NAME/hashes.bin。IMAGE 保存该窗口的字节,其 SHA-256
等于 profile 的 [root] <window>_image_sha256。存储归档配方读取其 --policy-dir
参数指定的策略目录。使用 CONFIG_XNU_SOURCE_STORAGE_TABLES="userdata" 时,用
--object NAME.vroot=FILE 把每个哈希表加入 userdata 镜像。
6. 适配驱动
按相同顺序完成驱动适配。macOS 内核集合有自己的类布局,macOS 用户空间还需要一些 iPadOS 不需要的服务。sheng 移植包含以下各项:
| 范围 | macOS 适配 |
|---|---|
| 私有类绑定 | 每个被绑定的类族按构建各有一份 fixture:scripts/<family>-26C5035r.json。scripts/gen-board-abi.py 根据内核集合的符号生成,显示配方按构建号选择 |
| 加密 | SoftwareAES 加入 components.include 和 kernel.archives,按 26C5035r 的类布局编译。AppleImage4 等待 IOAESAccelerator 服务,因此由板级 probe 注册它 |
| 网络 | en0 是原始 IONetworkingFamily 的 IOEthernetController,由 ethernet=1 启动,承载 Wi-Fi 模块的帧。TimeSync 时钟的标识取自以太网或 802.11 接口的地址,WindowServer 等待该时钟。supplicant 为 macOS 构建,其任务是 /Library/LaunchDaemons 中的 plist |
| 输入 | HID 设备由 offline-hid-home=1 启动。WindowServer 通过服务的 displayUUID 把触摸屏与显示器配对,该值是 framebuffer 发布的 IOMFBUUID |
| 键盘保护套 | 键盘加指针设备:相对位移、滚动步进和两个按键,不含 Keyboard Power usage |
| GPU | 插件构建为 macOS bundle,可执行文件位于 Contents/MacOS |
| 音频 | 音频服务器插件是位于 /Library/Audio/Plug-Ins/HAL 的 macOS driver bundle |
| 蓝牙 | 守护进程打开串口设备 /dev/cu.BLTH。板级的守护进程、BlueTool 和能力库位于 addon 的 sbin 与 lib,覆盖显示在 /usr/sbin 和 /usr/lib 上 |
| 内核内的固件镜像 | 放在 __DATA,__firmware |
7. 启动并检查
按启动镜像刷入 userdata 镜像并启动。 启动验证顺序同样适用,macOS 另有以下检查点:
| 阶段 | 检查 |
|---|---|
| 存储与根卷 | 分区方案发布 OS、SystemOS 和 App。根卷是只读系统卷,SystemOS 挂载在其上 |
| Data | Data 挂载到 /System/Volumes/Data。/System/Volumes/VM 和 /System/Volumes/Hardware 解析到其中 |
| Cryptex | OS cryptex 视图和 App cryptex 出现在 /System/Volumes/Preboot/Cryptexes 下 |
| 用户空间 | launchd 完成启动任务,WindowServer 显示登录窗口或设置助理 |
vc-text=1 让内核日志保持显示在面板上。exec-log=1 指出失败的启动任务。
8. 记录结果
porting.toml 的 device.os_profile 等于 board.os_profile,即板子的默认 profile。
服务多个 profile 的板子只保留一份记录:把 macOS 的配置、发现和证据写入相同的范围,
并在每一项中写明 profile 和构建号。见移植记录。