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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
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.
|
