hvisor build and benchmark workspace

本仓库是统一的 Cargo workspace，同时提供 hvisor-build 和 hvisor-bench 两个命令。hvisor-build 负责可复现构建、发布产物、运行和验证虚拟机； hvisor-bench 负责 Asterinas 在 QEMU 与 hvisor 上的对照测量和统计报告。

Workspace 结构

.
├── Cargo.toml                  # virtual Cargo workspace
├── Cargo.lock                  # 所有 package 共用的依赖锁
├── crates/
│   ├── hvisor-build/           # build CLI
│   ├── hvisor-bench/           # benchmark CLI、脚本与文档
│   └── hvisor-workspace-core/  # 共享 Profile schema、校验与源码缓存 API
├── profiles/                   # 平台、源码、Zone 和构建 DAG
├── docs/                       # build 使用与架构文档
└── .cargo/config.toml          # cargo hvisor-build / hvisor-bench alias

Workspace 命令

# 构建两个工具
cargo build --release --workspace

# 构建、运行和验证
cargo hvisor-build list
cargo hvisor-build x86_64-asterinas build

# benchmark 编排和报告
cargo hvisor-bench list
cargo hvisor-bench run lmbench/process_getppid_lat --subject both

Cargo alias 定义在 .cargo/config.toml；它们分别等价于 cargo run --release -p hvisor-build -- 和 cargo run --release -p hvisor-bench --。

功能

• 使用 Profile 描述平台、Zone、源码、构建命令和运行方式；
• 支持 hvisor 与 hvisor-tool 的锁定远端源码或本地只读输入；
• 使用 native 或 Docker runner 执行可缓存的构建 DAG；
• 按构建身份发布 ArtifactSet，并在运行前校验或恢复产物；
• 自动运行客户机、检查串口输出并保存验证记录；
• 安全清理当前 workspace 或回收历史构建。

仓库当前提供以下 Profile：

Profile	架构	平台	Zone1 系统
aarch64-linux	AArch64	QEMU GICv3	Linux
riscv64-linux	RISC-V 64	QEMU PLIC	Linux
riscv64-asterinas	RISC-V 64	QEMU PLIC	Asterinas
x86_64-linux	x86-64	QEMU	Linux
x86_64-asterinas	x86-64	QEMU	Asterinas

list 会显示仓库中的实际 Profile、声明状态和最近一次本地验证结果。

环境要求

构建 hvisor-build 本身需要：

• Linux；
• Rust 1.75 或更高版本；
• Cargo；
• Git。

实际构建和运行依赖所选 Profile。当前 Profile 可能使用 Docker、交叉编译器、QEMU、KVM、归档 工具或文件系统工具，并可能运行 privileged container。先用 doctor 检查 Profile 声明的宿主 工具、Docker daemon/image 和 KVM 状态：

Profile 中的 runner image 必须使用 name@sha256:<digest>；可变 tag 会在构建执行前被拒绝。 构建节点仅在 mount/chroot 等确有需要时启用 privileged，宿主网络与 /dev 直挂保留给 QEMU 运行节点。

build、run 和 test 会在本地缺少 Profile 锁定的 runner image 时自动拉取；doctor 只检查并提示准确的 docker pull 命令，clean 和各类清理命令不会拉取镜像。也可以提前手动取得公共镜像：

docker pull \
  ghcr.io/yanlien/hvisor-runner@sha256:f0c1111992d64813c500f2f0e2f17f5611e4c3f74fe9b5346444371e4d705855

cargo hvisor-build riscv64-linux doctor

doctor 只检查环境，不取得源码或创建构建 workspace。它对缺少 /dev/kvm 给出提示；是否必须 使用 KVM 取决于所选 Profile 的运行方式。

快速开始

下面以 riscv64-linux 为例：

# 查看可用 Profile
cargo hvisor-build list

# 检查宿主环境
cargo hvisor-build riscv64-linux doctor

# 查看声明式构建图，不取得源码或创建 workspace
cargo hvisor-build riscv64-linux plan

# 构建并发布产物
cargo hvisor-build riscv64-linux build

# 启动并进入 Zone0 控制台；已有产物会直接复用
cargo hvisor-build riscv64-linux run

# 使用已发布产物执行自动验证
cargo hvisor-build riscv64-linux test

省略 action 时默认执行 run：

cargo hvisor-build riscv64-linux

日常操作建议显式写出 build、run 或 test，这样命令的行为更清楚。完整的命令、源码选项、 数据目录和清理方法见使用手册。

Benchmark 快速开始

查看测例与执行计划：

cargo hvisor-bench list
cargo hvisor-bench plan all --subject both

先用单轮小测例验证 QEMU/hvisor 完整链路：

cargo hvisor-bench \
  run lmbench/process_getppid_lat \
  --subject both \
  --warmup 0 \
  --repeat 1

正式测量默认使用 2 轮预热和 10 轮有效样本：

cargo hvisor-bench \
  run lmbench/process_getppid_lat --subject both

块设备测例同样按选择器逐个执行。例如下面只运行指定的 lmbench job；每个 warmup/measurement round 都会为 QEMU 和 hvisor 分别使用全新的 2 GiB ext2 镜像：

cargo hvisor-bench \
  run lmbench/ext2_create_delete_files_0k_ops \
  --subject both \
  --warmup 0 \
  --repeat 1

每次运行会输出 RUN_ID，可以生成报告或恢复中断运行：

cargo hvisor-bench report <RUN_ID>
cargo hvisor-bench resume <RUN_ID> --continue-on-error

standalone QEMU 失败或中断时会保留可写 workspace 以便恢复。可先预览并显式回收旧 workspace；默认保留最新 5 个：

cargo hvisor-bench prune --dry-run
cargo hvisor-bench prune --keep 5
cargo hvisor-bench prune --keep 20 --delete-outputs

prune 只删除 work/benchmark/ 下带合法受管记录的直接子目录，不会处理 build workspace 或用户自行创建的目录。只有显式传入 --delete-outputs 时，才会按同一个 --keep 独立回收 output/benchmark/ 下带合法 run.json 的旧结果。 正在执行或恢复的 run 及其 standalone workspace 持有生命周期锁；prune 会显示 skip active ...，不会等待或删除活跃目录，--dry-run 使用相同判断。 使用 hvisor build workspace 的 benchmark 也会在整个运行期间持有该 workspace 的 .hvisor-lifecycle.lock，因此 cargo hvisor-build clean/prune 不会删除活跃 workspace。

schema 11 的 run.json 将受管 workspace/源码记录为相对 data root 的路径，将样本目录记录为 相对 run 目录的路径。整体搬迁 data root 后，只需传入新的 --data-root，报告与恢复不会继续 引用旧机器上的绝对目录；data root 外的用户路径仍明确保留为绝对路径。 每个 run 还固定 Docker digest 引用、image ID、嵌入式 benchmark 后端摘要和 bench 工具摘要；resume 在这些 身份变化时拒绝继续，避免同一份统计混入不同执行实现产生的样本。 记录还保存 run 级 pending/running/passed/failed/interrupted 状态与开始/结束时间。恢复失败轮次 前会删除并重建该轮目录，避免旧日志或中间文件污染重试。 执行期间按 Ctrl-C 会停止当前 case runner，将当前 round、case 和 run 立即记录为 interrupted，清理容器后以状态码 130 退出。

QEMU baseline 与 hvisor guest 的 Asterinas commit 都来自所选 Profile，避免对照组 意外使用不同源码版本。完整的测例、恢复和统计说明见 Benchmark 使用文档。

缓存与数据目录

build 与 benchmark 默认共用仓库根目录作为 data root，也可以统一设置：

export HVISOR_BUILD_DATA_ROOT=/var/lib/hvisor-build
# 或分别传入 cargo hvisor-build/hvisor-bench --data-root <path>

优先级为 --data-root、HVISOR_BUILD_DATA_ROOT、Cargo workspace 根目录。以下路径都相对 同一个 data root：

.cache/
├── git/<repo-id>.git/             # 共享 bare mirror
├── sources/<repo-id>/<commit>/    # 共享的不可变源码快照
├── downloads/                     # 已校验的归档下载
├── build-cache/                   # DAG 节点 stamp
├── build-artifacts/               # 可跨 workspace 恢复的节点产物
├── cargo/ 与 rustup/              # Docker runner 工具链缓存
└── locks/                         # Profile 和源码并发锁
work/
├── build/<build-id>/              # hvisor-build 可修改工作区
└── benchmark/<bench-work-id>/     # QEMU benchmark 隔离可写工作区
output/
├── build/<profile>/<build-id>/    # 已发布 ArtifactSet
└── benchmark/<run-id>/            # benchmark 原始样本与 run.json
logs/<profile>/<build-id>/         # build / run / test 日志
target/                            # 所有 Rust package 共用的 Cargo 产物

build 与 bench 通过 hvisor-workspace-core 共用 Profile schema 与校验、Git mirror 和按 commit 物化的源码快照。 snapshot 只作为受管输入；hvisor 构建在 work/build/<build-id>/ 内进行， QEMU benchmark 在 work/benchmark/<bench-work-id>/ 的隔离副本中进行。 两类 workspace 都使用 .hvisor-workspace.json，并通过记录中的 kind 区分。build workspace 还记录其源码 content IDs，供源码缓存回收和 benchmark run 固定引用。旧版 .cache/mirrors/ 以及缺少合法 marker 的旧 snapshot 不会被自动删除。

远端 Git 快照和本地内容快照只通过显式命令回收；Git mirror 和 downloads 始终保留：

cargo hvisor-build cache-prune --dry-run
cargo hvisor-build cache-prune

命令会保留 Profile、workspace、ArtifactSet 或 benchmark run 仍引用的 commit、content ID 或 路径，并在源码缓存正被 build/benchmark 使用时整体跳过。未引用的平铺本地 hvisor 与 hvisor-tool 内容快照也会删除；dry-run 会显示每个保留快照的引用记录。Git mirror、downloads 和工具/节点缓存继续保留。

文档

• 使用手册 — 命令速查、本地源码、数据与产物、清理与回收
• 架构文档 — Profile 驱动的 DAG、Execution Identity、缓存、产物与验证
• Benchmark 使用文档 — 测例、执行对象、恢复和报告
• Benchmark 架构文档 — 测量模型、记录结构和能力矩阵
• hvisor 与 Asterinas Guest — 启动协议、Zone 配置、启动流程与问题修复记录
• 文档索引

开发

cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo test --workspace --all-targets --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings

CI 对整个 workspace 执行以上四项 Rust 检查、release 构建、全部 Profile plan、架构边界搜索 和 benchmark payload Shell 语法检查。实际平台 build/runtime matrix 由 仓库变量显式启用，默认不会启动虚拟机或 benchmark。