# 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.