A Rust port of the Bochs x86 emulator -- a complete CPU/system emulator targeting 32/64-bit x86 architecture with virtualization support.

• DLX Linux boots to an interactive bash shell (BIOS POST, LILO, kernel, init, login)
• Alpine Linux fully boots through OpenRC with all packages installed
• Full x87 FPU with Berkeley SoftFloat 3e (80-bit extended precision)
• AVX-512 Foundation (320 handlers), AVX2, SSE4.2, AES-NI, SHA, BMI1/BMI2
• AMD SVM (Secure Virtual Machine) extensions
• Bus Master DMA, ATAPI CD-ROM, PCI IDE
• Runs in the browser via WASM (egui frontend)
• Compiles and runs without alloc (no_std + no heap) for embedded/UEFI targets
• UEFI bootable -- runs as an EFI application on real/virtual hardware

# Build with optimizations (required for acceptable performance)
cargo build --release --features std

# DLX Linux -- headless (boots to login prompt)
RUSTY_BOX_HEADLESS=1 cargo run --release --example dlxlinux --features std

# DLX Linux -- with GUI
cargo run --release --example rusty_box_egui --features "std,gui-egui"

# Alpine Linux -- headless BIOS boot
RUSTY_BOX_HEADLESS=1 MAX_INSTRUCTIONS=3500000000 cargo run --release --example alpine_direct --features std

# Run tests
cargo test

# WASM build
cd examples/rusty_box_web && trunk serve

cargo xtask android build
cargo xtask android run
cargo xtask android screenshot rustybox_android.png

cargo xtask android installs the Android SDK components, Rust target, and cargo-apk as needed; copies ~/Downloads/alpine-virt-3.23.3-x86_64.iso to the ignored rusty_box_android/assets/alpine.iso; signs with a generated local dev keystore under your home directory; and uses adb_client for install, launch, and screenshots. The first Android crate embeds Alpine with include_bytes! for simplicity, does not commit the ISO or signing material, and shows emulated Linux serial logs in the Linux Serial Log (ttyS0) panel.

See UEFI Example for building and running on UEFI firmware.

To run Alpine Linux in the emulator:

1. Visit alpinelinux.org/downloads
2. Download the Virtual x86 ISO (e.g., alpine-virt-3.21.3-x86.iso)
3. Place it in the project root or set ALPINE_ISO=/path/to/alpine.iso

The web version supports uploading the ISO directly from the browser.

Emulator<'a, I: BxCpuIdTrait>
+-- BxCpuC<I>         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]

# Full desktop build (default)
cargo build --release

# no_std + no_alloc -- core emulation only, no heap
cargo check -p rusty_box --no-default-features

# no_std + alloc -- adds Emulator::new(), GUI, diagnostic methods
cargo check -p rusty_box --no-default-features --features alloc

# UEFI target -- no allocator, placement construction
cargo build --release -p rusty_box_uefi --target x86_64-unknown-uefi

• No global state -- each Emulator<I> is fully self-contained; multiple instances can run concurrently
• Bochs parity -- all logic matches the Bochs C++ source; deviations are bugs
• no_std + no_alloc core -- CPU, memory, decoder, I/O devices all compile without alloc; fixed-size arrays and ring buffers replace Vec/VecDeque throughout
• Type-safe CPU models -- BxCpuIdTrait makes CPU model a compile-time type parameter

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_android/         # Android NativeActivity APK frontend
+-- rusty_box_bximage/         # bximage-compatible disk image creation helpers
+-- xtask/                     # Cross-platform repository automation
+-- examples/rusty_box_web/    # WASM web frontend
+-- examples/rusty_box_uefi/   # UEFI bootable emulator (no allocator)

The WASM frontend provides a browser-based emulator with two boot options:

• DLX Linux -- embedded 10 MB disk image, boots instantly
• Alpine Linux -- upload your own ISO via file picker

Build and run locally:

cd examples/rusty_box_web
trunk serve

Then open http://localhost:8080 in your browser.

# Run all tests (187 tests)
cargo test

# Fuzz the decoder
cd rusty_box_decoder && cargo +nightly fuzz run fuzz_target_1

Release build on modern hardware: typically 50+ MIPS on a recent laptop and 100+ MIPS on newer desktops, depending on workload phase. Numbers vary with CPU model, clock, and the guest's instruction mix (BIOS real-mode is slower than long-mode kernel/userspace).

• Bochs x86 Emulator
• Intel Software Developer Manual, Volume 2 (Instruction Set Reference)
• Sandpile.org (x86 opcode maps)

This project is a derivative work of the Bochs x86 emulator and is licensed under the GNU Lesser General Public License v2.1 (LGPL-2.1-or-later).

See THIRD-PARTY-LICENSES for bundled third-party code (Berkeley SoftFloat 3e, Hauser FPU transcendentals).