Files
UniXNU/docs/zh/guide/debugging.md

399 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 调试与日志
为每个启动检查点收集固件日志、内核输出、诊断截图和构建报告。
## 操作步骤 {#procedure}
1. 记录失败命令或最后完成的[启动检查点](/zh/porting/bring-up),以及设备、固件和镜像版本。
2. 选择可用的[日志来源](#日志来源)。使用 USB 终端前确认设备实现了其[通信协议](#设备兼容性);也可使用目标支持的 UART、屏幕诊断或 QEMU 日志。
3. 绿色交接条按[入口探针步骤](#green-bar)检查;panic 抓取 [panic 屏幕](#panic-屏幕),用户进程故障收集[用户态证据](#用户态故障证据)。
4. 每次应用一项诊断修改,重新构建受影响的产物。启动参数修改需要 `./unixnu payload` 和 `./unixnu bootimg`。重复失败操作,记录最后确认的检查点。
5. 保存[证据包](#证据包),更新对应[适配记录](/zh/porting/records)。结果应明确失败阶段、输入版本和具体错误。
## 按阶段抓取日志
按[日志抓取与自动测试步骤](/zh/porting/log-capture)操作:固件菜单中使用二维码导出,
内核入口使用 UART 或屏幕诊断,存储完成后加入持久化日志和自动循环。
## USB 调试终端
来自 giulia 移植的电脑端工具已整合为 `scripts/debug_terminal.py` 和 Windows CMD 启动器 `scripts/debug-terminal.cmd`,支持 CDC 日志采集、有界诊断命令、按主题导出日志及 GSC1 帧缓冲解码。需要 Python 3.10 或更新版本。交互编辑与 PTY 键盘输入需要 Windows CMD;脚本采集可在 Windows、Linux 和 macOS 上运行。
```sh
python -m pip install -r scripts/terminal-requirements.txt
python scripts/debug_terminal.py --list
python scripts/debug_terminal.py --port COM21 --command collect --seconds 20
# Linux 示例,请使用实际端口:
python3 scripts/debug_terminal.py --port /dev/ttyACM0 --command status --seconds 5
```
Windows 交互模式运行 `scripts\debug-terminal.cmd --port COM21`,输入 `:help` 查看命令。可以显式指定端口,或同时提供完整 USB 身份参数:giulia 开发设备使用 `--vid 0x1209 --pid 0x0001 --usb-serial ACE5DBG001`。未提供完整身份或匹配到多个设备时不会自动连接。工具使用 115200 波特率并置位 DTR;连接前关闭其他占用端口的程序。
| 命令 | 结果 |
| --- | --- |
| `all` / `collect` | 排队发送有界查询;`collect` 额外请求 replay/sample,至少 15 秒后保存 |
| `logs wifi` / `logs gpu` / `logs panic` | 筛选保留的会话日志,记录对应会话的硬件观测 |
| `save` | 导出主题文本与会话元数据 |
| `watch status 2` / `unwatch` | 轮询只读状态查询 / 停止轮询 |
| `screen.start` / `screen.stop` | 打开本机浏览器投屏 / 停止帧传输 |
| `screen.snapshot` | 设备提供帧缓冲后保存真实 PNG |
| `shell` | 进入设备 PTY;Ctrl+] 返回诊断模式 |
| `reboot.fastboot` | 请求设备同步磁盘后重启 |
会话保存到 `out/terminal/<时间戳>/`,包含轮转的 `device-*.log`、主题文本、`session.json` 和独立屏幕图片。主题导出保留最近 20,000 条完整日志行,屏幕数据包与文本日志分离。浏览器保留最后一张真实画面,启用可选鼠标/键盘控制前检查设备输入能力。
```sh
python scripts/debug_terminal.py --port COM21 --command screen.start --seconds 60 --max-size 695 --max-fps 1
python scripts/debug_terminal.py --port COM21 --command reboot.fastboot --fastboot-serial DEVICE_SERIAL --seconds 20
```
Fastboot 验证需要 PATH 中有 `fastboot`,收到内核重启确认且 CDC 断开后,精确匹配指定的设备序列号。
### 设备兼容性
这些工具运行在电脑端,不会升级设备内核。初始后端实现 giulia 协议 2 命令集、`GIULIA` shell/输入/重启标记和 GSC1 屏幕格式(最多 1264 × 2780 RGB565 像素)。其他板型需要实现兼容协议或增加对应后端,修改 USB ID 本身不提供协议兼容性。板级驱动、地址、启动参数和守护进程安装保留在设备仓库,参见 [giulia 终端实现与配置](https://github.com/tycykp/UniXNU-OnePlus-Ace5/blob/main/docs/USB_TERMINAL.md)。
基础内核可能仅支持 `help`、`ping`、`status`、`replay`;扩展查询需要匹配的终端实现。投屏需要帧缓冲生产者,远程输入需要设备 HID 提供者。PTY shell 需要开发启动参数和已安装的守护进程/shell,尚未实机验证。MMIO 命令保留 giulia 后端的低地址外设窗口及显式开发开关;时钟、映射和支持操作以设备说明为准。GPU/HFI 命令需要对应开发内核。设备会报告不支持的命令,安装电脑工具不会启用这些能力。
导入代码来自 `UniXNU-OnePlus-Ace5` 的 `694b39e`,并包含本地终端/投屏改动。电脑端验证:
```sh
python -m unittest discover -s tests/terminal -v
```
可选 C 发送端互操作测试需要设置 `GIULIA_SCREEN_FIXTURE`,指向设备仓库屏幕测试脚本生成的样本。默认测试使用合成数据包和模拟串口。硬件状态通过设备检查记录。
## 日志来源
| 来源 | 通道 | 用途 |
| --- | --- | --- |
| [固件日志导出](/zh/porting/log-capture#qr-logs) | OneSend 二维码 | 当前 UEFI Advanced Logger 缓冲 |
| [持久化日志](/zh/porting/log-capture#persistent-logs) | 预留存储区域、Linux 读取器或 recovery 读取器 | 内核消息与诊断快照 |
| UEFI 串口 | UART | 固件、UniXNU、DarwinBoot |
| 内核串口 | 由 `serial=` 选择的 UART | XNU 控制台和 panic 输出 |
| 诊断页 | framebuffer | 控制台停止后的实时状态 |
| 脉冲条 | framebuffer 底部 | 诊断页占用面板时的心跳 |
| panic 屏幕 | framebuffer | panic 文本和寄存器 |
| QEMU 日志 | 文件 | UniXNU 和加载器测试 |
| 构建报告 | JSON | 输入哈希和阶段结果 |
## 串口
把参数加入负载:
```toml
[payload]
kernel_args = ["-v", "serial=3", "debug=0x14e"]
```
UniXNU 启动管理器写到第一个 `EFI_SERIAL_IO_PROTOCOL`,行以 `UNIXNU:` 开头。DarwinBoot 的行以 `DARWINBOOT:` 开头。
抓取串口:
```sh
tio -b 115200 -d 8 -p none -s 1 /dev/tty.usbserial-0001 -L out/serial.log
```
其他工具:
```sh
picocom -b 115200 /dev/tty.usbserial-0001
screen -L /dev/tty.usbserial-0001 115200
minicom -D /dev/tty.usbserial-0001 -b 115200
```
设备页面记录 UART 引脚和波特率。支持 USB device 模式的板子可以暴露 CDC ACM 串口。
常用的早期输出:
```
UNIXNU: UniXNU 0.1.0 starting as firmware boot option
UNIXNU: config: loaded \EFI\UniXNU\unixnu.toml
UNIXNU: driver ...: started
UNIXNU: menu: shown 2 entries, default 0
DARWINBOOT: loader v2 installed EL1
DARWINBOOT: ARM64 va=... pa=... args=... entry=... owned=...
DARWINBOOT: inputs validated; exiting boot services
```
## 屏幕诊断页
诊断页是绘制到 XNU framebuffer 映射上的全屏文本覆盖层。启用方式:
```
boot-progress=1
```
级别 1 启动监视器。30 秒没有阶段或存储活动,或达到 120 秒观察上限时,页面冻结并保留屏幕,便于拍照。
```
boot-progress=2
```
级别 2 连续运行。超过时限只报告,系统继续运行。
页面使用 48 行、120 列。面板至少 2160x1400 时缩放为 3。
| 行区域 | 内容 |
| --- | --- |
| 标题 | 构建标签、live 或 stop 状态、原因 |
| 1 | 时间、空闲、IRQ 计数、监视器计数、root 状态、进程数、空闲页 |
| 2 | 存储请求、已验证块、失败、完整性计数 |
| 3 到 30 | 阶段历史、进程状态、存储细节、最后 PC 和寄存器 |
| 31 到 47 | 缓存存储输出、UFS 计时、内存、进程采样、UI trace、触控行 |
| 47 | 独立脉冲条 |
给镜像加标签,拍照后可以确认构建:
```
build-tag=ks-001
```
标题栏会以 `[ks-001]` 开头。
用户态接管显示并停止扫描输出后,可以收回面板:
```
boot-diag-resume=10
```
10 秒没有 scanout 后页面重绘。新的有效 scanout 会再次让出面板。
页面字段:
| 字段 | 含义 |
| --- | --- |
| `time` | 监视器启动后的秒数 |
| `idle` | 距上次阶段或 I/O 进展的秒数 |
| `IRQ` | 监视器统计的中断入口数 |
| `monitor` | 监视器线程迭代数 |
| `lost` | 丢弃的记录更新数 |
| `root` | owner root 接受状态 |
| `procs` | 进程数 |
| `free` | 空闲 4 KiB 页 |
| `requests` | 存储请求 |
| `verified4K` | 已验证 4 KiB 块 |
| `failures` | 存储失败 |
| `integrity` | 存储完整性失败 |
| `last PC` | 最后中断入口 PC |
| `TCR`、`TTBR`、`SCTLR` | 翻译控制和页表基址寄存器 |
## 脉冲条
脉冲条位于面板底部,高 32 像素,2 倍缩放,绿色文字,由独立高优先级监视线程每秒更新。
```
P<turn> I<irq> M<monitor>/<seconds> B<bind>:<result> d<depth> @<base> lock<busy>/<render> PC<pc>
```
| 字段 | 含义 |
| --- | --- |
| `P` | 脉冲轮次 |
| `I` | 中断入口数 |
| `M` | 监视器计数和距上次推进的秒数 |
| `B` | framebuffer 绑定次数、结果和深度 |
| `@` | framebuffer 基址 |
| `lock` | 记录器和渲染器忙碌标志 |
| `PC` | 最后中断入口 PC |
诊断页占用面板时脉冲条持续存在。OS 接管显示后它关闭。`boot-diag-resume` 会重新打开诊断页和脉冲条。
## panic 屏幕
负载可以把 panic 屏幕打进内核副本:
```toml
[payload]
panic_screen = true
```
负载步骤运行:
```sh
python3 scripts/patch-xnu-entry-probe.py <kernel> --panic-screen --no-reset
```
UniXNU 主仓库提供入口探针和 `xnu-panic-screen.c`,构建工具将它们复制到每个设备的构建树。Panic 渲染使用 Mu-Silicium 的 `Silicon/Silicium/SiliciumPkg/Library/FrameBufferSerialPortLib/Font.h`。在 `unixnu.local.toml` 的 `[build]` 中设置 `uefi`,或运行 `./unixnu payload --uefi /path/to/Mu-Silicium`。直接运行脚本时设置 `UNIXNU_UEFI`。
panic 屏幕把格式化后的 panic 消息和寄存器写到 framebuffer,并保持显示。`--no-reset` 停止自动复位,屏幕保留到拍照完成。
### 交接时的绿色条 {#green-bar}
顶部绿色条由 DarwinBoot 的 `DarwinEnter` 在 `ExitBootServices` 之后绘制,随后才执行缓存维护、关闭 MMU 和跳转 XNU。持久化内核日志记录后续检查点,包括 `Darwin Kernel Version` 和 `SourceStorage: Data disk started`。framebuffer 保留加载器画面时,按最新内核检查点定位。
内核入口故障按以下步骤检查:
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`。
sheng 使用 `storage-probe=1 log=1` 记录 BSD 初始化、后续 bootstrap 调用和 PID 1 执行阶段。UFS 日志区的空闲块分别保留 bootstrap 和 PID 1 的环形记录,包含序号、PID、线程、构建标签、阶段、计数器、虚拟定时器状态、DAIF、待处理中断和调用地址。`read-sheng-log.py --expected-tag TAG` 将匹配记录导出为 `startup-checkpoints.txt`,并将最新记录保存为 `startup-checkpoint.txt`。自动循环传入预期标签,并记录日志文件头和检查点是否属于本次启动。保持已验证的固件 watchdog 和自动返回 fastboot 功能启用。
持久化启动日志覆盖关闭屏幕进度层时的 PID 1 阶段、挂载与启动策略返回码,并在进入调试器前保存第一条格式化 panic 消息。读取器通过状态为 `5` 的日志文件头导出 panic 消息缓冲区。
配置修改未体现在启动镜像中时,按[应用启动参数](/zh/xnu/boot-arguments#apply-arguments)检查。
### 颜色条
早期启动会在 framebuffer 上画三条 1/16 屏幕高度的色条。正常方向下从上到下:
| 色条 | 绘制者 | 含义 |
| --- | --- | --- |
| 绿色 | DarwinBoot `DarwinEnter` | 已退出 boot services,进入跳转内核前的加载器交接阶段 |
| 蓝色 | 入口探针阶段 1 | 内核入口代码已执行,MMU 仍关闭 |
| 品红 | 入口探针阶段 2 | 内核到达打开 MMU 之前的位置 |
入口探针把每条画在绿色条下方。阶段 3 没有色条:它在 MMU 打开后等待 `--reset-delay` 秒再复位。过了这段时间设备重启,说明 MMU 已打开。
### 入口探针复位
内核还不能绘图之前,重启是唯一的信号。`entry_probe_reset_delay` 保留入口探针的复位:打过补丁的内核在 MMU 打开后等待这么多秒,然后用 PSCI SYSTEM_RESET 复位。过了这段时间设备自己重启,说明 CPU 已经通过 MMU 打开这一步。
```toml
[payload]
entry_probe_reset_delay = 6
entry_probe_reset_after = "_arm_vm_init" # 可选:改为在这个调用之后复位
entry_probe_reset_in = "_arm_init" # 发出调用的函数(默认值)
entry_probe_reset_occurrence = 1 # 第几次调用(默认 1)
entry_probe_reset_before = false # 在调用点复位,不执行调用,也不等待
```
设置 `entry_probe_reset_after` 后,复位移到该调用之后,一次运行只回答一个问题:内核有没有走过这个调用。这些键对应共享 `patch-xnu-entry-probe.py` 的 `--reset-delay`、`--reset-after`、`--in`、`--occurrence` 和 `--reset-before`,可以和 `panic_screen` 同时使用。不设置 `entry_probe_reset_delay` 时,负载仍传 `--no-reset`。
第一条 panic 消息也会复制到 `boot_progress_panic_text`。secondary core 上的 panic 只停住该 core,实时横幅在屏幕重绘后仍保留文本。
设备树 panic 区域需要:
```
CONFIG_XNU_DT_PANIC_REGION=y
```
内核读取 `/chosen` 的 `embedded-panic-log-size` 和区域的 `reg` 属性,映射前先校验。
## 用户态故障证据
故障探针在异常投递前记录 EL0 breakpoint 和 abort 状态:
| 字段 | 含义 |
| --- | --- |
| `pid`、`name` | 进程 |
| `PC`、`LR`、`SP`、`FP` | 故障时寄存器 |
| `ESR`、`FAR` | 异常综合征和故障地址 |
| `slide` | shared region slide |
| `x0` 到 `x28` | 通用寄存器 |
| frames | 最多 12 个返回地址 |
捕获在 trap 路径中完成,不分配内存。匹配的进程退出时,记录随信号打印。未捕获异常的原因会从退出进程的可写 malloc 区域中搜索并打印到崩溃行。
## UI 栈追踪
UI trace 采样指定进程,打印 PC、LR、FP 和栈切片:
```
boot-ui-focus=launchd
boot-ui-focus2=SpringBoard
boot-ui-focus3=backboardd
boot-ui-focus4=Setup
boot-ui-chrono=1
```
地址使用 64 进制字母表编码,以适配行宽。把抄录的行交给解码器:
```sh
python3 scripts/decode-boot-ui-trace.py trace.txt
```
解码器为每个线程组输出一个 JSON 对象,包含 `pc`、`lr`、帧和错误码。
trace 每 8 秒轮换一页。间隔几秒拍三到四张照片,覆盖全部页面。
## 拍照
诊断页按拍照场景设计。建议流程:
1. 把 `build-tag` 设为简短的镜像标签。
2. 冻结页面用 `boot-progress=1`,实时页面用 `boot-progress=2`。
3. 用户态会清屏时设置 `boot-diag-resume`。
4. 把设备放在支架上,相机与面板平行。
5. 关闭闪光灯,从侧面打光,避免反射。
6. 对标题栏锁定焦点和曝光。
7. 让面板填满画面,包含四个角。
8. 先拍标题栏,再拍整页。
9. UI trace 页面间隔 8 秒拍三到四张。
10. 拍底部脉冲条。
11. 记录启动镜像 SHA-256 和拍摄时间。
| 检查项 | 原因 |
| --- | --- |
| 标题栏可读 | 构建标签和状态标识镜像 |
| 文字区域无眩光 | 第 3 到 30 行承载阶段历史 |
| 四角可见 | 确认完整面板和缩放 |
| 脉冲条可见 | 显示拍摄时的心跳 |
| 至少两张 | 变化的计数器说明屏幕在实时更新 |
相机照片是面板显示内容的证据。保留原始文件。只抄录需要的行,并把照片与抄录一起保存。
## QEMU 抓取
```sh
python3 package/Scripts/qemu-run.py out/esp \
--log out/qemu.log --screenshot out/qemu.png \
--expect 'UNIXNU: menu: shown'
```
运行器把去掉 ANSI 的日志写到 `out/qemu.clean.log`。`--screenshot` 在菜单出现时截屏。`--keys` 在菜单后发送 QEMU 键码。
停止辅助脚本在指定符号处记录寄存器和内存:
```sh
python3 scripts/qemu-entry/gdb-stop.py --help
```
## 调试参数
| 参数 | 用途 |
| --- | --- |
| `-v` | 详细内核输出 |
| `serial=3` | 串口控制台 |
| `debug=0x14e` | 调试输出掩码 |
| `kextlog=0xfff` | kext 日志 |
| `boot-progress=1` | 诊断页,30 秒停滞后冻结 |
| `boot-progress=2` | 诊断页连续运行 |
| `build-tag=<tag>` | 标题栏镜像标签 |
| `boot-diag-resume=<seconds>` | OS 停止 scanout 后收回面板 |
| `platform-stage=<n>` | 在平台专家阶段停住 |
| `touch=<n>` | 触控探针阶段 |
| `offline-legacy-phase=<n>` | 显示探针阶段 |
| `-no_slto_panic` | 关闭 SLTO panic |
| `cs_debug=<mask>` | 代码签名输出 |
## 证据包
收集:
| 项目 | 来源 |
| --- | --- |
| 串口日志 | UART 抓取文件 |
| 诊断照片 | 标题栏、整页、trace 页、脉冲条 |
| panic 照片 | panic 屏幕 |
| 启动报告 | `out/<device>/<os_profile>/<config>/boot/boot.json` |
| 负载报告 | `out/<device>/<os_profile>/<config>/payload/payload.json` |
| 构建日志 | `out/<device>/<os_profile>/<config>/logs/` |
每张照片都记录启动镜像哈希:
```sh
shasum -a 256 out/<device>/<os_profile>/<config>/boot/boot.img
jq . out/<device>/<os_profile>/<config>/boot/boot.json
```
## 下一步
- [启动参数](/zh/xnu/boot-arguments)
- [故障排查](/zh/reference/troubleshooting)
- [QEMU 测试](/zh/reference/qemu)
- [参考设备记录](/zh/devices/sheng)
panic 显示器在本轮内核清零的 BSS 中记录首次 panic。热重启可以保留显存内容,旧画面不影响新一轮显示和导出 panic。2,048 字节 panic 文本缓冲区的最后一个字节用于记录该状态。