yindo/archived-oboromi
1
0
Fork 0
mirror of https://github.com/0xNikilite/oboromi.git synced 2026-01-31 01:15:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

readme.md update

Browse Source
This commit is contained in:
Nikilite
2025-11-08 00:33:34 +01:00
parent 28623c3862
commit 5ea427dad9
2 changed files with 53 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
README.md
View File

@@ -9,107 +9,96 @@
<h4 align="center">(◕‿◕)&nbsp;&nbsp;Join our Discord here 🢰</h4>
<h1 align="center">oboromi</h1>
<h4 align="center">a proof-of-concept Nintendo Switch 2 emulator written in Rust</h4>
<h4 align="center">a proof-of-concept Nintendo Switch 2 emulator foundation written in Rust</h4>
## Overview
**oboromi** is a modular and work-in-progress emulator for the Nintendo Switch 2. It's built in Rust and focuses on correctness, clarity, and traceability rather than performance at this stage. The current implementation includes a functioning ARM64 CPU core using Dynarmic JIT compilation, comprehensive instruction testing, and cross-platform compatibility.
**oboromi** is a modular and work-in-progress emulator foundation for the Nintendo Switch 2. It's built in Rust and focuses on correctness, clarity, and traceability rather than performance at this stage.
> [!IMPORTANT]
> oboromi is **not** yet playable and does not emulate any commercial firmware or games.
> oboromi is **not (yet)** a full Switch 2 emulator. It does not run any Nintendo firmware or games.
## Features
## Current Features
### JIT Backend (Dynarmic)
### ARM64 CPU Emulation (Unicorn Engine)
oboromi uses [Dynarmic](https://github.com/0xNikilite/dynarmic) as a JIT backend for AArch64 instruction translation.
The included version is a **fork with custom modifications** designed to integrate directly with `DynarmicCPU` in oboromi.
oboromi uses [Unicorn Engine](https://www.unicorn-engine.org/) for ARM64 instruction emulation. The `UnicornCPU` wrapper provides:
- Full ARM64 register access (X0-X30, SP, PC)
- Memory mapping with permission control
- Breakpoint handling via `BRK` instructions
- Safe Rust interface with proper error handling
### Comprehensive Instruction Testing
- Reliable test framework using breakpoints and `run()` instead of single-stepping
- 10+ instruction tests covering core ARM64 operations:
- NOP, ADD, SUB, MOV operations
- Register and immediate arithmetic
- Control flow (branches, returns)
- Multi-instruction sequences
- Reliable test framework using breakpoints and `run()` for stable execution
- **10/10 instruction tests passing** covering core ARM64 operations:
- NOP, ADD (immediate/register), SUB (immediate)
- MOV (register), RET, B (branch)
- Multi-instruction sequences and memory access patterns
- **Fast execution**
### Memory Management
- **32-bit and 64-bit load/store operations** with proper alignment handling
- **Endianness-aware memory access** using little-endian byte ordering
- **Virtual address translation support** via MMU with 4KB paging and 64-entry TLB
- **8MB emulated RAM** with bounds-checked access
- **32-bit and 64-bit load/store operations** with little-endian byte ordering
- Direct memory read/write primitives for testing
#### Key Components:
**Memory Backend** (`memory.rs`)
- 8MB RAM allocation with bounds checking on all accesses (`dynarmic_interface.rs`)
- Atomic operations support (compare-and-swap, atomic add)
- Exclusive monitor for ARM load/store exclusive instructions
- Direct C interface for Dynarmic integration
**Memory Management Unit** (`mmu/`)
- Virtual to physical address translation
- Sparse page table implementation with permission flags
- Translation Lookaside Buffer (TLB) with FIFO replacement
### GUI (via `eframe`)
- Built-in GUI based on `egui`
- Provides:
- Real-time test result display with pass/fail indicators
- Execution timing statistics
- Clean, responsive interface
## Testing & Verification
```
🧪 Starting Dynarmic JIT Instruction Tests...
Starting Unicorn Instruction Tests...
Base address: 0x0000000000001000
Using run() with breakpoints for reliable execution
Breakpoint address: 0x0000000000002000
✅ NOP - PASS (24.3ms)
✅ ADD X1, X1, #2 - PASS (22.9ms)
✅ SUB X2, X2, #1 - PASS (23.4ms)
✅ ADD X0, X0, X1 - PASS (23.2ms)
✅ MOV X3, X4 - PASS (23.8ms)
✅ B +8 - PASS (24.1ms)
✅ RET - PASS (23.0ms)
✅ Atomic ADD Test - PASS (23.0ms)
✅ Memory Access Pattern - PASS (23.7ms)
✅ Multiple Arithmetic Ops - PASS (22.2ms)
Warming up Unicorn emulator...
JIT warmup completed in 199.4µs
Running test: NOP
Running test: ADD X1, X1, #2
Running test: SUB X2, X2, #1
Running test: ADD X0, X0, X1
Running test: MOV X3, X4
Running test: B +8
Running test: RET
Running test: Atomic ADD Test
Running test: Memory Access Pattern (3 instructions)
Running test: Multiple Arithmetic Ops (3 instructions)
📊 Test Summary:
Total tests: 10
Passed: 10 ✅
Failed: 0 ❌
Total time: 254.8ms
Total time: 18.7ms
```
## GUI (via `eframe`)
- Built-in GUI based on `egui`
- Provides:
- Test result display
- Real-time execution statistics
## How to Run
```shell
git clone --recurse-submodules https://github.com/0xNikilite/oboromi
git clone https://github.com/0xNikilite/oboromi
cd oboromi
# Build and run (requires CMake and Ninja)
cargo run
```
The build system will automatically:
- Handle architecture-specific linking (Zydis/Zycore on x86_64 only)
- Compile the C++ interface
- Run the test suite when clicked on the main button
- Compile the Unicorn Engine C++ bindings
- Link required libraries
- Launch the GUI with integrated test suite
## Platform-Specific Notes
### Prerequisites
### Windows
- Supports both MSVC and MinGW toolchains
- Automatic library linking for Windows APIs
### macOS
- First test run may be slower due to JIT compilation
- Native support for both Intel and Apple Silicon
### Linux
- nothing to note
- **Rust** (latest stable)
- **CMake** (3.16+)
- **Ninja** build system
- **C++ compiler**: MSVC (Windows), Clang (macOS/Linux)
## Contributing
@@ -128,7 +117,7 @@ See [LICENSE](LICENSE) for details.
* [Rust Lang](https://www.rust-lang.org/)
* [AArch64 ISA Reference](https://developer.arm.com/documentation/ddi0602/latest/)
* [egui](https://github.com/emilk/egui)
* [Dynarmic (my fork)](https://github.com/0xNikilite/dynarmic)
* [Unicorn Engine](https://www.unicorn-engine.org/)
* [official mirror](https://git.eden-emu.dev/Nikilite/oboromi)
---

2
oboromi-core/src/tests/run.rs
View File

@@ -386,7 +386,7 @@ pub fn run_tests() -> Vec<String> {
let mut results = Vec::new();
let start_time = Instant::now();
println!("🧪 Starting Dynarmic JIT Instruction Tests...");
println!("Starting Unicorn Instruction Tests...");
println!(" Base address: 0x{:016X}", TEST_BASE_ADDR);
println!(" Breakpoint address: 0x{:016X}", BREAKPOINT_ADDR);
println!();