# Strix OS — Developer Notes

> **READ THIS FIRST after a context reset.** Then read `PLAN.md` for the full roadmap.
> Updated at every commit.

---

## How to Resume After Context Reset

1. Read this file top-to-bottom
2. Read `PLAN.md` — check the Progress Tracker table for current status
3. Run `cargo test` from `StrixKernel/` to confirm current build state
4. Continue from the first `🔲 TODO` item in PLAN.md

---

## Current Status

**Branch**: `CLAUDE_TEST`
**Phase**: Starting Phase 2 — User Space Foundation
**Last commit**: `[Step 0] Add PLAN.md and NOTES.md`
**Next task**: `[Phase 2.1]` — Extend GDT with user space segments

---

## Key Decisions & Rationale

| Decision | Rationale |
|----------|-----------|
| ext4 as primary filesystem | Nix requires symlinks, xattrs, POSIX perms; ext4 covers all. Impl as ext2 first |
| SYSCALL/SYSRET for syscall interface | Faster than int 0x80; Linux ABI compatible |
| GDT segment order: kcode/kdata/udata/ucode/tss | Required for STAR MSR arithmetic (see Phase 2.1 notes) |
| Heap 100 KiB → 4 MiB | Process table (256 entries) + 64 KiB kernel stacks needs > 16 MiB; start at 4 MiB |
| goblin crate for ELF parsing | no_std compatible, well-maintained, handles ELF64 |
| Embedded busybox initramfs | Self-contained rescue shell; no disk dependency for Phase 3 testing |
| OpenRC default init, `init=` configurable | Lightweight; swappable without kernel changes |
| W^X enforced on all mappings | Prevents code injection via data segments |
| All user pointers validated | Prevents kernel memory disclosure/corruption via syscalls |

---

## Architecture Notes

### GDT Segment Order (Critical for SYSCALL/SYSRET)
```
0x00: null
0x08: kernel code (DPL=0)  ← STAR[47:32]
0x10: kernel data (DPL=0)  ← auto: SYSCALL sets SS = CS+8
0x18: user data (DPL=3)    ← SYSRET: SS = STAR[63:48]+8
0x20: user code (DPL=3)    ← SYSRET: CS = STAR[63:48]+16
0x28/0x30: TSS (128-bit)
```
STAR MSR values: `STAR[47:32]=0x08`, `STAR[63:48]=0x10`

### Heap Layout
```
HEAP_START = 0x4444_4444_0000
HEAP_SIZE  = 4 MiB (was 100 KiB)
```

### Key Virtual Address Constants
```
Physical memory offset: 0x0000_2560_0000_0000 (from bootloader)
Heap start:             0x4444_4444_0000
User stack top:         0x7fff_f000_0000 (8 MiB stack)
User address limit:     0x0000_8000_0000_0000 (canonical boundary)
```

---

## Log

### [Step 0] 2026-04-08 — Bootstrap repo docs
**Done**: Created `PLAN.md` (full roadmap with progress tracker) and `NOTES.md` (this file).
**Next**: Phase 2.1 — Extend GDT.
**Decisions**: None new.

---