r3bb1t/rusty_box

# Rusty Box 一个 [Bochs](https://bochs.sourceforge.io/) x86 模拟器的 Rust 移植版 —— 这是一个完整的 CPU/系统模拟器，目标是支持虚拟化的 32/64 位 x86 架构。 ## 状态 - **DLX Linux** 可启动至交互式 bash shell（BIOS POST、LILO、kernel、init、login） - **Alpine Linux** 可通过 OpenRC 完整启动，并安装所有软件包 - 完整的 x87 FPU，基于 Berkeley SoftFloat 3e（80 位扩展精度） - AVX512 Foundation（320 个处理程序）、AVX2、SSE4.2、AES-NI、SHA、BMI1/BMI2 - AMD SVM (Secure Virtual Machine) 扩展 - Bus Master DMA、ATAPI CD-ROM、PCI IDE - 通过 WASM 在浏览器中运行（egui 前端） - 无需 `alloc` 即可编译运行（no_std + 无堆），适用于嵌入式/UEFI 目标 - [支持 UEFI 启动](examples/rusty_box_uefi/) —— 可作为 EFI 应用程序在真实/虚拟硬件上运行 ## 快速开始 ``` # 使用优化进行构建（需要优化以获得可接受的性能） cargo build --release --features std # DLX Linux -- 无头模式（启动到登录提示符） RUSTY_BOX_HEADLESS=1 cargo run --release --example dlxlinux --features std # DLX Linux -- 带 GUI cargo run --release --example rusty_box_egui --features "std,gui-egui" # Alpine Linux -- 无头 BIOS 启动 RUSTY_BOX_HEADLESS=1 MAX_INSTRUCTIONS=3500000000 cargo run --release --example alpine_direct --features std # 运行测试 cargo test # WASM 构建 cd examples/rusty_box_web && trunk serve ``` 有关在 UEFI 固件上构建和运行的内容，请参阅 [UEFI 示例](examples/rusty_box_uefi/)。 ## 获取 Alpine Linux ISO 要在模拟器中运行 Alpine Linux： 1. 访问 [alpinelinux.org/downloads](https://alpinelinux.org/downloads/) 2. 下载 **Virtual** x86 ISO（例如 `alpine-virt-3.21.3-x86.iso`） 3. 将其放在项目根目录下，或设置 `ALPINE_ISO=/path/to/alpine.iso` Web 版本支持直接从浏览器上传 ISO。 ## 架构 ``` Emulator<'a, I: BxCpuIdTrait> +-- BxCpuC CPU (generic over CPUID model like Corei7SkylakeX) +-- BxMemC Memory subsystem (block-based, supports >4GB) +-- BxDevicesC I/O port handler manager (65536 ports, fixed arrays) +-- DeviceManager Hardware (PIC, PIT, CMOS, DMA, VGA, Keyboard, IDE, Serial) +-- BxPcSystemC Timers and A20 line control +-- GUI Display (NoGui, TermGui, or EguiGui) [alloc only] ``` ## 功能标志 | 标志 | 默认 | 描述 | |------|---------|-------------| | `std` | yes | 标准库（终端 GUI、文件 I/O、tempfile）。包含 `alloc`。 | | `alloc` | no | 堆内存分配（Box, Vec）。启用 `Emulator::new()`、GUI 和诊断功能。 | | `gui-egui` | no | 使用 egui/eframe 的图形界面。 | | `instrumentation` | no | 基于 closure 的 CPU 钩子（syscall 追踪、内存观察点）。包含 `alloc`。 | | `bx_debugger` | no | 内置 debugger 支持。 | | `bx_gdb_stub` | no | GDB 远程调试 stub。 | ### 构建配置 ``` # 完整桌面构建（默认） cargo build --release # no_std + no_alloc -- 仅核心仿真，无堆 cargo check -p rusty_box --no-default-features # no_std + alloc -- 添加 Emulator::new(), GUI, 诊断方法 cargo check -p rusty_box --no-default-features --features alloc # UEFI target -- 无 allocator, 就地构造 cargo build --release -p rusty_box_uefi --target x86_64-unknown-uefi ``` ### 关键设计原则 - **无全局状态** —— 每个 `Emulator` 都是完全独立的；多个实例可以并发运行 - **Bochs 一致性** —— 所有逻辑都与 Bochs C++ 源码保持一致；任何偏差都被视为 bug - **no_std + no_alloc 核心** —— CPU、内存、decoder、I/O 设备均在无 alloc 的情况下编译；全程使用固定大小数组和环形缓冲区代替 Vec/VecDeque - **类型安全的 CPU 模型** —— `BxCpuIdTrait` 将 CPU 模型设为编译时类型参数 ## 项目结构 ``` rusty_box/ +-- rusty_box/ # Main emulator library | +-- src/cpu/ # CPU (instruction handlers, mirrors Bochs cpu/) | +-- src/memory/ # Memory subsystem | +-- src/iodev/ # I/O devices (PIC, PIT, CMOS, VGA, IDE, Serial, etc.) | +-- src/ring_buffer.rs # Fixed-capacity ring buffer (replaces VecDeque) | +-- examples/ # Desktop examples (DLX, Alpine, egui GUI) +-- rusty_box_decoder/ # x86 instruction decoder (separate crate) +-- rusty_box_gui/ # User launcher with CLI/TOML config and egui disk creator +-- rusty_box_bximage/ # bximage-compatible disk image creation helpers +-- examples/rusty_box_web/ # WASM web frontend +-- examples/rusty_box_uefi/ # UEFI bootable emulator (no allocator) ``` ## Web 演示 WASM 前端提供了一个基于浏览器的模拟器，包含两种启动选项： - **DLX Linux** —— 内置 10 MB 磁盘镜像，即时启动 - **Alpine Linux** —— 通过文件选择器上传你自己的 ISO 在本地构建并运行： ``` cd examples/rusty_box_web trunk serve ``` 然后在浏览器中打开 `http://localhost:8080`。 ## 测试 ``` # 运行所有测试（187 个测试） cargo test # Fuzz decoder cd rusty_box_decoder && cargo +nightly fuzz run fuzz_target_1 ``` ## 性能 在现代硬件上的发布构建：在最近的笔记本电脑上通常为 **50+ MIPS**，在较新的台式机上为 **100+ MIPS**，具体取决于工作负载阶段。数值会因 CPU 模型、时钟频率和 guest 的指令混合情况而异（BIOS 实模式比 long-mode kernel/userspace 慢）。 ## 参考 - [Bochs x86 模拟器](https://bochs.sourceforge.io/) - [Intel 软件开发者手册，第 2 卷](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html)（指令集参考） - [Sandpile.org](https://www.sandpile.org/)（x86 opcode 映射） ## 许可证 本项目是 [Bochs](https://bochs.sourceforge.io/) x86 模拟器的衍生作品 并根据 [GNU Lesser General Public License v2.1](LICENSE) (LGPL-2.1-or-later) 获得许可。 有关内置的第三方代码（Berkeley SoftFloat 3e、Hauser FPU transcendentals），请参阅 [第三方许可证](THIRD-PARTY-LICENSES)。