AxVisor实习计划 — Backtrace 实现与 Xtask 修复

[aptacc2421]

AxVisor 实习计划

作者: Xinhong Hu
日期: 2026-07-16 ~ 2026-10-10（约三个月）
当前分支: fix/axvisor-scripts-cargo-commands
基线: dev @ dbbe0e065

---

总体路线

第一、二周 (7/16 — 7/26)：代码熟悉 + Xtask 修复 + Backtrace 实现  ← 详细
第一月 (7/27 — 8/26)：Web VM Management — HTTP API           ← 方向级
第二月 (8/27 — 9/26)：Web VM Management — virtio-console      ← 方向级
第三月 (9/27 — 10/10)：Web VM Management — 完善与收尾         ← 方向级

后三个月的计划仅为方向级描述，详细计划在每个月初拆分。本周和下周的计划详细到任务和 PR 粒度。

---

背景与动机

AxVisor 是基于 ArceOS 的 Type-1 虚拟机管理器。本计划覆盖两个独立方向：

1. Xtask 修复：3 月 axbuild 统一重构后，os/axvisor/xtask/ 沦为死代码（import 已失效，逻辑全在 scripts/axbuild/ 里）。但 每个 crate 是独立发布单元，axvisor 的 xtask 必须是自包含的。需要修复它，使 axvisor 可以脱离 monorepo 独立构建运行。
2. Backtrace 实现：当前 AxVisor 的 panic/异常不输出调用栈回溯。ArceOS 生态已有成熟的 axbacktrace 组件，且 axruntime 已集成完整链路，AxVisor 仅需启用 backtrace feature 即可获得 panic backtrace 能力。进一步需要在异常处理路径中集成 trap backtrace。

关键发现

发现	来源	影响
axbacktrace 已通过 ax-std → ax-runtime 在依赖树中	调研	不需要新增依赖，只需启用 feature
panic handler 在 axruntime::lang_items.rs 中，已含 backtrace 调用链	代码	不需要修改 panic 处理逻辑
axvisor::args::Command 中的 Image 子命令引用了 axbuild::image（顶层模块）	调研	影响独立发布时的依赖声明
本地 xtask binary（os/axvisor/xtask/src/main.rs）import 了不存在的 axbuild::axvisor::image	调研	xtask 修复的关键点之一
quick-start.sh:789,796 仍用旧 cargo axvisor image pull 语法	调研	当前分支遗漏的修复点
Tokio current_thread runtime 可在 AxVisor hypervisor 内直接运行（EL2） — 8 个 async primitive 全部通过 qemu-aarch64	实证 (5f5f42575)	HTTP server 可选 Tokio 方案，不限于 thread::spawn

---

发布模型说明

Monorepo 仅是为了统一开发方便。每个 crate 保持独立发布能力是我们的基本原则。具体到 axvisor：

• axvisor crate 发布到 crates.io 时，别人 clone 下来后应能独立构建运行
• os/axvisor/xtask/ 是 axvisor 的自有 xtask，不依赖 workspace-root 的 tg-xtask
• xtask 可以通过 axbuild crate（作为 crates.io 依赖）复用构建逻辑，但接口必须正确维护

---

第一周（7/16 — 7/19，本周剩余）：代码熟悉 + Xtask 修复

本周重点：熟悉 AxVisor 代码结构，同时将 xtask 修复为可独立工作的状态。

任务 1：AxVisor 代码熟悉（贯穿本周）

目标：建立对 AxVisor 代码结构的整体理解，为后续工作打基础。

1.1 构建与启动流程

• AxVisor 启动流程：main.rs → VMM 初始化 → VM 创建 → vCPU 调度
• 构建链路：Cargo.toml → feature flags → ax-std / ax-hal / axvm → linker.x → binary
• 快速启动脚本：quick-start.sh / setup_qemu.sh 的作用和差异
• QEMU 配置：configs/qemu/qemu-*.toml 各字段含义

1.2 核心模块概览

• axvm — VM 生命周期、vCPU 调度、stage2 页表
• axvmconfig — VM 配置解析
• ax-std / ax-hal — 依赖 ArceOS 的运行时支撑
• src/shell/ — 交互式 Shell（命令框架、VM 管理、历史记录）
• src/vmm/ — VMM 核心逻辑

1.3 异常处理路径

• Host panic 路径：axruntime::lang_items → axpanic → axbacktrace（当前 backtrace 被禁用）
• Host 异常路径：ax-hal / ax-cpu 的 exception handler
• Guest 异常路径：vcpu_run → vm.run_vcpu() → VM Exit 处理 → stage2 fault 处理

---

任务 2：AxVisor Xtask 独立化修复（小 PR 拆分）

目标：修复 os/axvisor/xtask/，使其可独立编译运行。拆分为 2-3 个小 PR。

当前状态：PR 1 (#1607) 和 PR 2 (#1651) 已提交，等待 review 合入；PR 3 推迟。

PR 1：修复当前分支的遗留问题（✅ 已提交 #1607）

范围很小，仅含以下修复：

a) quick-start.sh RDK S100P 语法修复

• 问题：setup_rdk_s100()（第 789、796 行）仍用旧语法：

  cargo axvisor image ... pull ...

  其他 setup 函数已在 commit 2528776e5 中改为：

  cargo xtask image pull ...

• 修复：统一为 cargo xtask image pull 语法

b) 文档中残留的旧命令

• 全局搜索 os/axvisor/ 下所有 .md / .sh 文件中残留的 cargo axvisor image / cargo xtask qemu（应为 cargo xtask axvisor qemu）等旧命令模式
• 逐一修正

验证：grep -rn "cargo axvisor image" os/axvisor/ 无残留

PR 2：修复本地 xtask binary 使其可编译（✅ 已提交 #1651）

问题（已修复）：os/axvisor/xtask/src/main.rs 第 105 行：

use axbuild::axvisor::{Command, TestCommand, image};

其中 image 是 axbuild 的顶层模块（axbuild::image），不在 axbuild::axvisor 下。

同时，Command::Image(args) 变体使用的 image::Command 指向 axbuild::image::Command（顶层模块），需要修正 import 路径。

修复：

1. 将 use axbuild::axvisor::{Command, TestCommand, image} 改为分开导入：

 use axbuild::axvisor::{Command, TestCommand};
 use axbuild::image;

2. 确保 normalize_command_paths 中对 Command::Image(args) 的处理使用正确的 image::Command 类型
3. 验证 cargo build -p axvisor --bin xtask 编译通过

PR 3（可选，取决于独立发布需要）：梳理 xtask 的 axbuild 依赖接口（⏸ 推迟）

目标：确认 axvisor xtask 对 axbuild crate 的依赖是最小化的、接口明确的。

• 审查 os/axvisor/xtask/src/main.rs 中使用的所有 axbuild::axvisor::* 类型
• 列出 axvisor xtask 依赖的 axbuild 接口清单
• 如果 axbuild::axvisor::Axvisor::new()?.execute(command).await 链路有接口变更，同步更新
• 确认 axvisor xtask 的 Cargo.toml（目前缺失，因为在 os/axvisor/Cargo.toml 中作为 [[bin]] 定义）的依赖声明正确

关于 Cargo.toml：当前 xtask binary 定义在 axvisor 的 Cargo.toml 中作为 [[bin]] target，其依赖通过 axvisor 的 [dependencies] 间接获取。这在独立发布时可能需要调整为独立的 xtask/Cargo.toml。此 PR 暂时保持现有结构，仅修复编译问题。

---

任务 3：当前分支收尾

目标：将 fix/axvisor-scripts-cargo-commands 分支合并回 dev。

• Rebase 到最新 dev HEAD（当前分支已有全部修复）
• 推动 PR fix(axvisor): correct cargo commands and update image layout in scripts and docs #1607 合入 dev
• PR fix(axvisor): standalone xtask CLI compatibility #1651（xtask 编译修复）已作为独立 PR 跟进

---

第二周（7/20 — 7/26，下周）：Backtrace 实现

本周重点：backtrace 从 feature 启用到异常处理集成，从测试验证到文档。

任务 4：Backtrace Feature 启用与基础验证

目标：通过启用 feature flag 使 AxVisor 获得 panic backtrace 能力。

4.1 现有链路分析（已调研完成）

panic!() 宏
  → axruntime::lang_items::panic()              // #[panic_handler]
    → axpanic::enter_panic(cpu_id)              // panic 所有权仲裁
      → panic_primary()
        → panic_message()                       // 打印 panic 信息
        → panic_backtrace()
          → axbacktrace::Backtrace::capture()   // frame pointer 栈回溯
            .kind("panic")
        → panic_shutdown()

当前 ax-std 未启用 backtrace feature → axbacktrace 无 alloc feature → capture() 返回 Disabled。

4.2 启用 Backtrace

修改点：os/axvisor/Cargo.toml 中 ax-std 的 features 列表：

# 修改后
ax-std = { workspace = true, features = [
    "ext-ld", "paging", "irq", "multitask", "task-ext", "smp", "hv",
    "backtrace",   # ← 新增：启用 panic backtrace
] }

feature 链路：ax-std/backtrace → axbacktrace/alloc → frame pointer 栈回溯可用。

4.3 初始化验证

axbacktrace::init(ip_range, fp_range) 在 ax-runtime 初始化时自动调用。需要验证：

• Linker script 提供 _stext / _etext 段符号 → IP_RANGE 正确过滤非 kernel 地址
• FP_RANGE 覆盖 kernel 栈范围
• 如果 linker script 使用 INCLUDE "runtime.x"，确认 runtime.x 中有这些符号

4.4 首次验证

启用后触发故意 panic，验证输出包含 BACKTRACE_BEGIN kind=panic arch=<arch> ... BACKTRACE_END 且栈帧 ≥ 3。

---

任务 5：Trap/Exception Backtrace

目标：在 AxVisor 异常处理路径中集成 backtrace。

5.1 Host Trap Backtrace

利用 axbacktrace::Backtrace::capture_trap(fp, ip, ra)：

参数	x86_64	aarch64	riscv64
fp	rbp	x29	s0
ip	rip	elr_el1	sepc
ra	0	x30 (lr)	ra

• 在 ax-cpu / ax-hal 的 exception handler 中添加 capture_trap() 调用
• 在异常信息输出后打印 backtrace

5.2 Guest Stage2 Fault Backtrace（重点调试场景）

known-issues.md 中 #2（NimbOS UEFI stage2 page fault）和 #3（RISC-V64 guest page fault）目前仅有简单日志：

VM[1] unhandled x86 nested page fault at 0x1a00000, access=WRITE

在 axvm 的 VM exit / stage2 fault 处理路径中添加 Backtrace::capture()，显示 hypervisor 调用链，辅助定位这两个问题的根因（不直接修复）。

---

任务 6：符号解析（可选增强）

使用 host-side symbolize（scripts/axbuild/src/backtrace/symbolize.rs + addr2line）解析裸地址为函数名。ArceOS/StarryOS 已有现成管道可复用。

---

任务 7：测试与文档

• 至少 2 个 QEMU backtrace 测试用例（x86_64 + aarch64）
• 编写 doc/backtrace.md 使用文档

---

Backtrace 期间可同步学习的内容

在写 backtrace 的过程中，会自然接触到以下模块。主动深入理解它们，将为后续 Web VM Management 主线节省大量学习时间：

在 Week 1（Xtask 修复）期间

可学习内容	对应文件	与 Web VM Mgmt 的关联
VM 生命周期 API	src/manager.rs → axvm/src/manager.rs → runtime/mod.rs	HTTP handler 直接调用这些 API
VM 状态机	axvm/src/lifecycle/machine.rs, status.rs	HTTP API 的状态转换验证
Shell 命令框架	src/shell/command/mod.rs, vm.rs	Web API 是 shell 命令的 HTTP 映射
TOML 配置解析	src/config.rs, axvmconfig/src/lib.rs	POST /vms 的 request body 即 TOML
DeviceFactory 体系	axdevice/src/factory.rs	virtio-console 需要注册新 factory

在 Week 2（Backtrace）期间

可学习内容	对应文件	与 Web VM Mgmt 的关联
vCPU 运行循环	axvm/src/runtime/vcpus.rs:294 vcpu_run()	HTTP handler 必须理解 vCPU task 状态
VM Exit 处理路径	axvm/src/arch/x86_64/exit.rs	console I/O 通过 VMExit 触发
中断注入机制	axvm/src/manager.rs:inject_interrupt()	console 输入需要注入中断到 guest
WaitQueue 机制	axvm/src/host/task.rs, axtask wait_queue.rs	HTTP server 任务需要理解阻塞/唤醒
axstd 网络能力	axstd/src/net/tcp.rs	HTTP server 的 TcpListener
异常向量表	axruntime/src/lang_items.rs	理解 bare-metal 上的错误处理模型

建议: 每周花 1-2 小时读这些模块，不要求深入实现细节，但要对调用链和数据结构有清晰认识。此时的理解将直接转化为 Web VM Management 第一周的设计文档。

---

第三阶段（7/27 — 10/10）：Web VM Management 主线

背景与动机

AxVisor 当前只能通过串口 shell 管理 VM。增加 Web 管理面可以使 AxVisor 从一个"开发者工具"变成一个"可用的虚拟化管理程序"。该任务按三个月拆分，每月一个里程碑。

前提条件

在开始之前，以下调研结论已通过代码分析确认（详细分析见 doc/axvisor-analysis.md）：

结论	说明
HTTP server 可行	axstd 提供 TcpListener + thread::spawn，可与 vCPU 共存；或使用 Tokio current_thread runtime（已验证 EL2 可运行，见 tokio-in-axvisor-analysis.md）
virtio-console 为零实现	EmulatedDeviceType::VirtioConsole 仅枚举定义，需从 MMIO transport 开始构建
设备模型可扩展	DeviceFactoryRegistry 可通过注册新 factory 支持 virtio-console
CubeSandbox 经验可迁移	Endpoint 抽象、ApiRequest 分发、ConsoleOutputMode 等设计模式直接借鉴
Tokio 在 AxVisor hypervisor 中可运行	已验证 qemu-aarch64 上 EL2 级别可跑 Tokio current_thread runtime，8 个 async primitive 全部通过（tokio_demo.rs）

第一月（7/27 — 8/26）：HTTP VM Management API

目标: 交付可合并的 VM CRUD + Lifecycle REST API。

模块设计（参考 CubeSandbox 的链路）:

方案 A — axstd TcpListener + thread::spawn（最小依赖）:

axstd TcpListener (main task)
  → HTTP/1.1 手动解析（或引入微型 HTTP crate）
    → Router 分发
      → VmApiHandler（参数提取 + 验证）
        → VmService（业务逻辑）
          → AxvmManager / AxvmRuntime（现有 API）

方案 B — Tokio current_thread runtime（已验证可行，见 os/axvisor/doc/tokio-in-axvisor-analysis.md）:

tokio::net::TcpListener
  → tokio::spawn per connection
    → HTTP 解析（hyper / mini-http）
      → VmApiHandler → VmService → AxvmManager

第一周调研已验证：Tokio current_thread runtime 可在 AxVisor hypervisor 内（EL2）直接运行，8 个 async primitive 全部通过 qemu-aarch64。正式开发时在方案 A/B 中选择，不影响业务逻辑层（VmService/VmApiHandler）的设计。

主要任务:

• 设计 VmApiRequest enum（借鉴 CubeSandbox ApiRequest）：VmCreate, VmDelete, VmBoot, VmShutdown, VmList, VmInfo, VmPause, VmResume
• 实现 HTTP/1.1 解析 + JSON serde（复用 axstd 同步 TcpListener）
• 实现 VmService 层：包装 AxvmManager，添加状态转换验证 + 错误映射
• 实现 6-8 个 REST endpoint：GET /vms, POST /vms, GET /vms/:id, DELETE /vms/:id, POST /vms/:id/start, POST /vms/:id/stop
• 错误映射：AxVmError → HTTP status code（400/404/409/500）
• 基本测试：curl 创建 VM、查看状态、启停

交付物: PR to AxVisor main — HTTP VM Management API（预计 ~800-1200 行 Rust）

第二月（8/27 — 9/26）：virtio-console + WebSocket Bridge

目标: guest 控制台可通过浏览器 WebSocket 访问。

模块设计（参考 CubeSandbox Endpoint + Console + SerialManager）:

Guest virtio-console driver
  → virtio MMIO transport（需实现）
    → virtqueues（transmitq / receiveq）
      → AxVisor ConsoleBackend trait（需定义）
        ├─ NullBackend
        ├─ FileBackend
        └─ WebSocketBackend
            → WebSocket frame ↔ ConsoleEpollHandler（WaitQueue 替代 epoll）
              → 浏览器终端

主要任务:

• 定义 ConsoleBackend trait（借鉴 CubeSandbox Endpoint enum）
• 实现 virtio MMIO transport（设备发现、feature 协商、config space）
• 实现 virtqueue 管理（descriptor/available/used ring，参考 virtio-drivers crate）
• 实现 virtio-console DeviceFactory 并注册到 DeviceFactoryRegistry
• 实现 WebSocket upgrade + frame 编解码
• WebSocket ↔ ConsoleBackend 数据桥接（参考 ConsoleEpollHandler::process_input_queue/output_queue）
• Console resize 支持（cols/rows → virtio config space → config change interrupt）

交付物: PR — virtio-console device + WebSocket console backend

风险提示: virtio-console 实现量较大（~1500-2000 行），如果遇到 virtio spec 不明确处，可以降级为先在现有 x86 16550 UART 上实现 ConsoleBackend trait + WebSocket bridge。

第三月（9/27 — 10/10）：完善与收尾

目标: 测试覆盖、文档编写、上游 review 反馈修复。

主要任务:

• 认证（API key / basic auth）
• VM 创建参数校验（TOML schema 验证）
• 集成测试（QEMU 环境，自动化 VM 创建→启动→console→停止→删除）
• 文档：doc/web-vm-management.md（架构、API 参考、快速开始）
• 上游 review 反馈修复

交付物: 完整的 Web VM Management 系统 + 测试 + 文档

架构风险与应对

风险	应对
axstd TcpListener API 不完整（缺 accept() / incoming()）	直接使用底层 smoltcp socket API；或切换到 Tokio 方案（已验证 Tokio current_thread 可在 EL2 运行）
virtio MMIO transport 调试困难	先复用 x86 16550 UART 作为 console backend，验证 WebSocket 桥接链路
HTTP server 与 vCPU 任务饥饿	在 SMP 下 HTTP task 跑 dedicated core；必要时开启 sched-cfs；Tokio 方案下可通过 spawn_blocking 避免阻塞 vCPU 任务
上游 review 周期长	拆分为独立 PR：API 基础 → console backend → virtio-console

---

已知残留问题（本计划范围外）

#	问题	原因	优先级
1	Shell 文件系统 EISDIR（#6-#11）	根因在 axfs-ng 目录处理，跨模块	后续
2	NimbOS UEFI stage2 fault（#2）	stage2 页表映射缺失，backtrace 可辅助定位	后续
3	RISC-V64 guest page fault（#3）	虚拟化后端配置路径不支持	后续
4	mkdir -p 递归创建（#8）	axstd 占位实现	后续
5	Shell 终端输入问题（#13-#17）	SGR mouse、Delete 键、快捷键等	后续

---

第一阶段风险

风险	概率	影响	应对
AxVisor 代码量大于预期，熟悉过程超时	中	中	第一周任务 1 与任务 2 部分并行；任务 2 的 PR 拆分已预留缓冲
os/axvisor/xtask/ 的 axbuild 依赖接口与独立发布要求不匹配	中	高	PR 3 专门梳理接口；如 axbuild 尚未发布到 crates.io，先确保 path 依赖 + git 依赖可用
Linker script 缺少段边界符号	中	中	检查 runtime.x，添加缺失符号
RISC-V frame pointer 不可靠	高	中	确认编译参数中 -fno-omit-frame-pointer；仅影响 riscv64
当前分支与 dev 的差异太少，rebase 后问题不明显	低	低	尽快合并当前分支，避免偏离过远

---

交付物清单

第一周

• PR 1：quick-start.sh RDK S100P + 文档旧命令修复（~20 行改动）
  — PR fix(axvisor): correct cargo commands and update image layout in scripts and docs #1607 已提交，等待 review 合入
• PR 2：本地 xtask binary 编译修复（~10 行改动）
  — PR fix(axvisor): standalone xtask CLI compatibility #1651 已提交，等待 review 合入
• PR 3（可选）：xtask 与 axbuild 依赖接口梳理
  — 推迟到后续
• fix/axvisor-scripts-cargo-commands 分支合并
  — PR fix(axvisor): correct cargo commands and update image layout in scripts and docs #1607 未合入，待上游 merge

第一周追加任务（计划外，已并入主线文档）

• Tokio in AxVisor 可行性分析 + demo 验证（feat/tokio-in-axvisor-analysis / feat/tokio-axvisor-demo）
  — 结论：Tokio current_thread 可在 hypervisor EL2 运行，HTTP server 可选 Tokio 方案
  — 已在"前提条件"、"模块设计"、"架构风险"中补充

第二周

• Panic backtrace feature 启用（~1 行改动）
• Host trap backtrace 集成
• Guest stage2 fault backtrace 集成
• 至少 2 个 QEMU backtrace 测试用例
• doc/backtrace.md 使用文档

第一月：HTTP VM Management API

• 设计文档：doc/web-vm-management.md（架构、API 设计）
• PR：HTTP server skeleton + VmApiRequest/VmService/AppState
• PR：VM CRUD endpoints（create/list/get/delete）+ 端到端 curl 测试
• PR：VM lifecycle endpoints（start/stop/pause/resume/info）

第二月：virtio-console + WebSocket Bridge

• PR：ConsoleBackend trait + Null/File backend
• PR：virtio MMIO transport + virtqueue + virtio-console DeviceFactory
• PR：WebSocket bridge + ConsoleBackend 集成

第三月：完善与收尾

• PR：认证、参数校验、错误处理完善
• 集成测试（QEMU 环境，VM 全生命周期 + console）
• doc/web-vm-management.md 完整文档

---

时间线

第一周 (7/16 ─ 7/19，本周剩余)：代码熟悉 + Xtask 修复
├── 7/16 (周四): 任务 1.1, 1.2 — 构建流程 + 核心模块熟悉
├── 7/17 (周五): 任务 1.3 — 异常处理路径 + 任务 2 PR 1 — 脚本/文档修复 (#1607)
├── 7/18 (周六): 任务 2 PR 2 — xtask binary 编译修复 (c9308c24a) + Tokio 调研
└── 7/19 (周日): PR #1651 提交 + 计划同步 + PR 3 推迟
实际产出: PR #1607 (open), PR #1651 (open), feat/tokio-* Tokio 调研验证

第二周 (7/20 ─ 7/26，下周)：Backtrace 实现
├── 7/20 (周一): 任务 4 — feature 启用 + 首次 backtrace 验证
├── 7/21 (周二): 任务 5.1 — Host trap backtrace
├── 7/22 (周三): 任务 5.2 — Guest stage2 fault backtrace
├── 7/23 (周四): 任务 6 — 符号解析（可选）
├── 7/24 (周五): 任务 7 — 测试矩阵验证
├── 7/25 (周六): 任务 7 — 文档编写
└── 7/26 (周日): 缓冲 / 最终整理

第一月 (7/27 ─ 8/26)：HTTP VM Management API
├── 第 1 周: 设计文档（VmApiRequest enum, Router, VmService, AppState） + 搭建 HTTP skeleton
├── 第 2 周: 实现 VM CRUD endpoints（create/list/get/delete）
├── 第 3 周: 实现 VM lifecycle endpoints（start/stop/pause/resume/info）
├── 第 4 周: 错误映射、测试、PR review

第二月 (8/27 ─ 9/26)：virtio-console + WebSocket Bridge
├── 第 5 周: ConsoleBackend trait 设计 + Null/File backend 实现
├── 第 6 周: virtio MMIO transport + virtqueue 管理
├── 第 7 周: virtio-console DeviceFactory 注册 + 端到端调试
├── 第 8 周: WebSocket upgrade + ConsoleBackend bridge + 缓冲

第三月 (9/27 ─ 10/10)：完善与收尾
├── 第 9 周 (9/27-10/3): 认证、参数校验、错误处理完善
├── 第 10 周 (10/4-10/10): 集成测试 + 文档 + 上游 review 反馈修复

---

参考

• axbacktrace 组件源码
• axruntime panic handler
• axpanic 实现
• axbuild axvisor 模块
• axbuild backtrace 工具
• axvisor 已知问题
• axvisor Shell 文档
• 参考计划 (YoungCIoud) — 中断注入架构重构
• AxVisor Web VM Management 架构分析（本调研）
• CubeSandbox VMM 架构对比与可迁移设计
• Tokio in AxVisor 可行性分析
• Tokio in Hypervisor Demo 运行指南

[aptacc2421]

组会 Discussion 提纲

---

背景

本次目标：

用户按照 Axvisor 文档里的命令，能成功启动 Linux guest。

检查 quick-start 流程时发现命令不一致：

1. scripts 中残留旧命令：

   cargo axvisor image pull    →  应为 cargo xtask image pull
   

2. README / doc 中缺少 axvisor namespace：

   cargo xtask qemu            →  应为 cargo xtask axvisor qemu
   

→ PR #1607 修这些入口问题。

---

新问题：scripts 是否应该保留？

Review 意见：

目前主要通过 cargo xtask 完成构建、运行和镜像管理，scripts 与 xtask 功能重复，后续可以考虑清理。

当前结构：

scripts ── build / image / qemu
cargo xtask ── build / image / qemu

两个入口做同一件事，长期保留会导致功能逐渐不一致。

→ 最终方向：用户 → cargo xtask → axbuild（删掉 scripts）。

但删 scripts 引出一个问题：Axvisor 独立发布，不能依赖 tgoskits 的 tg-xtask。必须有 standalone xtask。

---

Axvisor standalone xtask 怎么做？

方案 A：复用 axbuild（PR #1651）

tg-xtask ──┐
           ├── axbuild（共享构建逻辑）
axvisor ───┘

• xtask 负责命令入口，axbuild 负责构建逻辑
• Axvisor 和 tgoskits 用同一套实现
• 独立发布时：axvisor xtask → axbuild::axvisor

方案 B：Axvisor 自己维护 xtask

问题：未来需要同时维护 tg-xtask、axvisor xtask、axbuild，与 tgoskits"复用模块"理念背离。

→ 当前倾向方案 A，"发行时再拆分"。

---

需要讨论

1. scripts 去留：现在删，还是先保留、等 xtask 成为唯一入口后再删？
2. PR 推进：fix(axvisor): correct cargo commands and update image layout in scripts and docs #1607 和 fix(axvisor): standalone xtask CLI compatibility #1651 是否都继续？

---

Backtrace（简要同步）

• Host backtrace：已通过复用 ArceOS backtrace 完成（PR feat(axvisor): add optional panic backtrace via axbacktrace + std::panic::set_hook #1653）
• Guest backtrace：倾向由 guest 自己负责，Axvisor 不介入 guest 内部调试。是否需要额外支持，可以讨论。

[aptacc2421]

Week2 组会内容

本周工作：

• 主要是读了axvisor和cubesandbox的代码，看看能不能找到共同点
• 继续推进了原来的PR

问题

本次改动的范围应该是哪些？

• 1. 是否支持开抢占？(不开抢占是因为默认每个guest都能够分到独立的cpu吗？）
• 2.能否忍受网络管理独占一个CPU？(也就是说默认多核吗?)
• 3.设计是否是性能优先，容忍饿死？
• 4.网络管理的内容应该放在哪里？是像shell一样等待默认的guest跑完吗还是一来就初始化放到task里面？

其它问题：

• x86的idel目前不支持yield,是直接loop的，但是其它架构支持yield,yield在guest linux上应该取决于负载，所以要同步其它架构吗？

[aptacc2421]

目前挂起的PR基本上都通过了检查(待合入）:

• 使x86架构Vm-exit能够正常yield(PR fix(x86_vcpu): make HLT yield vCPU task and fix timer wakeup deadlock #1769)
• 文档的修复工作,(已经approve)(PR fix(axvisor): correct cargo commands and update image layout in scripts and docs #1607)

正在做的工作(预计本周内完成)

• core0 固定控制面（http,shell等等），采用spawn
• 添加网络控制面,目前的实现是通过调用AxvmManager来实现,但是此处需要注意,比如stop命令实际上只是请求stop，要等所有vcpu全部退出之后才是真正的stop，这里后续可能需要修正？
• 网络控制面将作为一系列pr完成：
  PR 1: VM 生命周期文档 ✅ PR docs(axvm): add authoritative VM lifecycle docs and align crate overview #1828（已发布，不占本系列序号）
  └─ PR 2 [系列1]: 网络 + SMP + 核隔离 ✅ 已提交 分支: feat/axvisor-pr1-net-smp-isolation ← dev
  └─ PR 3 [系列2]: 只读 HTTP API ✅ 已实现（待提交） 分支: feat/axvisor-pr2-http-readonly ← PR 2
  └─ PR 4 [系列3]: HTTP 控制 API 分支: feat/axvisor-pr3-http-control ← PR 3
  └─ PR 5 [系列4]: 测试硬化+文档 分支: feat/axvisor-pr4-test-hardening ← PR 4
  └─ PR 6 [系列5]: 动态增删 VM 分支: feat/axvisor-pr5-http-dynamic ← PR 5
  └─ PR 7 [系列6]: 生命周期扩展 分支: feat/axvisor-pr6-lifecycle-ext ← PR 6

PR 注册表（系列序号从 1 开始，PR 2 为系列 #1；PR 标题为提交/PR 标题）：

计划 PR	系列序号	分支名	PR 标题	base
PR 1	—（已发布）	feat/axvm-lifecycle-doc	docs(axvm): 新增 VM 生命周期权威文档并同步 crate 概览	dev ✅ #1828
PR 2	#1	feat/axvisor-pr1-net-smp-isolation	feat(net): 启用 ArceOS 网络栈、SMP=2 与 vCPU 核隔离	dev ✅ 已提交 25260de5a
PR 3	#2	feat/axvisor-pr2-http-readonly	feat(http): 只读 VM 状态 API（GET /api/vms）	PR 2 分支 ✅ 已实现，待提交
PR 4	#3	feat/axvisor-pr3-http-control	feat(http): VM start/stop 控制 API	PR 3 分支
PR 5	#4	feat/axvisor-pr4-test-hardening	test(http): 测试硬化与安全边界文档	PR 4 分支
PR 6	#5	feat/axvisor-pr5-http-dynamic	feat(http): 动态创建/删除 VM（POST create / DELETE）	PR 5 分支
PR 7	#6	feat/axvisor-pr6-lifecycle-ext	feat(http): 生命周期扩展（resume/reset/pause）	PR 6 分支

• 当状态在stoped情况下start后，如果新 vCPU task 排进队列时，Core 1 正好睡在 WFI，而没有任何中断到来，循环就永远走不到下一次
  yield_now_unchecked()，任务永远不被调度。（待修复）

TODO?:

• 完善网络管理的界面UI?
• 让网络管理(或者说AxvmManager)不是request,而是执行之后立马（或在一定时间内）切换guest的实际运行状态？
• ？

[aptacc2421]

AxVisor 网络管理控制面 — 组会进展汇报（2026-08-10）

目前实现的工作

• 网络管理功能（支持 list, start, stop, create, delete）：feat(axvisor): axum management HTTP control plane with VM lifecycle API #1909
• 网络管理 UI（支持 list, start, stop）：未 PR
• 安全加固：Bearer token 认证（默认拒绝）+ 默认 loopback 绑定 + 真实 TCP 拒绝访问回归（aarch64/x86_64 均 PASS）

PR 中的问题

1. restart-after-stop 不支持（最核心残缺）

• 现象（若无 409 防护）：stop 后 VM 进入 Stopped；再 start → HTTP 返回 200、状态变 Running，但 vCPU 永远不进 guest，VM 卡死在 Running。
• 根因（已逐行确认）：vCPU 退出后 Core 1 run queue 清空 → 进 WFI 睡眠；restart 时 spawn_task 把新 vCPU task 同步入队但不 wake（kick_remote_cpu 被 #[cfg(all(smp, ipi))] 门控，当前构建未启用 axtask ipi）→ 新 task 永不调度。首次 start 能跑是因为启动阶段手动发过 IPI，restart 路径没人发。
• 现状：API 已用 409 拒绝 restart（避免挂死），自测刻意不测 restart。
• 处置：已搁置（2026-08-03 组会：不修改调度器，axtask 重构中，预期自带 wake 修复）。

2. 受限 create

• 现象：运行时 create 只能对「已内嵌镜像且当前未注册」的 id（remove-then-recreate 默认 VM），不能从任意 TOML / 外部镜像建新 VM。
• 原因：这是部署/测试配置层面的限制，不是系统硬限制——当前构建未开 fs + 测试无磁盘 → image_location = "fs" 直接 InvalidInput → 只剩 memory 内嵌可用。打开 fs + 挂盘后，就可以用任意 TOML + 盘上镜像建 VM（fs 路径按 kernel_path 读文件，无 id 限制）。

3. 测试专用 feature 暴露在内核 feature 面（ZCShou 阻塞）

• 原来的 test 是通过 QEMU 输出匹配的，因此需要把测试编译进内核进行输出；但这些测试专用 feature 作为公开 Cargo feature 暴露、且内核内有测试回传端点。后续是否需要移除这类测试？(原来是调API,后面curl它？（可能会更重)）

4. quickstart 文档位置不对（ZCShou 阻塞）

• 设计文档应统一放 docs/docs/architecture/axvisor，是否需要待网络管理完全完成之后再 PR 文档？

TODO（本周）按顺序进行

1. 清 ZCShou 两个阻塞 → 合入当前网络管理 PR feat(axvisor): axum management HTTP control plane with VM lifecycle API #1909（其测试均为 memory 内嵌，不依赖 fs）
2. 使能fs, PR 当前实现的 UI（web-ui 依赖 fs + nvme rootfs）。fs 编译面与 rootfs 拉取机制 CI 已有（smoke job 已开 fs+nvme，image pull 已存在），新增成本仅是"一个需挂盘的用例"；且 fs + rootfs 同时解决 web-ui 伺服与 create-from-fs 两个问题
3. 开发 pause / resume / reset 的控制面以及其 UI
   • 现状：axvm 底层机制已存在（状态机 + vCPU park/wake + reset 管线）；resume/reset 已通到 manager 层、pause 未接 runtime。缺的是 HTTP 端点 + 端到端验证（resume 唤醒 park 的 vCPU 这条路从未真实跑过，是主要风险）。

Pending PR?

• fix(x86_vcpu): make HLT yield vCPU task and fix timer wakeup deadlock #1769 ?

[aptacc2421]

AxVisor 网络管理控制面 — 组会进展汇报（2026-08-17）

目前实现的工作

• 更新PR上周阻塞项： feat(axvisor): axum management HTTP control plane with VM lifecycle API #1909
• 本地开发其余的web ui和pause / resume / reset 等功能

TODO

• 合入上述几个pr（UI, pause / resume / reset）

[aptacc2421]

AxVisor 网络管理控制面 — 组会进展汇报（2026-08-24）

目前推进的工作

• 推进网络管理的pause / resume等功能(feat(axvisor): add pause/resume VM lifecycle endpoints #2098)
• reset 因为没有更新RAM,但是更新了寄存器,，而寄存器指向的boot位置在上一次程序运行过程中已经被修改了,无法正确boot,后续的话打算做冷启动，即在第一次create时在内存中创建一个快照（kernel，（bios,ramdisk,dtb可选）），后续reset时把快照搬到内存中。这个pr打算与网络控制面的reset一起提交（因为发现axVM组件没有直接拉起虚拟机的测试，所以测试在网络控制面会更好做一些）

TODO:

• 待pause / resume合入之后提交 reset的PR
• 合入上面两项之后提交web UI的PR
• 撰写文档

[aptacc2421]

组会汇报（2026-08-31）

一、做了什么

1. syscall 修复：eventfd 边沿语义与 Linux 对齐（https://github.com/rcore-os/tgoskits/pull/2235）

• 问题：Linux eventfd_write 每次都无条件 wake_up_locked_poll(EPOLLIN)（fs/eventfd.c）；ArceOS 实现只在 counter 从 0 变
  非 0 时推进 readiness_version，导致 counter 已非 0 时再写（1→2）不产生新边沿，边沿触发的 epoll 把这个 wake 吞掉。
• 影响：async runtime 的 mio::Waker eventfd 从不 drain，第一次 wake 后所有后续 spawn_blocking 永远卡在 epoll_wait——这
  正是 web-ui 异步读挂起的根因（见问题 3）。
• 修复：每次 accepted write 都 bump readiness_version（2 commits：a3b22ef00 + 回归测试 7eee5adab）。测试用
  epoll_wait(timeout=0)，丢边沿表现为确定性「零事件」失败而非挂起调度器。

2. 网络控制面：web-ui 管理台重构与联调（exp/webui-without-eventfd-fix，6+ commits）

• dashboard 重建：React + TS + Vite + shadcn/ui 替换手写静态页；build.rs 确定性打包（npm ci → build → 归一化 tar.gz 嵌
  入 include_bytes!，运行时流式解压到 /web/axvisor-ui/current）；严格 CSP + MIME 断言 + CI job 注册（Node 24 引导）；
  解压失败 UI 返 503 但 /api/* 不受影响。
• 伺服路径修正：先因 wake-loss 退到同步 std::fs::read 规避，修掉 eventfd 根因后改回流式输出 assets，并补 wake-delivery
  • fs 回归测试。
• 直通修复：guest_type="passthrough" 空列表自动给根路径 /，把宿主自己的 virtio-net-pci（管理 eth0）和 NVMe 都给了
  guest → 显式排除宿主 PCI bridge。
• axvm 生命周期计数修复（8-24，fae2d17ca）：guest_entry_count 在 vCPU 从未真正运行时也发布「重入」信号，broken
  wake/faulting resume 会伪造证据 → 只在真实 park/re-entry 后发布。

3. 网络终端方案设计（本周主要设计产出，两个新文档）

• docs/design/network-terminal-from-cubesandbox.md：借鉴 CubeSandbox 的 envd 终端/日志架构（流式会话、多客户端广播、
  guest 控制台 FIFO 旁路），对照 Linux pty 模型（master 哑管道、TIOCSWINSZ/SIGWINCH）。
• docs/design/network-terminal-plan.md：落地执行计划，拆 7 个 PR（P1a subscriber API → P1b websocket MVP → P2 广播+隔
  离 → P3 resize+日志流 → P4 web UI 标签 → P5 文档+e2e；旁线 R: rebase pr4-webui），并明确了两条重要取舍（见问题 1、
  2）。

4. 其他项

• ax-net NIC IRQ 边沿丢失 watchdog（8-29，246aa8962）：边沿触发 IRQ 在队列执行器 idle 睡眠期间丢失，且不 poll 就永远不
  回收 RX buffer → 10ms idle watchdog 强制 full poll 兜底。
• 配套文档：web-ui-manual-build-run.md（8-27）、http-lifecycle-curl-reference.md（8-24）、AXVISOR_HTTP_PR_ROADMAP.md、
  pr1887-comment-draft.md。

二、遇到的问题与取舍

1. 每个字节都切换特权级的问题（每字符 VM-exit 陷阱开销）

guest 写虚拟 UART 的 TX，每个字符触发一次 VM exit 到 EL2，特权级切换开销按字节累计。已写进网络终端计划作为已知项：本期
只记录设计预期，不上 virtio-serial 就不声称改善吞吐。

2. virtio console 的取舍

• 方案 A（本期）：复用现有 SerialBackend（UART），guest_console+console_mux 已有 2414 行底座，网络终端只是加 fan-out
  订阅层（约 +1.2–1.8k 行）；raw 字节桥接，cooking/termios 交给 guest 自身。
• 方案 B（后续）：新写 virtio-serial 设备后端，+1.5–3k 行（MMIO transport + virtqueue + DeviceFactory 注册），能批量传
  字节、支持 resize 语义，但实现量大、virtio spec 有不明确处。
• 结论：本期选 A；resize 在裸串口下只能透传尺寸元信息，virtio-serial 才彻底解决。备选降级路径（16550 UART 先验证
  websocket 桥接）已写入计划。

3. 遗留/待办

• exp 分支与 feat/axvisor-webui 分支内容需整理（wake-loss 文档、eventfd fix 已拆出）。
• 工作区未跟踪文件待归位：docs/design/network-terminal-、os/axvisor/doc/、qemu-aarch64-axum.toml、
  test-suit/.../qemu-http-control-plane/ 等。
• 非阻塞 fan-out 纪律是 P2 主要风险（对应 fix(console): unify sleepable runtime console arbitration #2113/e1048e954 历史坑：慢/死客户端不能回压 vCPU 或阻塞其他 VM）。

三、下周计划（按 network-terminal-plan §5–6 的节奏）

• 1.合入eventfd修复pr
• 2.重构web-ui,方便之后其接入终端（https://github.com/rcore-os/tgoskits/pull/2200）
• 3. P1a：guest_console/mux subscriber API + 历史回放 + 单元测试（~250 行）。
• 4. P1b：websocket MVP（ws 路由 + 单订阅者 + 输入注入 + QEMU echo 回显用例）。

[aptacc2421]

组会汇报（2026-09-07）

一、做了什么

• 由于开学校内课设，主要是调研和竞态bug
• 竞态bug: 在VM_entry是有一个Once初始化的操作，但是此时是禁止睡眠上下文，但是会有两个核心同时来初始化，然后就panic了，panic之后还有一个查FD_TABLE的操作，然后查的过程中会访问一个坏地址，然后又panic， panic 尝试又访问坏地址，然后死循环了，目前是打算把预热放到前面（类似KVM),但是谁把地址搞坏了还不太清楚,依然在追踪
• 网络控制面的重构;要点在于插件式的ui,每个终端相互隔离，串口那里解耦合，他只知道串口是串口，不用知道串口是用来干什么的（参考重构文件），还有demo:https://github.com/aptacc2421/axvisor-webui-demo
  二、TODO
• 补完前面两项

[aptacc2421]

组会汇报（2026-09-14)

一、做了什么

• ui: feat(axvisor): add HTTP control-plane contract and React dashboard #2366
• 修复了上周提到的竞态问题：fix(axvm): prepare host GIC before CPU enable and centralize fatal traps #2356

二、TODO

• 把串口也接上ui
• 合并之前的console

[aptacc2421]

组会汇报（2026-09-20)

一、做了什么

• 把web终端接线接好了
• 修了一个在禁止抢占区域睡眠的bug: fix(axvm)!: destroy VM resources outside the machine lock #2467
  二、TODO
• 当前ui的实现还有一些bug, 我将做一个修复，以及写ui架构文档
• 上传文件功能

[aptacc2421]

组会汇报（2026-09-27)

一、做了什么

• ui基本结束了:feat(axvisor): serve a web control plane for guest lifecycle and file transfer #2514
• fix(axvm)!: destroy VM resources outside the machine lock #2467 阻塞ui

二、TODO

• 补文档以及合入pr
• 文档：
  docs/
  ├── design/
  │ └── axvisor-webui-control-plane.md + 新增
  └── docs/
  ├── architecture/axvisor/
  │ ├── guest-console.md ~ 修改
  │ └── control-plane.md + 新增
  ├── build/axvisor/
  │ └── runtime.md ~ 修改
  └── ci/
  ├── overview.md ~ 修改
  └── testing/
  ├── execution.md ~ 修改
  └── runners.md ~ 修改

os/axvisor/
├── src/http/browser_console/assets/README.md - 删除
└── web-ui/
└── README.md + 新增

virtualization/axvm/docs/
├── lifecycle.md ~ 修改
└── lifecycle-internals.md ~ 修改