# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Strix OS** is a bare-metal x86-64 operating system kernel written in Rust, aiming for Linux application compatibility. Currently in Phase 1 (memory management complete, heading into user space).

## Build Commands

All commands run from `/StrixKernel/`:

```bash
# Build the kernel
cargo build

# Build and run in QEMU
cargo run

# Run all tests (unit + integration)
cargo test

# Run a specific integration test
cargo test --test basic_boot
cargo test --test stack_overflow

# Clean build artifacts
cargo clean
```

**Requirements**: Rust nightly toolchain (specified in `rust-toolchain`), QEMU for running/testing.

## Architecture

### Boot Flow
1. Bootloader (bootloader crate 0.9) loads kernel and provides `BootInfo` with memory map and physical memory offset
2. `kernel_main()` in `main.rs` receives control
3. `strix_os::init()` initializes GDT → IDT → PICs
4. Kernel enters `hlt_loop()` waiting for interrupts

### Core Modules (`StrixKernel/src/`)

| Module | Purpose |
|--------|---------|
| `gdt.rs` | Global Descriptor Table + Task State Segment (double-fault stack) |
| `interrupts.rs` | IDT setup, exception handlers, hardware interrupts (timer/keyboard via PIC 8259) |
| `memory.rs` | Page table access (`OffsetPageTable`), `BootInfoFrameAllocator` for physical frames |
| `allocator.rs` | Heap allocator dispatcher; `HEAP_START`/`HEAP_SIZE` constants; `init_heap()` |
| `allocator/bump.rs` | Simple bump allocator (fast alloc, dealloc only when all freed) |
| `allocator/linked_list.rs` | First-fit linked-list allocator (arbitrary alloc/dealloc) |
| `allocator/fixed_size_block.rs` | **Active**: hybrid fixed-size block allocator with 9 size classes (8–2048 bytes) + linked-list fallback |
| `vga_buffer.rs` | VGA text mode (80x25), `print!`/`println!` macros |
| `serial.rs` | UART 16550 serial output, `serial_print!`/`serial_println!` for debugging |

### Memory Model
- Uses bootloader's `map_physical_memory` feature: all physical memory mapped at a fixed offset (`0x0000256000000000`)
- `OffsetPageTable` translates virtual ↔ physical addresses
- `BootInfoFrameAllocator` provides frames from bootloader's memory map
- Heap region: virtual address `0x4444_4444_0000`, size 100 KiB

### Test Framework
- Custom `#[test_case]` attribute with `Testable` trait
- Tests output to serial port (QEMU `-serial stdio`)
- QEMU exit codes: `0x10` = success, `0x11` = failure
- Integration tests in `tests/` run as separate kernel instances

## Key Patterns

- **Lazy statics with spinlocks**: `lazy_static!` + `spin::Mutex` for global mutable state (no std)
- **Volatile writes**: VGA buffer uses `volatile` crate to prevent optimization
- **x86_64 crate**: Provides CPU structures (GDT, IDT, page tables) and port I/O

## Target Specification

`x86_64-strix_os.json` defines the custom target:
- No OS, no standard library
- Disables red zone, uses soft floats
- Panic strategy: abort

## Roadmap

See `roadmap.md` for the 6-phase development plan. Phase 1 (memory management) is complete. Next priorities:
1. User space (Ring 3 transition, syscall interface via SYSCALL/SYSRET MSRs)
2. ELF loading (parser + execve)
3. Process management (fork, exec, scheduler)