1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
|
# 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 0-1 (foundational infrastructure).
## 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 |
| `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
- `OffsetPageTable` translates virtual ↔ physical addresses
- `BootInfoFrameAllocator` provides frames from bootloader's memory map
### 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. Next priorities:
1. Heap allocator (GlobalAlloc implementation)
2. User space (Ring 3 transition, syscall interface)
3. Process management (fork, exec, scheduler)
|
