Translation pending. This page is currently available in Chinese.
x86_64 PC 兼容机¶
本平台使用 ARCH=x86_64 BOARD=x86_64-pc,面向提供 PC 兼容启动与 COM1 串口的真实硬件。实例是 instances/x86_64-pc.toml。它不是对任意品牌迷你主机的支持认证;具体机器的固件、串口电平/引脚、存储控制器和网卡必须分别确认。
默认实例是 单核内核 bring-up,只初始化内核、检查内存分配并请求关机,没有用户态 shell 或持久 rootfs。实机启动与电源结果仍需验收。
支持状态¶
| 接口 | 实现与限制 |
|---|---|
| 启动 | GRUB Multiboot v1 ELF,GRUB 可由 BIOS 或 x86_64 UEFI 启动;Secure Boot 关闭 |
| CPU/MMU | 64 位模式、2 MiB 页启动映射,不要求可选的 1 GiB 页;首轮使用 1 CPU |
| 内存 | 解析 Multiboot RAM 地图;只向分配器提交受映射约束的可用 RAM,不按标称容量假定 |
| 控制台 | COM1 I/O 0x3f8、IRQ4、38400 8N1;需硬件实际提供该资源 |
| 中断/时钟 | APIC/IOAPIC 与 PC 平台定时器;真实芯片组投递仍需验收 |
| PCI | ACPI MCFG 的 segment 0 ECAM;不可用时尝试传统 0xcf8/0xcfc 配置访问 |
| PCI INTx | ACPI _PRT 子集及部分已知芯片组路径;无法解析时不猜路由,设备可退回轮询 |
| 存储 | 所支持 AHCI ID,首个可用 port、512 字节扇区、单 command slot;不是通用 NVMe/eMMC 支持 |
| 网络 | 仅驱动 ID 表覆盖的 E1000/RTL8139 等;不承诺任意 Realtek 或无线网卡 |
| 显示 | 无通用 VGA 文本、VBE 或 EFI GOP 控制台;普通物理 PC 应依赖串口 |
| 电源 | uACPI 执行 _S5 等睡眠状态协议并发出关机请求;实际机器断电仍需验收 |
GRUB 不一定向内核传递 ACPI RSDP,PCI/电源功能可能因固件表缺席而不可用。本页不把 MCFG unavailable 当成成功。内核参数优先来自 Multiboot command line,不要求真实主机存在 QEMU fw_cfg。
内核默认物理加载地址为 32 MiB(0x02000000),避免低地址固件/ACPI 区域。解析器保留 Multiboot 交接数据、模块和 ACPI 表;保留记录优先于重叠的可用 RAM。已有内存图格式错误、段数超限或完整内核跨越保留区时会停止启动,不回退成假定容量。未提供内存图的旧引导路径才使用显式的兼容回退。
X86_KERNEL_LOAD_ADDRESS 同时控制汇编入口、ELF 的物理/虚拟链接地址与 EFI 载入地址,默认值之外的变体有独立构建目录。它必须为 2 MiB 对齐,范围为0x00200000..0x3e000000,且完整内核必须位于初始 1 GiB 恒等映射内。只有确认完整内核所在范围均可用后才调整,例如重新打包:
2–4 GiB 窗口保留给 MMIO;4 GiB 以上只接纳可用 RAM 完整覆盖的 1 GiB 范围,内部用 2 MiB 页映射。部分覆盖的范围和洞不会按普通 RAM 缓存;可用内存少于机器标称内存是当前映射能力的限制。
宿主依赖与构建¶
以下命令在 Linux 构建主机的仓库根目录执行。Python 需 3.11 或更新版本:
sudo apt install build-essential git curl ca-certificates python3 xz-utils file \
gcc-x86-64-linux-gnu binutils-x86-64-linux-gnu \
grub-common grub-pc-bin grub-efi-amd64-bin xorriso util-linux
安装 rustup 后准备仓库选择的 Rust 工具链与源码:
rustup toolchain install 1.96.0 --profile minimal
rustup target add --toolchain 1.96.0 x86_64-unknown-none
git submodule update --init --recursive
tools/a20 check instances/x86_64-pc.toml
tools/a20 build x86_64-pc
tools/a20 package x86_64-pc
tools/a20 ledger x86_64-pc
build 只编译默认 bring-up 内核;package 调用 pc-rescue-iso,生成固定路径:
ISO 内只有 GRUB 配置与 /boot/kernel.elf,默认参数包括 a20.dhcp=1;不附带用户态 rootfs。装上两种 GRUB 平台模块才能期望 BIOS 和 UEFI 两种入口。若宿主仅安装其中一种模块,grub-mkrescue 成功不证明两种固件均可启动。xorriso、GRUB 缺失属于打包依赖问题。
串口与写入介质¶
先核实目标机器维修手册或主板原理图中的串口接口。外部 DB9 通常是 RS-232 电平,内部排针可能是 TTL;必须使用电平匹配的适配器,不能直接把 RS-232 接到 3.3 V TTL。确认 COM1 真正位于 0x3f8/IRQ4。USB 转串口插在目标机上不能代替其原生 COM1;没有受支持 UART 的机器目前无法完成本页的串口验收。
把实例 [target].serial 改为构建/控制主机实际串口,推荐 /dev/serial/by-id/...。默认波特率是 38400、8N1、无流控。先打开控制台,再让目标启动:
在另一个终端核对专用 U 盘的容量、型号和序列号,卸载其分区后进行 dry-run:
lsblk -o NAME,SIZE,MODEL,SERIAL,MOUNTPOINTS
tools/a20 deploy x86_64-pc --media-device /dev/disk/by-id/实际USB整盘设备 \
--dry-run --no-console
tools/a20 deploy x86_64-pc --media-device /dev/disk/by-id/实际USB整盘设备 \
--no-console
必须选择**整盘**设备,不能选择 -part1。该步骤覆盖 U 盘现有分区与内容;使用可丢弃介质。工具检查挂载/交换状态和容量,但不能替你确认所选设备身份。实例 /dev/sdX 是占位符。--no-console 允许写卡和已打开的日志终端分离。
写完将盘插到目标,关闭 Secure Boot,通过固件一次性启动菜单选择对应 BIOS/UEFI USB 项。U 盘上的 ISO 是启动介质,不会安装到内置硬盘。先不要挂载或写入有价值的内置盘;默认 bring-up 不需要 rootfs 盘。
验收¶
在完整串口日志中检查:
| 标记 | 含义 |
|---|---|
[BOOTARGS] multiboot cmdline |
GRUB 参数实际到达内核 |
[RAM] usable |
解析得到至少一段可用内存 |
| 内存/定时器初始化日志 | 平台初始化继续执行,仍需单独测精度/中断 |
System ready (bringup, no userspace) |
内核 bring-up 初始化完成,不表示用户态启动 |
part ok |
本次内存分配/释放检查通过 |
随后确认关机请求是否真正使机器掉电。留在 WFI、重启或必须人工断电,应记录为电源功能未完成验收;不能由最后一条日志推断掉电成功。本实例没有 shell,因此不要发送 cat /etc/os-release 或期望出现命令提示符。
需要完整用户态时,必须另建 bringup=false 实例、提供内核能够访问的 FAT32 rootfs 磁盘并验收其存储驱动。本页的救援 ISO 不会凭空提供这些内容。首轮不要增加 CPU 数;多核能力和具体固件发现是另一项验收。
失败定位与限制¶
| 现象 | 检查 |
|---|---|
| 启动菜单无 U 盘 | 写入目标、写入完整性、固件 USB 启动模式和 GRUB 平台模块 |
| Secure Boot 拒绝 | 关闭 Secure Boot;本流程不提供固件信任链签名 |
| 有 GRUB 无内核输出 | COM1 资源、线缆电平/接线、38400、内核 ELF 是否在 ISO 内 |
无 [RAM] usable |
检查固件地图、内核完整加载范围与保留区;保存日志,不能继续认为内存已初始化 |
| 无 PCI/网卡/存储 | 固件表缺失、配置空间探测、实际 PCI ID、BAR 和驱动绑定 |
有 System ready 无 shell |
默认就是无用户态 bring-up,检查 part ok 而不是等待 shell |
part ok 后不掉电 |
ACPI/芯片组关机路径限制,保留固件信息与日志 |
内核驱动覆盖范围由实际 PCI ID 决定,不以处理器型号推断。显示、USB、NVMe、无线、电源、休眠和任意主板 AML 都不在通用兼容承诺内。需要提交问题时记录机器型号、固件模式/版本、PCI ID、ISO 哈希和从上电开始的串口日志。