Asterinas on hvisor 适配与验证

目标：在 hvisor Type-1 Hypervisor 的 x86_64/QEMU 非 root zone 中启动 Asterinas，并验证 CPU/内存初始化、virtio-mmio console/net/blk、virtio-blk completion IRQ、基础系统调用与挂载流程。

1. 成果摘要

本项目完成了 Asterinas 在 hvisor x86_64/QEMU 虚拟化环境中的基础启动适配，并验证 virtio-mmio 设备发现与 virtio-blk 读请求/中断完成路径。

当前关键成果：

Asterinas 能作为 hvisor zone1 启动。
Asterinas 能从 kernel command line 发现 3 个 virtio-mmio 设备。
hvisor-tool virtio-blk backend 能处理读请求。
Asterinas 能收到 virtio-blk completion IRQ。
最新复现日志中 panic=0、ERROR=0。

仓库	PR	状态	作用
Asterinas	asterinas/asterinas#3401	已合并	x86 支持 `virtio_mmio.device=` 命令行发现
hvisor	syswonder/hvisor#355	CI 通过	Asterinas zone 配置、CPUID 0x15、non-root IOAPIC 目标 CPU 映射
hvisor-tool	syswonder/hvisor-tool#104	CI 通过	virtio-blk config 初始化与 blk_size 修复

2. 系统架构

flowchart TB
    subgraph QEMU["QEMU x86_64/q35"]
        subgraph Z0["hvisor root zone: Linux"]
            HVKO["hvisor.ko"]
            HTOOL["hvisor-tool\nzone/virtio control"]
            VCON["virtio-mmio console backend"]
            VNET["virtio-mmio net backend"]
            VBLK["virtio-mmio blk backend\nrootfs2.img"]
        end
        subgraph HV["hvisor Type-1 Hypervisor"]
            IOAPIC["virtual IOAPIC"]
            CPUID["CPUID virtualization\nleaf 0x15/0x16"]
            MEM["stage-2 memory mapping"]
        end
        subgraph Z1["zone1: Asterinas"]
            AK["Asterinas kernel"]
            VIRTIO["virtio-mmio bus"]
            BLKDRV["virtio-blk driver"]
            INIT["initramfs / user init"]
        end
    end

    HTOOL --> HVKO
    HTOOL --> VCON
    HTOOL --> VNET
    HTOOL --> VBLK
    HVKO --> HV
    HV --> Z1
    CPUID --> AK
    MEM --> AK
    IOAPIC --> BLKDRV
    VCON <--> VIRTIO
    VNET <--> VIRTIO
    VBLK <--> BLKDRV
    AK --> INIT

3. 启动流程

sequenceDiagram
    participant User as User/root-zone shell
    participant Tool as hvisor-tool
    participant HV as hvisor
    participant AST as Asterinas zone1
    participant BLK as virtio-blk backend

    User->>Tool: insmod hvisor.ko
    User->>Tool: hvisor virtio start virtio_asterinas_cfg.json
    Tool->>BLK: create console/net/blk backends
    User->>Tool: hvisor zone start zone1_asterinas.json
    Tool->>HV: create non-root zone1
    HV->>AST: load boot.bin/setup.bin/vmlinux.bin/initramfs
    AST->>AST: OSTD/kernel init
    AST->>AST: parse virtio_mmio.device cmdline
    AST->>BLK: submit virtio-blk read request
    BLK->>HV: inject completion IRQ
    HV->>AST: translate guest-local APIC id to zone CPU and inject vector
    AST->>AST: handle blk IRQ, continue mount/init

4. 资源配置

4.1 CPU / 内存

资源	配置
zone id	1
zone name	`asterinas`
CPUs	2, 3
low memory	`0x0` 起映射到 root-zone physical `0x40300000` 附近
high memory	`0x100000000` 起，大小 `0x70000000`
kernel image	`/asterinas/vmlinux.bin`
initramfs	`/asterinas/initramfs.cpio`

4.2 virtio-mmio

设备	MMIO base	size	hvisor-tool IRQ	Asterinas 发现到的 IRQ	作用
console	`0x5950f000`	`0x200`	10	35	hvc console
net	`0x5950f200`	`0x200`	14	36	网络设备
blk	`0x5950f400`	`0x200`	11	37	`rootfs2.img` 块设备

Asterinas kernel command line：

console=hvc0 \
virtio_mmio.device=0x200@0x5950f000:10 \
virtio_mmio.device=0x200@0x5950f200:14 \
virtio_mmio.device=0x200@0x5950f400:11

5. 核心改动

5.1 Asterinas

Asterinas 侧通过上游 PR #3401 支持 x86 下从 kernel command line 解析：

virtio_mmio.device=<size>@<base>:<irq>

这使 Asterinas 不依赖 device tree，也能在 hvisor x86 zone 中发现 virtio-mmio console/net/blk。

5.2 hvisor

hvisor 侧补充：

zone1_asterinas.json 与 virtio_asterinas_cfg.json；
CPUID leaf 0x15，给 guest 暴露 TSC/crystal clock ratio，避免 guest 依赖 PIT 校准；
non-root zone virtual IOAPIC IRQ destination 修复：当 guest 使用 guest-local APIC ID 0,1,... 编程 IOAPIC RTE 时，将其映射到 zone 的实际物理 CPU 集合。

关键 patch：deliverables/patches/0001-hvisor-support-asterinas-x86-guest.patch

5.3 hvisor-tool

hvisor-tool 侧补充：

virtio-blk BlkDev 使用 calloc 初始化，避免未初始化字段；
virtio-blk config 设置默认 blk_size = 512；
清理与当前 zone config 不匹配的 PCI virtual BDF 字段解析。

关键 patch：deliverables/patches/0002-hvisor-tool-support-asterinas-virtio-blk.patch

6. 复现步骤概要

完整 quick-start 已附在 hvisor PR 评论：

Quick-start guide comment

最小流程：

# 1. build hvisor
cd hvisor
make defconfig ARCH=x86_64 BOARD=qemu
make ARCH=x86_64 BOARD=qemu MODE=release

# 2. build hvisor-tool
cd ../hvisor-tool
make ARCH=x86_64 LOG=LOG_INFO KDIR=/path/to/linux-or-linux-headers

# 3. deploy hvisor-tool, configs, rootfs2.img and Asterinas artifacts into rootfs1.img
# 4. start root-zone
cd ../hvisor
make ARCH=x86_64 BOARD=qemu MODE=release run

# 5. in root-zone shell
./start_asterinas_hvisor.sh

root-zone 内启动脚本：

#!/bin/sh
set -x
cd /
insmod ./hvisor.ko || true
./hvisor virtio start ./virtio_asterinas_cfg.json &
sleep 3
./hvisor zone start ./zone1_asterinas.json

7. 启动日志截图

7.1 验证统计

Validation summary

7.2 Asterinas 入口与 OSTD 初始化

Asterinas startup

7.3 virtio-mmio 设备发现

virtio-mmio devices

7.4 virtio-blk 请求和 completion IRQ

virtio-blk irq

完整日志：deliverables/assets/logs/hvisor-asterinas-autostart.log

8. 最新验证结果

最新日志关键计数：

Entering the Asterinas                         1
OSTD initialized                               1
Found MMIO device                              3
spawn the virtio-block thread                  1
Handle Request                                 37
block device handle IRQ                        37
All components initialization completed        1
SYS_MOUNT                                      6
panic                                          0
ERROR                                          0

结论：Asterinas 在 hvisor zone1 中完成内核入口、OSTD 初始化、virtio-mmio 设备发现、virtio-blk 读请求与 completion IRQ 路径验证。

9. 目录索引

方案文档：deliverables/docs/方案文档.md（英文文件名副本：deliverables/docs/solution.md）
关键 patch：deliverables/patches/
关键源文件快照：deliverables/source-snapshot/
日志截图：deliverables/assets/
完整启动日志：deliverables/assets/logs/hvisor-asterinas-autostart.log