diff --git a/AGENTS.md b/AGENTS.md index 1e42457..3625406 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ The published documentation is at https://unixnu.com. Site sources, navigation, translations, assets, build configuration, and deployment belong to this repository. Update English and Chinese pages together. Link every documentation page from a relevant guide or topic index reachable -through body links from `docs/guide/overview.md` and its Chinese edition. +through body links from `docs/porting/index.md` and its Chinese edition. Keep prerequisites and next steps in the page body. ## Component discovery diff --git a/README.md b/README.md index f59d9a1..79e5a64 100644 --- a/README.md +++ b/README.md @@ -41,11 +41,10 @@ Linux setup supports apt, dnf, pacman and zypper, plus environments with depende The documentation is at [unixnu.com](https://unixnu.com). Its sources, navigation, translations, assets, configuration, and deployment workflow are maintained in this repository. It covers the boot chain, the build driver, device porting, driver development, the 4 KiB XNU page patches, boot arguments and per-device notes. -- [Overview](https://unixnu.com/guide/overview) +- [Port a device](https://unixnu.com/porting/) - [Build](https://unixnu.com/building) - [Boot the image](https://unixnu.com/guide/boot) - [Debugging and logs](https://unixnu.com/guide/debugging) -- [Porting](https://unixnu.com/porting/) - [Drivers](https://unixnu.com/drivers/overview) - [XNU and 4 KiB pages](https://unixnu.com/xnu/four-k-page-tables) - [Devices](https://unixnu.com/devices/) diff --git a/README.zh-CN.md b/README.zh-CN.md index 5357d7d..a61ce9c 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -41,11 +41,10 @@ Linux 安装脚本支持 apt、dnf、pacman、zypper,以及单独准备依赖 文档位于 [unixnu.com](https://unixnu.com),源码、导航、翻译、资源、配置和部署工作流由本仓库维护。文档覆盖启动链、构建驱动、设备移植、驱动开发、XNU 4 KiB 页补丁、启动参数和设备说明。 -- [总览](https://unixnu.com/zh/guide/overview) +- [移植设备](https://unixnu.com/zh/porting/) - [构建](https://unixnu.com/zh/building) - [启动镜像](https://unixnu.com/zh/guide/boot) - [调试与日志](https://unixnu.com/zh/guide/debugging) -- [移植](https://unixnu.com/zh/porting/) - [驱动](https://unixnu.com/zh/drivers/overview) - [XNU 与 4 KiB 页](https://unixnu.com/zh/xnu/four-k-page-tables) - [设备](https://unixnu.com/zh/devices/) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index dfe4789..0c8e5a3 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -18,8 +18,8 @@ export default withMermaid(defineConfig({ link: '/zh/', themeConfig: { nav: [ - { text: '指南', link: '/zh/guide/overview', activeMatch: '^/zh/(guide/|building)' }, - { text: '移植', link: '/zh/porting/', activeMatch: '^/zh/porting/' }, + { text: '移植设备', link: '/zh/porting/', activeMatch: '^/zh/porting/' }, + { text: '构建', link: '/zh/building', activeMatch: '^/zh/(guide/|building)' }, { text: '驱动', link: '/zh/drivers/overview', activeMatch: '^/zh/drivers/' }, { text: 'XNU', link: '/zh/xnu/source-and-patches', activeMatch: '^/zh/xnu/' }, { text: '设备', link: '/zh/devices/', activeMatch: '^/zh/devices/' }, @@ -32,7 +32,7 @@ export default withMermaid(defineConfig({ { text: '指南', items: [ - { text: '从这里开始', link: '/zh/guide/overview' }, + { text: '移植设备', link: '/zh/porting/' }, { text: '构建环境', link: '/zh/guide/requirements' }, { text: '构建', link: '/zh/building' }, { text: '构建内核', link: '/zh/guide/build-kernel' }, @@ -48,7 +48,7 @@ export default withMermaid(defineConfig({ { text: '指南', items: [ - { text: '从这里开始', link: '/zh/guide/overview' }, + { text: '移植设备', link: '/zh/porting/' }, { text: '构建环境', link: '/zh/guide/requirements' }, { text: '构建', link: '/zh/building' }, { text: '构建内核', link: '/zh/guide/build-kernel' }, @@ -76,7 +76,7 @@ export default withMermaid(defineConfig({ { text: '移植', items: [ - { text: '移植总览', link: '/zh/porting/' }, + { text: '移植设备', link: '/zh/porting/' }, { text: '设备仓库', link: '/zh/porting/device-repository' }, { text: '适配记录', link: '/zh/porting/records' }, { text: 'UFS 移植', link: '/zh/porting/ufs' }, @@ -266,8 +266,8 @@ export default withMermaid(defineConfig({ }, siteTitle: 'UniXNU', nav: [ - { text: 'Guide', link: '/guide/overview', activeMatch: '^/(guide/|building)' }, - { text: 'Porting', link: '/porting/', activeMatch: '^/porting/' }, + { text: 'Port a device', link: '/porting/', activeMatch: '^/porting/' }, + { text: 'Build', link: '/building', activeMatch: '^/(guide/|building)' }, { text: 'Drivers', link: '/drivers/overview', activeMatch: '^/drivers/' }, { text: 'XNU', link: '/xnu/source-and-patches', activeMatch: '^/xnu/' }, { text: 'Devices', link: '/devices/', activeMatch: '^/devices/' }, @@ -280,7 +280,7 @@ export default withMermaid(defineConfig({ { text: 'Guide', items: [ - { text: 'Start here', link: '/guide/overview' }, + { text: 'Port a device', link: '/porting/' }, { text: 'Requirements', link: '/guide/requirements' }, { text: 'Build', link: '/building' }, { text: 'Build the kernel', link: '/guide/build-kernel' }, @@ -296,7 +296,7 @@ export default withMermaid(defineConfig({ { text: 'Guide', items: [ - { text: 'Start here', link: '/guide/overview' }, + { text: 'Port a device', link: '/porting/' }, { text: 'Requirements', link: '/guide/requirements' }, { text: 'Build', link: '/building' }, { text: 'Build the kernel', link: '/guide/build-kernel' }, @@ -324,7 +324,7 @@ export default withMermaid(defineConfig({ { text: 'Porting', items: [ - { text: 'Porting overview', link: '/porting/' }, + { text: 'Port a device', link: '/porting/' }, { text: 'Device repository', link: '/porting/device-repository' }, { text: 'Porting records', link: '/porting/records' }, { text: 'UFS porting', link: '/porting/ufs' }, diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index a43c843..09beb54 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -46,8 +46,8 @@ docs/ 1. Create the Markdown file under the matching section. 2. Add the page to the sidebar in `docs/.vitepress/config.mts`. 3. Add the Chinese page under `docs/zh/` and to the Chinese sidebar. -4. Link the page from a relevant guide or topic index reachable from [Start here](/guide/overview). Put task prerequisites and the next step in the page body. -5. Follow the body links from Start here in each language to confirm the page is reachable. +4. Link the page from a relevant guide or topic index reachable from [Port a device](/porting/). Put task prerequisites and the next step in the page body. +5. Follow the body links from Port a device in each language to confirm the page is reachable. 6. Run `npm run build` and fix broken links. 7. Add the language switcher entry when a new section starts. @@ -86,7 +86,7 @@ VitePress fails the build on a broken internal link. ## Next steps - [Repository layout](/contributing/repository) -- [Overview](/guide/overview) +- [Port a device](/porting/) ## Device records diff --git a/docs/guide/overview.md b/docs/guide/overview.md index 55c8b9c..9b83b52 100644 --- a/docs/guide/overview.md +++ b/docs/guide/overview.md @@ -1,161 +1,16 @@ -# Start here +--- +title: Port a device +sidebar: false +aside: false +prev: false +next: false +head: + - - meta + - http-equiv: refresh + content: "0; url=/porting/" + - - link + - rel: canonical + href: https://unixnu.com/porting/ +--- -UniXNU starts iOS or macOS on an ARM64 device from a UEFI environment. The stack has six layers. Each layer has a repository, a build output and a handoff contract. - -## Build and boot an existing device - -1. Find your port in [supported devices](/devices/). Read its configuration, required inputs and current results. -2. Prepare the [host tools and external inputs](/guide/requirements). Linux users start with [toolchain setup](/guide/requirements#linux). -3. Save paths in [local build configuration](/reference/configuration#local-build-inputs), then follow [building](/building) and [kernel preparation](/guide/build-kernel). -4. Build the device's [UEFI firmware](/porting/uefi-firmware#required-integration) with the required loader and payload filesystem drivers. -5. Create the [payload](/concepts/payload) and [userdata image](/guide/userdata), then [pack and boot the image](/guide/boot). -6. Check [logs and boot stages](/guide/debugging). Use [troubleshooting](/reference/troubleshooting) for a failed build or boot. - -Changing boot arguments requires rebuilding the payload and boot image. Follow [apply boot arguments](/xnu/boot-arguments#apply-arguments). A top green bar marks loader handoff; follow [green-bar diagnosis](/guide/debugging#green-bar) for the next checks. - -## Choose a task - -| Task | Reading path | -| --- | --- | -| Add a device | [Porting workflow](/porting/) → [device repository](/porting/device-repository) → [driver adaptation](/porting/drivers) → [bring-up order](/porting/bring-up) → [porting record](/porting/records) | -| Migrate a device repository | [Migration guide](/porting/migration) → [configuration reference](/reference/configuration) | -| Select or develop a driver | [Component catalog](/reference/components) → [driver layers](/drivers/overview) → [driver repositories and component pages](/drivers/repositories) | -| Modify XNU | [Source and patches](/xnu/source-and-patches) → [patch reference](/xnu/patch-reference) → [4 KiB page tables](/xnu/four-k-page-tables) | -| Configure a build or boot entry | [Command line](/reference/cli), [device configuration](/reference/configuration), [boot configuration](/reference/boot-configuration), [output layout](/reference/output-layout) | -| Test with QEMU | [QEMU workflow](/reference/qemu) | -| Contribute code or documentation | [Repository layout](/contributing/repository) → [documentation workflow](/contributing/documentation) | - -## Understand the boot process - -Read the [boot chain](/concepts/boot-chain), [kernel prelink](/concepts/prelink), -[payload](/concepts/payload), [userdata layout](/concepts/userdata), and -[integrity and boot policy](/concepts/security). The [glossary](/reference/glossary) -defines the terms used throughout the guides. - -## Layer model - -``` -Android bootloader (ABL) - | - | fastboot boot boot.img - v -BootShim + UEFI firmware volume + device tree - | - | UEFI BDS starts UniXNU - v -UniXNU (UEFI boot manager) - | - | UNIXNU_LOADER_PROTOCOL - v -DarwinBoot (XNU loader) - | - | boot_args, ADT, trust cache, ramdisk - v -Patched XNU kernel - | - | IOKit, BSD, launchd - v -Userland from the IPSW (OS and SystemOS) -``` - -## Components - -### Boot image - -The boot image is an Android boot image with header version 0. Its kernel field holds gzip data with two parts: the compiled BootShim and the UEFI firmware volume. The device tree follows the gzip stream. The ramdisk field holds the UniXNU payload. - -The stock Android bootloader loads the image at the address declared by the Mu-Silicium device configuration, verifies the ARM64 image header, and jumps to the shim. BootShim relocates the firmware volume and enters UEFI. - -### UEFI firmware - -The firmware comes from a Mu-Silicium checkout for the device. It provides the UEFI services the boot manager needs: - -- `EFI_GRAPHICS_OUTPUT_PROTOCOL` for the menu and the kernel framebuffer. -- `EFI_SIMPLE_TEXT_IN_PROTOCOL` for menu input. -- `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL` and `EFI_BLOCK_IO_PROTOCOL` for the payload volume and disk partitions. -- `EFI_SERIAL_IO_PROTOCOL` for logs when the board exposes a UART. - -The `./unixnu build firmware` step applies the board patches to the shared edk2 tree, builds the board DSC and returns `SILICIUM_UEFI.fd`. For a Mu-Silicium initrd payload, the DSC and FDF include the shared `UniXNURamDiskDxe`, DiskIoDxe and FAT driver so UniXNU can discover the payload entries. Follow [required firmware integration](/porting/uefi-firmware#required-integration). - -### Boot manager - -The UniXNU boot manager is a UEFI application built from `package/UniXNUPkg`. It reads `\EFI\UniXNU\unixnu.toml` from the volume it was started from, then from every other volume. The configuration declares menu entries, drivers, device tree patches, ACPI tables, block slices and kits. - -The boot manager performs five jobs before the menu: - -1. Publishes every `[[block_slice]]` as a block device. -2. Loads and starts every configured UEFI driver. -3. Installs every configured ACPI table. -4. Merges every kit whose `[match]` section is satisfied. -5. Prepares the device tree for the selected entry. - -An entry of type `xnu` is handed to a loader that implements `UNIXNU_LOADER_PROTOCOL`. - -### DarwinBoot - -DarwinBoot is a UEFI driver in the firmware volume. It installs the loader protocol at `EL2` or `EL1`. On an `xnu` entry it performs these steps: - -1. Reads the kernel Mach-O from the payload volume. -2. Reads the `.adt` sidecar next to the kernel. -3. Reads the optional `.trustcache` sidecar. -4. Validates the Mach-O segments, the ADT and the trust cache structure. -5. Allocates a physical window for the kernel and its data. -6. Copies the kernel segments, the ADT, the trust cache and the ramdisk. -7. Builds a Darwin `boot_args` structure. -8. Exits boot services, disables the MMU and caches, and jumps to the kernel entry point in EL1. - -The loader requires a single ARM64 Mach-O with a `__TEXT` segment, a `LC_MAIN` entry point and a base address aligned to the firmware page size. - -### XNU kernel - -The selected OS profile pins the XNU source. The iPadOS 17.7.11 profile uses `xnu-10063.141.1`. Ordered profile and component series supply its patches. The BCM2837 machine configuration supplies the 4 KiB page layout for non-Apple ARM64 boards. - -The native kernel is prelinked against the original kernelcache from the target IPSW. The prelink keeps the original Apple kexts and binds the native kernel to their symbols. The result is a single `kernel.macho` that contains the native kernel segments and the selected original components. - -### Userland - -The userdata image holds the unchanged `OS` and `Cryptex1,SystemOS` disk images from the IPSW. A 4 KiB manifest at the start of the partition describes both windows. The native UFS or block driver publishes the partition, and XNU mounts the root volume by UUID. - -## Repositories - -| Repository | Purpose | -| --- | --- | -| `UniXNU` | Build tools, component catalog, ARM64 and OS profiles, templates, UEFI package, documentation site | -| `UniXNU--common` | Shared SoC configuration, DTSI, platform operations and patches | -| Component repositories | Drivers, libraries, loaders and tools | -| `UniXNU-` | Board description, kernel defconfig, device scripts, device drivers and package | -| `uefi-` | Mu-Silicium UEFI port for the device | - -A device repository selects pinned SoC support, an OS profile, and components. It describes board peripherals in DTS and supplies firmware inputs, partition layout, and packaging. The build tools resolve dependencies and assemble the target tree. - -## Build outputs - -Everything is written under `out/`: - -``` -out/ - state.json remembered device repository - feeds/ fetched git sources - ipsw// extracted IPSW members - /// - .config selected defconfig - tree/ assembled build tree - logs/ one log per build step - kernel/kernel.macho prelinked kernel - package/Build/Out/ UniXNU and test EFI binaries - payload/payload.img FAT payload volume - payload/payload.json payload report - boot/boot.img Android boot image - boot/boot.json boot image report - userdata/userdata-root.img - userdata/userdata-root.json -``` - -The reports record input hashes and the commands that produce the next step. The boot image is deterministic for a given firmware volume, device tree and ramdisk. The payload contains a random seed in the ADT, so two payload builds differ. - -## Next steps - -- [Requirements](/guide/requirements) lists the host tools and external inputs. -- [Build](/building) walks through the driver commands. -- [Porting](/porting/) describes how to add a device. -- [Devices](/devices/) lists device repositories. The sheng page records one device; the general guide uses placeholders. +[Port a device](/porting/) diff --git a/docs/index.md b/docs/index.md index 6954f33..9dd342e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,14 +13,11 @@ hero: alt: UniXNU logo actions: - theme: brand - text: Start here - link: /guide/overview + text: Port a device + link: /porting/ - theme: brand text: Supported devices link: /devices/ - - theme: alt - text: Port a device - link: /porting/ - theme: alt text: GitHub link: https://github.com/UniXNU/UniXNU diff --git a/docs/porting/index.md b/docs/porting/index.md index 72ab893..d98e4c8 100644 --- a/docs/porting/index.md +++ b/docs/porting/index.md @@ -1,8 +1,12 @@ # Port a device -Follow these steps from a UniXNU checkout. Each step produces an input for the -next. An existing port starts with the [migration guide](/porting/migration). -To build an existing supported port, use [Building](/building). +UniXNU runs iOS or macOS on ARM64 devices through UEFI. Follow the eight steps +below to collect inputs, select shared support, adapt drivers and build images. +Each step states its expected result. + +- **Add a device:** start at step 1. +- **Build an existing device:** check its inputs and current support in [Devices](/devices/), then follow [Building](/building). +- **Migrate an existing repository:** update its configuration with the [migration guide](/porting/migration), then continue with the required driver adaptation and build steps. ## 1. Collect the device inputs @@ -142,3 +146,16 @@ it to the central site. Follow [records](/porting/records) and [documentation contribution](/contributing/documentation). Link the new device page from [Devices](/devices/) in both languages. Keep the detailed guide in the main repository and link it from the device README. + +## Related documentation + +Use these references for the step you are working on: + +| Topic | Documentation | +| --- | --- | +| Boot process and image inputs | [Boot chain](/concepts/boot-chain), [prelink](/concepts/prelink), [payload](/concepts/payload), [userdata layout](/concepts/userdata), [integrity and boot policy](/concepts/security) | +| Component implementation and development | [Driver layers](/drivers/overview), [driver repositories and component pages](/drivers/repositories) | +| Kernel changes | [Source and patches](/xnu/source-and-patches), [patch reference](/xnu/patch-reference), [4 KiB page tables](/xnu/four-k-page-tables) | +| Build and boot configuration | [Command line](/reference/cli), [device configuration](/reference/configuration), [boot configuration](/reference/boot-configuration), [output layout](/reference/output-layout) | +| Host verification | [QEMU workflow](/reference/qemu) | +| Project maintenance | [Repository layout](/contributing/repository), [documentation workflow](/contributing/documentation), [glossary](/reference/glossary) | diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 61ead87..9553729 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -38,6 +38,6 @@ ## Next steps -- [Overview](/guide/overview) +- [Port a device](/porting/) - [Command line](/reference/cli) - [Devices](/devices/) diff --git a/docs/zh/contributing/documentation.md b/docs/zh/contributing/documentation.md index a27d932..72bc5da 100644 --- a/docs/zh/contributing/documentation.md +++ b/docs/zh/contributing/documentation.md @@ -46,7 +46,7 @@ docs/ 1. 在对应章节创建 Markdown 文件。 2. 在 `docs/.vitepress/config.mts` 的 sidebar 中加入页面。 3. 在 `docs/zh/` 下创建中文页面,并加入中文 sidebar。 -4. 从[从这里开始](/zh/guide/overview)可达的相关指南或主题索引中加入正文链接。在页面正文中链接任务前置步骤和下一步。 +4. 从[移植设备](/zh/porting/)可达的相关指南或主题索引中加入正文链接。在页面正文中链接任务前置步骤和下一步。 5. 在两个语言版本中从起始页沿正文链接检查新页面是否可达。 6. 运行 `npm run build`,修复坏链。 7. 新章节需要加入语言切换配置。 @@ -84,7 +84,7 @@ VitePress 在内部链接断开时构建失败。 ## 下一步 - [仓库布局](/zh/contributing/repository) -- [总览](/zh/guide/overview) +- [移植设备](/zh/porting/) ## 设备记录 diff --git a/docs/zh/guide/overview.md b/docs/zh/guide/overview.md index d4cce29..ec511ad 100644 --- a/docs/zh/guide/overview.md +++ b/docs/zh/guide/overview.md @@ -1,162 +1,16 @@ -# 从这里开始 +--- +title: 移植设备 +sidebar: false +aside: false +prev: false +next: false +head: + - - meta + - http-equiv: refresh + content: "0; url=/zh/porting/" + - - link + - rel: canonical + href: https://unixnu.com/zh/porting/ +--- -UniXNU 在 ARM64 设备上从 UEFI 环境启动 iOS 或 macOS。整个栈分为六层,每一层都有对应的仓库、构建产物和交接约定。 - -## 构建并启动已有设备 - -1. 在[支持的设备](/zh/devices/)中找到设备移植,阅读其配置、所需输入和当前结果。 -2. 准备[主机工具和外部输入](/zh/guide/requirements)。Linux 用户先完成[工具链安装](/zh/guide/requirements#linux)。 -3. 在[本地构建配置](/zh/reference/configuration#local-build-inputs)中保存路径,按[构建流程](/zh/building)和[内核准备](/zh/guide/build-kernel)操作。 -4. 构建设备的 [UEFI 固件](/zh/porting/uefi-firmware#required-integration),包含必需的加载器和负载文件系统驱动。 -5. 创建[负载](/zh/concepts/payload)和 [userdata 镜像](/zh/guide/userdata),再[打包并启动镜像](/zh/guide/boot)。 -6. 检查[日志和启动阶段](/zh/guide/debugging)。构建或启动失败时按[故障排查](/zh/reference/troubleshooting)定位。 - -修改启动参数后需要重新构建负载和启动镜像,步骤见[应用启动参数](/zh/xnu/boot-arguments#apply-arguments)。顶部绿色条标记加载器交接阶段,后续检查见[绿条诊断](/zh/guide/debugging#green-bar)。 - -## 按任务阅读 - -| 任务 | 阅读路径 | -| --- | --- | -| 新增设备 | [移植流程](/zh/porting/) → [设备仓库](/zh/porting/device-repository) → [驱动适配](/zh/porting/drivers) → [bring-up 顺序](/zh/porting/bring-up) → [适配记录](/zh/porting/records) | -| 迁移设备仓库 | [迁移指南](/zh/porting/migration) → [配置参考](/zh/reference/configuration) | -| 选择或开发驱动 | [组件目录](/zh/reference/components) → [驱动分层](/zh/drivers/overview) → [驱动仓库和组件页面](/zh/drivers/repositories) | -| 修改 XNU | [源码与补丁](/zh/xnu/source-and-patches) → [补丁参考](/zh/xnu/patch-reference) → [4 KiB 页表](/zh/xnu/four-k-page-tables) | -| 配置构建或启动项 | [命令行](/zh/reference/cli)、[设备配置](/zh/reference/configuration)、[启动配置](/zh/reference/boot-configuration)、[输出布局](/zh/reference/output-layout) | -| 使用 QEMU 测试 | [QEMU 流程](/zh/reference/qemu) | -| 贡献代码或文档 | [仓库布局](/zh/contributing/repository) → [文档维护流程](/zh/contributing/documentation) | - -## 理解启动过程 - -按需阅读[启动链](/zh/concepts/boot-chain)、[内核预链接](/zh/concepts/prelink)、 -[启动负载](/zh/concepts/payload)、[userdata 布局](/zh/concepts/userdata)和 -[完整性与启动策略](/zh/concepts/security)。[术语表](/zh/reference/glossary)解释指南中的术语。 - -## 分层模型 - -``` -Android bootloader (ABL) - | - | fastboot boot boot.img - v -BootShim + UEFI 固件卷 + 设备树 - | - | UEFI BDS 启动 UniXNU - v -UniXNU(UEFI 启动管理器) - | - | UNIXNU_LOADER_PROTOCOL - v -DarwinBoot(XNU 加载器) - | - | boot_args、ADT、trust cache、ramdisk - v -打过补丁的 XNU 内核 - | - | IOKit、BSD、launchd - v -来自 IPSW 的用户态(OS 与 SystemOS) -``` - -## 组件 - -### 启动镜像 - -启动镜像是 header version 0 的 Android boot image。kernel 字段存放 gzip 数据,由两部分组成:编译后的 BootShim 和 UEFI 固件卷。gzip 流之后是设备树。ramdisk 字段存放 UniXNU 负载。 - -设备原有的 Android bootloader 按 Mu-Silicium 设备配置中的地址加载镜像,校验 ARM64 image header,然后跳转到 shim。BootShim 重定位固件卷并进入 UEFI。 - -### UEFI 固件 - -固件来自设备的 Mu-Silicium 仓库,提供启动管理器所需的服务: - -- `EFI_GRAPHICS_OUTPUT_PROTOCOL`:菜单和内核 framebuffer。 -- `EFI_SIMPLE_TEXT_IN_PROTOCOL`:菜单输入。 -- `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL` 与 `EFI_BLOCK_IO_PROTOCOL`:负载卷和磁盘分区。 -- `EFI_SERIAL_IO_PROTOCOL`:板级 UART 日志。 - -`./unixnu build firmware` 会把板级补丁应用到共享 edk2 树,构建板级 DSC,并返回 `SILICIUM_UEFI.fd`。使用 Mu-Silicium initrd 负载时,DSC 和 FDF 需包含共享的 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 驱动,供 UniXNU 发现负载启动项。步骤见[必需的固件集成](/zh/porting/uefi-firmware#required-integration)。 - -### 启动管理器 - -UniXNU 启动管理器是由 `package/UniXNUPkg` 构建的 UEFI 应用。它先从启动所在卷读取 `\EFI\UniXNU\unixnu.toml`,再扫描其他卷。配置声明菜单项、驱动、设备树补丁、ACPI 表、块设备切片和 kit。 - -菜单出现前,启动管理器完成五件事: - -1. 把每个 `[[block_slice]]` 发布为块设备。 -2. 加载并启动配置中的 UEFI 驱动。 -3. 安装配置中的 ACPI 表。 -4. 合并 `[match]` 条件满足的 kit。 -5. 为选中项准备设备树。 - -类型为 `xnu` 的菜单项会交给实现 `UNIXNU_LOADER_PROTOCOL` 的加载器。 - -### DarwinBoot - -DarwinBoot 是固件卷中的 UEFI 驱动,在 EL2 或 EL1 安装加载器协议。处理 `xnu` 菜单项时执行以下步骤: - -1. 从负载卷读取内核 Mach-O。 -2. 读取内核旁边的 `.adt` sidecar。 -3. 读取可选的 `.trustcache` sidecar。 -4. 校验 Mach-O 段、ADT 和 trust cache 结构。 -5. 为内核及其数据分配物理窗口。 -6. 复制内核段、ADT、trust cache 和 ramdisk。 -7. 构造 Darwin `boot_args`。 -8. 退出 boot services,关闭 MMU 和缓存,在 EL1 跳转到内核入口。 - -加载器要求单个 ARM64 Mach-O,包含 `__TEXT` 段、`LC_MAIN` 入口,基地址按固件页大小对齐。 - -### XNU 内核 - -内核由 Apple `xnu-10063.141.1` 源码加上 `patches/xnu` 中的补丁构建。BCM2837 机型配置提供非 Apple ARM64 板所需的 4 KiB 页布局。 - -构建出的原生内核会与目标 IPSW 的原始 kernelcache 预链接。预链接保留原始 Apple kext,并把原生内核绑定到它们的符号。结果是单个 `kernel.macho`,包含原生内核段和选中的原始组件。 - -### 用户态 - -userdata 镜像保存 IPSW 中未修改的 `OS` 和 `Cryptex1,SystemOS` 磁盘镜像。分区开头有一个 4 KiB manifest,描述两个窗口。原生 UFS 或块驱动发布分区,XNU 按 UUID 挂载根卷。 - -## 仓库 - -`UniXNU` 维护构建工具、组件目录、ARM64 与 OS 配置、模板、UEFI package 和文档站。`UniXNU--common` 维护共享 SoC 配置、DTSI、平台操作和补丁。组件仓库维护驱动、库、加载器和工具。 - -| 仓库 | 用途 | -| --- | --- | -| `UniXNU` | 构建工具、组件目录、ARM64 与 OS 配置、模板、UEFI package 和文档站 | -| `UniXNU--common` | SoC 配置、DTSI、平台操作和补丁 | -| 组件仓库 | 驱动、库、加载器和工具 | -| `UniXNU-` | 板级描述、内核 defconfig、设备脚本、设备驱动和 package | -| `uefi-` | 设备的 Mu-Silicium UEFI 移植 | - -设备仓库选择固定版本的 SoC 支持、OS 配置和组件,用 DTS 描述板级外设,并提供固件输入、分区布局与打包。构建工具解析依赖并组装目标树。 - -## 构建产物 - -所有输出位于 `out/`: - -``` -out/ - state.json 记住的设备仓库 - feeds/ 拉取的 git 源码 - ipsw// 解压的 IPSW 成员 - /// - .config 选中的 defconfig - tree/ 组装后的构建树 - logs/ 每一步的日志 - kernel/kernel.macho 预链接内核 - package/Build/Out/ UniXNU 和测试 EFI 程序 - payload/payload.img FAT 负载卷 - payload/payload.json 负载报告 - boot/boot.img Android 启动镜像 - boot/boot.json 启动镜像报告 - userdata/userdata-root.img - userdata/userdata-root.json -``` - -报告记录输入哈希和生成下一步的命令。给定固件卷、设备树和 ramdisk 时,启动镜像是确定性的。ADT 包含随机种子,因此两次负载构建的结果不同。 - -## 下一步 - -- [构建环境](/zh/guide/requirements)列出主机工具和外部输入。 -- [构建](/zh/building)介绍驱动命令。 -- [移植](/zh/porting/)介绍如何新增设备。 -- [设备](/zh/devices/)列出设备仓库。sheng 页面记录一个设备,通用指南使用占位符。 +[移植设备](/zh/porting/) diff --git a/docs/zh/index.md b/docs/zh/index.md index 6684b9c..147cb40 100644 --- a/docs/zh/index.md +++ b/docs/zh/index.md @@ -13,14 +13,11 @@ hero: alt: UniXNU 标志 actions: - theme: brand - text: 从这里开始 - link: /zh/guide/overview + text: 移植设备 + link: /zh/porting/ - theme: brand text: 支持的设备 link: /zh/devices/ - - theme: alt - text: 移植设备 - link: /zh/porting/ - theme: alt text: GitHub link: https://github.com/UniXNU/UniXNU diff --git a/docs/zh/porting/index.md b/docs/zh/porting/index.md index 44b04d1..09ed27a 100644 --- a/docs/zh/porting/index.md +++ b/docs/zh/porting/index.md @@ -1,7 +1,10 @@ # 移植设备 -从 UniXNU 仓库按以下顺序操作,每一步都为下一步准备输入。现有设备仓库先读 -[迁移指南](/zh/porting/migration);构建已有移植请读[构建指南](/zh/building)。 +UniXNU 通过 UEFI 在 ARM64 设备上运行 iOS 或 macOS。按下面八个步骤准备输入、选择共享支持、适配驱动并构建镜像,每一步都写明完成结果。 + +- **新增设备:** 从步骤 1 开始。 +- **构建已有设备:** 在[设备列表](/zh/devices/)确认输入和当前支持范围,再按[构建指南](/zh/building)操作。 +- **迁移已有仓库:** 按[迁移指南](/zh/porting/migration)更新配置,再继续需要完成的驱动适配和构建步骤。 ## 1. 收集设备输入 @@ -120,3 +123,16 @@ python3 scripts/porting-record.py check --device "../UniXNU-$DEVICE" 发布设备仓库后,在接入中央站点时将提交固定到 `devices.toml`。 按[记录指南](/zh/porting/records)和[文档贡献](/zh/contributing/documentation)操作, 在两种语言的[设备列表](/zh/devices/)中加入页面链接。详细指南放在主仓库,设备 README 链接到对应指南。 + +## 相关文档 + +按当前步骤查阅以下说明: + +| 内容 | 文档 | +| --- | --- | +| 启动过程与镜像输入 | [启动链](/zh/concepts/boot-chain)、[预链接](/zh/concepts/prelink)、[payload](/zh/concepts/payload)、[userdata 布局](/zh/concepts/userdata)、[完整性与启动策略](/zh/concepts/security) | +| 组件实现与开发 | [驱动分层](/zh/drivers/overview)、[驱动仓库和组件页面](/zh/drivers/repositories) | +| 内核修改 | [源码与补丁](/zh/xnu/source-and-patches)、[补丁参考](/zh/xnu/patch-reference)、[4 KiB 页表](/zh/xnu/four-k-page-tables) | +| 构建与启动配置 | [命令行](/zh/reference/cli)、[设备配置](/zh/reference/configuration)、[启动配置](/zh/reference/boot-configuration)、[输出布局](/zh/reference/output-layout) | +| 主机验证 | [QEMU 流程](/zh/reference/qemu) | +| 项目维护 | [仓库布局](/zh/contributing/repository)、[文档维护](/zh/contributing/documentation)、[术语表](/zh/reference/glossary) | diff --git a/docs/zh/reference/glossary.md b/docs/zh/reference/glossary.md index a13e1ff..1f6622f 100644 --- a/docs/zh/reference/glossary.md +++ b/docs/zh/reference/glossary.md @@ -38,6 +38,6 @@ ## 下一步 -- [总览](/zh/guide/overview) +- [移植设备](/zh/porting/) - [命令行](/zh/reference/cli) - [设备](/zh/devices/)