# xhyper **Repository Path**: gueeos-lite/xhyper ## Basic Information - **Project Name**: xhyper - **Description**: No description available - **Primary Language**: C - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-08-29 - **Last Updated**: 2026-09-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # XHyper XHyper 是面向嵌入式与混合关键系统的静态分区 Type-1 Hypervisor。它直接运行在 硬件虚拟化特权级，启动前确定 VM 的 CPU、内存、MMIO、设备和中断资源；每个 vCPU 永久绑定一个 pCPU，运行时不进行 vCPU 调度或 CPU 超售。 当前有三条可执行基线：AArch64 QEMU `virt` 已形成静态多 VM、Linux/NXOS/FreeRTOS、 虚拟中断、双向控制台和 VirtIO Block/Net/GPU/Input闭环；Khadas VIM3 Pro已在真实 A311D 硬件上启动 AArch64 Linux、FreeRTOS以及 eMMC Android 9，并完成四核、GICv2、设备直通、 Meson UART双向切换和显示中断恢复；RISC-V 64已在 QEMU `virt`/OpenSBI上完成单 VM、 Sv39x4 G-stage、虚拟 SBI、vPLIC、裸机和FreeRTOS，Linux已运行到`/init`，但BusyBox交互 终端仍待最终回归。RISC-V SMP/多 VM/VirtIO、VIM3 DMA隔离和 x86-64仍是后续工作。 ## 1. 架构原则 - **静态分区**：VM 拓扑和资源所有权由 YAML 在启动前确定，运行期只改变预定义 VM 的生命周期，不改变其资源边界。 - **固定 CPU 绑定**：始终保持 `vCPU:pCPU = 1:1`，没有时间片调度器和 CPU 超售。 - **最小 EL2**：Hypervisor 使用静态数组、定长池和有界循环，不在 EL2 引入线程、 文件系统、通用网络协议栈或阻塞 I/O。 - **Host VM 管理模型**：静态定义的多核最小 Linux 作为未来管理 VM；它可以管理 预定义 VM 的生命周期，但不能改变 CPU、内存、设备或 IRQ 所有权。 - **配置分层**：板卡硬件事实位于 `configs/boards//`，VM 拓扑和部署策略位于 `configs/profiles//`，构建入口位于 `configs/defconfigs//`。 - **可移植边界**：通用 VM、vCPU、VMEM、IRQ 和设备接口保持架构无关，寄存器和平台 地址留在架构、驱动或板卡层。 ## 2. 当前实现状态 | 子系统 | 当前状态 | |---|---| | AArch64 EL2 | 已实现启动汇编、per-pCPU 栈、异常向量和进入 EL1 Guest | | VM/vCPU | 已实现静态多 VM、固定 pCPU 绑定、启动、关机、资源释放和重新启动 | | Stage-2 | 已实现 1 GiB、2 MiB、4 KiB 贪心映射以及 Guest RAM 范围校验 | | 中断 | 已实现 GICv2/GICv3 后端、vGIC、维护中断和主动 vIRQ 注入 | | SMP/PSCI | 已实现物理 PSCI、虚拟 PSCI 和双核 Linux 启动/关机/重启 | | vConsole | 已实现 PL011与 Meson UART MMIO模型、RX缓冲、vIRQ和物理TTY所有权切换 | | CLI | 已实现 5 秒单行倒计时、历史命令、光标编辑和统一 `vm` 命令 | | VirtIO Block | 已实现Guest设备、QEMU物理frontend和固定异步桥，VM1可从32 MiB ext4磁盘启动 | | VirtIO Net | 已实现双队列、固定 EL2 二层交换机和 QEMU VirtIO-MMIO 上行 | | VirtIO GPU | 已实现物理/Guest 2D frontend、Linux DRM fbdev 与 QEMU SDL 显示 | | VirtIO Input | 已实现 QEMU SDL 键盘/鼠标、物理/Guest frontend、Linux evdev 与 Xfce 输入 | | Linux 网络 | 双 Linux VM 已验证内部 ICMP、DNS 和通过 QEMU user NAT 访问公网 | | Guest | 支持 AArch64裸机、FreeRTOS V11.3.0、Linux + BusyBox、NXOS/BookOS、Ubuntu 24.04 + Xfce和 Android；RISC-V裸机/FreeRTOS已闭环，Linux已到`/init` | | 配置 | 已实现嵌入式有界 YAML 解析、schema 校验和 defconfig 工作流 | | VIM3 Pro | 已实机启动四核64位Android，完成DTB资源发现、GICv2、PSCI、原生Meson ABI串口和设备直通 | “已实现”不等于所有目标平台均已验证。当前运行基线包括AArch64 QEMU与VIM3实机；各子系统 更精确的已验证范围、当前架构和分阶段未完成项见 [项目进度与路线](doc/governance/project-status.md)和[设计文档索引](doc/README.md)。 ## 3. 快速开始 ### 3.1 环境依赖 推荐在 Ubuntu 或 WSL 中构建： ```sh sudo apt update sudo apt install -y \ gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu \ make qemu-system-arm device-tree-compiler \ curl cpio gzip bzip2 xz-utils e2fsprogs bc bison flex libssl-dev ``` FreeRTOS Kernel 通过 Git 子模块连接，首次克隆后执行： ```sh git submodule update --init --recursive ``` Linux 和 BusyBox 的固定版本源码会由 Guest 构建流程下载并缓存。Windows 用户应在 仓库目录中通过 WSL 执行下面的 `make` 命令。 ### 3.2 最短运行路径 运行双核 Linux Host VM： ```sh make aarch64_qemu_linux_defconfig make run ``` 运行两个双核 Linux VM，并启用 VirtIO Block、VirtIO Net 和公网验证上行： ```sh make qemu_linux_linux_defconfig make run ``` 运行双核管理Linux和使用Ubuntu Base 24.04.4 arm64根文件系统的双核VM1： ```sh make qemu_linux_ubuntu_defconfig make run ``` 运行两个双核 Linux VM，并给 VM1 提供由 QEMU SDL 显示的 VirtIO GPU 与 `/dev/fb0`： ```sh make qemu_linux_gpu_defconfig make run ``` 运行 Ubuntu 24.04 ARM64 VM1，把官方 Xfce/Xubuntu 桌面通过 `/dev/fb0` 显示到 QEMU SDL，并使用 VirtIO 键盘和鼠标交互： ```sh make qemu_linux_ubuntu_gpu_defconfig make run ``` 桌面完成初始化后串口输出： ```text [NX-UBUNTU-DESKTOP] Xfce display :0 active on /dev/fb0 ``` 运行双核管理 Linux 和四核 AArch64 Android VM1；Android 的 VirtIO GPU 图形路径配置为经 XHyper 转发到 QEMU SDL 窗口，当前运行验证状态见专项文档： ```sh make qemu_linux_android_defconfig make run ``` Android 制品准备、串口附着和网络 ADB 命令见 [AArch64 Android VM1 第一阶段](doc/architecture/aarch64/android-guest.md)。 启动成功后会进入 BusyBox： ```text [NX-LINUX] BusyBox userspace is running [NX-LINUX] starting interactive shell on /dev/console / # ``` QEMU 终端使用 `Ctrl-A X` 退出。 ### 3.3 Khadas VIM3 Pro Android VIM3构建必须在 Ubuntu/WSL中执行。Windows TFTP根目录固定为 `G:\hypervisor_tftp`，一键构建并原子导出四个文件： ```sh cd /mnt/g/hypervisor/xhyper VIM3_GUEST=android JOBS=56 \ sh tools/export_vim3_tftp.sh /mnt/g/hypervisor_tftp ``` U-Boot完整加载命令为： ```text tftp 0xeb80c000 xhyper_aarch64_android-booti.bin tftp 0xec800000 nx_guest_aarch64_android.bin tftp 0xf0600000 nx_guest_aarch64_android.dtb tftp 0x42000000 vim3_uboot.dtb dcache flush booti 0xeb80c000 - 0x42000000 ``` 四个地址分别是 XHyper入口、Android Image loader source、Android final DTB source和 U-Boot交接 DTB，不能互换或省略。完整的持久化`bootcmd`、内存布局、寄存器和故障树见 [VIM3 Pro / Android BSP手册](doc/vim3/bsp/README.md)。Android运行时按`Ctrl+/`切回 XHyper，执行`vm -t 0`把后续输入重新交给`console:/ $`。 Android + BusyBox Linux双 VM使用独立配置和六文件布局： ```sh VIM3_GUEST=android-linux JOBS=56 \ sh tools/export_vim3_tftp.sh /mnt/g/hypervisor_tftp ``` 完整 U-Boot命令、CPU/内存分配和串口切换见 [VIM3 Android + BusyBox Linux双VM](doc/vim3/bsp/13-android-linux-dual-vm.md)。 ## 4. 构建配置 | defconfig | Guest/拓扑 | GIC | pCPU | |---|---|---:|---:| | `aarch64_qemu_baremetal_defconfig` | 单裸机 Guest，默认别名 | v3 | 1 | | `aarch64_qemu_baremetal_gicv2_defconfig` | 单裸机 Guest | v2 | 1 | | `aarch64_qemu_baremetal_gicv3_defconfig` | 单裸机 Guest | v3 | 1 | | `aarch64_qemu_freertos_gicv2_defconfig` | 单 FreeRTOS Guest | v2 | 1 | | `aarch64_qemu_freertos_gicv3_defconfig` | 单 FreeRTOS Guest | v3 | 1 | | `aarch64_qemu_nxos_gicv2_defconfig` | 单 NXOS/BookOS Guest | v2 | 1 | | `aarch64_qemu_nxos_linux_gicv2_defconfig` | NXOS Host + Linux普通VM，支持HVC生命周期管理 | v2 | 2 | | `riscv_qemu_freertos_defconfig` | RISC-V VS-mode FreeRTOS Guest | PLIC | 1 | | `riscv_qemu_linux_defconfig` | RISC-V VS-mode Linux Guest；BusyBox交互终端待回归 | PLIC | 1 | | `aarch64_qemu_linux_defconfig` | 单双核 Linux Host VM | v3 | 2 | | `qemu_linux_baremetal_defconfig` | 双核 Linux + 单核裸机 | v3 | 3 | | `qemu_linux_rtos_defconfig` | 双核 Linux + 单核 FreeRTOS | v3 | 3 | | `qemu_linux_linux_defconfig` | 两个双核 Linux VM | v3 | 4 | | `qemu_linux_ubuntu_defconfig` | 双核管理 Linux + 双核 Ubuntu Base VM1 | v3 | 4 | | `qemu_linux_gpu_defconfig` | 两个双核 Linux VM，VM1 使用 VirtIO GPU/SDL framebuffer 与键鼠输入 | v3 | 4 | | `qemu_linux_ubuntu_gpu_defconfig` | 双核管理 Linux + 双核 Ubuntu Xfce VM1，VirtIO GPU/SDL 与键鼠输入 | v3 | 4 | | `qemu_linux_android_defconfig` | 双核管理 Linux + 四核 AArch64 Android VM1，VirtIO GPU/SDL、串口与手动配网 ADB | v3 | 6 | | `khadas_vim3_baremetal_defconfig` | VIM3单核裸机Guest，实机TFTP启动 | v2 | 1 | | `khadas_vim3_freertos_defconfig` | VIM3单核FreeRTOS Guest，实机TFTP启动 | v2 | 1 | | `khadas_vim3_linux_defconfig` | VIM3 Linux + 内置BusyBox，实机TFTP启动 | v2 | 1 | | `khadas_vim3_android_defconfig` | VIM3 Pro四核AArch64 Android Host VM | v2 | 4 | | `khadas_vim3_android_linux_defconfig` | VIM3 Pro四核Android Host + 单核Linux 6.12/BusyBox VM | v2 | 5 | | `khadas_vim3_android_linux_headless_defconfig` | VIM3 Pro原生显示Android Host + 无显示设备的单核Linux 6.12/BusyBox VM | v2 | 5 | 通用工作流： ```sh make _defconfig # 选择配置并生成 .config make # 构建 Guest 和 XHyper make run # 构建并启动 QEMU make clean # 删除生成文件，保留 .config make distclean # 删除生成文件和 .config ``` 不要手工修改生成的 `.config` 来代替板卡或部署 YAML。新增硬件资源时修改 `configs/boards/`；新增 VM 拓扑和策略时修改 `configs/profiles/`，并同步 schema 校验。 ## 5. 启动和终端工作流 XHyper 加载并校验资源后显示 5 秒单行倒计时： - 倒计时期间没有输入：自动启动 `role: host` 的 VM； - 有输入：取消自动启动并进入 XHyper Shell； - VM使用受管 vConsole时按 `Ctrl+/`：该字节由EL2截获，物理TTY返回XHyper； - 使用 `vm -t `：把后续物理串口输入交给指定 VM。 Shell 支持上下方向键浏览历史，左右方向键移动光标。VM 命令统一为： ```text vm 显示VM命令帮助 vm -l 列出静态配置的VM vm -i 查看运行状态和VirtIO Net统计 vm -c 查看静态配置与资源 vm -s 启动指定VM vm -s -h 启动Host VM vm -o 关闭指定VM vm -o -h 关闭Host VM vm -t 将物理TTY输入绑定到指定VM vm -t 查看当前TTY归属 ``` 最小 Linux 以交互 shell 作为 PID 1。验证 PSCI 关机应执行： ```sh poweroff -f ``` VM 关闭后会释放运行资源并返回 XHyper Shell；再次执行 `vm -s ` 会重建 VMEM、 设备、vGIC 和 IRQ 状态，重新装载可信镜像后启动。 ## 6. 双 Linux、Block 和网络验证 `qemu_linux_linux_defconfig` 是当前覆盖能力最多的集成配置： - VM0：双核 Host Linux，使用内置 initramfs； - VM1：双核 Linux，经XHyper物理VirtIO Block frontend从32 MiB raw ext4磁盘启动； - 两个 VM 都有 VirtIO Net，位于同一个静态 `switch_id`； - VM0 为 `10.0.2.15/24`，VM1 为 `10.0.2.16/24`； - 默认网关为 `10.0.2.2`，DNS 为 `10.0.2.3`； - XHyper 驱动固定 QEMU VirtIO-MMIO 上行，QEMU user networking 提供 NAT/DNS。 在任一 Linux VM 中验证： ```sh ping -c 1 -W 3 10.0.2.2 ping -c 1 -W 3 baidu.com ``` VM0 和 VM1 均已观察到 DNS 解析和公网 ICMP reply。XHyper 只转发有界二层帧， 不在 EL2 实现 ARP、IP、ICMP、DNS 或 NAT。当前上行用于 QEMU 集成验证；真实板卡 计划由 Host VM 持有物理网卡并提供共享 packet channel、bridge/routing/NAT。 ## 7. 核心运行路径 ```text 固件/Bootloader -> XHyper EL2入口与per-pCPU初始化 -> 解析board/profile YAML并校验静态资源 -> 初始化UART、GIC和可选物理VirtIO上行 -> 创建VM、vCPU、Stage-2、vGIC和虚拟设备 -> 装载Guest Image/DTB并初始化可选物理Block frontend -> 5秒倒计时或XHyper Shell -> 固定pCPU进入对应Guest EL1 -> MMIO/IRQ/HVC trap返回EL2处理 ``` Guest串口按 board选择 PL011或 Meson寄存器模型，并通过虚拟IRQ进入VM；需要TTY逃逸的 profile中，物理 UART MMIO/PIRQ始终属于XHyper。VIM3 Android仍看到原生 Meson UART ABI， 但`0xff803000`页由Stage-2 trap代理，因此`Ctrl+/`能在进入Guest FIFO前被截获。Guest VirtIO descriptor、地址、长度和索引均作为不可信输入进行范围、溢出、所有权和有界遍历检查。 ## 8. 配置与资源边界 ```text configs/boards//board.yaml 板卡架构、RAM、物理UART、GIC、物理VirtIO上行 configs/profiles//.yaml VM数量、角色、vCPU/pCPU、Guest RAM、入口、vGIC、设备、vIRQ、网络交换域 configs/defconfigs//_defconfig 构建选择、Guest制品、QEMU CPU数量和可选验证设备开关 ``` 当前 YAML 由有界解析器直接解析并嵌入 XHyper 镜像。由 Host 工具生成二进制 manifest 仍是未来目标，当前没有实现。 ## 9. 目录结构 ```text xhyper/ ├── 3rd/ 第三方源码或仓库连接 ├── configs/ │ ├── boards/ 板卡硬件描述 │ ├── profiles/ VM部署YAML │ └── defconfigs/ 构建入口 ├── doc/ 架构、子系统和编号开发记录 ├── guest/ 裸机、FreeRTOS和Linux Guest ├── src/ │ ├── arch/arm64/ EL2入口、异常、PSCI和Stage-2 │ ├── config/ YAML解析、schema和平台校验 │ ├── core/ VM、vCPU、IRQ、设备、CLI和生命周期 │ ├── drivers/ UART、vConsole、GIC和VirtIO │ ├── include/nx/ 公共接口 │ ├── lib/ freestanding libc子集 │ └── linker/ 平台链接脚本 └── Makefile 顶层配置、构建和QEMU入口 ``` ## 10. 文档入口 - [设计文档索引](doc/README.md) - [当前进度、架构状态与后续路线](doc/governance/project-status.md) - [架构文档入口](doc/architecture/README.md) - [总体架构](doc/architecture/overview.md) - [核心数据模型](doc/architecture/data-model.md) - [配置模型](doc/architecture/configuration.md) - [VM与生命周期](doc/architecture/vm.md) - [多VM架构](doc/architecture/multi-vm.md) - [vCPU与固定绑定](doc/architecture/vcpu.md) - [Stage-2与VMEM](doc/architecture/vmem.md) - [GIC/vGIC实现](doc/architecture/aarch64/gic-implementation.md) - [Linux Guest与BusyBox](doc/architecture/aarch64/linux-guest.md) - [SMP与PSCI](doc/architecture/aarch64/smp.md) - [VirtIO Block](doc/devices/virtio/virtio-block.md) - [AArch64 Android VM1 第一阶段](doc/architecture/aarch64/android-guest.md) - [VirtIO Net](doc/devices/virtio/virtio-net.md) - [Khadas VIM3 Pro / Android完整BSP手册](doc/vim3/bsp/README.md) - [VIM3 Android实施与验证](doc/vim3/xhyper-vim3-pro-android-implementation.md) - [VIM3 Meson vConsole串口切换](doc/commit_doc/070-2026-09-09-vim3-meson-vconsole-switch.md) - [开发约束与踩坑记录](doc/governance/development-constraints.md) `doc/commit_doc/` 按提交顺序保存每次开发的目标、设计、改动、验证证据和剩余限制。 ## 11. 已知限制 - AArch64 QEMU `virt` 已完成多VM/Linux/VirtIO运行闭环；RISC-V QEMU `virt` 已完成单VM 裸机和FreeRTOS，Linux已运行到`/init`，但BusyBox FPU修复后的交互提示符仍待回归，且 尚无HSM/IPI、完整多source PLIC、SMP、多VM或VirtIO；树莓派和x86-64尚未达到可启动状态。 - Management HVC ABI v1、NXOS内核回调、DevFS ioctl和PowerBox命令已经实现并用于启动/ 停止预定义Linux VM；通用上游Linux管理驱动、共享ring和服务化工具仍未实现。 - VirtIO Block当前只支持QEMU `disk0`到VM1的单队列桥接，固定8个在途请求；I/O超时、 物理queue reset、多磁盘和生产板卡持久化后端尚未实现。 - Android 第一阶段已支持 GKI、initrd、动态分区、userdata、APEX、串口及网络 ADB； Cuttlefish 网卡重命名使每次启动仍需先在串口执行一次静态配网，图形和专用 HAL 未实现。 - VIM3 Pro已实机进入64位Android framework并保持EL2心跳；当前设备直通仍缺少IOMMU/DMA 隔离，显示RDMA丢边沿恢复虽已动态命中验证，仍需覆盖原约7071秒故障点的长时老化。 - VirtIO Net 公网路径依赖 QEMU user NAT。Host VM packet channel、TAP/bridge、 真实物理网卡和 IOMMU/DMA 隔离尚未实现。 - vGIC共享SPI的完整`IROUTER`保存和全部目标路由语义尚未完成。 - GICv3 次级pCPU Redistributor选择和VM重启时的本地GIC复位已经修复，并通过双Linux 两核timer计数及140秒回归；更长时间和高吞吐压力测试仍需继续补充。 - YAML 和 Linux DTS 仍有部分重复事实，尚未实现自动一致性生成。 ## 12. 开发约定 XHyper 公共宏、类型和枚举使用 `NX_` 前缀，函数和对象使用 `nx_` 前缀。提交代码前 请阅读[开发约束与踩坑记录](doc/governance/development-constraints.md)，并为每次仓库 修改新增编号开发记录、更新文档索引和执行与影响范围匹配的构建/运行验证。 ## 13. 许可证 XHyper 使用 [Apache License 2.0](LICENSE)。第三方组件保留各自许可证；例如 `3rd/freertos-kernel` 使用 MIT 许可证，详见其 [`LICENSE.md`](3rd/freertos-kernel/LICENSE.md)。