okooooooo/UniXNU
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: highlight firmware build and payload discovery requirements

Browse Source
This commit is contained in:
UniXNU Docs committed 2026-10-25 02:57:27 +08:00
1 parent 8d157ee18a
commit 9521f49712
26 files changed
+187 -30
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+5
View File
@@ -78,6 +78,11 @@ npm ci
npm run build
```
For a Mu-Silicium initrd payload, include `UniXNURamDiskDxe`, DiskIoDxe and
FAT support in the firmware DSC and FDF. Run `./unixnu build firmware` and
build the payload before `./unixnu bootimg`. Follow
[required firmware integration](https://unixnu.com/porting/uefi-firmware#required-integration).
## Verification and reporting
Run existing checks and targeted build exercises for changed behavior. Add a
README.md
+4
View File
@@ -27,6 +27,10 @@ UniXNU provides shared build tools, ARM64 support, OS profiles and reusable comp
**🎉 News:** Adreno740 and AdrenoMetal provide GPU acceleration on sheng. The render server composites the system UI through the Adreno 740, and listed processes get their own Metal devices. These components are shared GPU implementations; each device port supplies the required firmware, power, memory and display integration. See the [Adreno 740 driver documentation](https://unixnu.com/drivers/adreno740).
## Firmware requirement
Build the device firmware with `./unixnu build firmware --uefi ../uefi-<device>` before `./unixnu bootimg`. Include UniXNU, UniXNUDxe, DarwinBoot and the shared `UniXNURamDiskDxe` payload driver in the firmware. Follow the [required firmware integration](https://unixnu.com/porting/uefi-firmware#required-integration).
## Documentation
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.
README.zh-CN.md
+4
View File
@@ -27,6 +27,10 @@ UniXNU 为不同 SoC 和设备的移植提供共享构建工具、ARM64 支持
**🎉 News:** Adreno740 和 AdrenoMetal 在 sheng 上提供 GPU 加速。render server 通过 Adreno 740 合成系统界面，列入白名单的进程会获得各自的 Metal 设备。这两个组件提供共享 GPU 实现，各设备适配提供所需的固件、电源、内存和显示集成。详见 [Adreno 740 驱动文档](https://unixnu.com/zh/drivers/adreno740)。
## 固件要求
运行 `./unixnu bootimg` 前，先用 `./unixnu build firmware --uefi ../uefi-<device>` 构建设备固件，并将 UniXNU、UniXNUDxe、DarwinBoot 和共享负载驱动 `UniXNURamDiskDxe` 纳入固件。步骤见[必需的固件集成](https://unixnu.com/zh/porting/uefi-firmware#required-integration)。
## 文档
文档位于 [unixnu.com](https://unixnu.com)，源码、导航、翻译、资源、配置和部署工作流由本仓库维护。文档覆盖启动链、构建驱动、设备移植、驱动开发、XNU 4 KiB 页补丁、启动参数和设备说明。
devices.toml
+1 -1
View File
@@ -3,4 +3,4 @@ schema_version = 1
[[device]]
name = "sheng"
repository = "UniXNU/UniXNU-sheng"
revision = "95295f4874cf3da2cdfffff8784e185d2eba8f62"
revision = "93e25c6b8606902de13f12c4d160c860f52a7d98"
docs/building.md
+6 -1
View File
@@ -2,6 +2,10 @@
`unixnu` resolves ARM64, SoC, OS, and device profiles, selects component dependencies, assembles a target tree, and runs each build step. Format 2 uses `out/<device>/<os_profile>/<config>/`. Format 1 uses `out/<board>/`.
::: warning Required firmware integration
Build the device firmware with `./unixnu build firmware --uefi ../uefi-<device>` before packing the boot image. Its DSC and FDF must include UniXNU, UniXNUDxe, DarwinBoot and the payload volume driver. For the Mu-Silicium FDT initrd path, use the shared `UniXNURamDiskDxe` with DiskIoDxe and FAT support. Follow [firmware integration](/porting/uefi-firmware#required-integration).
:::
## Quick start
```sh
@@ -19,6 +23,7 @@ git submodule update --init --recursive
./unixnu build kernel
./unixnu build package
./unixnu build firmware --uefi ../uefi-sheng
./unixnu build payload --unique-chip-id <hex> --trust-cache <file> --data-ramdisk <seed>
./unixnu bootimg --uefi ../uefi-sheng --dtb /path/to/device.dtb
```
@@ -177,7 +182,7 @@ The output is `out/<device>/<os_profile>/<config>/kernel/kernel.macho`.
### package
The package step builds `package/` with EDK II. The output is `out/<device>/<os_profile>/<config>/package/Build/Out`. It contains `UniXNU.efi`, `UniXNUDxe.efi`, `HelloPayload.efi`, `SampleDriver.efi` and `XnuTest.efi`.
The package step builds `package/` with EDK II. The output is `out/<device>/<os_profile>/<config>/package/Build/Out`. It contains `UniXNU.efi`, `UniXNUDxe.efi`, `UniXNURamDiskDxe.efi`, `HelloPayload.efi`, `SampleDriver.efi` and `XnuTest.efi`.
### firmware
docs/concepts/payload.md
+2
View File
@@ -2,6 +2,8 @@
The payload is a FAT volume that becomes the ramdisk of the Android boot image. UniXNU reads the configuration from it, and DarwinBoot reads the kernel, the ADT and the optional trust cache from it.
For a Mu-Silicium initrd payload, embed `UniXNURamDiskDxe`, DiskIoDxe and the FAT driver in the firmware. They expose the payload volume before UniXNU reads its configuration. See [payload discovery](/porting/uefi-firmware#payload-discovery).
## Volume layout
```
docs/drivers/uefi-drivers.md
+2
View File
@@ -2,6 +2,8 @@
A UEFI driver is an EDK II module built as a `.efi` image. It runs in boot services and can publish protocols, bind devices and prepare hardware for the next stage.
The shared `UniXNURamDiskDxe` module in `package/UniXNUPkg/Driver/` exposes a Mu-Silicium FDT initrd as a read-only Block I/O device. Include it in the firmware DSC and FDF with DiskIoDxe and FAT support. See [firmware integration](/porting/uefi-firmware#required-integration).
## Module layout
```
docs/guide/boot.md
+2
View File
@@ -2,6 +2,8 @@
The boot image runs from RAM. The workflow starts the image and leaves the installed boot partition unchanged.
Build the firmware with `./unixnu build firmware --uefi ../uefi-<device>` and include `UniXNURamDiskDxe` plus DiskIoDxe and FAT support for a Mu-Silicium initrd payload. Build the payload before `./unixnu bootimg`. The [firmware integration guide](/porting/uefi-firmware#required-integration) lists the required DSC/FDF entries and menu checks.
## Prerequisites
- An unlocked bootloader with `fastboot`.
docs/guide/overview.md
+1 -1
View File
@@ -45,7 +45,7 @@ The firmware comes from a Mu-Silicium checkout for the device. It provides the U
- `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`.
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
docs/porting/bring-up.md
+1 -1
View File
@@ -12,7 +12,7 @@ Checks:
- The boot image header matches the bootloader requirement.
- `fastboot boot boot.img` starts the firmware without a reset.
- The framebuffer shows output, or the serial port shows UEFI output.
- Block devices and the payload volume are visible.
- Block devices and the payload volume are visible. For a Mu-Silicium initrd payload, check `UniXNURamDiskDxe`, DiskIoDxe and FAT in the FD using the [firmware integration guide](/porting/uefi-firmware#required-integration).
Tools:
docs/porting/index.md
+2
View File
@@ -2,6 +2,8 @@
UniXNU assembles a device from shared profiles and independent repositories.
Start firmware integration with the [required modules and build commands](/porting/uefi-firmware#required-integration). Mu-Silicium initrd payloads use the shared `UniXNURamDiskDxe` driver to make their configured entries available to UniXNU.
| Repository | Responsibility |
| --- | --- |
| `UniXNU` | Build tools, catalog, ARM64 support, OS profiles, templates, UEFI package, documentation site |
docs/porting/migration.md
+2
View File
@@ -4,6 +4,8 @@ Read the root `AGENTS.md`, [device repository specification](/porting/device-rep
[component catalog](/reference/components), and [device-tree specification](/porting/device-tree).
Run commands from the UniXNU checkout unless a command selects another directory.
For firmware migration, add `UniXNURamDiskDxe` and its filesystem dependencies to the device DSC and FDF, then run `./unixnu build firmware --uefi ../uefi-<device>`. Follow [required firmware integration](/porting/uefi-firmware#required-integration) before assembling the boot image.
## Format detection
```sh
docs/porting/uefi-firmware.md
+65 -10
View File
@@ -2,6 +2,64 @@
The UEFI firmware port comes from Mu-Silicium. It supplies the services UniXNU and DarwinBoot use.
## Required integration
Build firmware from the UniXNU checkout after selecting the device:
```sh
./unixnu defconfig <device>_defconfig -D ../UniXNU-<device>
./unixnu build firmware --uefi ../uefi-<device>
```
The firmware needs all of these modules in its DSC `[Components]` and FDF firmware volume:
| Module | Purpose |
| --- | --- |
| `UniXNUPkg/Application/UniXNU/UniXNU.inf` | Boot menu and configuration reader |
| `UniXNUPkg/Driver/UniXNUDxe/UniXNUDxe.inf` | Firmware boot option registration |
| `DarwinBootPkg/Driver/DarwinBoot.inf` | XNU loader |
| `UniXNUPkg/Driver/UniXNURamDiskDxe/UniXNURamDiskDxe.inf` | Publish the Mu-Silicium FDT initrd as a read-only block device |
| `MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIoDxe.inf` | Disk access for the filesystem driver |
| `FatPkg/EnhancedFatDxe/Fat.inf` | Expose the payload's FAT filesystem |
List each path directly under DSC `[Components]`; use `INF <path>` in the FDF. Map the shared driver's libraries in DSC `[LibraryClasses]`:
```ini
HobLib|MdePkg/Library/DxeHobLib/DxeHobLib.inf
FdtLib|MdePkg/Library/BaseFdtLib/BaseFdtLib.inf
```
Add `PartitionDxe` when the payload uses a partition table. The FAT driver also needs the platform's Unicode collation service. sheng's `Include/DXE.inc` contains these dependencies.
`UniXNURamDiskDxe` is shared by devices using Mu-Silicium's FDT handoff. Its source is in UniXNU's `package/UniXNUPkg/Driver/UniXNURamDiskDxe/`. Board memory reservations and memory expansion remain in the firmware platform.
A supplied `.fd` must contain this integration and match the board's firmware base and size. `./unixnu bootimg --fd <file>` packages the supplied firmware. Rebuild the FD after changing its DSC, FDF or drivers.
Build the payload with the selected device's inputs, then pack the image:
```sh
./unixnu build payload --unique-chip-id <hex> --trust-cache <file> --data-ramdisk <seed>
./unixnu bootimg --uefi ../uefi-<device> --dtb /path/to/firmware.dtb
```
Use the options required by the device's payload profile. See [payload inputs](/concepts/payload).
## Payload discovery
The Android bootloader places the FAT payload in RAM and writes `/chosen/linux,initrd-start` and `linux,initrd-end` into the firmware FDT. Each property is a 32-bit or 64-bit big-endian address. The range must contain complete 512-byte sectors and remain reserved while UEFI uses it.
Mu-Silicium SEC preserves the incoming FDT address as a `UINT64` in the entry-argument HOB (`DAEE82E6-8090-4E72-BFB9-78C13CD4E359`). `UniXNURamDiskDxe` reads this handoff and publishes Block I/O. DiskIoDxe and the FAT driver expose `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL`, allowing UniXNU to read `\EFI\UniXNU\unixnu.toml` and list its entries.
If the menu appears without the configured entries, check:
1. `boot/boot.json` reports a nonzero `ramdisk_bytes` value.
2. The FD contains `UniXNURamDiskDxe`, DiskIoDxe and the FAT driver.
3. The firmware FDT has valid initrd start and end properties.
4. The serial log contains `UNIXNURAMDISK: initrd block device` with a successful status.
5. The payload FAT volume contains `EFI/UniXNU/unixnu.toml` and its referenced files.
The RAM disk driver must be embedded in the firmware so the payload can be discovered before its configuration is read.
## Required services
| Service | Consumer |
@@ -86,10 +144,11 @@ UniXNU and DarwinBoot are included through their INFs:
```
UniXNUPkg/Application/UniXNU/UniXNU.inf
UniXNUPkg/Driver/UniXNUDxe/UniXNUDxe.inf
UniXNUPkg/Driver/UniXNURamDiskDxe/UniXNURamDiskDxe.inf
DarwinBootPkg/Driver/DarwinBoot.inf
```
The firmware FDF decides whether they are embedded in the firmware volume or copied to the ESP.
Embed these modules in the firmware volume for an initrd payload. Place the configuration and kernel files in the payload FAT volume.
## Preflight
@@ -142,16 +201,12 @@ The output path comes from `[firmware] fd`:
fd = "Build/<device>Pkg/{target}_CLANGPDB/FV/SILICIUM_UEFI.fd"
```
## Standalone build
## External firmware builds
The Mu-Silicium checkout can be built with its own script:
```sh
cd Mu-Silicium
python3 build_uefi.py -d <device>
```
The UniXNU driver performs the same build with the board defines and the shared edk2 patches.
A firmware supplied with `./unixnu bootimg --fd <file>` needs the same DSC/FDF
modules, package paths, board defines and EDK II patches as the selected
`[firmware]` configuration. Check the [required integration](#required-integration)
and use the matching board configuration when packing the image.
## Boot image integration
docs/reference/troubleshooting.md
+1 -1
View File
@@ -40,7 +40,7 @@
| Firmware stalls | Random Silicium stall | Start the same image again |
| No display | GOP driver | Use `console = "text"` or a serial console |
| No menu | Configuration path | Place `unixnu.toml` at `\EFI\UniXNU\unixnu.toml` |
| No boot entry | Payload volume | Check the FAT label, the entry path and the volume driver |
| No boot entry | Payload volume | Check `boot.json` for a nonzero `ramdisk_bytes`, the FD for UniXNURamDiskDxe/DiskIoDxe/FAT, the FDT initrd range, and `EFI/UniXNU/unixnu.toml`. Follow [payload discovery](/porting/uefi-firmware#payload-discovery). |
| Driver failed | First failure reason in the menu | Fix the driver path or its dependencies |
| `no loader protocol installed` | DarwinBoot in the firmware volume | Add DarwinBoot to the FDS or the payload |
| `loader revision 1 cannot accept kexts` | Loader revision | Use a revision 2 loader or remove the kexts |
docs/zh/building.md
+6 -1
View File
@@ -2,6 +2,10 @@
`unixnu` 解析 ARM64、SoC、OS 和设备配置，选择组件依赖并组装目标树。格式 2 输出位于 `out/<device>/<os_profile>/<config>/`，格式 1 使用 `out/<board>/`。
::: warning 必需的固件集成
打包启动镜像前，运行 `./unixnu build firmware --uefi ../uefi-<device>` 构建设备固件。DSC 和 FDF 必须包含 UniXNU、UniXNUDxe、DarwinBoot 和负载卷驱动。Mu-Silicium 的 FDT initrd 路径使用共享的 `UniXNURamDiskDxe`，并需要 DiskIoDxe 和 FAT 支持。步骤见[固件集成](/zh/porting/uefi-firmware#required-integration)。
:::
## 快速开始
```sh
@@ -19,6 +23,7 @@ git submodule update --init --recursive
./unixnu build kernel
./unixnu build package
./unixnu build firmware --uefi ../uefi-sheng
./unixnu build payload --unique-chip-id <hex> --trust-cache <file> --data-ramdisk <seed>
./unixnu bootimg --uefi ../uefi-sheng --dtb /path/to/device.dtb
```
@@ -179,7 +184,7 @@ kernelcache 来自 IPSW，除非 `--kernelcache` 指定文件。`KernelCache` IM
### package
package 步骤用 EDK II 构建 `package/`，输出到 `out/<device>/<os_profile>/<config>/package/Build/Out`，包含 `UniXNU.efi`、`UniXNUDxe.efi`、`HelloPayload.efi`、`SampleDriver.efi` 和 `XnuTest.efi`。
package 步骤用 EDK II 构建 `package/`，输出到 `out/<device>/<os_profile>/<config>/package/Build/Out`，包含 `UniXNU.efi`、`UniXNUDxe.efi`、`UniXNURamDiskDxe.efi`、`HelloPayload.efi`、`SampleDriver.efi` 和 `XnuTest.efi`。
### firmware
docs/zh/concepts/payload.md
+2
View File
@@ -2,6 +2,8 @@
负载是一个 FAT 卷，作为 Android 启动镜像的 ramdisk。UniXNU 从中读取配置，DarwinBoot 从中读取内核、ADT 和可选 trust cache。
使用 Mu-Silicium initrd 负载时，固件需嵌入 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 驱动，在 UniXNU 读取配置前发布负载卷。详见[负载发现](/zh/porting/uefi-firmware#payload-discovery)。
## 卷布局
```
docs/zh/drivers/uefi-drivers.md
+2
View File
@@ -2,6 +2,8 @@
UEFI 驱动是构建为 `.efi` 的 EDK II 模块，运行在 boot services，可以发布协议、绑定设备，为下一阶段准备硬件。
共享模块 `UniXNURamDiskDxe` 位于 `package/UniXNUPkg/Driver/`，把 Mu-Silicium FDT 中的 initrd 发布为只读 Block I/O 设备。将它与 DiskIoDxe、FAT 支持一起加入固件 DSC 和 FDF。详见[固件集成](/zh/porting/uefi-firmware#required-integration)。
## 模块布局
```
docs/zh/guide/boot.md
+2
View File
@@ -2,6 +2,8 @@
启动镜像从内存运行。流程启动镜像，并保持已安装的 boot 分区不变。
使用 `./unixnu build firmware --uefi ../uefi-<device>` 构建固件。Mu-Silicium initrd 负载需要在固件中加入 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 支持，并在 `./unixnu bootimg` 前构建负载。[固件集成指南](/zh/porting/uefi-firmware#required-integration)列出了必需的 DSC/FDF 条目和菜单检查步骤。
## 前提
- bootloader 已解锁并支持 `fastboot`。
docs/zh/guide/overview.md
+1 -1
View File
@@ -45,7 +45,7 @@ DarwinBoot（XNU 加载器）
- `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL` 与 `EFI_BLOCK_IO_PROTOCOL`：负载卷和磁盘分区。
- `EFI_SERIAL_IO_PROTOCOL`：板级 UART 日志。
`unixnu build firmware` 会把板级补丁应用到共享 edk2 树，构建板级 DSC，并返回 `SILICIUM_UEFI.fd`。
`./unixnu build firmware` 会把板级补丁应用到共享 edk2 树，构建板级 DSC，并返回 `SILICIUM_UEFI.fd`。使用 Mu-Silicium initrd 负载时，DSC 和 FDF 需包含共享的 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 驱动，供 UniXNU 发现负载启动项。步骤见[必需的固件集成](/zh/porting/uefi-firmware#required-integration)。
### 启动管理器
docs/zh/porting/bring-up.md
+1 -1
View File
@@ -12,7 +12,7 @@ bring-up 按阶段推进。每个阶段都有可见结果和日志行，一次
- 启动镜像 header 满足 bootloader 要求。
- `fastboot boot boot.img` 启动固件，不复位。
- framebuffer 有输出，或串口有 UEFI 输出。
- 块设备和负载卷可见。
- 块设备和负载卷可见。Mu-Silicium initrd 负载需要在 FD 中包含 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT，详见[固件集成](/zh/porting/uefi-firmware#required-integration)。
```sh
fastboot boot out/<device>/<os_profile>/<config>/boot/boot.img
docs/zh/porting/index.md
+2
View File
@@ -2,6 +2,8 @@
UniXNU 通过共享配置和独立仓库组装设备构建。
固件集成从[必需模块与构建命令](/zh/porting/uefi-firmware#required-integration)开始。Mu-Silicium initrd 负载通过共享的 `UniXNURamDiskDxe` 驱动向 UniXNU 提供配置中的启动项。
| 仓库 | 职责 |
| --- | --- |
| `UniXNU` | 构建工具、组件目录、ARM64 支持、OS 配置、模板、UEFI package 和文档站 |
docs/zh/porting/migration.md
+2
View File
@@ -4,6 +4,8 @@
[组件目录](/zh/reference/components)和[设备树规范](/zh/porting/device-tree)。
以下命令从 UniXNU 检出目录运行，带目录参数的命令使用指定目录。
迁移固件时，把 `UniXNURamDiskDxe` 及其文件系统依赖加入设备 DSC 和 FDF，再运行 `./unixnu build firmware --uefi ../uefi-<device>`。组装启动镜像前，完成[必需的固件集成](/zh/porting/uefi-firmware#required-integration)。
## 格式识别
```sh
docs/zh/porting/uefi-firmware.md
+64 -10
View File
@@ -2,6 +2,64 @@
UEFI 固件移植来自 Mu-Silicium，提供 UniXNU 和 DarwinBoot 使用的服务。
## 必需的集成 {#required-integration}
选择设备后，从 UniXNU 仓库构建固件：
```sh
./unixnu defconfig <device>_defconfig -D ../UniXNU-<device>
./unixnu build firmware --uefi ../uefi-<device>
```
固件 DSC 的 `[Components]` 和 FDF 固件卷都需要包含以下模块：
| 模块 | 用途 |
| --- | --- |
| `UniXNUPkg/Application/UniXNU/UniXNU.inf` | 启动菜单和配置读取 |
| `UniXNUPkg/Driver/UniXNUDxe/UniXNUDxe.inf` | 注册固件启动项 |
| `DarwinBootPkg/Driver/DarwinBoot.inf` | XNU 加载器 |
| `UniXNUPkg/Driver/UniXNURamDiskDxe/UniXNURamDiskDxe.inf` | 将 Mu-Silicium FDT 中的 initrd 发布为只读块设备 |
| `MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIoDxe.inf` | 为文件系统驱动提供磁盘访问 |
| `FatPkg/EnhancedFatDxe/Fat.inf` | 发布负载的 FAT 文件系统 |
在 DSC 的 `[Components]` 中直接列出路径，在 FDF 中使用 `INF <path>`。在 DSC 的 `[LibraryClasses]` 中配置共享驱动的库：
```ini
HobLib|MdePkg/Library/DxeHobLib/DxeHobLib.inf
FdtLib|MdePkg/Library/BaseFdtLib/BaseFdtLib.inf
```
负载使用分区表时还需加入 `PartitionDxe`。FAT 驱动需要平台提供 Unicode collation 服务。sheng 的 `Include/DXE.inc` 包含这些依赖。
`UniXNURamDiskDxe` 供使用 Mu-Silicium FDT 交接的设备共用，源码位于 UniXNU 的 `package/UniXNUPkg/Driver/UniXNURamDiskDxe/`。板级内存保留区和内存补充由固件平台维护。
传入的 `.fd` 必须包含这些集成，并匹配设备的固件基址和大小。`./unixnu bootimg --fd <file>` 打包指定固件。修改 DSC、FDF 或驱动后，重新构建 FD。
使用所选设备的输入构建负载，然后打包镜像：
```sh
./unixnu build payload --unique-chip-id <hex> --trust-cache <file> --data-ramdisk <seed>
./unixnu bootimg --uefi ../uefi-<device> --dtb /path/to/firmware.dtb
```
按设备负载配置提供所需选项，详见[负载输入](/zh/concepts/payload)。
## 负载发现 {#payload-discovery}
Android bootloader 将 FAT 负载放入 RAM，并把地址写入固件 FDT 的 `/chosen/linux,initrd-start` 和 `linux,initrd-end`。两个属性均使用 32 位或 64 位大端地址。范围需要包含完整的 512 字节扇区，并在 UEFI 使用期间保持保留。
Mu-Silicium SEC 把传入的 FDT 地址以 `UINT64` 保存到入口参数 HOB（`DAEE82E6-8090-4E72-BFB9-78C13CD4E359`）。`UniXNURamDiskDxe` 读取该交接并发布 Block I/O。DiskIoDxe 和 FAT 驱动提供 `EFI_SIMPLE_FILE_SYSTEM_PROTOCOL`，供 UniXNU 读取 `\EFI\UniXNU\unixnu.toml` 并列出其中的启动项。
菜单出现但缺少配置中的启动项时，依次检查：
1. `boot/boot.json` 的 `ramdisk_bytes` 大于零。
2. FD 包含 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 驱动。
3. 固件 FDT 中的 initrd 起止地址有效。
4. 串口出现 `UNIXNURAMDISK: initrd block device` 且状态成功。
5. 负载 FAT 卷包含 `EFI/UniXNU/unixnu.toml` 及其引用的文件。
RAM disk 驱动需要嵌入固件，以便在读取负载配置之前发现负载卷。
## 必需服务
| 服务 | 使用方 |
@@ -86,10 +144,11 @@ UniXNU 和 DarwinBoot 通过 INF 加入：
```
UniXNUPkg/Application/UniXNU/UniXNU.inf
UniXNUPkg/Driver/UniXNUDxe/UniXNUDxe.inf
UniXNUPkg/Driver/UniXNURamDiskDxe/UniXNURamDiskDxe.inf
DarwinBootPkg/Driver/DarwinBoot.inf
```
FDF 决定它们嵌入固件卷还是复制到 ESP。
使用 initrd 负载时，将这些模块嵌入固件卷，把配置和内核文件放入负载 FAT 卷。
## 预检
@@ -140,16 +199,11 @@ patches = ["Resources/MuPatches/Gic-Spurious.patch"]
fd = "Build/<device>Pkg/{target}_CLANGPDB/FV/SILICIUM_UEFI.fd"
```
## 独立构建
## 外部固件构建
Mu-Silicium 也可以用自己的脚本构建：
```sh
cd Mu-Silicium
python3 build_uefi.py -d <device>
```
UniXNU 驱动使用板级 defines 和共享 edk2 补丁执行同样的构建。
通过 `./unixnu bootimg --fd <file>` 传入的固件需要与所选 `[firmware]` 配置一致的
DSC/FDF 模块、package 路径、板级 define 和 EDK II 补丁。检查[必需的集成](#required-integration)，
并在打包镜像时使用匹配的板级配置。
## 启动镜像集成
docs/zh/reference/troubleshooting.md
+1 -1
View File
@@ -40,7 +40,7 @@
| 固件停住 | Silicium 随机停顿 | 再次启动同一镜像 |
| 无显示 | GOP 驱动 | 使用 `console = "text"` 或串口 |
| 无菜单 | 配置路径 | 把 `unixnu.toml` 放到 `\EFI\UniXNU\unixnu.toml` |
| 无启动项 | 负载卷 | 检查 FAT 卷标、菜单项路径和卷驱动 |
| 无启动项 | 负载卷 | 检查 `boot.json` 的 `ramdisk_bytes` 是否大于零、FD 中的 UniXNURamDiskDxe/DiskIoDxe/FAT、FDT initrd 范围和 `EFI/UniXNU/unixnu.toml`，步骤见[负载发现](/zh/porting/uefi-firmware#payload-discovery)。 |
| 驱动失败 | 菜单中的第一条失败原因 | 修正驱动路径或依赖 |
| `no loader protocol installed` | 固件卷中的 DarwinBoot | 把 DarwinBoot 加入 FDS 或负载 |
| `loader revision 1 cannot accept kexts` | 加载器 revision | 使用 revision 2 或移除 kext |
examples/device/AGENTS.md
+5
View File
@@ -44,6 +44,11 @@ Run from UniXNU, replacing the device path and defconfig:
./unixnu bootimg --uefi ../uefi-example --dtb <firmware.dtb>
```
For a Mu-Silicium initrd payload, include `UniXNURamDiskDxe`, DiskIoDxe and
FAT support in the firmware DSC and FDF. Follow
[required firmware integration](https://unixnu.com/porting/uefi-firmware#required-integration)
before building the firmware and boot image.
Record commands, revisions, output paths, results, and unresolved inputs.
Report hardware boot, storage, display, input, and GPU results separately.
Update the device revision in UniXNU's devices.toml for publication and keep this README concise.
examples/device/README.md
+1 -1
View File
@@ -4,7 +4,7 @@ This template selects shared SM8550 and iPadOS 17.7.11 support. Complete the
hardware inputs before building.
1. Copy this directory to `UniXNU-<device>` and read `AGENTS.md`.
2. Set the board name, description, firmware paths, and complete component selection.
2. Set the board name, description, firmware paths, and complete component selection. Add the shared `UniXNURamDiskDxe` and filesystem dependencies to the firmware DSC and FDF using the [firmware integration guide](https://unixnu.com/porting/uefi-firmware#required-integration).
3. Pin a reviewed SoC commit in `feeds.toml`.
4. Fill the DTS model, compatible values, memory map, CPU selection, and peripherals.
5. List firmware sources and hashes in `proprietary-files.txt`.