diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..9c6a99e --- /dev/null +++ b/README.md @@ -0,0 +1,144 @@ +# Strix OS + +A bare-metal x86-64 operating system kernel written in Rust, designed for eventual Linux application compatibility. + +## Overview + +Strix OS is a hobby operating system project that starts from first principles: no standard library, no operating system, just raw hardware. The long-term goal is to run Linux applications (ELF binaries with syscall compatibility), making it a practical learning platform for OS development. + +### Current Status: Phase 0-1 (Foundational Infrastructure) + +The kernel boots, handles interrupts, displays text, and manages memory at a basic level: + +| Component | Status | +|-----------|--------| +| GDT/TSS/IDT | Configured with double-fault stack | +| Interrupts | Timer (PIT), keyboard (PS/2), page faults | +| VGA Text Mode | 80x25 with `print!`/`println!` macros | +| Serial Output | UART 16550 for debugging | +| Page Tables | Read access via OffsetPageTable | +| Frame Allocator | Bump allocator from bootloader memory map | + +**Not yet implemented:** Heap allocation, user space, syscalls, file systems, process management. + +## Building + +### Prerequisites + +- **Rust nightly toolchain** (specified in `rust-toolchain`) +- **QEMU** for running and testing + +### Commands + +All commands run from the `StrixKernel/` directory: + +```bash +# Build the kernel +cargo build + +# Build and run in QEMU +cargo run + +# Run all tests +cargo test + +# Run a specific integration test +cargo test --test basic_boot +cargo test --test stack_overflow +cargo test --test should_panic +``` + +## Project Structure + +``` +. +├── CLAUDE.md # AI assistant instructions +├── roadmap.md # Development roadmap (6 phases) +├── README.md # This file +└── StrixKernel/ + ├── Cargo.toml # Dependencies and build config + ├── x86_64-strix_os.json # Custom target specification + ├── src/ + │ ├── main.rs # Kernel entry point, panic handlers + │ ├── lib.rs # Core library, test framework + │ ├── gdt.rs # Global Descriptor Table + TSS + │ ├── interrupts.rs # IDT, exception/IRQ handlers + │ ├── memory.rs # Page tables, frame allocation + │ ├── vga_buffer.rs # VGA text mode output + │ └── serial.rs # Serial port debugging + └── tests/ + ├── basic_boot.rs # Smoke test for boot process + ├── stack_overflow.rs # IST stack switching test + └── should_panic.rs # Panic handler test +``` + +## Architecture + +### Boot Process + +1. **Bootloader** (bootloader crate v0.9) loads kernel ELF and sets up paging +2. **Entry point** (`kernel_main` in `main.rs`) receives `BootInfo` +3. **Initialization** (`strix_os::init()`) sets up GDT → IDT → PICs +4. **Halt loop** waits for interrupts + +### Memory Model + +The bootloader maps all physical memory at a fixed virtual offset (`0x0000256000000000`). This enables: + +- **OffsetPageTable**: Simple virtual ↔ physical translation +- **BootInfoFrameAllocator**: Allocates frames from the bootloader's memory map + +### Interrupt Handling + +| Vector | Source | Handler | +|--------|--------|---------| +| 3 | Breakpoint | Prints debug info | +| 8 | Double Fault | Uses IST stack, panics | +| 14 | Page Fault | Prints fault info, panics | +| 32 | Timer (IRQ0) | Increments tick counter | +| 33 | Keyboard (IRQ1) | Translates scancodes, prints | + +The 8259 PIC remaps IRQs 0-15 to vectors 32-47 to avoid conflicts with CPU exceptions. + +### Test Framework + +Tests run as separate kernel instances in QEMU: + +- Output goes to serial port (`-serial stdio`) +- Exit codes via ISA debug device (port 0xf4) +- Success = 0x10 (QEMU exit 33), Failure = 0x11 (QEMU exit 35) + +## Roadmap + +See [roadmap.md](roadmap.md) for the full 6-phase development plan: + +1. **Memory Management** - Heap allocator, advanced paging +2. **User Space Foundation** - Ring 3, syscalls, processes +3. **ELF Loading** - execve(), static binaries +4. **Virtual File System** - VFS layer, ramfs, devfs +5. **POSIX Essentials** - Signals, pipes, process groups +6. **Init System** - TTY, mount, OpenRC support + +## Key Dependencies + +| Crate | Purpose | +|-------|---------| +| `bootloader` | Creates bootable image, provides BootInfo | +| `x86_64` | CPU structures (GDT, IDT, page tables) | +| `volatile` | Memory-mapped I/O without optimization | +| `spin` | Spinlocks for no_std | +| `lazy_static` | Lazy initialization for statics | +| `uart_16550` | Serial port driver | +| `pic8259` | Interrupt controller driver | +| `pc-keyboard` | PS/2 scancode translation | + +## Resources + +- [Writing an OS in Rust](https://os.phil-opp.com/) - Primary learning resource +- [OSDev Wiki](https://wiki.osdev.org/) - x86 hardware documentation +- [Intel SDM](https://software.intel.com/en-us/articles/intel-sdm) - Official CPU manuals +- [Linux Syscall Table](https://blog.rchapman.org/posts/Linux_System_Call_Table_for_x86_64/) - Syscall reference + +## License + +This project is for educational purposes. |