path: root/roadmap.md

# Strix OS Roadmap: Linux Application Compatibility

This roadmap outlines the path from the current kernel state to full Linux application compatibility.

## Current State

The kernel has a solid foundation:
- GDT/TSS/IDT properly configured
- Interrupt handling (timer, keyboard, page fault exceptions)
- VGA text mode output + serial debugging
- PS/2 keyboard input with scancode translation

**Missing for Linux compatibility**: heap allocation, paging control, user-space, syscalls, processes, VFS, ELF loader.

---

## Phase 1: Memory Management

### 1.1 - Page Table Access
- [ ] Access bootloader's page tables via BootInfo
- [ ] Implement page table walking (translate virtual → physical)
- [ ] Create OffsetPageTable or RecursivePageTable mapper
- **Files**: `src/memory.rs`

### 1.2 - Frame Allocator
- [ ] Parse memory map from bootloader
- [ ] Implement FrameAllocator trait
- [ ] Track used/free physical frames (bitmap or linked list)
- **Files**: `src/memory/frame_allocator.rs`

### 1.3 - Heap Allocator
- [ ] Map heap region in virtual memory
- [ ] Implement GlobalAlloc (linked_list_allocator crate or custom)
- [ ] Enable alloc crate (Vec, Box, String, etc.)
- **Files**: `src/allocator.rs`

**Dependencies to add:**
```toml
linked_list_allocator = "0.9.0"
```

---

## Phase 2: User Space Foundation

### 2.1 - Ring 3 Transition
- [ ] Set up user-mode GDT segments (ring 3 code/data)
- [ ] Create per-process page tables
- [ ] Implement context switch (save/restore registers)
- [ ] Use IRET to jump to ring 3
- **Files**: `src/gdt.rs` (extend), `src/task/mod.rs`

### 2.2 - System Call Interface
- [ ] Set up SYSCALL/SYSRET MSRs (STAR, LSTAR, SFMASK)
- [ ] Create syscall entry point in assembly
- [ ] Implement syscall dispatcher
- [ ] Start with: write, exit, mmap (minimal set)
- **Files**: `src/syscall/mod.rs`, `src/syscall/handler.S`

### 2.3 - Basic Process Structure
- [ ] Process struct (pid, page table, registers, state)
- [ ] Process list/table
- [ ] Simple round-robin scheduler
- [ ] fork() and exit() syscalls
- **Files**: `src/task/process.rs`, `src/task/scheduler.rs`

---

## Phase 3: ELF Loading & exec()

### 3.1 - ELF Parser
- [ ] Parse ELF64 header and program headers
- [ ] Identify PT_LOAD segments
- [ ] Handle static binaries first
- **Files**: `src/loader/elf.rs`

### 3.2 - execve() Implementation
- [ ] Load ELF into fresh address space
- [ ] Set up user stack with argc/argv/envp
- [ ] Set up auxiliary vector (AT_ENTRY, AT_PHDR, etc.)
- [ ] Jump to entry point
- **Files**: `src/syscall/exec.rs`

**Dependencies to add:**
```toml
xmas-elf = "0.9.0"  # or goblin for ELF parsing
```

---

## Phase 4: Virtual File System

### 4.1 - VFS Layer
- [ ] Define File, Inode, Superblock traits
- [ ] File descriptor table per process
- [ ] open(), read(), write(), close(), lseek()
- **Files**: `src/fs/vfs.rs`, `src/fs/fd.rs`

### 4.2 - In-Memory Filesystems
- [ ] ramfs/tmpfs for root filesystem
- [ ] devfs (/dev/null, /dev/zero, /dev/console)
- [ ] procfs (/proc/self/*, /proc/[pid]/*)
- **Files**: `src/fs/ramfs.rs`, `src/fs/devfs.rs`, `src/fs/procfs.rs`

### 4.3 - Disk Filesystem
- [ ] ATA/AHCI driver
- [ ] ext2/ext4 read support (start read-only)
- [ ] mount() syscall
- **Files**: `src/drivers/ata.rs`, `src/fs/ext2.rs`

---

## Phase 5: POSIX Essentials

### 5.1 - Signals
- [ ] Signal delivery mechanism
- [ ] Default handlers (SIGKILL, SIGTERM, SIGSEGV)
- [ ] sigaction(), kill() syscalls
- **Files**: `src/task/signal.rs`

### 5.2 - Pipes & IPC
- [ ] pipe() syscall
- [ ] dup(), dup2() for fd manipulation
- [ ] Anonymous pipes for shell support
- **Files**: `src/fs/pipe.rs`

### 5.3 - Wait & Process Groups
- [ ] wait4(), waitpid() syscalls
- [ ] Process groups, sessions
- [ ] Foreground/background processes
- **Files**: `src/task/wait.rs`

---

## Phase 6: Init System Support (OpenRC)

### 6.1 - Required Syscalls & Filesystems
- [ ] mount(), umount() syscalls
- [ ] Working /proc and /sys
- [ ] chroot(), pivot_root()
- [ ] Basic TTY/PTY support
- **Files**: `src/syscall/mount.rs`, `src/fs/sysfs.rs`

### 6.2 - Device Management
- [ ] /dev population (static or dynamic)
- [ ] ioctl() for device control
- [ ] Console/TTY driver
- **Files**: `src/drivers/tty.rs`

---

## Suggested Directory Structure

```
src/
├── main.rs
├── lib.rs
├── memory/
│   ├── mod.rs
│   ├── paging.rs
│   ├── frame_allocator.rs
│   └── heap.rs
├── task/
│   ├── mod.rs
│   ├── process.rs
│   ├── scheduler.rs
│   ├── context.rs
│   └── signal.rs
├── syscall/
│   ├── mod.rs
│   ├── handler.rs
│   ├── table.rs          # syscall number → handler mapping
│   ├── fs.rs             # open, read, write, close
│   ├── process.rs        # fork, exec, exit, wait
│   └── memory.rs         # mmap, munmap, brk
├── fs/
│   ├── mod.rs
│   ├── vfs.rs
│   ├── fd.rs
│   ├── ramfs.rs
│   ├── devfs.rs
│   └── procfs.rs
├── loader/
│   └── elf.rs
└── drivers/
    ├── tty.rs
    └── ata.rs
```

---

## Linux Syscall Priority List

Essential syscalls to implement (roughly in order of importance):

### Tier 1 - Minimal Execution
| Syscall | Number | Purpose |
|---------|--------|---------|
| write | 1 | Output to console/files |
| exit | 60 | Terminate process |
| exit_group | 231 | Terminate all threads |
| brk | 12 | Heap memory allocation |
| mmap | 9 | Memory mapping |
| munmap | 11 | Unmap memory |

### Tier 2 - Process Management
| Syscall | Number | Purpose |
|---------|--------|---------|
| fork | 57 | Create child process |
| clone | 56 | Create thread/process |
| execve | 59 | Execute program |
| wait4 | 61 | Wait for child |
| getpid | 39 | Get process ID |
| getppid | 110 | Get parent PID |

### Tier 3 - File Operations
| Syscall | Number | Purpose |
|---------|--------|---------|
| read | 0 | Read from fd |
| open | 2 | Open file |
| close | 3 | Close fd |
| stat | 4 | File information |
| fstat | 5 | File info by fd |
| lseek | 8 | Seek in file |
| dup | 32 | Duplicate fd |
| dup2 | 33 | Duplicate to specific fd |
| pipe | 22 | Create pipe |
| ioctl | 16 | Device control |

### Tier 4 - Signals & Advanced
| Syscall | Number | Purpose |
|---------|--------|---------|
| rt_sigaction | 13 | Signal handlers |
| rt_sigprocmask | 14 | Block signals |
| kill | 62 | Send signal |
| getcwd | 79 | Current directory |
| chdir | 80 | Change directory |
| mount | 165 | Mount filesystem |
| umount2 | 166 | Unmount filesystem |

---

## Resources

- [Linux x86_64 Syscall Table](https://blog.rchapman.org/posts/Linux_System_Call_Table_for_x86_64/)
- [OSDev Wiki](https://wiki.osdev.org/)
- [Writing an OS in Rust (blog_os)](https://os.phil-opp.com/)
- [POSIX.1-2017 Specification](https://pubs.opengroup.org/onlinepubs/9699919799/)
- [musl libc source](https://musl.libc.org/) - Clean syscall reference
- [Linux kernel source](https://github.com/torvalds/linux) - `arch/x86/entry/syscalls/syscall_64.tbl`