docs: explain saved inputs, boot arguments and green bar diagnosis
This commit is contained in:
UniXNU Docs committed
1 parent
80cf8d4923
commit
dd284bc5a0
30 files changed
+224
-11
No files matched your search
@@ -102,3 +102,12 @@ For storage, also read the [UFS guide](https://unixnu.com/porting/ufs).
|
||||
Update each affected area's findings or evidence with its code change.
|
||||
The documentation site renders this same record. Follow its schema and
|
||||
completion levels for both maintainer and agent work.
|
||||
|
||||
## Local builds and boot diagnosis
|
||||
|
||||
Copy `unixnu.example.toml` to `unixnu.local.toml` in the main checkout and fill
|
||||
in device inputs using the [configuration reference](https://unixnu.com/reference/configuration#local-build-inputs).
|
||||
Read [boot arguments](https://unixnu.com/xnu/boot-arguments#apply-arguments)
|
||||
before changing the command line. Rebuild the payload and boot image after
|
||||
argument changes. Use the [green-bar diagnosis](https://unixnu.com/guide/debugging#green-bar)
|
||||
for stalls at loader handoff. Record the last confirmed stage and relevant logs.
|
||||
@@ -31,6 +31,8 @@ UniXNU provides shared build tools, ARM64 support, OS profiles and reusable comp
|
||||
|
||||
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).
|
||||
|
||||
Save paths and boot arguments in [`unixnu.local.toml`](https://unixnu.com/reference/configuration#local-build-inputs) to run `./unixnu kernel`, `./unixnu firmware`, `./unixnu payload`, and `./unixnu bootimg`. After changing boot arguments, rebuild the payload and boot image. See [boot arguments](https://unixnu.com/xnu/boot-arguments#apply-arguments) and [green-bar diagnosis](https://unixnu.com/guide/debugging#green-bar).
|
||||
|
||||
## 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.
|
||||
|
||||
@@ -31,6 +31,8 @@ UniXNU 为不同 SoC 和设备的移植提供共享构建工具、ARM64 支持
|
||||
|
||||
运行 `./unixnu bootimg` 前，先用 `./unixnu build firmware --uefi ../uefi-<device>` 构建设备固件，并将 UniXNU、UniXNUDxe、DarwinBoot 和共享负载驱动 `UniXNURamDiskDxe` 纳入固件。步骤见[必需的固件集成](https://unixnu.com/zh/porting/uefi-firmware#required-integration)。
|
||||
|
||||
在 [`unixnu.local.toml`](https://unixnu.com/zh/reference/configuration#local-build-inputs) 保存路径和启动参数，即可使用 `./unixnu kernel`、`./unixnu firmware`、`./unixnu payload` 和 `./unixnu bootimg`。修改启动参数后重新构建负载和启动镜像。检查步骤见[启动参数](https://unixnu.com/zh/xnu/boot-arguments#apply-arguments)和[绿条诊断](https://unixnu.com/zh/guide/debugging#green-bar)。
|
||||
|
||||
## 文档
|
||||
|
||||
文档位于 [unixnu.com](https://unixnu.com)，源码、导航、翻译、资源、配置和部署工作流由本仓库维护。文档覆盖启动链、构建驱动、设备移植、驱动开发、XNU 4 KiB 页补丁、启动参数和设备说明。
|
||||
|
||||
+1
-1
@@ -3,4 +3,4 @@ schema_version = 1
|
||||
[[device]]
|
||||
name = "sheng"
|
||||
repository = "UniXNU/UniXNU-sheng"
|
||||
revision = "93e25c6b8606902de13f12c4d160c860f52a7d98"
|
||||
revision = "516a780473a2ac59c8b438e132bb60204dda9e22"
|
||||
@@ -6,6 +6,20 @@
|
||||
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).
|
||||
:::
|
||||
|
||||
## Saved build inputs
|
||||
|
||||
Copy `unixnu.example.toml` to `unixnu.local.toml` and fill in the paths and platform seed using the [local build configuration](/reference/configuration#local-build-inputs). Then run:
|
||||
|
||||
```sh
|
||||
./unixnu defconfig <device>_defconfig
|
||||
./unixnu kernel
|
||||
./unixnu firmware
|
||||
./unixnu payload
|
||||
./unixnu bootimg
|
||||
```
|
||||
|
||||
After changing boot arguments, run `./unixnu payload` and `./unixnu bootimg`, then boot the new image. The [boot argument guide](/xnu/boot-arguments#apply-arguments) shows how to inspect the packed configuration.
|
||||
|
||||
## Quick start
|
||||
|
||||
```sh
|
||||
|
||||
@@ -4,6 +4,8 @@ The payload is a FAT volume that becomes the ramdisk of the Android boot image.
|
||||
|
||||
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).
|
||||
|
||||
Boot arguments are stored in the payload's `EFI/UniXNU/unixnu.toml`. After changing them, run `./unixnu payload` and `./unixnu bootimg`, then boot the new image. See [apply boot arguments](/xnu/boot-arguments#apply-arguments) for precedence and inspection commands.
|
||||
|
||||
## Volume layout
|
||||
|
||||
```
|
||||
|
||||
+2
-2
@@ -9,7 +9,7 @@ uke is the Xiaomi Pad 7 and POCO Pad X1 with the SM7675 SoC. The port below is a
|
||||
|
||||
## State
|
||||
|
||||
The stock ABL reaches stages 1 to 5: UEFI firmware, UniXNU menu, payload, DarwinBoot and the XNU entry. The green bar means the kernel entry code ran. On hardware, UFS root mounts and launchd starts. The display stays on the Apple logo because IOMFB finds no default framebuffer surface.
|
||||
The stock ABL reaches stages 1 to 5: UEFI firmware, UniXNU menu, payload, DarwinBoot and the XNU entry. The green bar marks DarwinBoot handoff before the kernel branch. On hardware, UFS root mounts and launchd starts. The display stays on the Apple logo because IOMFB finds no default framebuffer surface.
|
||||
|
||||
The stage 6 full kernel compiles and prelinks with `uke-full_defconfig`. The UFS block class binds to the pinned original candidate. On hardware, the root volume mounts and launchd runs; display and GPU remain the blockers.
|
||||
|
||||
@@ -18,7 +18,7 @@ The stage 6 full kernel compiles and prelinks with `uke-full_defconfig`. The UFS
|
||||
| UEFI firmware | works |
|
||||
| UniXNU menu | works |
|
||||
| Payload and DarwinBoot | works |
|
||||
| XNU entry | works, green bar |
|
||||
| DarwinBoot handoff | green bar |
|
||||
| Root device | mounted; launchd starts |
|
||||
| Display | Apple logo; no default framebuffer surface |
|
||||
| Watchdog | partial; watchdogd still hits SIGTRAP |
|
||||
|
||||
@@ -4,6 +4,8 @@ The boot image runs from RAM. The workflow starts the image and leaves the insta
|
||||
|
||||
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.
|
||||
|
||||
For repeated builds, save paths in [unixnu.local.toml](/reference/configuration#local-build-inputs). After changing boot arguments, rebuild the payload and boot image using the [argument workflow](/xnu/boot-arguments#apply-arguments). Follow the [green-bar diagnosis](/guide/debugging#green-bar) for a stall at loader handoff.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- An unlocked bootloader with `fastboot`.
|
||||
|
||||
+12
-1
@@ -200,13 +200,24 @@ python3 scripts/patch-xnu-entry-probe.py <kernel> --panic-screen --no-reset
|
||||
|
||||
The panic screen writes the formatted panic message and registers to the framebuffer and keeps the image visible. `--no-reset` stops the automatic reset, so the screen stays for a photograph.
|
||||
|
||||
### Green bar at handoff {#green-bar}
|
||||
|
||||
The top green bar is drawn by DarwinBoot's `DarwinEnter` after `ExitBootServices`, before cache maintenance, MMU shutdown, and the branch to XNU. A screen that stays there requires an entry probe or serial log to locate the next stage. The cause is undetermined from the green bar alone.
|
||||
|
||||
1. Record the last `DARWINBOOT:` lines, including kernel entry address, video geometry, command line, and CPU state. Confirm the selected kernel and ADT belong to the same device and OS profile.
|
||||
2. For a kernel supported by `scripts/patch-xnu-entry-probe.py`, set `[payload] panic_screen = true` in the device profile. Rebuild with `./unixnu payload`, then `./unixnu bootimg`, and boot the new image. Check `logs/payload-patch.log` for successful probe installation.
|
||||
3. Look for the blue and magenta bars below the green band. Blue marks the MMU-off kernel entry; magenta marks the point before enabling the MMU. Check the recorded framebuffer base and stride when probe output is absent.
|
||||
4. Use `entry_probe_reset_delay = 6` for a timed reset checkpoint after MMU enable. Record the observed bars, reset timing, serial output, and `payload.json` in the device's porting record.
|
||||
|
||||
See [applying boot arguments](/xnu/boot-arguments#apply-arguments) when a configuration change is missing from the booted image.
|
||||
|
||||
### Color bars
|
||||
|
||||
The early boot draws three bands of 1/16 screen height in the frame buffer. In the normal orientation they run from the top:
|
||||
|
||||
| Bar | Painted by | Meaning |
|
||||
| --- | --- | --- |
|
||||
| Green | DarwinBoot `DarwinEnter` | boot services exited and control reached the kernel entry |
|
||||
| Green | DarwinBoot `DarwinEnter` | boot services exited; loader handoff started before the kernel branch |
|
||||
| Blue | Entry probe stage 1 | the kernel entry code ran with the MMU off |
|
||||
| Magenta | Entry probe stage 2 | the kernel reached the point just before the MMU is enabled |
|
||||
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
Bring-up proceeds in stages. Each stage has a visible result and a log line. Isolate one stage at a time.
|
||||
|
||||
For repeated builds, save paths in [unixnu.local.toml](/reference/configuration#local-build-inputs). After changing boot arguments, rebuild the payload and boot image using the [argument workflow](/xnu/boot-arguments#apply-arguments). Follow the [green-bar diagnosis](/guide/debugging#green-bar) for a stall at loader handoff.
|
||||
|
||||
## Stage 1: UEFI
|
||||
|
||||
Goal: the firmware reaches a UEFI shell, a boot menu or the UniXNU application.
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
The UEFI firmware port comes from Mu-Silicium. It supplies the services UniXNU and DarwinBoot use.
|
||||
|
||||
For repeated builds, save paths in [unixnu.local.toml](/reference/configuration#local-build-inputs). After changing boot arguments, rebuild the payload and boot image using the [argument workflow](/xnu/boot-arguments#apply-arguments). Follow the [green-bar diagnosis](/guide/debugging#green-bar) for a stall at loader handoff.
|
||||
|
||||
## Required integration
|
||||
|
||||
Build firmware from the UniXNU checkout after selecting the device:
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
The UniXNU boot manager reads `\EFI\UniXNU\unixnu.toml` from the volume it was started from, then from every other volume. A kit directory contains `Kit.toml` with the same match and injection sections.
|
||||
|
||||
Boot arguments are stored in the payload's `EFI/UniXNU/unixnu.toml`. After changing them, run `./unixnu payload` and `./unixnu bootimg`, then boot the new image. See [apply boot arguments](/xnu/boot-arguments#apply-arguments) for precedence and inspection commands.
|
||||
|
||||
## unixnu.toml
|
||||
|
||||
```toml
|
||||
|
||||
@@ -4,7 +4,9 @@
|
||||
./unixnu <command> [options]
|
||||
```
|
||||
|
||||
Options follow the command. The driver reads a device repository from `-D`, `UNIXNU_DEVICE` or `out/state.json`.
|
||||
Options follow the command. The driver reads a device repository from `-D`, `UNIXNU_DEVICE`, the local build file, or `out/state.json`.
|
||||
|
||||
`kernel`, `package`, `firmware`, `payload`, `prelink`, and `userdata` are shortcuts for `build <step>`. Save paths and boot arguments in [unixnu.local.toml](/reference/configuration#local-build-inputs), then run `./unixnu kernel`, `./unixnu firmware`, `./unixnu payload`, and `./unixnu bootimg`. `--config FILE` selects another local build file. `status --json` includes its path in `build_config`.
|
||||
|
||||
## Commands
|
||||
|
||||
|
||||
@@ -4,6 +4,39 @@ Format 2 uses `schema_version = 2` at the top of `board.toml`. Files without
|
||||
this field use format 1. See the [device repository specification](/porting/device-repository)
|
||||
for profile ownership and examples.
|
||||
|
||||
## Local build inputs {#local-build-inputs}
|
||||
|
||||
Copy `unixnu.example.toml` to `unixnu.local.toml` in the UniXNU checkout and fill in your device paths. The file is ignored by Git. Use `--config /path/to/build.toml` to select another file.
|
||||
|
||||
```toml
|
||||
[build]
|
||||
device = "../UniXNU-<device>"
|
||||
uefi = "../uefi-<device>"
|
||||
dtb = "/path/to/firmware.dtb"
|
||||
kernelcache = "/path/to/kernelcache"
|
||||
trust_cache = "/path/to/trustcache.bundle"
|
||||
data_ramdisk = "/path/to/data-seed.dbr"
|
||||
unique_chip_id = "<hex>"
|
||||
jobs = 8
|
||||
target = "DEBUG"
|
||||
kernel_args = ["-v", "serial=3", "debug=0x14e"]
|
||||
```
|
||||
|
||||
Replace the placeholders with your port's inputs. Relative paths start at the configuration file's directory. Command-line flags take priority, followed by environment variables, then this file, then device defaults. `kernel_args` overrides board arguments by name; `--kernel-arg` overrides local arguments by name.
|
||||
|
||||
Supported path keys are `device`, `out`, `uefi`, `edk2`, `kernelcache`, `kernel`, `trust_cache`, `owner_trust_cache`, `data_ramdisk`, `gpu_addon`, `dtb`, `fd`, `ramdisk`, and `output`. Other keys are `ipsw` (path or URL), `unique_chip_id` (hex string), `jobs` (positive integer), `target` (`DEBUG` or `RELEASE`), and `kernel_args` (string array). `ramdisk = "none"` selects an empty boot-image ramdisk.
|
||||
|
||||
```sh
|
||||
./unixnu defconfig <device>_defconfig
|
||||
./unixnu kernel
|
||||
./unixnu firmware
|
||||
./unixnu payload
|
||||
./unixnu bootimg
|
||||
./unixnu status --json
|
||||
```
|
||||
|
||||
`status` reports the selected file as `build_config`. Build inputs use `unixnu.local.toml`; module source overrides use the device repository's `local.toml`.
|
||||
|
||||
## Profile fields
|
||||
|
||||
| Table | Key | Meaning |
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Early boot checks
|
||||
|
||||
- A top green bar marks DarwinBoot's handoff before the kernel branch. Follow the [green-bar diagnosis](/guide/debugging#green-bar).
|
||||
- To apply changed boot arguments, rebuild the payload and boot image, then boot that image. Follow [apply boot arguments](/xnu/boot-arguments#apply-arguments).
|
||||
- Save firmware and image paths in [unixnu.local.toml](/reference/configuration#local-build-inputs) for `./unixnu firmware`, `./unixnu kernel`, and `./unixnu bootimg`.
|
||||
|
||||
## Build
|
||||
|
||||
| Symptom | Check | Action |
|
||||
|
||||
@@ -1,6 +1,21 @@
|
||||
# Boot arguments
|
||||
|
||||
The kernel command line comes from `[payload] kernel_args` in the board file. An extra `--kernel-arg NAME=VALUE` replaces the board argument with the same name. The payload step writes the joined line into `unixnu.toml`, and DarwinBoot copies it into `boot_args`.
|
||||
## Apply boot arguments {#apply-arguments}
|
||||
|
||||
The effective command line combines `[payload] kernel_args` in the board profile, `[build] kernel_args` in `unixnu.local.toml`, and `--kernel-arg` overrides. Later sources replace arguments with the same name. The payload builder writes it to `EFI/UniXNU/unixnu.toml` as the XNU entry's `args`. UniXNU passes the selected entry to DarwinBoot, which copies the line into XNU's `boot_args.CommandLine` at boot. Kernel configuration switches are compiled by `./unixnu kernel`.
|
||||
|
||||
With [local build inputs](/reference/configuration#local-build-inputs) saved:
|
||||
|
||||
```sh
|
||||
./unixnu payload --kernel-arg serial=3 --kernel-arg debug=0x14e
|
||||
./unixnu bootimg
|
||||
jq -r .kernel_args out/<device>/<os_profile>/<config>/payload/payload.json
|
||||
mtype -i out/<device>/<os_profile>/<config>/payload/payload.img ::/EFI/UniXNU/unixnu.toml
|
||||
```
|
||||
|
||||
Boot the newly generated `boot/boot.img`. `bootimg` copies the current payload into that file. Editing a payload after packaging requires running `bootimg` again. A custom `--ramdisk FILE` selects that file's configuration. Check the XNU entry you select and any appended `confirm_args`. When several volumes contain `unixnu.toml`, check the configuration on the boot manager's own volume first.
|
||||
|
||||
The payload command prints `kernel args:` and DarwinBoot prints `DARWINBOOT: command line:` before handoff. If they differ, inspect the selected volume and entry. If they match and behavior is unchanged, check that the kernel or selected driver implements the argument. A green handoff bar is covered in [early boot diagnosis](/guide/debugging#green-bar).
|
||||
|
||||
## Format
|
||||
|
||||
|
||||
@@ -6,6 +6,20 @@
|
||||
打包启动镜像前，运行 `./unixnu build firmware --uefi ../uefi-<device>` 构建设备固件。DSC 和 FDF 必须包含 UniXNU、UniXNUDxe、DarwinBoot 和负载卷驱动。Mu-Silicium 的 FDT initrd 路径使用共享的 `UniXNURamDiskDxe`，并需要 DiskIoDxe 和 FAT 支持。步骤见[固件集成](/zh/porting/uefi-firmware#required-integration)。
|
||||
:::
|
||||
|
||||
## 保存构建参数
|
||||
|
||||
将 `unixnu.example.toml` 复制为 `unixnu.local.toml`，按[本地构建配置](/zh/reference/configuration#local-build-inputs)填写路径和平台种子，然后运行：
|
||||
|
||||
```sh
|
||||
./unixnu defconfig <device>_defconfig
|
||||
./unixnu kernel
|
||||
./unixnu firmware
|
||||
./unixnu payload
|
||||
./unixnu bootimg
|
||||
```
|
||||
|
||||
修改启动参数后，运行 `./unixnu payload` 和 `./unixnu bootimg`，再启动新镜像。[启动参数指南](/zh/xnu/boot-arguments#apply-arguments)说明如何检查已打包的配置。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```sh
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
使用 Mu-Silicium initrd 负载时，固件需嵌入 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 驱动，在 UniXNU 读取配置前发布负载卷。详见[负载发现](/zh/porting/uefi-firmware#payload-discovery)。
|
||||
|
||||
启动参数保存在负载的 `EFI/UniXNU/unixnu.toml` 中。修改后运行 `./unixnu payload` 和 `./unixnu bootimg`，再启动新镜像。参数优先级和检查命令见[应用启动参数](/zh/xnu/boot-arguments#apply-arguments)。
|
||||
|
||||
## 卷布局
|
||||
|
||||
```
|
||||
|
||||
@@ -9,7 +9,7 @@ uke 是搭载 SM7675 的小米平板 7 和 POCO Pad X1。下面的移植是独
|
||||
|
||||
## 状态
|
||||
|
||||
原厂 ABL 已到阶段 1 到 5：UEFI 固件、UniXNU 菜单、负载、DarwinBoot 和 XNU 入口。绿色条表示内核入口代码已执行。真机上 UFS 根已挂载，launchd 启动。屏幕停在 Apple 标志，因为 IOMFB 找不到默认 framebuffer surface。
|
||||
原厂 ABL 已到阶段 1 到 5：UEFI 固件、UniXNU 菜单、负载、DarwinBoot 和 XNU 入口。绿色条标记 DarwinBoot 跳转内核前的交接阶段。真机上 UFS 根已挂载，launchd 启动。屏幕停在 Apple 标志，因为 IOMFB 找不到默认 framebuffer surface。
|
||||
|
||||
阶段 6 的完整内核用 `uke-full_defconfig` 编译并预链接。UFS 块类绑定到固定的原始候选。真机上根卷已挂载，launchd 已运行；显示和 GPU 仍是阻塞点。
|
||||
|
||||
@@ -18,7 +18,7 @@ uke 是搭载 SM7675 的小米平板 7 和 POCO Pad X1。下面的移植是独
|
||||
| UEFI 固件 | 工作 |
|
||||
| UniXNU 菜单 | 工作 |
|
||||
| 负载和 DarwinBoot | 工作 |
|
||||
| XNU 入口 | 工作，绿色条 |
|
||||
| DarwinBoot 交接 | 绿色条 |
|
||||
| 根设备 | 已挂载，launchd 启动 |
|
||||
| 显示 | Apple 标志，无默认 framebuffer surface |
|
||||
| watchdog | 部分生效，watchdogd 仍触发 SIGTRAP |
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
使用 `./unixnu build firmware --uefi ../uefi-<device>` 构建固件。Mu-Silicium initrd 负载需要在固件中加入 `UniXNURamDiskDxe`、DiskIoDxe 和 FAT 支持，并在 `./unixnu bootimg` 前构建负载。[固件集成指南](/zh/porting/uefi-firmware#required-integration)列出了必需的 DSC/FDF 条目和菜单检查步骤。
|
||||
|
||||
重复构建时，在 [unixnu.local.toml](/zh/reference/configuration#local-build-inputs) 保存路径。修改启动参数后，按[参数应用流程](/zh/xnu/boot-arguments#apply-arguments)重新构建负载和启动镜像。画面停在加载器交接阶段时，按[绿条诊断](/zh/guide/debugging#green-bar)检查。
|
||||
|
||||
## 前提
|
||||
|
||||
- bootloader 已解锁并支持 `fastboot`。
|
||||
|
||||
@@ -200,13 +200,24 @@ python3 scripts/patch-xnu-entry-probe.py <kernel> --panic-screen --no-reset
|
||||
|
||||
panic 屏幕把格式化后的 panic 消息和寄存器写到 framebuffer，并保持显示。`--no-reset` 停止自动复位，屏幕保留到拍照完成。
|
||||
|
||||
### 交接时的绿色条 {#green-bar}
|
||||
|
||||
顶部绿色条由 DarwinBoot 的 `DarwinEnter` 在 `ExitBootServices` 之后绘制，随后才执行缓存维护、关闭 MMU 和跳转 XNU。画面停在这里时，需要入口探针或串口日志定位后续阶段。仅凭绿色条，原因未查明。
|
||||
|
||||
1. 记录最后的 `DARWINBOOT:` 日志，包括内核入口地址、显示几何信息、命令行和 CPU 状态。确认所选内核和 ADT 对应同一设备及 OS 配置。
|
||||
2. 对 `scripts/patch-xnu-entry-probe.py` 支持的内核，在设备配置中设置 `[payload] panic_screen = true`，运行 `./unixnu payload` 和 `./unixnu bootimg`，再启动新镜像。检查 `logs/payload-patch.log` 中的探针安装结果。
|
||||
3. 查看绿色条下方的蓝色和品红色条。蓝色表示进入 MMU 关闭状态下的内核入口，品红色表示到达开启 MMU 前的位置。缺少探针画面时，检查记录的 framebuffer 基址和行跨度。
|
||||
4. 使用 `entry_probe_reset_delay = 6` 设置开启 MMU 后的定时复位检查点。在设备移植记录中保存色条、复位时间、串口输出和 `payload.json`。
|
||||
|
||||
配置修改未体现在启动镜像中时，按[应用启动参数](/zh/xnu/boot-arguments#apply-arguments)检查。
|
||||
|
||||
### 颜色条
|
||||
|
||||
早期启动会在 framebuffer 上画三条 1/16 屏幕高度的色条。正常方向下从上到下：
|
||||
|
||||
| 色条 | 绘制者 | 含义 |
|
||||
| --- | --- | --- |
|
||||
| 绿色 | DarwinBoot `DarwinEnter` | 已退出 boot services，控制权到达内核入口 |
|
||||
| 绿色 | DarwinBoot `DarwinEnter` | 已退出 boot services，进入跳转内核前的加载器交接阶段 |
|
||||
| 蓝色 | 入口探针阶段 1 | 内核入口代码已执行，MMU 仍关闭 |
|
||||
| 品红 | 入口探针阶段 2 | 内核到达打开 MMU 之前的位置 |
|
||||
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
bring-up 按阶段推进。每个阶段都有可见结果和日志行，一次隔离一个问题。
|
||||
|
||||
重复构建时，在 [unixnu.local.toml](/zh/reference/configuration#local-build-inputs) 保存路径。修改启动参数后，按[参数应用流程](/zh/xnu/boot-arguments#apply-arguments)重新构建负载和启动镜像。画面停在加载器交接阶段时，按[绿条诊断](/zh/guide/debugging#green-bar)检查。
|
||||
|
||||
## 阶段 1：UEFI
|
||||
|
||||
目标：固件进入 UEFI shell、启动菜单或 UniXNU。
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
UEFI 固件移植来自 Mu-Silicium，提供 UniXNU 和 DarwinBoot 使用的服务。
|
||||
|
||||
重复构建时，在 [unixnu.local.toml](/zh/reference/configuration#local-build-inputs) 保存路径。修改启动参数后，按[参数应用流程](/zh/xnu/boot-arguments#apply-arguments)重新构建负载和启动镜像。画面停在加载器交接阶段时，按[绿条诊断](/zh/guide/debugging#green-bar)检查。
|
||||
|
||||
## 必需的集成 {#required-integration}
|
||||
|
||||
选择设备后，从 UniXNU 仓库构建固件：
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
UniXNU 启动管理器先从启动所在卷读取 `\EFI\UniXNU\unixnu.toml`，再扫描其他卷。kit 目录中的 `Kit.toml` 使用相同的 match 和注入段。
|
||||
|
||||
启动参数保存在负载的 `EFI/UniXNU/unixnu.toml` 中。修改后运行 `./unixnu payload` 和 `./unixnu bootimg`，再启动新镜像。参数优先级和检查命令见[应用启动参数](/zh/xnu/boot-arguments#apply-arguments)。
|
||||
|
||||
## unixnu.toml
|
||||
|
||||
```toml
|
||||
|
||||
@@ -4,7 +4,9 @@
|
||||
./unixnu <command> [options]
|
||||
```
|
||||
|
||||
选项写在命令之后。驱动从 `-D`、`UNIXNU_DEVICE` 或 `out/state.json` 读取设备仓库。
|
||||
选项写在命令之后。驱动从 `-D`、`UNIXNU_DEVICE`、本地构建文件或 `out/state.json` 读取设备仓库。
|
||||
|
||||
`kernel`、`package`、`firmware`、`payload`、`prelink` 和 `userdata` 是 `build <step>` 的快捷命令。在 [unixnu.local.toml](/zh/reference/configuration#local-build-inputs) 保存路径和启动参数后，可运行 `./unixnu kernel`、`./unixnu firmware`、`./unixnu payload` 和 `./unixnu bootimg`。`--config FILE` 选择其他本地构建文件，`status --json` 的 `build_config` 字段显示其路径。
|
||||
|
||||
## 命令
|
||||
|
||||
|
||||
@@ -3,6 +3,39 @@
|
||||
格式 2 在 `board.toml` 顶层设置 `schema_version = 2`。省略该字段时使用格式 1。
|
||||
配置归属和示例见[设备仓库规范](/zh/porting/device-repository)。
|
||||
|
||||
## 本地构建参数 {#local-build-inputs}
|
||||
|
||||
在 UniXNU 仓库中将 `unixnu.example.toml` 复制为 `unixnu.local.toml`，填写设备路径。Git 忽略此文件。使用 `--config /path/to/build.toml` 选择其他文件。
|
||||
|
||||
```toml
|
||||
[build]
|
||||
device = "../UniXNU-<device>"
|
||||
uefi = "../uefi-<device>"
|
||||
dtb = "/path/to/firmware.dtb"
|
||||
kernelcache = "/path/to/kernelcache"
|
||||
trust_cache = "/path/to/trustcache.bundle"
|
||||
data_ramdisk = "/path/to/data-seed.dbr"
|
||||
unique_chip_id = "<hex>"
|
||||
jobs = 8
|
||||
target = "DEBUG"
|
||||
kernel_args = ["-v", "serial=3", "debug=0x14e"]
|
||||
```
|
||||
|
||||
将占位符替换为设备所需输入。相对路径从配置文件所在目录解析。优先级为命令行、环境变量、本地文件、设备默认值。`kernel_args` 按名称覆盖板级参数，`--kernel-arg` 按名称覆盖本地参数。
|
||||
|
||||
路径字段包括 `device`、`out`、`uefi`、`edk2`、`kernelcache`、`kernel`、`trust_cache`、`owner_trust_cache`、`data_ramdisk`、`gpu_addon`、`dtb`、`fd`、`ramdisk` 和 `output`。其他字段为 `ipsw`（路径或 URL）、`unique_chip_id`（十六进制字符串）、`jobs`（正整数）、`target`（`DEBUG` 或 `RELEASE`）、`kernel_args`（字符串数组）。`ramdisk = "none"` 选择空启动镜像 ramdisk。
|
||||
|
||||
```sh
|
||||
./unixnu defconfig <device>_defconfig
|
||||
./unixnu kernel
|
||||
./unixnu firmware
|
||||
./unixnu payload
|
||||
./unixnu bootimg
|
||||
./unixnu status --json
|
||||
```
|
||||
|
||||
`status` 的 `build_config` 字段显示选中的文件。`unixnu.local.toml` 保存构建输入，设备仓库的 `local.toml` 保存组件源码覆盖路径。
|
||||
|
||||
## 配置字段
|
||||
|
||||
| 表 | 键 | 含义 |
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# 故障排查
|
||||
|
||||
## 早期启动检查
|
||||
|
||||
- 顶部绿色条标记 DarwinBoot 跳转内核前的交接阶段，按[绿条诊断](/zh/guide/debugging#green-bar)检查。
|
||||
- 修改启动参数后重新构建负载及启动镜像，再启动该镜像，步骤见[应用启动参数](/zh/xnu/boot-arguments#apply-arguments)。
|
||||
- 在 [unixnu.local.toml](/zh/reference/configuration#local-build-inputs) 保存固件和镜像路径，即可使用 `./unixnu firmware`、`./unixnu kernel` 和 `./unixnu bootimg`。
|
||||
|
||||
## 构建
|
||||
|
||||
| 现象 | 检查 | 处理 |
|
||||
|
||||
@@ -1,6 +1,21 @@
|
||||
# 启动参数
|
||||
|
||||
内核命令行来自板级文件的 `[payload] kernel_args`。额外的 `--kernel-arg NAME=VALUE` 会替换板级同名参数。负载步骤把合并后的行写入 `unixnu.toml`，DarwinBoot 复制到 `boot_args`。
|
||||
## 应用启动参数 {#apply-arguments}
|
||||
|
||||
有效命令行依次合并板级配置的 `[payload] kernel_args`、`unixnu.local.toml` 的 `[build] kernel_args` 和 `--kernel-arg`。后面的来源覆盖同名参数。负载构建器将结果写入 `EFI/UniXNU/unixnu.toml` 中 XNU 启动项的 `args`。UniXNU 将选中的启动项交给 DarwinBoot，DarwinBoot 在启动时将命令行复制到 XNU 的 `boot_args.CommandLine`。内核配置开关由 `./unixnu kernel` 编译。
|
||||
|
||||
保存[本地构建参数](/zh/reference/configuration#local-build-inputs)后运行：
|
||||
|
||||
```sh
|
||||
./unixnu payload --kernel-arg serial=3 --kernel-arg debug=0x14e
|
||||
./unixnu bootimg
|
||||
jq -r .kernel_args out/<device>/<os_profile>/<config>/payload/payload.json
|
||||
mtype -i out/<device>/<os_profile>/<config>/payload/payload.img ::/EFI/UniXNU/unixnu.toml
|
||||
```
|
||||
|
||||
启动新生成的 `boot/boot.img`。`bootimg` 将当前负载复制进该文件，打包后修改负载需要再次运行 `bootimg`。指定 `--ramdisk FILE` 时使用该文件中的配置。检查选中的 XNU 启动项及追加的 `confirm_args`。多个卷包含 `unixnu.toml` 时，先检查启动管理器所在卷的配置。
|
||||
|
||||
负载命令输出 `kernel args:`，DarwinBoot 在交接前输出 `DARWINBOOT: command line:`。两者不同时检查所选卷和启动项；两者相同但行为未变时，检查内核或所选驱动是否实现该参数。绿色交接条的检查步骤见[早期启动诊断](/zh/guide/debugging#green-bar)。
|
||||
|
||||
## 格式
|
||||
|
||||
|
||||
@@ -61,3 +61,12 @@ For storage, also read the [UFS guide](https://unixnu.com/porting/ufs).
|
||||
Update each affected area's findings or evidence with its code change.
|
||||
The documentation site renders this same record. Follow its schema and
|
||||
completion levels for both maintainer and agent work.
|
||||
|
||||
## Local builds and boot diagnosis
|
||||
|
||||
Copy `unixnu.example.toml` to `unixnu.local.toml` in the main checkout and fill
|
||||
in device inputs using the [configuration reference](https://unixnu.com/reference/configuration#local-build-inputs).
|
||||
Read [boot arguments](https://unixnu.com/xnu/boot-arguments#apply-arguments)
|
||||
before changing the command line. Rebuild the payload and boot image after
|
||||
argument changes. Use the [green-bar diagnosis](https://unixnu.com/guide/debugging#green-bar)
|
||||
for stalls at loader handoff. Record the last confirmed stage and relevant logs.
|
||||
@@ -33,3 +33,12 @@ python3 scripts/porting-record.py check --device ../UniXNU-example
|
||||
```
|
||||
|
||||
Run this command from UniXNU.
|
||||
|
||||
## Local builds and boot diagnosis
|
||||
|
||||
Copy `unixnu.example.toml` to `unixnu.local.toml` in the main checkout and fill
|
||||
in device inputs using the [configuration reference](https://unixnu.com/reference/configuration#local-build-inputs).
|
||||
Read [boot arguments](https://unixnu.com/xnu/boot-arguments#apply-arguments)
|
||||
before changing the command line. Rebuild the payload and boot image after
|
||||
argument changes. Use the [green-bar diagnosis](https://unixnu.com/guide/debugging#green-bar)
|
||||
for stalls at loader handoff. Record the last confirmed stage and relevant logs.
|
||||
Reference in new issue
Block a user