10 KiB
构建内核
内核步骤从 Apple XNU 源码构建,并打上 UniXNU 补丁,然后与原始 kernelcache 预链接。
操作流程
- 完成主机准备,用
./unixnu defconfig <name> -D /path/to/device选择设备。 - 执行
./unixnu fetch和./unixnu status --json,检查 OS 版本、归档和补丁顺序。 按构建输入准备原始 kernelcache、固件和设备所需 ABI 候选内核。 - 执行
./unixnu build kernel。停止时读取输出目录logs/内首个失败步骤的日志。 最终输出为kernel/kernel.macho。 - 仅预链接输入变化且已有原生内核时使用
./unixnu build prelink;源码或归档变化时重建内核。 - 继续构建 package、固件和 payload。
使用导出输入在本机构建
sheng macOS lab 的 export_build_inputs=true 导出 XNU 目标文件、内核头文件、iPhoneOS SDK 和 Xcode 26.6 编译工具。解压 compiler-toolchain.tar.zst,得到包含 bin 和 lib 的 TOOLCHAIN。将缓存解压到选定构建树,修正路径后在本机编译:
python3 scripts/relocate-xnu-cache.py TREE --metadata build-paths.json --sdk SDK --device DEVICE --toolchain TOOLCHAIN
./unixnu build kernel -D DEVICE --os macos-27 --data-ramdisk SEED \
--kernel-sdk SDK --kernel-tools TOOLCHAIN/bin
导出任务收集工具依赖的非系统动态库,运行导出目录中的编译器、IIG 和链接器,用导出的编译器生成 arm64e 对象,再通过 classic 链接器执行部分链接。本地运行器在工具查找和执行时均选择导出的 SDK、编译器、链接器和内核工具。build-paths.json 记录编译器与 Xcode 版本。组件归档按当前源码重新编译,内核复用保留的 XNU 目标文件。重新准备源码树时,内容相同的补丁后源码和恢复头文件保留时间戳。
SEED 是现有启动 payload 中保留的 Data seed。仅构建内核时也会读取其 APFS UUID,将编译后的 Data 查找绑定到该安装。
完整打包入口使用相同的内核工具选择:
../UniXNU-sheng/scripts/package.sh --os macos-27 --data-ramdisk SEED \
--uefi UEFI --kernel-sdk SDK --kernel-tools TOOLCHAIN/bin
导出工具用于内核编译与预链接。运行时库和 GPU 工具使用主机的 macOS SDK,固件使用配置的 LLVM 工具链。将 kernel_sdk 和 kernel_tools 写入 unixnu.local.toml 可复用这些路径。scripts/run-local-kernel.py 将 --sdk 和 --tools 转交给相同构建入口。
源码与构建树
| 路径 | 内容 |
|---|---|
out/<device>/<os_profile>/<config>/tree/refer/xnu |
固定版本的 XNU 源码 |
out/<device>/<os_profile>/<config>/tree/.cache/xnu-work |
应用补丁的工作克隆 |
out/<device>/<os_profile>/<config>/tree/build/xnu/ios-obj |
目标文件和编译命令记录 |
out/<device>/<os_profile>/<config>/tree/build/xnu/ios-sym |
符号 |
out/<device>/<os_profile>/<config>/tree/build/xnu/ios-dst |
安装头文件 |
out/<device>/<os_profile>/<config>/tree/.cache/fakeroot |
内核 SDK 根 |
out/<device>/<os_profile>/<config>/tree/.cache/firmware |
设备专有输入,链接自设备仓库 |
out/<device>/<os_profile>/<config>/kernel/kernel.macho |
预链接内核 |
格式 2 从 OS profile 选择 XNU 版本字段,source feed 提供检出来源;格式 1 直接使用 feed 的版本字段。source 条目如下:
[[source]]
name = "xnu"
kind = "refer"
git = "https://github.com/apple-oss-distributions/xnu.git"
ref = "xnu-10063.141.1"
commit = "d8b80295118ef25ac3a784134bcf95cd8e88109f"
darwin = "23.6.0"
version = "10063.141.1"
driverkit_tag = "xnu-10063.121.3"
trustcache_tag = "xnu-8796.101.5"
unixnu build kernel 把这些值作为 UNIXNU_XNU_TAG、UNIXNU_XNU_COMMIT、UNIXNU_XNU_DARWIN、UNIXNU_XNU_VERSION、UNIXNU_DRIVERKIT_TAG 和 UNIXNU_TRUSTCACHE_TAG 传给 scripts/build-xnu-4k-baseline.sh。
内核参考源码还固定了 libpthread(libpthread-519.120.4)和 corecrypto-2023(commit 11fba65)。源码提供者按 XNU 编译记录构建。
构建目标:
SDKROOT=iphoneos
ARCH_CONFIGS=ARM64
MACHINE_CONFIGS=BCM2837
KERNEL_CONFIGS=DEVELOPMENT
ARM64_LINK_ADDR=0xfffffff007004000
ARM64_PLKSEG_ADDR=0xfffffff004004000
DEPLOYMENT_TARGET_FLAGS="-miphoneos-version-min=17.0 -DXNU_TARGET_OS_IOS"
BCM2837 携带 4 KiB 页布局。arm64 内核以 iOS 17 为目标,以匹配 iOS 16 或 iPadOS 17 kernelcache 的预链接 ABI;两个 arm64 目标使用同一套 arm64 补丁系列。
defconfig 开关
每个 CONFIG_XNU_<NAME> 变成构建环境中的 XNU_<NAME>。y 变成 1,n 变成 0,字符串按文本传入,字符串中的 {tree} 替换为构建树路径。
| 开关 | 作用 | 静态库 |
|---|---|---|
XNU_SOURCE_CORECRYPTO14 |
构建并链接源码 corecrypto | build/corecrypto-2023/libcorecrypto_kernel_noasm-namespaced.a |
XNU_SOURCE_PTHREAD |
构建并注册源码 pthread | build/libpthread-kernel/libpthread_kernel.a |
XNU_ARM_DT_PLATFORM |
链接 Apple 格式设备树平台专家 | build/armdt-platform/libArmDTPlatform.a |
XNU_ARMVIRT_PLATFORM |
链接 QEMU virt 平台专家 | build/armvirt-platform/libArmVirtPlatform.a |
XNU_ARMCPU |
链接 CPU 与中断控制器 | build/armcpu/libArmCpu.a |
XNU_NATIVE_UFS |
链接 UFS 存储驱动 | build/sheng-ufs/libShengUfs.a |
XNU_NATIVE_AES |
链接 AES 加速器驱动 | build/software-aes/libSoftwareAES.a |
XNU_NATIVE_VIRTIO_BLOCK |
链接 VirtIO 块驱动 | XNU_NATIVE_VIRTIO_BLOCK_ARCHIVE 或 build/virtio-mmio-block/libVirtioMmioBlock.a |
XNU_NATIVE_RAM_BLOCK |
链接 RAM 块驱动 | build/ram-block/libRamBlock.a |
XNU_NATIVE_VIRTIO_CONSOLE |
链接 VirtIO 控制台 | build/virtio-mmio-console/libVirtioMmioConsole.a |
XNU_NATIVE_MOBILE_DISPLAY |
链接移动显示驱动 | build/gop-framebuffer/libGopFramebuffer.late.a |
XNU_NATIVE_LEGACY_DISPLAY |
链接旧式显示驱动 | build/native-legacy-display/libNativeLegacyDisplay.late.a |
XNU_NATIVE_ADRENO |
链接 Adreno GPU 驱动 | build/adreno740/libAdreno740.a |
XNU_NATIVE_OFFLINE_GPU |
链接离线 GPU broker | build/native-offline-gpu/libNativeOfflineGPU.late.a |
XNU_VERIFIED_ROOT_PROBE |
链接 verified root | XNU_VERIFIED_ROOT_ARCHIVE 或 build/verified-root-xnu/libVerifiedRootProbe.a |
XNU_NATIVE_CS_HASH_CACHE |
从已验证 16 KiB 块派生 4 KiB 签名哈希 | 无 |
XNU_NATIVE_ARCH_TIMER |
使用架构定时器入口 | 无 |
XNU_NATIVE_PAN |
启用 ARMv8.1 PAN | 无 |
XNU_DT_PANIC_REGION |
从设备树读取 panic 区域 | 无 |
XNU_TRUST_CACHE_RUNTIME |
初始化 trust cache 运行时 | 无 |
XNU_BOOT_PROGRESS |
加入启动进度层 | build/boot-progress/libBootProgress.a |
XNU_SOURCE_MOCKFS |
加入 mockfs 测试文件 | build/mockfs-fixture/libmockfs_fixture.a |
board.toml 的 [kernel] archives 按顺序列出静态库脚本。每个条目是构建树中的脚本及其参数。例如:
[kernel]
defconfig = "myboard_defconfig"
archives = [
"build-software-aes-bindings.py",
"build-libpthread-kernel.py",
"build-corecrypto-14.py",
"build-corecrypto-14.py --namespace",
]
unixnu build kernel 在编译记录存在后运行这些脚本,然后链接内核。条目按顺序执行,依赖另一个脚本输出的条目排在它后面。没有脚本生成的静态库需要放入构建树。配置用 CONFIG_XNU_BUILD_ARCHIVES=y 选择运行;bootstrap pass 和 first-console 配置不设置该值。
脚本通过 scripts/xnu_symbols.py 读取符号名。它使用已记录的 checkpoint 内核,或 build/xnu/ios-obj/DEVELOPMENT_ARM64_BCM2837/link.filelist 中的目标文件以及 all-alias.exp 中的别名。新构建树因此只需要一轮生成编译记录的内核构建,静态库输出也不会与上一次链接的内核冲突。
内核步骤还会在静态库脚本运行前,把公开的 IOStorageFamily 头文件放到 build/storage-abi/include。
build-software-aes-bindings.py 和 build-adreno740-accelerator.py 在原始硬件证据缺失时使用 scripts/data/ 中记录的审计结果。记录的地址属于 board.toml 固定的 kernelcache。
构建顺序
unixnu fetch克隆 XNU、libpthread、corecrypto-2023 和 Apple 参考源码。unixnu build kernel应用补丁并恢复缺失头文件。- 编译记录不存在时,先运行一次 XNU 生成记录。该轮可以在链接前停止。
- 按
[kernel] archives的顺序运行静态库脚本。 - 构建并链接内核,然后与原始 kernelcache 预链接。
unixnu build prelink只重做预链接。它会替换上一轮的结果和报告。
预链接内核为 out/<device>/<os_profile>/<config>/kernel/kernel.macho。
预链接读取 board.toml 的 [kernel.prelink]:
[kernel.prelink]
tool = "kits/XnuPrelink/emit_prelink.py"
kernel = "build/xnu/ios-obj/DEVELOPMENT_ARM64_BCM2837/mach.development.bcm2837.unstripped.noctf"
kernelcache_sha256 = "..."
slide = "-0x1000000"
early_security_init = "com.apple.driver.AppleMobileFileIntegrity=0xfffffff005ab4ae0"
roots = [
"com.apple.driver.AppleARMPlatform",
"com.apple.filesystems.apfs",
]
roots 列出原生内核使用的原始 kernelcache 组件。early_security_init 指定在预链接安全初始化期间运行的组件地址。
新增内核开关
- 在设备 defconfig 中加入
CONFIG_XNU_<NAME>=y。 - 在
scripts/build-xnu-4k-baseline.sh中读取XNU_<NAME>。 - 用
EXTRA_MAKE_ARGS+=("<file>.o_CFLAGS_ADD=-DXNU_<NAME>=$VALUE")加入目标文件开关。 - 把构建脚本加入
[kernel] archives,再把静态库加入KERNEL_EXTRA_ARCHIVES和KERNEL_ARCHIVE_DEPENDENCIES。 - 通过补丁把 personality 加入
iokit/KernelConfigTables.cpp。
使用已有内核
unixnu build payload --kernel FILE 用已有的预链接内核打包,跳过 XNU 构建。