Skip to content

Translation pending. This page is currently available in Chinese.

A20OS 客户机(Guest)运行协议契约

本文档定义 A20OS 作为客户机内核运行于宿主 Hypervisor 之上的协议契约、异常委托规则与设备模型接口。


1. 运行模型与设计演进

特性 基础形态 (v1) 完整 Guest 模式 (v2)
guest 载体 手写最小指令序列 完整的 A20OS 内核镜像
异常与中断委托 hedeleg/hideleg 全 0,全部陷入 HS 异常绝大部分委托给 VS,中断按 VS 级掩码委托
guest 内存 全部由 hyp_vm_load() 预先静态装载 预装镜像 + Stage-2 物理页帧按需分配
设备模型 无(不访问外设 MMIO) 16550 UART + CLINT mtime 虚拟设备模型
guest 时钟 依赖宿主周期中断 time CSR 硬件虚拟化(htimedelta)+ CLINT mtime
引导环境 vcpu->pc = entry_gpa,寄存器清零 a0=hartid、a1=DTB GPA、标准 FDT 设备树
验收判据 console 输出 ^HYP$ guest 控制台标志输出(通过 marker 独立判定)

核心设计思路:由 Hypervisor 代理硬件边界,客户机自主管理内部中断与二级页表之前的异常,HS 仅介入二级缺页补页与 MMIO 访问拦截。该原则直接决定了中断委托表(§2)与路由表(§5)。


2. 委托表

2.1 掩码与理由

CSR 值 理由
hedeleg 全 1 减去 ecall-from-VS 那一项(cause 10) guest 自己管自己的 trap,包括给用户进程的缺页。只有 SBI 面必须由 HS 承接的那一个 ecall 留给 HS。掩码按"全 1 减一位"写,见下方关于逐位可写性的说明。
hideleg bit 2 | bit 6 | bit 10(VSSIP | VSTIP | VSEIP) 这三位是 hideleg 里的**可写** VS 级中断位。委托之后硬件会把它们翻译成 VS-mode 看到的 supervisor 软件/时钟/外部中断(cause ⅕/9),guest 的 sie 与 vs tvec 就能像在裸机上一样派发,WFI 也在被委托中断到来时自然醒来,不需要 HS 模拟 WFI。
hstatus.SPV 1 trap 返回的目标是虚拟态,这是 HS 侧唯一的"我在跑 guest"标志
hstatus.SPVP 1 允许 HS 读写 guest 的 vs* CSR(引导时读回 vsatp、诊断时用)
hstatus.VTVM 1 见 §3 与 §2.3(二):保留 VTVM,改在 scause 22 上模拟被拦下的 guest CSR 写
hstatus.HU 0 guest 不做虚拟化指令
hcounteren.TM 1 见 §3
htimedelta 0 guest 与宿主看到同一个单调时钟,见 §3

2.2 关于 hedeleg 的逐位可写性

规格 hypervisor.adoc 的 "Bits of hedeleg that must be writable or must be read-only zero" 一表,在本版本源码里与同一文件的编号 cause 表对不齐:位列表跳过 14 却一直写到 23,而异常列只有 0..21 共 22 项。因此本文**不逐位列举 hedeleg的可写位**,只写"全 1 减一位"——只读零的位写了也无效,两种情况下行为一致。

真正需要确认的实质问题只有一个:ecall-from-VS 必须没有被委托。委托了它就只到 VS 自己,HS 的 SBI 面永远不会被调用;而它是 guest 唯一能向 HS 说话的口子。这个要求与该位是否可写无关,写掩码时按"没被委托"来验证即可。

2.3 契约里写错的两处(必须先修)

这两条不是设计选择,是照抄会得到错误行为的地方,本片读规格后记录在此。

本文引用的规格文本全部来自 RISC-V ISA 手册仓库的 H 扩展一章,复现命令:

gh api repos/riscv/riscv-isa-manual/contents/src/priv/hypervisor.adoc \
  --jq '.content' | base64 -d > hypervisor.adoc

(本片用的是该仓库 main 分支当时的 src/priv/hypervisor.adoc,2943 行。异常 cause 编号见同文件的编号 cause 表:8 = from U/VU、9 = from HS、10 = from VS、 11 = from M、12/13/15 = insn/load/store page fault、14 与 17 是 Reserved、 22 = virtual instruction。本文 §2.2 提到的逐位表对不齐问题也出自这份文件。)

[!NOTE] scause 格式与异常解析 scause 输出为十六进制格式(%lx),因此日志中的 14 对应 0x14 = 20 = RISCV_EXCP_INST_GUEST_PAGE_FAULT(guest 取指缺页),由 HYP_SCAUSE_GPF_INST 处理(kernel/hyp/hyp_vcpu.c:71)。同理,scause=15 为 0x15 = 21 = RISCV_EXCP_LOAD_GUEST_ACCESS_FAULT,scause=17 为 0x17 = 23 = RISCV_EXCP_STORE_GUEST_AMO_ACCESS_FAULT。十六进制输出不可按十进制误判为规格中的保留编码。

(一)HYP_HIDELEG_DEFAULT 的三个位是只读零,写了等于没写。 —— 已修。

原始定义(kernel/include/hyp/hyp_vcpu.h)是

#define HYP_HIDELEG_DEFAULT (((uint64_t)1 << 1) | ((uint64_t)1 << 5) | \
                             ((uint64_t)1 << 9))

RISC-V H 扩展规格对 hideleg 的属性规定为(riscv-isa-manual src/priv/hypervisor.adoc,"Hypervisor Trap Delegation"一节):

Among bits 15:0 of hideleg, bits 10, 6, and 2 (corresponding to the standard VS-level interrupts) are writable, and bits 12, 9, 5, and 1 (corresponding to the standard S-level interrupts) are read-only zeros.

也就是说 bit ⅕/9 是 **S 级**中断位、只读零,bit 2/6/10 才是 VS 级可写位。按原宏写下去,hideleg 读回来是 0,一个中断也没委托——而契约正文宣称的是"guest 从 vs tvec 自己派发"。行为与契约相反。

QEMU 在软件里做同一件事,不靠 CSR 属性:rmw_hideleg64 用wr_mask & vs_delegable_ints 逐位与(target/riscv/csr.c:4658-4668),而vs_delegable_ints = (VS_MODE_INTERRUPTS | LOCAL_INTERRUPTS) & ~MIP_LCOFIP(csr.c:1779),VS_MODE_INTERRUPTS 正是 2/6/10(cpu_bits.h:790)。掩码外的位不是"写被拒绝",而是**被 AND 掉**,所以读回 0 是静默的。

当前状态:已按 (1<<2) | (1<<6) | (1<<10) 修正(hyp_vcpu.h:216-222),hyp_arch.c 里那句"nothing here is silently dropped"的注释也一并改正——原来那句断言与 QEMU 源码相反。委托后硬件按规格把 VS 级 cause 10/6/2 翻译成 VS-mode 看到的 cause 9/5/1,所以 guest 侧不需要任何改动。

**(二)hstatus.VTVM 与"VS CSR 硬件直通"互斥。**契约说(hyp_vcpu.h:187-188)

VS-mode CSR accesses (satp/sie/stvec/...) hit the VS variants in hardware -- no interception, nothing to save while one guest runs.

这句要成立,VTVM 必须是 0。而已落地的 v1 架构半把 VTVM 设成了 1:

  • kernel/arch/riscv64/hyp/hyp_arch.c:111 HYP_HSTATUS_GUEST_ON = SPV | SPVP | VTVM
  • kernel/arch/riscv64/hyp/hyp_vcpu_asm.S:45 同一掩码的汇编副本

规格对 VTVM 的规定是(hypervisor.adoc,norm:hstatus_vtvm_op):

When VTVM=1, an attempt in VS-mode to execute SFENCE.VMA or SINVAL.VMA or to access CSR satp raises a virtual-instruction exception.

只覆盖 satp / SFENCE.VMA / SINVAL.VMA 三样——vstvec/vsie/vsscratch这些 VS CSR 本来就直接可访问,不受 VTVM 影响。但 satp 受影响,而 A20OS 的启动路径一定会写 satp。VTVM=1 下的后果不是"陷回 HS 让 HS 模拟",而是一次**virtual-instruction exception(cause 22)**:委托与否它都落在 guest 自己的 trap handler 上(除非 HS 把它留在 HS 侧处理,那正是本文不建议的路)。guest 的csrw satp 因此变成一次它不认识的异常。

因此 v2 架构半必须把 VTVM 从 HYP_HSTATUS_GUEST_ON 里去掉(两处,C 与 .S 各一份)。这同时让 §3 的"无需保存"结论成立。

当前状态:没有去掉,改走另一条路。 工作树保留 VTVM=1(hyp_arch.c:166-167 与 hyp_vcpu_asm.S:47-53 的 HYP_HSTATUS_GUEST_ON / HSTATUS_GUEST_ON 都含该位),并在运行循环里模拟被 VTVM 拦下的那三条(kernel/arch/riscv64/hyp/hyp_emulate.c:622,hyp_emulate_virt_inst()):

  • csrr/csrw satp → 转成 HS-mode 下的 csrr/csrw vsatp(CSR 0x180 ↔ 0x280);
  • sfence.vma → 在 HS-mode 直接执行;
  • csrw vstimecmp → 转成 csrw 0x24d(vstimecmp)。

vsatp/vstvec/vsie/vsscratch 这些 VS CSR 不受 VTVM 影响,仍由硬件直通。代价是 guest 每写一次 satp/sfence.vma 多一次 HS 侧的解码与一趟 sfence;换来的是架构半不必再动 HYP_HSTATUS_GUEST_ON 的既有形状,且 vstimecmp 的写入路径(依赖 henvcfg.STCE 才不被 VTVM 拦)在 Sstc 缺失的平台上也有统一的落点。代价清单里还有一条未覆盖:模拟器只认这三种编码,guest 若在 VS-mode 执行别的虚拟指令(WFI 在 VTW 下、HLV 系列),仍是一次 cause 22;VTVM=1 时WFI 不在 VTVM 的拦截范围内(它归 VTW,本片让 VTW 保持 0),所以现役风险只有未被识别的 CSR 写与指令。


3. VS CSR 硬件直通,以及为什么无需保存

VS-mode 与 HS-mode 共享同一个 hart 的物理寄存器组,但**不共享 CSR**。规格给每个 VS 级 CSR 准备了影子寄存器,VS-mode 里的普通名字被重定向过去:

VS-mode 写的名字 实际落到
satp / sie / stvec / sscratch / sstatus / sepc / scause / stval vsatp / vsie / vstvec / vsscratch / vsstatus / vsepc / vscause / vstval
sip 的 SSI/STI/SEI 位 vsip 的对应位
sret 回到 vsstatus.SPP 指定的虚拟态

规格原话(hypervisor.adoc,"Virtual Supervisor Address Translation and Protection (vsatp) Register"):

vsatp substitutes for the usual satp, so instructions that normally read or modify satp actually access vsatp instead.

"无需保存"的准确含义:只要 VTVM=0、且 HS 不需要读 guest 的 vs* CSR,这些寄存器**在 guest 进出之间原样留着**,HS 根本不碰它们——没有 swap、没有进出钩子、没有 shadow 区。这与 v1 的 "帧即状态" 并不冲突:v1 要存的是**通用寄存器组**(共享,必须存),v2 免掉的是**VS 影子 CSR**(不共享,不必存)。二者的接口仍然是同一个 hyp_vcpu_handle_trap()。

这条结论有两个必须写下来的前提,都还没在代码里落地:

  1. VTVM 必须为 0(§2.3)。SPVP=1 保持不变——它是 HS 侧唯一能合法读vs* 的授权位。
  2. hcounteren.TM 必须置 1。 A20OS 的 timer_get_ticks() 直接读 time CSR(kernel/arch/riscv64/platform/timer.c:58-62)。规格(norm:hcounteren_op)规定 hcounteren 的位清零时,低于 HS 的特权级读cycle/time/instret 会触发异常;hcounteren 必须实现,具体位是 WARL。顺带:guest 的 timer_init() 自己会写 scounteren |= 0x2(timer.c:39-42),而 VU 模式读 time 需要 hcounteren 与 scounteren **同时**置位(norm:hcounteren_scounteren_vu_op),所以 hcounteren.TM 是硬要求。

time 本身**不陷到 HS**:规格("Hypervisor Time Delta (htimedelta) Register")规定 VS/VU 模式读 time 返回 htimedelta + time。htimedelta留在 0 就意味着 guest 与宿主共用同一个单调时钟,也意味着**不需要为时钟做任何 per-vcpu 状态**。


4. SBI 面:按 guest 实际会发出的调用面

guest 是 A20OS 自己,它的 SBI 调用面由kernel/arch/riscv64/platform/firmware.c 与kernel/arch/riscv64/platform/timer.c 决定,不是由"hypervisor 想支持什么"决定。下表是逐个读这两个文件得到的**实际会发出的调用**,EID 取自kernel/arch/riscv64/include/firmware.h:6-16。

发出方 a7 = EID a6 = FID a0 v1 现状 v2 必须
firmware_console_putchar 0x01 0 字符 已实现(hyp_vcpu.c:390-393) 改为走 16550 设备模型
firmware_console_getchar 0x02 0 — 未实现 允许,恒返回 -1(无输入)
firmware_set_timer 0x00 0 deadline 未实现 必须,或让 guest 走 sstc(见下)
firmware_shutdown 0x53525354 (SRST) 0 0 未实现 必须
firmware_reboot 0x53525354 (SRST) 0 1 未实现 建议实现为等价 shutdown
sbi_send_ipi 0x735049 0 mask, base 未实现 单 vcpu 下用不到
sbi_hart_start 0x48534D (HSM) 0 hart, addr, opaque 未实现 单 vcpu 下用不到
sbi_remote_sfence_vma 0x52464E43 (RFENCE) 1 mask, base, start, size 未实现 单 vcpu 下用不到

v1 与 v2 最大的行为断裂在这里。 v1 的冻结契约(hyp_vcpu.h:136-141)只服务 a7=0x01 与 a7=0x08,而 0x08 是 legacy SBI 的 shutdown EID;当前 firmware_shutdown() 走的是 SRST 扩展0x53525354(firmware.c:50-52),SBI_SHUTDOWN_EID 8 在firmware.c 里已无使用者。也就是说:v1 的 demo guest 能关机,是因为它的字节码是手写的、只发 a7=0x08;真正的 A20OS 内核不会发那个数。v2 必须按上表实现,0x08 只能作为向后兼容的别名保留。

set_timer 不是可选项。 timer_set_interval()(timer.c:46-56)只有在riscv64_fdt_has_isa_extension("sstc") 为真时才写 sstc 的 stimecmp CSR,否则调 firmware_set_timer()。而 riscv64_fdt_has_isa_extension() 查的是 FDT 里的riscv,isa 属性(kernel/arch/common/riscv/fdt.h)——最小 FDT 里若没有这一项,guest 一律走 SBI set_timer。此时 guest 自己没有任何办法给自己设定时器,除非 HS 实现 a7=0。把 sstc 写进最小 FDT 与实现 set_timer 两条路至少要有一条通;这是引导切片必须同时面对的两件事,不是可以推后的细节。

关于 ecall 的 cause 编号:契约写的"ecall-from-VS (scause 10)"是对的。规格的异常 cause 表里 8 = from U/VU、9 = from HS、10 = from VS、 11 = from M。v1 的 hyp_vcpu.c:44-46 三个都收,属于无害的超集。


5. 二级缺页路由

一次二级缺页(htval 给出 GPA)按三段裁决,顺序不可换:

顺序 判据 动作
1 GPA 已被 hyp_vm_load() 映射,或已在 RAM 窗口内被填充过 表里有映射就是表里的;无映射则走 2
2 GPA ∈ [ram_base, ram_base + ram_size) hyp_ram_fill():分配**一帧清零内存**,hyp_s2_map() 以 RWX 装入,guest 重试同一条指令即命中
3 其它 交给 hyp_dev_mmio();返回 0(地址不认识)则以 HYP_EXIT_FAULT 退出并留下 exit_htval
  • 窗口默认 [0x80000000, mem_size)(HYP_RAM_BASE_DEFAULT,kernel/hyp/hyp.c:24,赋值在 hyp.c:115-116)。这与 guest 板的内存布局一致:kernel/arch/riscv64/include/platform.h:14-16 把 QEMU virt 的PHYS_MEMORY_BASE 定为 0x80000000,启动代码链接在KERNEL_ENTRY = 0x80200000(:20)。
  • 窗口页必须是 RWX,且 PTE_U 必须置位(PTE_U 的理由见00-design.md §5.3 支撑改动)。已落地:工作树里HYP_RAM_PAGE_PROT 是 PTE_R|PTE_W|PTE_X(kernel/hyp/hyp.c:50),hyp_vm_load() 装镜像用的 HYP_GUEST_PAGE_PROT 是同一个值(kernel/hyp/hyp_vcpu.c:100),hyp_s2_map() 在 prot 之上再补 PTE_R|A|D|U(kernel/hyp/hyp.c:229)。理由与架构规范解析见 00-design.md §5.3 第 3 条:R|W|X 在 QEMU 10.0.13 的 get_physical_address() 里落到 PAGE_READ|PAGE_WRITE|PAGE_EXEC,正常翻译,不是保留编码。已验证:在 smoke-hyp-a20os 门禁中,guest 一路执行至 [RAMFS] Initialized,正常写入 .data、.bss、页表与内核栈。
  • 窗口页与预装页的关系:hyp_vm_load() 装过的页是显式映射,不会触发缺页;窗口只覆盖 guest 自己分配的内存。两者重叠时以先建立的映射为准(hyp_s2_map() 对已映射 GPA 返回 -EEXIST)。
  • 记账:hyp_ram_fill() 记到当前任务的 cgroup。树里已有的接口是cg_mem_charge() / cg_mem_uncharge()(kernel/mm/vmo.c:276,284),与 VMO 记的是同一本账——这正是 capability 叙事里"guest 内存就是宿主内存、只是被出借"的落点(见 §9)。
  • "静默按需补页"这条禁令已被一条可判定的规则替代:窗口内的 GPA 补页并让 guest 重试同一条指令,窗口外交给设备模型并由宿主**代执行这条指令**,补页失败就是一次记下来的 fault——三条都在 hyp_guest_mem_fault() 的注释与实现里(kernel/arch/riscv64/hyp/hyp_emulate.c:675 的两出口说明、815、843-848、851-857、866-872)。契约头还留着"no silent on-demand fill"那句(kernel/include/hyp/hyp_vcpu.h:154-155),指的是"补页不能藏在 trap 里悄无声息地进行",与这里写的是同一件事。

6. 设备模型行为表

设备模型由 kernel/hyp/hyp_dev.c 实现,对外提供 hyp_dev_mmio(vm, gpa, store, *value, len) 统一分派入口。下表左列为客户机内核对外设寄存器的访问,右列为虚拟化设备模型的响应逻辑:

一条贯穿全表的设计约束(hyp_dev.c 文件头):设备模型运行在 **guest trap 路径**上,guest 停在 HS-mode、trap 帧还活着,调用者马上就要 sret。所以这里不取任何锁、不睡眠、不分配;所有共享状态走 __atomic。

6.1 16550 UART [0x10000000, 0x10001000)

guest 的 UART 代码在 kernel/arch/riscv64/include/console.h(内联头,全部寄存器访问都在这里)。

寄存器 偏移 guest 侧做什么 模型该做什么
IER 1 arch_uart_init() 写 0x00 → … → 0x01(console.h:18-25) 静默丢弃,记写入
LCR 3 写 0x80 再写 0x03(8N1,去 DLAB) 静默丢弃
FCR 2 写 0x07(console.h:23) 静默丢弃
MCR 4 写 0x0B 静默丢弃
THR 0 arch_uart_putc() 自旋等 LSR,再写字节(console.h:27-32) 写到宿主 console,计入 guest console 字节数,逐字节比对 marker
RBR 0 arch_uart_poll_getc() 先读 LSR(console.h:34-39) 已实现:读弹出 ingress ring 里最老的一个字节,空环回 0(kernel/hyp/hyp_dev.c:290-304 的 HYP_UART_THR 分支,hyp_uart_pop_rx() 在 :269-279)。多字节读只认第一字节(byte_index != 0 不弹)
LSR 5 arch_uart_putc() 等 bit 0x20;arch_uart_flush() 等 bit 0x40;arch_uart_poll_getc() 读 bit 0x01 返回 0x60 或 0x61:0x60 恒在(HYP_UART_LSR_TX_EMPTY,hyp_dev.c:69),bit 0x01(DR)由"ring 非空"决定(hyp_dev.c:287-288;hyp_uart_rx_ready() 是**窥视不消费**,:262-267)
IIR 2 通用串口驱动会轮询中断标识 读 0x01("无中断待处理",HYP_UART_IIR_NONE,hyp_dev.c:76,286)。在途实现补了这一条:RAZ 会宣称有一个永远不会被投递的中断,那是唯一能把轮询 IIR 的驱动挂死的值
MSR 6 等 CTS/DSR 再写的驱动 读 0x30(DSR+CTS 置位,RLSD 不置,HYP_UART_MSR_CARRIER,hyp_dev.c:79,289)。在途实现补了这一条

LSR = 0x60 是**承重值**,不是随手填的:契约(hyp_vcpu.h 的 v3 一节,kernel/include/hyp/hyp_vcpu.h:250-262)给的就是 0x60,并明确说**只有 DR 位是后加的**。bit 0x20(THRE)必须常置,否则 arch_uart_putc() 里的while ((uart[5] & 0x20) == 0); 会把 guest 焊死在一个自旋里——这是启动冒烟最可能卡住的地方。bit 0x40(TEMT)同理,arch_uart_flush() 会等它。bit 0x01 从"恒 0"变成"有输入才 1",这正是契约 v3 带来的唯一寄存器语义变化。

中断:arch_uart_init() 打开了 IER bit 0,uart_init() 又无条件request_irq(UART0_IRQ=10, …)(kernel/drivers/char/uart.c:184)。v2 不路由中断(契约明说"interrupts are delegated, not routed"),所以 source 10 永远不会被断言。树里已经有现成的出路:board_config_t.uart_rx_is_polled(kernel/drivers/core/driver_core.h:548)正是给"UART IRQ 路由与定时器陷阱都不可用"的板子准备的,已有 LS2K1000 / VisionFive 2 / loongarch QEMU virt 三家在用。v2 guest 板应当置这个位,否则 guest 会挂一个永远不来的中断。

6.2 CLINT [0x02000000, 0x02010000)

寄存器 guest 侧做什么 模型该做什么
mtime 当前 riscv64 路径不读它(timer_get_ticks() 读 time CSR,timer.c:58-62;kernel/drivers/irqchip/plic.c 也不碰 CLINT) 读返回宿主 timebase,写丢弃
mtimecmp 只有 vstimecmp/sstc 路径会到(timer.c:49-52 写 CSR 0x14d) RAZ/WI
其它 — RAZ/WI

契约要求建模 mtime 读的理由是防止 guest 时钟冻结(hyp_vcpu.h:166-167)。事实是:今天的 A20OS guest 走 time CSR,不走 CLINT MMIO,所以这条模型当前是防御性的。保留它有两个好处:一是 guest 的启动/探测代码未来可能读 CLINT,二是hcounteren.TM 一旦被某个平台实现成只读零,MMIO 路径就是唯一的退路。

6.3 其余一切 RAZ/WI + 每页计数器

PLIC 在 0x0C000000(platform.h:46),virtio-mmio 从 0x10001000 起(:45),PCIe ECAM 在 0x30000000(:47)——全都在窗口外,全部落进这一档。

PLIC 特别值得说一句:plic_configure(PLIC_PLIC_BASE, …) 在 guest 的early_init 里是**无条件调用**的(kernel/arch/riscv64/boards/qemu-virt-riscv64/board.c:171),所以 guest 一启动就一定会去写 PLIC 的 PRIORITY/SENABLE 寄存器。RAZ/WI + 计数器保证这些写不卡死,也不至于让 guest 在一个"IRQ 永远不会来"的等待里停住。


7. 引导协议

7.1 入口约定

hyp_vcpu_set_boot(vcpu, hartid, dtb_gpa)(hyp_vcpu.h:196)把两个值放进 guest 的 a0/a1。guest 侧的解读在 kernel/arch/riscv64/boot/entry.S:88-90: a0 存进 __boot_hart_id,a1 存进 __boot_dtb_ptr。与 OpenSBI 的约定一致,也意味着**同一个 kernel.elf 既是宿主内核也是 guest 内核**,不需要为 guest 单独构建——这是"把 A20OS 自己当 guest"最省事的一处。

单 vcpu 切片下 hartid 只能是 0。a0 != 0 会走 entry.S 的 secondary 分支,那里要 sbi_hart_start() 与 riscv64_smp_release(entry.S:37-61),两者在 v2 的 SBI 面里都不存在——这条路径必须先失败得干净,不能半启动。

7.2 镜像怎么进 guest RAM

契约中**不包含内核 ELF 装载接口**。内核提供 hyp_vm_load()(整页复制)与 hyp_ram_fill()(清零填充),ELF 解析在宿主用户态装载器进行:user/cmds/core/hyp_boot.c 从宿主文件系统读取 guest ELF,按 PT_LOAD 段逐段通过 hyp_vm_load() 写入各段的 LMA。

装载地址是 LMA,不是 e_entry。这是这半最容易错的一处:kernel/arch/riscv64/boot/ldscript.ld:17-18 把内核链成高半区(PHYS_BASE = 0x80200000、VIRT_BASE = 0xFFFFFFC080200000),每段的 LMA 1:1 落在 VMA 之下,所以 e_entry 是个虚拟地址,不是 guest 物理地址。QEMU 的-kernel 装载器跳的是 LMA,hyp_boot 也是:入口 GPA 是 e_entry 经 program header 换算出来的 LMA,落在 0x80200000 一带(platform.h:20 的KERNEL_ENTRY 就是这个数)。entry.S 自己把启动页目录铺成BOOT_MAP_PHYS..+16 GiB 的 identity 映射,guest 的链接地址不能变;它还有.done_bss: 标签会自己清 bss,所以装载器不必也不该替它做这件事。

7.3 最小 FDT 要有什么

guest 侧对 FDT 的全部依赖有四处,逐个对着代码看:

需要的东西 谁在读 缺了会怎样
合法 FDT 头 fdt.c:194、fdt.c:205 打印一行告警后回退到板级窗口
/memory 的 reg riscv64_memory_init(),fdt.c:262 回退到板级窗口 0x80000000 .. +16 GiB(platform.h:16,19)——这条绝不能缺、更不能解析失败:hypvm -m 默认只给 128 MiB,回退值比窗口大 128 倍,guest 按回退值分配就立刻越窗(曾经的 kfree(magic=0x0) 就是这条链)
/cpus 的 riscv,isa 含 sstc timer.c:30 guest 改走 SBI set_timer(见 §4,这是个必须补的洞)
/chosen/bootargs arch_bootargs_get(),fdt.c:301 返回 NULL,命令行参数全丢

所以最小 FDT 的必需项是:合法头部 + 内存节点 + 一个 chosen/bootargs 节点。内存节点**必须给、而且必须真的解析成功**——回退值 +16 GiB 远大于 hypvm -m给的窗口,guest 拿回退值去分配就会越窗。当前树的合成 FDT 是解析成功的(实测[FDT] RAM range 0x80000000..0x88000000 (128 MiB)、bootargs='a20.hypguest=1',grep -cE 'memory node parse failed|using board window' = 0);曾有一版因为合成 blob 的 4 字节 padding 写错,整个结构块失步、四条属性同时读不到,见03-usage.md §2.3。sstc 给不给决定要不要实现 SBI set_timer——建议给,两条都通最省心。FDT 放在哪由装载器决定,但 §7.4 有一个硬约束必须满足。

7.4 FDT 指针的一个硬约束

__boot_dtb_ptr 被当作**指针直接解引用**(fdt.c:193、fdt.c:77),entry.S:90 存的是 a1 原值。SBI 约定里 a1 是**物理地址**,而 guest 一旦装上自己的页表,物理地址就不再是可直接解引用的虚拟地址。

v2 的 guest 是会装页表的(A20OS 的启动路径一定会写 satp),所以:

  • 要么把 FDT 放在 guest 装页表之后仍然 identity 可达的地方,
  • 要么改 guest 侧,让它在建表后把 __boot_dtb_ptr 走一次 va_to_pa。

v1 的 demo guest 没有这个问题(vsatp 停在 Bare,VA 就是 GPA)。这是 v2 引入的第一个"真实 guest 才暴露"的坑,本片只记录,未验证。


8. 冒烟判据:marker,不是日志交叉比对

8.1 为什么不用日志

v1 的 gate 靠两行 console 输出交叉比对:^HYP$ 与 HYP_VCPU_TEST: PASS(tools/smoke_cases.py:526-534)。那是可行的,因为 v1 的 guest 只打三个字符。 v2 的 guest 会打出整个内核启动日志,而宿主自己的日志与之共享同一个 console 通道:两者的行会交错,[FDT] 这类前缀在两边都可能出现。这种判据在日志变长之后不再是判据。

8.2 marker 机制

契约给了三个入口(hyp_vcpu.h:198-206):

  • hyp_vm_set_marker(vm, marker):≤ 32 字节。设备模型在**每一个** guest UART 字节上做匹配。
  • hyp_vm_marker_seen(vm):命中与否。
  • hyp_vm_console_bytes(vm):自 run 开始以来的 guest console 字节数。

判据因此是三个独立事实,而不是"日志长这样":

# 断言 它排除什么 实现状态
1 hyp_vm_marker_seen(vm) == 1 guest 走完了从入口到打印 banner 的整条路——包括委托的异常处理、按需 RAM 窗口和 16550 的 THR 路径 已实现(hyp_boot.c:218-219)
2 hyp_vm_console_bytes(vm) > <marker 长度> marker 不是"只匹配到开头就停"的退化命中 已实现(hyp_boot.c:221-223)
3 hyp_vcpu_run() 返回 0 且 vcpu->exit == HYP_EXIT_SHUTDOWN guest 是自己关机,不是撞死 未实现,且该判据本身与 PASS 的定义冲突:本门禁的 PASS 是"guest 打到了自己的 banner",不是"guest 正常关机"。当前代码只检查 exit_reason >= 0(hyp_boot.c:201),退出原因只输出供参考(:205-212),不参与判定。实测表明 exit=1(shutdown) 同样会在 guest panic 触发关机调用时产生(§8.3),不能将其作为独立的正常关机判据
4 mm_s2_audit(vm) 返回 0 出借的帧与 stage-2 表在 guest 死后仍然对得上 未实现:内核侧有 hyp_s2_audit()/mm_s2_audit()(kernel/hyp/hyp.c:275),但没有任何 syscall 能从用户态取到它的结果

第 1 条已经包含了"这份输出来自 guest 通道"这层意思——marker 只在 guest UART 字节上比对,宿主自己打的同名 banner 不会让它命中。这一点很要紧,因为宿主和 guest 是同一个内核,会打出字节完全相同的一行。

8.3 该带什么 marker,以及冒烟的边界

用 guest 自己最早打印的一行、且这行只可能在"启动真的走通"时出现的一行。理由是 marker 的强度等于它所证明的事情的强度:打在启动早期的短串只证明"进了 C 代码并能写串口",打在内存子系统就绪之后的串才顺带证明窗口填充成功。进行中:user/cmds/core/hyp_boot.c 选了 "A20OS Kernel",也就是 guest 最早的 banner 行。

**PASS 的定义是"guest 到达了自己的 banner",不是"guest 引导完成"。**这轮门禁构建的是 RAMFS_USER=0 镜像(tools/smoke_cases.py:630),guest 没有块设备、挂不上 rootfs,会死在 init_kthread 里——那是真实到达,不是失败。当前实测的终点正是那里:smoke-hyp-a20os 当前日志(632 行)里 guest 走完 banner、[INIT] entering scheduler...、driver manager,停在[INIT] Cannot open /bin/init: -2 → init: no init program found → KERNEL PANIC → HYP_A20OS: PASS。更早两轮的终点更靠前(slab 层的 kfree、进调度器时的栈页 use-after-free),两个根因都已修(§8.3 第五次)。这条边界必须写进 gate,否则两件坏事之一必然发生:

  • 把 PANIC 放进 forbid:guest 的 panic 文本与宿主的**逐字节相同**,一条正确的运行会被判红;
  • 不写清楚 PASS 的含义:读者会以为 gate 覆盖了 guest 的完整启动。

门禁 tools/smoke_cases.py 的 smoke-hyp-a20os:forbid 规则不含 PANIC,只列 LOCK-STALL、MCS DEADLOCK、HYP_A20OS: FAIL;宿主死锁或故障由“未输出 HYP_A20OS: PASS 标志”捕获。该门禁超时时间设为 300 s,以适配虚拟化多层陷入开销。

guest 在 banner 之后走到哪儿,与判据无关。 判据只看 marker,不看退出原因。五次实测(前三次是 .kernel-build/smoke/hyp-a20os-riscv64.log,第四、五次是hyp-shell-riscv64.log),五次门禁都 PASS——但第五次是 guest 真的通了,前四次是 marker 与 guest 崩溃同时出现:

第一次(日志可读,全文 573 行),guest 走到根 ramfs 就绪,然后:

556: [RAMFS] Initialized, root inode 0
557: [SLAB BUG] kfree(0xffffffc47fae0010): invalid non-slab pointer …
571: [PANIC] attempting firmware poweroff
572: HYP_A20OS: exit=1(shutdown) scause=0xa stval=0x0 htval=0x0 marker_seen=1 console_bytes=17840
573: HYP_A20OS: PASS

exit=1(shutdown) 与 PASS 同时出现,中间隔着一次 guest 自己的KERNEL PANIC。 shutdown 只说明 guest 发了一次 SBI SRST ecall (hyp_vcpu.c:413-418),那次是 panic 路径在打完堆栈之后发的。[SLAB BUG]是 guest 自己 slab 层报的(guest 用的是同一棵树的 slab 代码)。当时本片写的是"没有定位根因",现在已定位:合成 FDT 的 4 字节 padding 失步 → guest 回退板级 16 GiB 窗口 → 越窗分配 → RAZ 喂零 → kfree(magic=0x0),已修,见 §8.3 第五次。同一个日志里还有一条对照:292: [BUS] virtio-mmio: found 0 devices——guest 在自己的 stage-1 里数到了两个 virtio-mmio(宿主那次是 :103 的 2 个),但设备模型给的是 RAZ/WI 计数,不是真设备。

第二次(日志被在途调试打印刷成 43 万行,guest 段读不出):结果行逐字段相同(console_bytes 也是 17840),可 guest 侧换成停在 UART 页上的自旋(hyp: trap loop at pc=ffffffc080209664 scause=17),而且 [SLAB BUG] 与KERNEL PANIC 这两行**不再出现在日志里**——原因不是被修好了,是kernel/hyp/hyp_vcpu.c 两处在途 DBG 打印把日志撑到了 432,618 行。"这次没看见"不等于"这次没有"。

第三次(去掉调试打印后,那一轮的树,PASS,日志 573 行可读):和第一次停在同一个地方。 [RAMFS] Initialized, root inode 0 之后紧跟

[SLAB BUG] kfree(0xffffffc47fc20010): invalid non-slab pointer hdr=0xffffffc47fc20000 magic=0x0 order=0
[SLAB BUG]   pfn=4193312 flags=0x1 refcount=1 order_meta=5 cpu=0
[FRAME-TRACE] releases of pfn=4193312:

所以第二次的自旋是那两条 DBG 造成的假象;到第三次为止,guest 的真实终点是kfree 一个 RAMFS 指针(第四次已经不是了,见下面那条引注)。 flags=0x1 refcount=1 说明那一页在 buddy 层仍是"已分配"的——被 kfree 的地址落在 0xffffffc47f...,正是 guest 的 RAMFS 区间,ramfs 把自己持有的页当普通页还了回去。这不是 stage-2 的问题:解码零缺口(grep -c "undecodable guest access" = 0)、guest 一路走到 [INIT] USB devices scanned(17840 个 guest console 字节)、该走的二级页错配都走完了。同一现象在RAMFS_USER=1 的内核上**一模一样地复现**(同一个 [RAMFS] Initialized 后面、同一个 [SLAB BUG],只有 pfn 差了一点),所以也不是"guest 缺 /bin/init"那条路导致的。

核心判定原则:PASS 表明 guest 成功抵达指定 banner;exit= 记录 guest 最终退出状态。 评估运行结果需综合检查日志中的 [PANIC] / [SLAB BUG] 或陷阱循环标记。详细解读参见 03-usage.md §3.1-3.3。

[!NOTE] 启动调试阶段演进历史 早期阶段曾经历从 RAMFS 指针非法释放到内核栈内存故障的排查。当前版本在 make smoke-hyp-shell 中已实现端到端全绿:guest 完整走完初始化步骤并创建用户态 init(pid=3),拉起 shell,响应测试交互并优雅 exit 关机。合成 FDT 的 4 字节对齐补齐与 guest 浮点寄存器上下文修复参见 00-design.md 与 03-usage.md §3.3。

控制台输入门禁 smoke-hyp-console-p0(tools/smoke_cases.py:572-611):验证 guest 控制台双向交互契约(v3)。通过向 QEMU stdin 顺序发送测试序列,断言 guest 轮询 LSR、读取宿主输入字节并经 SBI 输出回显 HYP,随后正常 shutdown,门禁状态为 PASS。

它一度是红的,而红的不是通道。 第一版 hyp_test.c 里memcpy(code + n, guest_echo, sizeof(guest_echo) / sizeof(guest_echo[0]))把**元素个数当成了字节数**——拷了 13 字节(三个整字加第四个字的头一个字节)。 guest 于是把 andi a1,a1,1 取成 0x00000093,解成 addi ra,x0,0,带着过期的 LSR 字节跳进镜像后面的零填充,在 pc=0 取指失败。这条编译不报、运行不报、头一个字还对,四步之外的 trap #1 scause=14 pc=0 是它唯一的表现,而那四步全都"看起来对"——解码出的 va、gpa、rd 一项不差。

第三条门禁 smoke-hyp-console(tools/smoke_cases.py:742-808) 是端到端那条:用 -k /bin/boot/guest-kernel-ramfs.elf 引导 RAMFS_USER=1 的 guest 内核(userland 直接链进镜像,因此背后没有块设备也有 /bin/init 可 exec),并要求HYPVM: 行上的 rx_bytes 非零。实跑 PASS,rx_bytes=20——echo roundtrip 的 15 个字节加 exit\n 的 5 个。rx_bytes 是设备模型自己的入口计数器,只在hyp_dev_pump_rx() 里、只在真的从 uart_try_getc() 拿到字节时递增,而 pump 只在 guest trap 上跑,所以宿主伪造不了它。这条门禁的判据本身不声称 guest 把它们读回来了——虽然当前实跑里 guest 确实走到了 shell 并把 roundtrip 打了出来(日志 630-631 行),判据没变;要断言"guest 读了"看第四条。

第四条门禁 smoke-hyp-shell(tools/smoke_cases.py:810-962,tools/mk/targets-smoke.mk:202-213) 是"guest 能进 shell 并且能交互"那条目标的验收点,第三条覆盖不到的那一半就是它。实跑 PASS(当前)。 它在第三条的rx_bytes 之外**另外**要求:guest 走到 shell 提示符、执行门禁敲进去的echo AAAABBBBCCCC 与 echo DDEEEEEEFFFF、把两个 token 打印回来、回到提示符,最后由 exit 触发 user/init.c:264-283 的 do_shutdown() 收尾。"字节进了环"和"guest 读了"是两条分开的断言——第三条只断言了第一条。当前实测:rx_bytes=41(两条 echo 加 exit 共 18+19+4 字节),两个 token 都在 guest 区原样回显,grep -cE 'SLAB BUG|KERNEL PANIC' = 0(日志 630-641 行,见上文"第五次")。它此前是红的,红点与根因也见"第五次";门禁本身一度还会因为死锁而假红(健康 guest 敲 exit 前不自退,原 steps 等 HYPVM: PASS 才发poweroff,实测 300 s 超时),已把 guest exit 加为独立一步(tools/smoke_cases.py)。逐行对账见 03-usage.md §3.4.2,路线图上的状态见 02-roadmap.md。

命令行入口的行前缀是 HYPVM:,不是 HYP_A20OS:。 本节与tools/smoke_cases.py 记的是硬编码装载器 user/cmds/core/hyp_boot.c 的HYP_A20OS: 前缀。带参数的 CLI 工具 hypvm 另起一套 HYPVM: 前缀的行,其参数、DTB 放置规则、输出逐行含义、限制与排查表见03-usage.md。门禁 smoke-hyp-a20os 断言的仍是装载器那条HYP_A20OS: PASS;hypvm 的判据行是 HYPVM: PASS。集成时若两者行文另有出入,以实现为准并回来改这两篇。

8.4 一条纪律

-cpu rv64,h=true 依然是承重件(与 v1 相同,见00-design.md §5.2)。默认 rv64 CPU 不暴露 H,hyp_supported()会让所有调用返回 NOT_SUPPORTED,于是 gate 变成"过了但什么都没测"。

本条在 QEMU 10.0.13 上没能复现,已实跑核对。 user/cmds/core/hypvm.c 的使用文档那一片跑了四组 -cpu(h=true / rv64 / 完全不写 / h=false):QEMU 10.0.13 的默认 rv64 已经带 H,去掉 -cpu 门禁照样过;而-cpu rv64,h=false **不是**得到 NOT_SUPPORTED,是宿主在 hyp_arch_vcpu_exit里 KERNEL PANIC——hyp_probe() 只读一次 hstatus 看会不会陷,而 QEMU 在h=false 下这个 CSR 照样可读。逐条数据与命令见03-usage.md §1.1。建议保留该参数(它把意图写进命令行,换一台默认不带 H 的 QEMU 时不会静默退化),但别把"去掉它门禁会红"当事实。


9. 与 Linux KVM 的设计差异

维度 KVM RISC-V 本设计
内存来源 用户态 KVM_SET_USER_MEMORY_REGION 登记 memslot,QEMU 侧维护 GVA→HVA 映射 guest 帧由**内核自己**按需分配,FRAME_F_GUEST 出借,mm_s2_audit 双向交叉检查
guest RAM 生命周期 memslot 是一段被 pin 的宿主内存,QEMU 持有 一组帧的集合,引用计数 + 身份标志;VM 死了没还帧,审计能抓到
记账 QEMU 进程 + cgroup(QEMU 进程作为 unit) guest 帧记在**宿主任务自己的 cgroup** 上(cg_mem_charge()),VM 没有独立预算身份
用户态接口 /dev/kvm ioctl + QEMU 的虚拟 CPU 抽象 Native ABI 的五个调用;Linux ABI 桥上的八个调用(VM/vcpu 用 pid 打标签的槽表,v2 又加了 set_boot / set_marker / status)
缺页处理 QEMU 的 userfaultfd / 缺页 ioctl 回调 内核态 hyp_ram_fill(),guest 自己分配什么就补什么
设备 QEMU 的完整设备模型(virtio、PCI、virtio-net…) 只有 16550 与 CLINT mtime,其余 RAZ/WI
vCPU 调度 vCPU 是可抢占的线程,有独立的定时器与调度类 一个全局单 guest 槽,spin_trylock 抢,输了回 -EBUSY

核心差别只有一条:KVM 把"这台机器长什么样"整体放在用户态,内核只提供 stage-2 机制;本设计把机器的形状收进内核,因为 stage-2 页表、帧标志与审计在单级内存模型里已经是一等公民,把它们拆到用户态会立刻失去审计。 代价是设备模型与多 vCPU 都要在内核侧重建,这正是 02-roadmap.md 里后几项的由来。

capability 叙事的正主在 02-roadmap.md 的 §3(零拷贝 VMO guest RAM):guest 的页不再由 hypervisor 分配,而是宿主 VMO 的一页被**借**进 stage-2。"出借"已经是 FRAME_F_GUEST 的语义,零拷贝只是把它从帧级推到 VMO 级。


10. 已知限制

  1. 单 vcpu。 全局槽 + trylock(kernel/hyp/hyp_vcpu.c:418)。guest 的 secondary 路径要 sbi_hart_start(),不在 v2 SBI 面里。
  2. 不注入外部中断。 —— 本条此前写的是"guest 的时钟中断与外部中断不会到来",前半句是错的,已更正。 hideleg 委托了 VS 级中断位(HYP_HIDELEG_DEFAULT = bit 2/6/10,kernel/include/hyp/hyp_vcpu.h:226-227,写的地方 kernel/arch/riscv64/hyp/hyp_arch.c:284),hstatus.VIE 在HYP_HSTATUS_GUEST_ON 里(hyp_arch.c:151,166-167,315),而 vstimecmp 到期置 mip.VSTIP 是 QEMU 的硬件行为(target/riscv/time_helper.c:25-30的 riscv_vstimer_cb();写 CSR 0x24d 挂上它的是 target/riscv/csr.c:1680-1692)。 V=1 时 hsie 恒 1(target/riscv/cpu_helper.c:585),被委托的 VS 位被重编号后交给 VS-mode(:617-634)。所以 guest 用 Sstc 时定时器中断是通的,两条入口本树都接上了:guest 自己写 CSR 0x24d 由虚拟指令路径仿真(kernel/arch/riscv64/hyp/hyp_emulate.c:622),或 guest 发 legacy set_timer 由分派器代写(hyp_vcpu.c:386-388)。

真正缺的是外部中断注入:hvip(CSR 0x646)与 hgeip/hgeie 在全树零引用(grep -rn 'hvip\|hgeip\|hgeie' kernel/ user/cmds --include=*.c --include=*.h --include=*.S 无输出),PLIC 没有模型(kernel/hyp/hyp_dev.c:472-477 把非 UART/CLINT 页 RAZ/WI 并按页计数,hyp_dev_note_unknown() 在 :100-112), UART 的 IIR 恒回"无中断待处理"(hyp_dev.c:71-76,286)。规格 norm:hip_vseip_vstip_acc_op 那两条 OR 来源里,vstimecmp 那一半在位,hgeip/hvip 那一半没有。

后果:单 vcpu、无 PLIC、无 IPI 的启动冒烟能在有 tick 的情况下跑完(前提是启动路径不依赖 tick),而任何依赖**外部**中断推进的 guest 行为(PLIC 配置完成后的外设中断、guest 之间的 IPI)现在做不了。这条是"中断虚拟化"整件事,属于02-roadmap.md §2。当前尚未对 guest 侧的定时器抢占路径进行针对性实测验证。 3. 无 guest 页保护。 窗口页一律 RWX。guest 之间的隔离要等 vmid 侧的真隔离语义才有意义,而本设计一次只跑一个 guest。 4. GPA 上限 512 GiB。 hgatp 是 Sv39x4 但只编程根表 [0,512)(kernel/include/hyp/hyp.h:26-30)。见 02-roadmap.md 的 x4 根表项。 5. VMID 只增不重用(hyp.h:26-30 与 hyp_arch.c:50-54):宽度是 WARL,环绕是文档化限制。 6. 设备模型是寄存器级的,不是 virtio 的。 这直接决定了 PASS 的定义只能是"到达 banner"而不是"引导完成"(§8.3)。但"guest 挂不上 rootfs"这句话要分情况:RAMFS_USER=0(默认,Makefile:111)镜像的根 ramfs 里没有 /bin/init,init_kthread() 会 panic("init: no init program found")(kernel/main.c:352,361);RAMFS_USER=1 镜像则把 init、sh(BusyBox)、ls、cat、ps 等直接嵌进内核 ramfs,那种 guest 不需要块设备也能起 init。门禁 smoke-hyp-a20os 的构建变量是RAMFS_USER=0(tools/smoke_cases.py:630),所以对门禁而言原话成立。RAMFS_USER=1 的 guest 支持完整独立引导:make smoke-hyp-console 与 make smoke-hyp-shell 基于该配置构建(HYPVM: guest=/bin/boot/guest-kernel-ramfs.elf),可直接执行至交互式 shell 并通过命令交互验收(§8.3 第五次)。真 rootfs(读镜像上的文件、持久写)仍然要 virtio-blk,属于02-roadmap.md。guest 的 virtio-blk 是内核内驱动—— kernel/drvmod/examples/virtio_blk.c 只是 #include 了kernel/drivers/block/virtio_blk.c 的 16 行注册壳(components/drivers.toml:20-24 把它登记成 early .a20drv,kernel/arch/riscv64/platform/early_drivers.c:33 从 /boot/drivers 加载),不存在"guest 的 virtio 驱动是用户态程序"这回事。 7. R|W|X 叶页依赖 QEMU 的具体行为 —— 已推翻并修正,见00-design.md §5.3 第 3 条。 原结论说 W 与 X 同时置位在叶 PTE 里是保留组合、G-stage 走查直接拒;QEMU 10.0.13 的 get_physical_address() 只特判rwx==6(W|X)与 rwx==2(W),rwx==7(R|W|X)落到PAGE_READ|PAGE_WRITE|PAGE_EXEC,正常翻译。工作树按HYP_RAM_PAGE_PROT (PTE_R|PTE_W|PTE_X) 装 guest RAM。本条此前还写着"vendored 的 QEMU 树里没有 target/ 目录,无法核对"—— 该目录存在(/tmp/qs/qemu-10.0.13/target/),核对方式是读target/riscv/cpu_helper.c。 8. smoke-hyp-a20os 已经跑过,PASS。 本条此前写的是"本文写作时尚未运行,本文关于 v2 行为的一切描述都是推演"。运行结论与逐行日志见03-usage.md §3.3(smoke-hyp-a20os 与手工 hypvm 两次真跑, guest 侧结果逐字段相同)。仍然只验到 banner 一层,banner 之后的事见 §10 第 9 条。 9. 同一宿主的重复双 guest 已通过本轮验收。 2026-11-16 修复 RUN 寄存器恢复、EEVDF、线程组停止/继续、虚拟 UART 等问题后,同一宿主完成双 VM × 双 vCPU 的 100 次完整生命周期;管理进程 5 ms 睡眠审计最大耗时 139 ms,门限 150 ms。历史超时与回退行为记录完备,详见当前验证说明。smoke-hyp-vm 与 smoke-hyp-vm-96 仍使用各自的 QEMU 启动作为独立冒烟。


11. 用户入口:hypvm

/hyp_boot(user/cmds/core/hyp_boot.c)是这套引导的**门禁**:所有参数编译期写死,因为 smoke-hyp-a20os 按它打印的字面行判定(§8.3)。它不适合当工具——想在 shell 里换一台 guest 的内存大小都做不到。

/hypvm(user/cmds/core/hypvm.c)是同一套引导的**用户入口**:ELF 路径、 RAM 窗口、guest 的 bootargs、marker、入口 GPA 全部来自 argv,默认值逐个等于hyp_boot 的编译期常量,所以裸跑 hypvm 和 hyp_boot 引导的是同一台机器。两者共用的机械部分(ELF 装载、最小 FDT、八个系统调用的包装)提炼在user/cmds/core/hyp/hyp_guest.c;它只返回结果、不打印,所以两个程序各自的措辞互不牵连。

怎么用(命令行、输出行逐行含义、排查)见03-usage.md。 本节只留三件属于设计记录的事。

11.1 FDT 放在窗口顶部,而不是固定地址

hyp_boot 把 DTB 写死在 0x87f00000,那个数只对 128 MiB 的窗口成立:窗口一小,它就落进 guest 镜像里,而 entry.S 在读 a1 之前用自己的 la 指令清 bss,会把它擦掉(§7.2、§7.4 的两条约束同时发作)。hypvm 因此从窗口顶端往下留 1 MiB 放 FDT(hypvm.c:300),并在它与镜像重叠时报错而不是硬塞。默认值下算出来的地址恰好还是 0x87f00000,所以"参数化的工具"和"写死的门禁"在默认配置下引导的是同一台机器——这正是 smoke-hyp-vm 要断言的东西。

-g 还多两条约束,因为 §7.4 那条硬约束对用户是可见的:基址必须页对齐(hyp_vm_load() 整页取),且整个窗口必须落在 entry.S 铺的 16 GiB identity 映射里,否则 __boot_dtb_ptr 在 guest 装上 satp 之后就不是可解引用的指针。

11.2 判据不变,措辞可变

hypvm 的 PASS 判据与 hyp_boot 同款且只有两条:marker 命中(设备模型只在 guest 控制台字节上匹配,排除宿主同名输出干扰),以及 console_bytes 大于 marker 长度。exit= 与 PASS 判定规则:门禁判据以 marker 识别为核心,只要 guest 抵达指定 banner 即满足 PASS 条件;exit= 记录最终退出状态(可能为 normal shutdown、guest panic 触发的关机或 fault)。RAMFS_USER=0 镜像因无 /bin/init 会在进入 init_kthread 时主动 panic 关机;而 RAMFS_USER=1 配置则可继续进入完整用户态 shell。相关排查细节参见 03-usage.md §4.3 与 02-roadmap.md §4。hyp_boot 的字面输出被 smoke-hyp-a20os 按固定模式匹配;hypvm 的 PASS 行带上窗口大小以区分不同参数的运行。

11.3 门禁是两个,不是一个

smoke-hyp-vm 跑一次裸 hypvm(默认参数),smoke-hyp-vm-96 跑hypvm -m 96 -b ...;两条期望行都锚在各自报告的窗口大小上,否则一条HYPVM: PASS 的 grep 会被任何一次运行满足,等于没测出参数有没有生效。第二个门禁为什么必要,就是 §11.1:窗口不是 128 MiB 时固定 DTB 地址必错。

是两次 QEMU 启动,不是一个门禁里的两行命令:§10 第 9 条,同一会话里第二次 guest 引导不回来。把两行塞进一个门禁只会得到一个必红的门禁。

-cpu rv64,h=true 依然是承重件(§8.4)。没有 H 时内核对每个调用回 ENOTSUP,hypvm 把它单独报成 HYPVM: FAIL vm_create ... 并以退出码 4 结束,而不是伪装成一次引导尝试。