refactor(axvm): decouple axvisor arch logic

docs/docs/architecture/axvisor.md

@@ -118,7 +118,7 @@ Guest 的存在方式是"配置驱动的 VM 实例化过程"，而非代码中
 
 ### vCPU 作为 ArceOS task
 
-每个 vCPU 最终被包装成 ArceOS task，进入独立的等待队列与运行循环。主 vCPU 在 `setup_vm_primary_vcpu()` 中首先被分配 task，初始为阻塞状态，直到 `notify_primary_vcpu()` 唤醒。`vcpu_run()` 中不断调用 `vm.run_vcpu()` 并处理不同的 `AxVCpuExitReason`。
+每个 vCPU 最终被包装成 ArceOS task，进入独立的等待队列与运行循环。主 vCPU 在 `setup_vm_primary_vcpu()` 中首先被分配 task，初始为阻塞状态，直到 `notify_primary_vcpu()` 唤醒。`vcpu_run()` 中不断调用 `vm.run_vcpu()` 并处理不同的 `VmExit`。
 
 AxVisor 的并发模型可理解为：
 
@@ -232,7 +232,7 @@ sequenceDiagram
 
 ### vCPU 运行循环
 
-`vcpu_run()` 是 AxVisor 动态行为最密集的入口，不断处理不同的 `AxVCpuExitReason`：
+`vcpu_run()` 是 AxVisor 动态行为最密集的入口，不断处理不同的 `VmExit`：
 
 ```mermaid
 flowchart TD

docs/docs/components/crates/arm-vcpu.md

@@ -48,7 +48,7 @@
 ```mermaid
 flowchart TD
     A["Aarch64VCpu::new"] --> B["setup / init_hv"]
-    B --> C["set_entry / set_ept_root"]
+    B --> C["set_entry / set_nested_page_table_root"]
     C --> D["run()"]
     D --> E["save_host_sp_el0"]
     E --> F["restore_vm_system_regs"]
@@ -57,17 +57,17 @@ flowchart TD
     H --> I["exception.S 保存 Guest 上下文"]
     I --> J["vmexit_trampoline 切回宿主栈"]
     J --> K["vmexit_handler"]
-    K --> L["生成 AxVCpuExitReason"]
+    K --> L["生成 VmExit"]
 ```
 
 可以进一步拆解为：
 
 1. `new()` 只构造基本上下文，并把 DTB 地址写到约定参数寄存器。
 2. `setup()` / `init_hv()` 配置 `SPSR_EL2`、`VTCR_EL2`、`HCR_EL2`、`VMPIDR_EL2` 等虚拟化状态。
-3. `set_entry()` 设置 guest 入口 PC；`set_ept_root()` 设置 `VTTBR_EL2`。
+3. `set_entry()` 设置 guest 入口 PC；`set_nested_page_table_root()` 设置 `VTTBR_EL2`。
 4. `run()` 先保存宿主 `SP_EL0`，再恢复 guest 系统寄存器，最后通过裸函数 `run_guest()` 跳到 `context_vm_entry` 并 `eret` 进入 guest。
 5. guest 一旦因同步异常、IRQ 或系统寄存器 trap 回到 EL2，`exception.S` 会把 guest 上下文写回 `Aarch64VCpu`，再通过 `vmexit_trampoline` 切回宿主栈。
-6. `vmexit_handler()` 把硬件 trap 归类为 `AxVCpuExitReason`，再交给上层 hypervisor 处理。
+6. `vmexit_handler()` 把硬件 trap 归类为 `VmExit`，再交给上层 hypervisor 处理。
 
 ### 1.5 VM exit 与内建处理逻辑
 `arm_vcpu` 的 VM exit 路径不是简单“返回异常号”，而是做了明确分类：
@@ -79,7 +79,7 @@ flowchart TD
 这说明 `arm_vcpu` 不只是“上下文切换器”，它同时承担了第一层 trap 解码器的角色。
 
 ### 1.6 与 GIC、中断与 Stage-2 页表的关系
-- `set_ept_root()` 实际写的是 `VTTBR_EL2`，即 Stage-2 根页表基址。
+- `set_nested_page_table_root()` 实际写的是 `VTTBR_EL2`，即 Stage-2 根页表基址。
 - `VTCR_EL2` 会根据 `ID_AA64MMFR0_EL1` 探测宿主支持的物理地址位宽和页表层级。
 - `HCR_EL2` 会根据配置选择虚拟中断或物理直通中断行为。
 - 真正的“虚拟中断注入”并不在本 crate 内建模，而是调用 `axvisor_api::arch::hardware_inject_virtual_interrupt()`，与 `arm_vgic` 形成分工。
@@ -88,25 +88,25 @@ flowchart TD
 ### 功能概览
 - 创建和维护 AArch64 guest 上下文。
 - 在 EL2 和 guest EL1/EL0 之间切换执行。
-- 解析常见 VM exit 并生成 `AxVCpuExitReason`。
+- 解析常见 VM exit 并生成 `VmExit`。
 - 提供 per-CPU EL2 本地状态管理。
 - 与宿主 HAL / 中断注入接口协作完成 IRQ 路径。
 
 ### 使用场景
 - `Aarch64VCpu::new()` / `setup()`：构造 vCPU 并初始化 EL2 虚拟化寄存器。
 - `set_entry()`：设置 guest 起始执行地址。
-- `set_ept_root()`：安装 Stage-2 根页表。
+- `set_nested_page_table_root()`：安装 Stage-2 根页表。
 - `run()`：进入 guest 并等待下一次 VM exit。
 - `inject_interrupt()`：调用宿主侧架构 API 注入虚拟中断。
 
 ### 使用方式
-`arm_vcpu` 并不直接作为最终业务 API 暴露给用户，典型用法是由 `axvm` 绑定为当前架构的 `AxArchVCpuImpl`：
+`arm_vcpu` 并不直接作为最终业务 API 暴露给用户，典型用法是由 `axvm` 绑定为当前架构的 `ArchVCpu`：
 
 ```rust
 let mut vcpu = Aarch64VCpu::<MyHal>::new(vcpu_id, dtb_addr)?;
 vcpu.setup(config)?;
 vcpu.set_entry(entry_gpa);
-vcpu.set_ept_root(stage2_root);
+vcpu.set_nested_page_table_root(stage2_root);
 let exit = vcpu.run()?;
 ```
 
@@ -164,7 +164,7 @@ arm_vcpu = { workspace = true }
 ### 单元测试
 - `VTCR_EL2` 参数计算与寄存器位域解析。
 - ESR/ISS/FAR/HPFAR 到 GPA 的合成逻辑。
-- `AxVCpuExitReason` 映射中那些可纯 Rust 验证的分支。
+- `VmExit` 映射中那些可纯 Rust 验证的分支。
 
 ### 集成测试
 - Axvisor + aarch64 场景下的 guest 启动、HVC、SMC、MMIO、IPI 与定时器路径。

docs/docs/components/crates/ax-cpumask.md

@@ -48,7 +48,7 @@
 ### 使用场景
 - `CpuMask::new()` / `set()`：`ax-task/src/api.rs` 用来构造 `AxCpuMask`。
 - `get()` / `is_empty()`：`ax-task/src/run_queue.rs` 用于根据 affinity 选择运行队列。
-- `CpuMask`：`virtualization/axvm/src/vm.rs` 和 `os/axvisor/src/vmm/vcpus.rs` 直接使用，用来描述 vCPU 目标集合。
+- `CpuMask`：`virtualization/axvm/src/vm.rs` 和 `virtualization/axvm/src/runtime/vcpus.rs` 直接使用，用来描述 vCPU 目标集合。
 
 ### 边界说明
 - `ax-cpumask` 不负责验证 CPU 是否在线；它只存位。

docs/docs/components/crates/ax-timer-list.md

@@ -4,7 +4,7 @@
 > 类型：库 crate
 > 分层：组件层 / 定时事件队列基础件
 > 版本：`0.1.0`
-> 文档依据：`Cargo.toml`、`README.md`、`src/lib.rs`、`os/axvisor/src/vmm/timer.rs`
+> 文档依据：`Cargo.toml`、`README.md`、`src/lib.rs`、`virtualization/axvm/src/timer.rs`
 
 `ax-timer-list` 提供一个按截止时间排序的定时事件容器。它内部用 `BinaryHeap` 实现最小堆语义，向上暴露“插入事件、取消事件、取出最早到期事件”的接口。它是容器型叶子基础件：不是硬件定时器驱动、不是中断时钟源，也不是完整的定时器子系统。
 
@@ -53,7 +53,7 @@ flowchart TD
 - 逐个弹出已经到期的事件。
 
 ### 使用场景
-- `TimerList::set()`：`os/axvisor/src/vmm/timer.rs` 在注册 VMM timer 时调用。
+- `TimerList::set()`：`virtualization/axvm/src/timer.rs` 在注册 VMM timer 时调用。
 - `cancel()`：Axvisor 按 token 取消已登记的事件。
 - `expire_one()`：Axvisor 的 `check_events()` 循环不断取出已到期事件，再由上层显式执行回调。
 - `TimerEventFn::new()`：本 crate 测试里用于快速包装闭包事件。

docs/docs/components/crates/axdevice.md

@@ -146,7 +146,7 @@ flowchart TD
 `axvm` 才是 `axdevice` 的主要上层：
 
 - `axvm` 负责构建客户机地址空间，建立线性映射和 Stage-2/EPT。
-- `axvm` 负责在 vCPU 退出循环中把 `AxVCpuExitReason` 变成对 `AxVmDevices::handle_*()` 的调用。
+- `axvm` 负责在 vCPU 退出循环中把 `VmExit` 变成对 `AxVmDevices::handle_*()` 的调用。
 - 某些附加设备（如系统寄存器设备）也可能在 `axvm` 层再通过 `add_sys_reg_dev()` 注入。
 
 换言之，`axdevice` 是 per-VM device table，而 `axvm` 是把这个 table 纳入 VM 执行模型的调度者。

docs/docs/components/crates/axhvc.md

@@ -4,7 +4,7 @@
 > 类型：库 crate
 > 分层：组件层 / HyperCall ABI 定义组件
 > 版本：`0.2.0`
-> 文档依据：当前仓库源码、`Cargo.toml`、`README.md`、`src/lib.rs`、`os/axvisor/src/vmm/hvc.rs`
+> 文档依据：当前仓库源码、`Cargo.toml`、`README.md`、`src/lib.rs`、`virtualization/axvm/src/runtime/hvc.rs`
 
 `axhvc` 的真实定位是 **AxVisor HyperCall ABI 描述层**。它负责把“来宾发起的 hypercall 编号”定义为稳定的 Rust 类型，并给出统一的结果类型；它并不负责 trap 入口、寄存器编组、权限校验、实际功能实现，也不是完整的 hypercall 子系统。
 
@@ -69,7 +69,7 @@
 
 ### 1.5 与 Axvisor 当前实现的真实关系
 
-当前仓库里的真实消费者是 `os/axvisor/src/vmm/hvc.rs`。那里会：
+当前仓库里的真实消费者是 `virtualization/axvm/src/runtime/hvc.rs`。那里会：
 
 1. 从 trap 参数里拿到原始 hypercall 编号
 2. 用 `HyperCallCode::try_from(code as u32)` 做检查
@@ -136,7 +136,7 @@
 
 实际调用链为：
 
-- `axhvc` -> `os/axvisor/src/vmm/hvc.rs`
+- `axhvc` -> `virtualization/axvm/src/runtime/hvc.rs`
 
 ### 3.3 关系解读
 
@@ -212,7 +212,7 @@ crate 目录里没有单独测试。当前主要依赖：
 | --- | --- | --- | --- |
 | ArceOS | 当前仓库未见直接接线 | 共享 ABI 组件 | 本身不属于 ArceOS 运行时主线 |
 | StarryOS | 当前仓库未见直接接线 | 共享 ABI 组件 | 尚未看到直接集成 |
-| Axvisor | HyperCall 入口边界 | HyperCall 编号与返回值定义层 | 被 `os/axvisor/src/vmm/hvc.rs` 直接使用 |
+| Axvisor | HyperCall 入口边界 | HyperCall 编号与返回值定义层 | 被 `virtualization/axvm/src/runtime/hvc.rs` 直接使用 |
 
 ## 总结
 

docs/docs/components/crates/axvm.md

@@ -19,7 +19,7 @@
 可以把 `axvm` 理解为“可被 Hypervisor 编排的 VM 对象层”，而不是顶层 Hypervisor 程序。
 
 ### 模块结构
-- `src/lib.rs`：crate 入口，导出 `AxVM`、`AxVMRef`、`AxVCpuRef`、`VMMemoryRegion`、`VMStatus`、`config`、`AxVMHal` 与 `has_hardware_support()`。
+- `src/lib.rs`：crate 入口，导出 `AxVM`、`AxVMRef`、`VMMemoryRegion`、`VMStatus`、`config`、`AxVMHal` 与 `has_hardware_support()`。
 - `src/vm.rs`：核心实现文件，定义 `AxVM`、内部可变/不可变状态、内存区管理、状态切换、`init()`、`boot()`、`shutdown()`、`run_vcpu()` 等。
 - `src/vcpu.rs`：AxVM 自有 vCPU wrapper、状态机、current-vCPU 绑定和架构适配层，按 `x86_64`、`riscv64`、`aarch64`、`loongarch64` 选择具体后端。
 - `src/hal.rs`：定义 `AxVMHal` trait，规定宿主必须提供的能力边界。
@@ -31,7 +31,7 @@
 - `AxVMInnerMut<H>`：可变状态，包含 `address_space`、`memory_regions`、`config` 和 `vm_status`。
 - `VMMemoryRegion`：记录客户机物理地址、宿主虚拟地址、布局信息和是否需要回收。
 - `VMStatus`：`Loading`、`Loaded`、`Running`、`Suspended`、`Stopping`、`Stopped`，描述 VM 生命周期。
-- `AxVCpuRef<U>`：统一的 vCPU 引用类型，是上层调度与 VM exit 处理的基本单元。
+- `VcpuSnapshot`：对外暴露的架构无关 vCPU 状态快照。
 - `AxVMConfig` / `AxVMCrateConfig`：前者用于运行时 VM 创建，后者更贴近 TOML 配置源。
 
 ### 1.4 VM 生命周期与主线
@@ -59,7 +59,7 @@ flowchart TD
 1. `AxVM::new(config)` 创建空的客户机地址空间，并把状态初始化为 `Loading`。
 2. `init()` 负责真正完成 VM 组装：创建 vCPU、合并直通地址区间、建立设备、设置页表根与 vCPU 初始入口。
 3. `boot()` 把状态切换到 `Running`，但不直接执行客户机代码。
-4. 真正执行路径在 `run_vcpu(vcpu_id)`，它循环处理 `VmExit` / 兼容名 `AxVCpuExitReason`。
+4. 真正执行路径在 `run_vcpu(vcpu_id)`，它循环处理 `VmExit`。
 5. `shutdown()` 把 VM 推入停止状态；`Drop` 中会触发资源清理。
 
 当前源码表明：
@@ -111,7 +111,7 @@ vm.boot()?;
 let exit_reason = vm.run_vcpu(0)?;
 ```
 
-在实际仓库中，这套流程由 `os/axvisor/src/vmm/*` 完成，而不是由普通库使用者直接手写。
+在实际仓库中，这套流程由 `virtualization/axvm/src/runtime/*` 完成，而不是由普通库使用者直接手写。
 
 ## 依赖关系
 ```mermaid

docs/docs/components/crates/axvmconfig.md

@@ -4,7 +4,7 @@
 > 类型：库 + 二进制混合 crate
 > 分层：组件层 / 虚拟机配置模型
 > 版本：`0.2.2`
-> 文档依据：当前仓库源码、`Cargo.toml`、`README.md`、`src/lib.rs`、`src/tool.rs`、`virtualization/axvm/src/config.rs` 与 `os/axvisor/src/vmm/config.rs`
+> 文档依据：当前仓库源码、`Cargo.toml`、`README.md`、`src/lib.rs`、`src/tool.rs`、`virtualization/axvm/src/config.rs` 与 `os/axvisor/src/config.rs`
 
 `axvmconfig` 是 Axvisor 虚拟机配置链路的静态模型层。它的职责不是直接创建 VM，也不是直接操作页表或设备，而是把 TOML 中描述的 VM 元信息、镜像布局、内存区域、模拟设备、直通设备和中断模式转换成一组稳定的数据结构；这些结构随后被 `axvm` 转成运行时 `AxVMConfig`，再由 `os/axvisor` 继续执行内存分配、镜像加载、FDT 处理和 VM 实例化。
 
@@ -177,7 +177,7 @@ flowchart TD
 - 各类镜像 load addr 转为 `GuestPhysAddr`
 - 设备配置整体搬运进运行时配置
 
-而 `os/axvisor/src/vmm/config.rs` 则负责：
+而 `os/axvisor/src/config.rs` 则负责：
 
 - 调 `AxVMCrateConfig::from_toml()` 解析原始配置
 - 在 AArch64 上做 FDT 相关调整

docs/docs/components/crates/riscv-vcpu.md

@@ -6,7 +6,7 @@
 > 版本：`0.2.2`
 > 文档依据：当前仓库源码、`Cargo.toml`、`README.md`、`trap.S`、`guest_mem.rs` 及其在 `axvm` 中的接入方式
 
-`riscv_vcpu` 是 Axvisor 在 RISC-V 架构上的 vCPU 后端实现。它围绕 RISC-V Hypervisor Extension 组织，负责完成四类核心工作：每核 H 扩展环境准备、vCPU 寄存器与 CSR 上下文保存恢复、客户机进入/退出虚拟化执行、以及把 SBI 调用、外部中断、timer 事件和 guest page fault 转译成 `axvm-types::VmExit` / 兼容名 `AxVCpuExitReason`。
+`riscv_vcpu` 是 Axvisor 在 RISC-V 架构上的 vCPU 后端实现。它围绕 RISC-V Hypervisor Extension 组织，负责完成四类核心工作：每核 H 扩展环境准备、vCPU 寄存器与 CSR 上下文保存恢复、客户机进入/退出虚拟化执行、以及把 SBI 调用、外部中断、timer 事件和 guest page fault 转译成 `axvm-types::VmExit`。
 
 ## 架构设计
 
@@ -24,7 +24,7 @@
 - VS 级 CSR 需要在 vCPU 绑定与解绑时手工保存恢复。
 - 虚拟中断依赖 `hvip` 的 `vseip` / `vstip` / `vssip` 位。
 
-因此，尽管泛型接口里保留了 `set_ept_root()` 这类跨架构命名，实际实现并非 EPT，而是写入 `hgatp`。
+因此，尽管泛型接口里保留了 `set_nested_page_table_root()` 这类跨架构命名，实际实现并非 EPT，而是写入 `hgatp`。
 
 ### 模块结构
 
@@ -105,7 +105,7 @@ flowchart TD
 
 ### 1.5 每核初始化与 H 扩展探测
 
-`RISCVPerCpu<H>` 实现 `AxArchPerCpu`，其核心工作是在 `new()` 时调用 `setup_csrs()`：
+`RISCVPerCpu<H>` 实现 `VmArchPerCpuOps`，其核心工作是在 `new()` 时调用 `setup_csrs()`：
 
 - `hedeleg` 委托一部分同步异常。
 - `hideleg` 委托 VS 级 timer / external / software interrupt。
@@ -119,12 +119,12 @@ flowchart TD
 
 ### 1.6 vCPU 生命周期
 
-`RISCVVCpu` 实现 `AxArchVCpu` 的主要阶段如下：
+`RISCVVCpu` 实现 `VmArchVcpuOps` 的主要阶段如下：
 
 1. `new()`：初始化 guest `a0`/`a1`，建立最小寄存器态。
 2. `setup()`：准备 guest `sstatus` 与 `hstatus`，打开 `SPV`、`VSXL=64`、`SPVP`。
 3. `set_entry()`：写 guest `sepc`。
-4. `set_ept_root()`：把 stage-2 根页表地址编码到 `virtual_hs_csrs.hgatp`。
+4. `set_nested_page_table_root()`：把 stage-2 根页表地址编码到 `virtual_hs_csrs.hgatp`。
 5. `bind()`：把 `vsatp`、`vstvec`、`vsepc`、`vscause`、`vsstatus`、`vsie`、`htimedelta` 等写入硬件，并安装 `hgatp`。
 6. `run()`：临时调整 host `sie/sstatus`，调用 `_run_guest()` 进入客户机，返回后进入 `vmexit_handler()`。
 7. `unbind()`：从硬件读回 VS 级 CSR 和 `hgatp`，清空硬件中的 `hgatp` 并执行 `hfence_gvma_all()`。
@@ -141,7 +141,7 @@ flowchart TD
 
 - Legacy SBI：支持 `SET_TIMER`、`CONSOLE_PUTCHAR`、`CONSOLE_GETCHAR`、`SHUTDOWN`。
 - HSM：把 `HART_START`、`HART_STOP`、`HART_SUSPEND` 转为 `CpuUp`、`CpuDown`、`Halt`。
-- 自定义 `EID_HVC`：转为 `AxVCpuExitReason::Hypercall`。
+- 自定义 `EID_HVC`：转为 `VmExit::Hypercall`。
 - Debug Console Extension (`EID_DBCN`)：支持读写 guest 缓冲区和单字节输出。
 - System Reset：对 shutdown 转为 `SystemDown`。
 - 其余扩展：交给 `RISCVVCpuSbi` 的 `RustSBI` 前向器处理。
@@ -204,19 +204,19 @@ flowchart TD
 - `RISCVVCpu::new()`
 - `setup()`
 - `set_entry()`
-- `set_ept_root()`
+- `set_nested_page_table_root()`
 - `bind()` / `run()` / `unbind()`
 - `has_hardware_support()`
 - `RISCVPerCpu::new()` / `hardware_enable()`
 
 ### 2.3 典型使用场景
 
-在 `axvm` 中，该 crate 会被包装成架构相关的 `AxArchVCpuImpl`：
+在 `axvm` 中，该 crate 会被包装成架构相关的 `ArchVCpu`：
 
 - 创建 VM 时根据配置构建 `RISCVVCpuCreateConfig`
 - 每核先建立 `RISCVPerCpu`
 - 每个 vCPU 安装 guest 入口和 `hgatp`
-- `run_vcpu()` 循环中持续消费 `AxVCpuExitReason`
+- `run_vcpu()` 循环中持续消费 `VmExit`
 
 对调用者而言，`riscv_vcpu` 提供的是“RISC-V 版本的统一 vCPU 后端”，而不是一个直接面向应用的 API。
 
@@ -238,7 +238,7 @@ flowchart TD
 
 ### 主要消费者
 
-- `virtualization/axvm`：把它作为 RISC-V 架构后端重导出为 `AxArchVCpuImpl` 与 `AxVMArchPerCpuImpl`。
+- `virtualization/axvm`：把它作为 RISC-V 架构后端重导出为 `ArchVCpu` 与 `ArchPerCpu`。
 - `os/axvisor`：通过 `axvm` 间接使用，是当前仓库中的实际落地对象。
 
 ### 3.3 关系示意
@@ -260,9 +260,9 @@ graph TD
 1. 为每个物理核创建 `RISCVPerCpu`，并执行 `hardware_enable()` 检查 H 扩展。
 2. 构造 `RISCVVCpuCreateConfig`，设置 `hart_id` 和 `dtb_addr`。
 3. 调用 `new()` 和 `setup()` 初始化 guest 初始态。
-4. 用 `set_entry()` 安装 guest 入口，用 `set_ept_root()` 安装 stage-2 根页表。
+4. 用 `set_entry()` 安装 guest 入口，用 `set_nested_page_table_root()` 安装 stage-2 根页表。
 5. 在每次调度前 `bind()`，执行 `run()`，退出后 `unbind()`。
-6. 根据返回的 `AxVCpuExitReason` 在 `axvm` 中继续处理设备、中断和 hypercall。
+6. 根据返回的 `VmExit` 在 `axvm` 中继续处理设备、中断和 hypercall。
 
 ### 4.2 调试重点
 
@@ -294,7 +294,7 @@ cargo build -p riscv_vcpu --target riscv64gc-unknown-none-elf
 ### 4.4 维护注意事项
 
 - `trap.S` 与 `regs.rs` 的偏移关系非常紧，改动结构体字段顺序必须同步检查汇编偏移宏。
-- `set_ept_root()` 这个名字来自通用抽象，但实现写的是 `hgatp`，文档和代码审查中应避免用 x86 语义误读。
+- `set_nested_page_table_root()` 这个名字来自通用抽象，但实现写的是 `hgatp`，文档和代码审查中应避免用 x86 语义误读。
 - `guest_mem.rs` 通过清空 `vsatp` 访问 GPA，修改时要同步考虑 `hfence_vvma_all()` 语义。
 - `vmexit_handler()` 集中承载了 SBI、timer、external IRQ 和 MMIO trap 语义，属于最敏感路径。