跳转至

Hypervisor 使用指南

本文说明 A20OS Hypervisor 的多架构使用与验证流程。从仓库根目录执行开发机命令;标注“A20 宿主 shell”的命令在启动后的 A20OS 中执行。先用无 rootfs 的内核测试确认后端可用,再按需构建用户态或 RISC-V 完整 guest 环境。RISC-V 架构下统一实现与验收参见 RISC-V SBI 增补。

1. 支持范围与前提

A20 宿主架构 / 后端 必要条件 guest 初始模式 / RAM 基址 本地验收
riscv64 / H H、Sstc,firmware 开放 STCE VS,0x80000000 QEMU,2 vCPU
riscv32 / H H、Sstc,firmware 开放 STCE RV32 VS,0x80000000 QEMU,2 vCPU
aarch64 / EL2 启动时拥有 EL2,MMU 配置 AArch64 EL1h,0x40000000 QEMU,2 vCPU
arm32 / HYP ARMv7 virtualization,启动时拥有 HYP ARM SVC,0x40000000 QEMU Cortex-A15,2 vCPU
x86_64 / AMD SVM SVM、NPT,firmware 未设置 SVMDIS flat32 CPL0,0x100000 QEMU TCG / AMD KVM,2 vCPU
x86_64 / Intel VMX VMX、EPT、unrestricted guest、INVEPT、preemption timer,firmware 允许 VMX flat32 CPL0,0x100000 Bochs 软件 CPU,2 vCPU
loongarch64 / LVZ 实验 LVZ v1、8 个 scratch CSR、MATP_ROOT、显式实验参数 整数 guest,0x80000000 仅编译与无 LVZ 回退验证

同一 ISA 的宿主与 guest 配对;没有跨 ISA guest 执行。ARM 后端需要启动阶段保留的 monitor,不能在已由其它 hypervisor 占用 EL2/HYP 的环境中直接启用。CONFIG_NOMMU 不提供这些原生二级页表后端。

RV64 的完整 A20OS RAMFS guest 和管理器有独立运行路径。ARM/x86/RV32 当前验收载荷为小型 guest 指令程序,没有覆盖完整 Linux、Windows 或 A20OS SMP guest 引导。VMX 在 Bochs 软件 CPU 上验证;LoongArch 尚未在真实 LVZ 硬件上执行。当前也没有 A20 /dev/kvm 兼容层,不能据此在 A20 内直接运行 QEMU/KVM。详见 后端说明 和 验证范围。

1.1 开发机依赖

通用构建依赖按 构建指南 准备,包括 Python 3.11+、GNU make、仓库配置的 Rust 工具链与所选架构 GCC/binutils。编译器常见名称:

架构 编译器 外层模拟器
riscv64 riscv64-unknown-elf-gcc 或仓库识别的 RISC-V ELF 工具链 qemu-system-riscv64
riscv32 带 RV32 multilib 的 RISC-V ELF 工具链,或 RV32 交叉编译器 qemu-system-riscv32
aarch64 aarch64-linux-gnu-gcc qemu-system-aarch64
arm32 arm-linux-gnueabihf-gcc qemu-system-arm
x86_64 x86_64-linux-gnu-gcc qemu-system-x86_64;VMX 用 Bochs
loongarch64 loongarch64-linux-gnu-gcc qemu-system-loongarch64,仅无 LVZ 回退验证

内核测试不需要磁盘镜像、rootfs、GUI 或 root 权限。完整宿主镜像还需要qemu-img、mtools、dosfstools、e2fsprogs、xorriso 等镜像工具。KVM 验证需要开发机能访问 /dev/kvm,并向外层 A20 虚拟机暴露嵌套 SVM/NPT;当前 KVM 验证环境基于 AMD 平台。RISC-V 测试使用 QEMU 自带的默认 OpenSBI;已验证版本为 QEMU 10.0.13 / RV32 OpenSBI 1.6,旧 firmware 若不开放 STCE 会被拒绝。

2. 最快运行:不依赖 rootfs 的内核测试

以下每条命令从当前源码构建新内核,再启动、检查结果并等待模拟宿主关机。默认 KERNEL_WERROR=1。--cpus 2 同时设置构建的 NR_CPUS=2 和模拟 CPU 数量,并开启双 guest vCPU 测试;省略时为单 CPU。

python3 tools/qemu/check_hyp_multiarch.py --arch aarch64 --cpus 2 --build
python3 tools/qemu/check_hyp_multiarch.py --arch arm32 --cpus 2 --build
python3 tools/qemu/check_hyp_multiarch.py --arch riscv32 --cpus 2 --build
python3 tools/qemu/check_hyp_multiarch.py --arch riscv64 --cpus 2 --build
python3 tools/qemu/check_hyp_multiarch.py --arch x86_64 --cpus 2 --build --accel tcg
# 下面一项只用于可暴露嵌套 SVM 的 AMD KVM 开发机:
python3 tools/qemu/check_hyp_multiarch.py --arch x86_64 --cpus 2 --build --accel kvm

Intel VMX 的实际执行命令见第 3 节。当前 QEMU runner 的 x86 虚拟化启用测试默认按 SVM 检查后端名称;不能直接将其 KVM 选项当作 Intel VMX 的验收入口。

禁用虚拟化扩展的异常/回退测试对上述每个架构加 --without-virtualization:

python3 tools/qemu/check_hyp_multiarch.py --arch arm32 --cpus 2 --build --without-virtualization
python3 tools/qemu/check_hyp_multiarch.py --arch riscv32 --cpus 2 --build --without-virtualization
# LoongArch 本地仅支持此项,runner 会在 UART 提示后发送显式 LVZ 实验参数:
python3 tools/qemu/check_hyp_multiarch.py --arch loongarch64 --cpus 2 --build --without-virtualization

禁用测试中 ARM 关闭 virtualization,RISC-V 设置 h=false,x86 关闭 SVM/VMX。LoongArch TCG 本身不包含 LVZ;该选项验证显式 opt-in 依然受到严格的硬件能力检查保护。成功的回退测试应打印 HYP_ARCH_TEST: SKIP (backend unavailable) 并正常关机。

2.1 参数、产物与启动参数

runner 参数 用途
--arch ARCH 选择上表中的架构
--build 用 BRINGUP=1 NR_CPUS=N kernel-only 构建;与 --kernel 二选一
--kernel PATH 运行已有镜像;调用者保证它与当前源码及 CPU 数量一致
--cpus 1 / --cpus 2 单核生命周期 / 双核并行会合测试,默认 1
--jobs N 构建并行数,默认 8
--accel tcg / --accel kvm 默认 TCG;KVM 仅开放给 x86 runner
--without-virtualization 要求 SKIP 和关机,出现正常 guest PASS 会判失败
--timeout SEC 模拟器运行超时,默认 90 秒,不包括编译
--log PATH 指定运行日志位置;默认在 .kernel-build/smoke/

构建日志为 .kernel-build/smoke/hyp-ARCH-build.log。运行日志例如hyp-arm32-smp-tcg.log、hyp-x86_64-smp-kvm.log,禁用测试日志增加 -disabled。构建输出中的 Kernel-only build complete: 给出实际镜像路径,不要假定所有构建配置共享同一个内核文件。

ARM32/AArch64 必须给 runner 传 kernel.bin,使 QEMU 按 raw Linux handoff 提供 DTB 与 bootargs;RV32/RV64/x86 使用 kernel.elf。LoongArch 构建额外设置 UART_CMDLINE=y,runner 等待 UART command prompt 后发送参数。

手动 QEMU 引导时需设置 a20.hyp_test=1;双核再加 a20.hyp_smp=1,并保证构建与 -smp 都为 2。例如:

make ARCH=arm32 BRINGUP=1 NR_CPUS=2 kernel-only -j8
# 将 PATH 换成上一步打印的实际路径:
qemu-system-arm -machine virt,virtualization=on -cpu cortex-a15 -accel tcg \
  -m 1G -nographic -smp 2 -kernel PATH/kernel.bin \
  -append 'a20.hyp_test=1 a20.hyp_smp=1'

AArch64 改用 qemu-system-aarch64 与 cortex-a57。RISC-V 使用-machine virt -cpu rv32,h=true / rv64,h=true 和 -bios default。 x86 的 QEMU 引导还需通过 -fw_cfg name=opt/x86/cmdline,string=... 传入相同参数,优先使用 runner 避免漏项。测试选项是精确匹配的独立 boot token,普通启动不设置这些参数就不会自动执行该测试。

2.2 如何判断通过

以 ARM32 双核启用测试为例,关键输出应同时存在:

HYP_SELFTEST: PASS (vmid=0 entries=9)
HYP_ARCH_TEST: NX+RO PASS
HYP_ARCH_TEST: preemption+stop PASS
HYP_ARCH_TEST: PASS backend=arm32-hyp rounds=3
HYP_SMP_TEST: ready peak=2
HYP_SMP_TEST: PASS backend=arm32-hyp cpus=0,1 peak=2 step=stopped
System is going down for power-off NOW

entries 因页表格式而异,不应硬编码为 9。三轮 guest 输出 HYP 并请求关机,同时检查第二页按需补页和内容读回。NX/RO 让真实 guest 取指/写入失败,要求 FAULT 且只读数据不变。除 RV64 尚无对应 spin payload 外,测试还要求屏蔽中断的无限循环被宿主抢占,并能成功 STOP。

SMP 不是串行运行两次:两个固定到不同宿主 CPU 的 worker 各调用一个 vCPU 的 RUN,guest 各写 ready 后等待宿主 release;控制器必须观察到两个 ready 和并发 RUN 峰值 peak=2,才释放两个 guest 并等待 CPU_OFF。最后要求 VM/vCPU/映射/页表计数回到基线。测试由宿主调用 hart_start 启动次 vCPU; guest CPU_ON/HSM 包装已实现,作为后续演进路径。

runner 检查所需 PASS、宿主关机、进程返回值和 FAIL/PANIC 标记,返回 0 才算通过。只看到启动 banner、HYP 或 SKIP 不能作为完整执行通过的依据。

3. Intel VMX:使用 Bochs 实际执行

本地 AMD 开发机不能用 KVM 执行 Intel VMX,QEMU TCG 也不实现 VMX。可从上游 Bochs 3.0 构建带 VMX、SMP 与 debugger 的软件 CPU。准备 C/C++ 编译器、 make、curl 与 tar,在自行选择的临时构建目录执行:

curl -L https://github.com/bochs-emu/Bochs/archive/refs/tags/REL_3_0_FINAL.tar.gz -o bochs.tar.gz
tar xf bochs.tar.gz
cd Bochs-REL_3_0_FINAL/bochs
./configure --enable-vmx=2 --enable-smp --enable-x86-64 --with-nogui \
  --disable-docbook --enable-debugger --enable-disasm
make -j8

回到 A20OS 仓库根目录构建并执行;替换两个 PATH:

make ARCH=x86_64 BRINGUP=1 NR_CPUS=2 kernel-only -j8
python3 kernel/arch/x86_64/hyp/check_vmx_bochs.py \
  --bochs-dir PATH/Bochs-REL_3_0_FINAL/bochs --kernel PATH/kernel.bin \
  --cpus 2 --output .kernel-build/vmx-bochs
python3 kernel/arch/x86_64/hyp/check_vmx_bochs.py \
  --bochs-dir PATH/Bochs-REL_3_0_FINAL/bochs --kernel PATH/kernel.bin \
  --cpus 2 --without-virtualization --output .kernel-build/vmx-bochs-disabled

这里必须使用 kernel.bin,由 BIOS、最小 Multiboot loader 和 debugger 装载;无需 GRUB/rootfs。runner 分 4 KiB 装载以避开上游 Bochs 3.0 loadmem 多块地址递增问题,没有修改模拟器 CPU 实现。--timeout 默认 120 秒。成功后端名为 x86-vmx,仍要求三轮生命周期、NX/RO、抢占/STOP 和 SMP。日志 serial.log、bochs.log、console.log 及配置保存在 --output 下。 Bochs 的 ACPI 关机可能返回 1,runner 根据完整标记和关机记录裁决。这是 VMX/EPT 指令的软件 CPU 执行证据,没有测得 Intel 实机性能或稳定性。

4. A20 宿主 shell:运行用户态最小 guest

内核测试无需用户态。要运行 syscall 路径,还需构建包含 /bin/hyp_test 的 Linux/both ABI 完整 A20 宿主镜像并启动到 shell,参照通用构建指南。单独编译这个命令可用:

make -C user ARCH=arm32 build/arm32/hyp_test -j8
make -C user ARCH=riscv32 build/riscv32/hyp_test -j8
make -C user ARCH=aarch64 build/aarch64/hyp_test -j8
make -C user ARCH=x86_64 build/x86_64/hyp_test -j8

A20 宿主 shell 执行 hyp_test。它创建 VM、装入相同 ISA 的小型载荷、运行至 shutdown,检查输出计数并销毁。通过标记为 HYP_VCPU_TEST: PASS。 x86 根据 SVM CPUID 选择 VMMCALL 或 VMCALL;ARM 使用 HVC。hyp_test echo仅有 RISC-V UART 载荷,消耗宿主输入中的三个字节,避免用在共享交互输入上。四架构命令均已编译链接;多架构 syscall 端到端全量运行仍在持续收敛。

用户态公共包装在 user/cmds/core/hyp/hyp_guest.h,Native 和 Linux 扩展 ABI 最终调用同一内核 VM/vCPU 核心。Linux 扩展编号在kernel/include/core/syscall_nr.h;Native 使用自己的 handle/权限表,不能把 Linux 编号直接用于 Native 调用。

4.1 编写 VMM 与 SMP 调用顺序

  1. 探测后端,创建 VM;内存大小非零且按 4 KiB 对齐,受后端 GPA 范围限制。默认 RAM 基址见第 1 节,ELF/FDT 装载器不能继续硬编码 RISC-V 地址。
  2. 多 vCPU 在创建 vCPU 前调用 hyp_guest_vm_smp(vm, count);内核对应hyp_vm_configure_smp。同时启用 managed console,分别处理每 VM 的 console_read/write,避免 legacy console 的单 runner 约束。
  3. 通过 vm_load 装入 guest 程序/引导数据,再按 id 创建 vCPU 和设置启动寄存器。同一 vCPU 的 RUN 不可并发;每个运行线程持有自己的 vCPU 引用。
  4. 一个宿主线程运行一个 vCPU,根据返回原因处理 I/O、让出调度或等待重启。次 vCPU 初始停止,经对应 ISA 的 HSM/PSCI/显式启动 ABI 激活。
  5. 销毁前 STOP 所有 runner,等待线程退出,释放全部 vCPU 和 VM 引用。 STOP 与 guest CPU_OFF 不同:后者是可再次启动的 hart 停止状态。

公共 VM 上限 HYP_MAX_VCPUS=8,实际并发数还受后端和宿主 CPU 配置限制;当前实测验证并发数为 2。增加 NR_CPUS 或传更多 vCPU 参数不构成有效验证。

RUN 返回原因 VMM 处理
YIELD 可恢复;处理 I/O/调度后再次 RUN
PAUSED 等待控制器恢复
HART_STOPPED 等待 CPU_ON/HSM 启动,不能误作整台 VM 关机
SHUTDOWN 停止其它 runner 并回收该 VM
STOPPED 控制器已取消运行,结束 runner
FAULT / ERROR 保存 PC、cause、stval、htval 等诊断后停止并回收

C API 返回错误与 guest FAULT 是两层结果。EBUSY 表示更新与运行或同 vCPU RUN 冲突,不应忙循环;让出调度并协调持有者。native stage-2 只允许并行新增映射,替换已有叶子返回 EEXIST;远端 vCPU 活跃时 unmap 返回 EBUSY。先停止相关 vCPU,再修改映射并回收 backing。内核调用者的 guest 执行权限用HYP_PROT_EXEC,ARM32 不可用宿主 PTE_X=0 代替。

各 ISA 的 reset 寄存器、hypercall、支持的 CSR/MSR 和设备范围分别见ARM32、AArch64、RV32、x86。

5. 完整 RISC-V A20OS guest 与多 VM 管理

hypvm、hyp_boot、guest ELF/FDT 装载器和 a20-vmd 的完整 OS 工作流仍面向 RV64。它们没有随硬件后端自动获得 ARM/x86 完整 OS 引导能力。

tools/a20 build hyp-host-riscv64 -- -j4
tools/a20 run hyp-host-riscv64 --name lab --detach --no-build
tools/a20 attach lab

该模板使用 ABI=both、1 CPU、1 GiB RAM、TCG,显式启用 H/Sstc,打包 RAMFS guest 和用户程序。命名运行有独立磁盘 overlay、宿主 UART 与管理 socket,应看到 A20VMD: READY protocol=2。Ctrl-] 断开控制台后宿主继续运行。

tools/a20 vm start a20-ramfs-riscv64 --host lab --name guest-a
tools/a20 vm start a20-ramfs-riscv64 --host lab --name guest-b
tools/a20 vm list --host lab
tools/a20 vm console guest-a --host lab

另一个终端连接 guest-b。等待实际 shell 提示符后执行命令;START accepted 只代表接受请求,不能代替 console/list 中的启动结果。默认 guest 为 128 MiB、 1 vCPU、仅 RAMFS,无磁盘和网络。控制与清理命令:

tools/a20 vm pause guest-a --host lab
tools/a20 vm resume guest-a --host lab
tools/a20 vm stats --host lab
# 正常结束:在 guest shell 输入 exit,等 list 显示 exited 后:
tools/a20 vm destroy guest-a --host lab
# 对另一台尚在运行的 guest,可先强制停止再等退出:
tools/a20 vm stop guest-b --host lab
tools/a20 vm list --host lab
tools/a20 vm destroy guest-b --host lab
tools/a20 stop lab
tools/a20 destroy lab

资源不足时 runner 会等待,可通过 A20_WAIT_TIMEOUT=60 和A20_PREFLIGHT_TIMEOUT=60 限定等待时间。外层 stop 退出整个 QEMU;destroy 删除停止实例的临时磁盘和运行目录,先保存需要的 guest 数据。完整管理约束、传输协议和控制台重连见 宿主运行目录 与guest supervisor。

在 A20 shell 也可运行:

hypvm --managed -k /bin/boot/guest-kernel-ramfs.elf -m 128
hypvm --help

并行进程需独立 stdin/stdout 管道或 PTY。仓库保留hyp-host-riscv64-smp2 与 a20-ramfs-riscv64-smp2 实验 profile,必须构建匹配的 SMP 宿主与 guest 内核。小型载荷 SMP 通过不代表完整 RV64 OS guest 的 trap frame 边界全部收敛,不能据此将这些 profile 的完整 OS SMP 标为已验收。

双 guest 真实场景检查:

python3 tools/probes/hyp_pair_probe.py --host lab --timeout 120 --report /tmp/a20-pair/report.json

它检查 shell 命令、控制台隔离、重连、暂停隔离、正常退出、记录销毁和计数基线;证据属于独立完整 guest 场景,单次通过不代表重复运行或长稳稳定。

6. LoongArch 实验开关

LoongArch 后端默认不可用,未来 LVZ 硬件实验需显式传a20.lvz_experimental=1,且所有硬件能力检查通过。开关不会模拟缺失的 LVZ。本地仅执行第 2 节禁用回退测试,当前 runner 会拒绝在不支持 LVZ 的环境下执行该测试。

实现含整数/GCSR bank、原生 GPA root、entry/exit、HVCL 小载荷和公共 SMP 接线;guest FP/vector/LBT、guest timer、完整设备/OS 启动未实现,真实 LVZ 下的隔离、抢占和 SMP 均未验收。部署实验前阅读LoongArch 后端。

7. 常见问题与复测

现象 检查方法
编译器不存在 / RV32 ABI 不匹配 检查第 1 节工具链、RV32 multilib 和构建指南;保留 build log
没有 HYP 测试行 是否传精确 boot token;ARM 是否 raw bin;Loong 是否 UART 命令行构建
正常测试打印 SKIP / 创建返回 errno=95 查 H/Sstc/STCE、EL2/HYP handoff、SVM/NPT 或 VMX 所需能力;关闭扩展的禁用测试应打印 SKIP
ARM 单核能启而双核卡住 构建 NR_CPUS、QEMU -smp 与 runner --cpus 是否一致;宿主是否观察到两个 online CPU
SMP ready 超时 / peak=1 检查 worker affinity、managed console、次 vCPU 状态及最后的 PC/cause;保留完整日志
KVM 不可用 检查 /dev/kvm 访问和嵌套 SVM;可用 TCG 验 SVM、Bochs 验 VMX
guest 立即 FAULT 检查 ISA、初始模式、entry/RAM 基址、执行权限、hypercall 与支持的设备;不要按完整 PC/virt 机型假定设备齐全
manager 找不到 查看宿主日志是否 READY,模板是否 vm_manager=true、是否命名运行;guest console 与宿主 attach 不同
管理请求超时 保存宿主/guest 日志;stop guest 无法恢复时退出外层宿主再重建

无需模拟器的相关检查:

python3 -m unittest tools.tests.test_hyp_s2 tools.tests.test_hyp_backend_contract \
  tools.tests.test_arch_boundary tools.tests.test_a20_trim -v
make check-trim-registry

实际测试结果、最终镜像/日志 SHA-256 和尚未覆盖的物理板、虚拟中断控制器、完整 OS SMP、长稳范围见 验证记录。构建缓存与运行日志在 .kernel-build/,确认没有正在使用的进程并保存所需证据后,可删除自行创建的测试输出目录;无需删除其它实例、worktree 或开发任务的缓存。