docs: update POSIX roadmap and current kernel features

diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md
index 0572a444421149e769138589bfa1138f6d0dfe00..fbe2490f80de67f32bd09469f8692e605fe4afd0 100644 (file)
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -44,10 +44,20 @@ This produces `adros-x86.iso`.
 make ARCH=x86 run
 ```
 
+If you are iterating on kernel changes and want to avoid hanging runs, you can wrap it with a timeout:
+```bash
+timeout 60s make ARCH=x86 run || true
+```
+
 Generated outputs/artifacts:
 - `serial.log`: UART log (primary kernel output)
 - `qemu.log`: only generated when QEMU debug logging is enabled (see below)
 
+Static analysis helper:
+```bash
+make ARCH=x86 cppcheck
+```
+
 To enable QEMU debug logging (disabled by default to avoid excessive I/O):
 ```bash
 make ARCH=x86 run QEMU_DEBUG=1

diff --git a/README.md b/README.md
index f7ab93e8e4c6923e8f5c95d504853ed3fdfe4dc0..da917ab5a66e4d86c9574d7f5f056d0676f1a08f 100644 (file)
--- a/README.md
+++ b/README.md
@@ -35,15 +35,23 @@ AdrOS is a multi-architecture operating system developed for research and academ
   - PIT timer + periodic tick
 - **Kernel services**
   - Simple scheduler / multitasking (kernel threads)
-  - Basic shell with built-in commands
-- **InitRD + VFS glue**
-  - InitRD-backed filesystem node tree
-  - Minimal VFS helpers (`vfs_read`/`vfs_write`/open/close)
-- **Syscalls & ring3 bring-up (x86)**
+  - Basic shell with built-in commands (fallback when userspace fails)
+- **InitRD + VFS (read-only)**
+  - InitRD image in TAR/USTAR format (with directory support)
+  - InitRD-backed filesystem node tree (`fs_node_t` + `finddir`)
+  - Absolute path lookup (`vfs_lookup("/bin/init.elf")`)
+- **File descriptors + syscalls (x86)**
   - `int 0x80` syscall gate
-  - `SYSCALL_WRITE`, `SYSCALL_EXIT`, `SYSCALL_GETPID`
+  - `SYSCALL_WRITE`, `SYSCALL_EXIT`, `SYSCALL_GETPID`, `SYSCALL_OPEN`, `SYSCALL_READ`, `SYSCALL_CLOSE`
+  - Per-process fd table (starting at fd=3)
   - Centralized user-pointer access API (`user_range_ok`, `copy_from_user`, `copy_to_user`)
-  - Ring3 stub test program with fault-injection for invalid pointers
+  - Ring3 init program (`/bin/init.elf`) exercising open/read/close
+- **TTY (canonical line discipline)**
+  - Keyboard -> TTY input path
+  - Canonical mode input (line-buffered until `\n`)
+  - Echo + backspace handling
+  - Blocking reads with a simple wait queue (multiple waiters)
+  - `fd=0` wired to `tty_read`, `fd=1/2` wired to `tty_write`
 - **W^X (Option 1) for user ELFs (x86)**
   - User segments are mapped RW during load, then write permissions are dropped for non-writable segments
   - This provides "text is read-only" hardening without requiring NX/PAE
@@ -63,15 +71,27 @@ QEMU debug helpers:
 - **Multi-architecture kernel bring-up**
   - Implement VMM/interrupts/scheduler for ARM/RISC-V/MIPS
   - Standardize arch entrypoint behavior (`arch_early_setup`) across architectures
-- **Userspace**
-  - Process model (fork/exec/wait), per-process address spaces, and cleanup on `exit`
-  - Syscall ABI expansion (read/open/close, file descriptors, etc.)
+- **Userspace / POSIX process model**
+  - Per-process address spaces (currently a single shared address space)
+  - `fork`, `execve`, `waitpid`, `getppid`, `brk`/`sbrk`
+  - Proper process lifecycle: `exit` cleanup, zombies, reaping
+  - Signals (at least `SIGKILL`/`SIGSEGV` basics)
+- **Syscalls / ABI**
+  - `dup`, `dup2`, `pipe`, `ioctl` (TTY), `stat`, `fstat`, `lseek`, `getcwd`, `chdir`
+  - Error reporting via `errno` conventions
 - **Virtual memory hardening**
   - Option 2: PAE + NX enforcement (execute disable for data/stack)
   - Guard pages, and tighter user/kernel separation checks
 - **Filesystem**
+  - VFS mount table (multiple filesystems)
   - Persisted storage (ATA/AHCI/virtio-blk or similar)
-  - Path resolution, directories, permissions
+  - Permissions/ownership (`uid/gid`, mode bits) and `umask`
+  - Special files: char devices, block devices, `/dev`, `/proc`
+  - Writable fs (tmpfs) and a real on-disk fs (ext2/fat)
+- **TTY / PTY**
+  - Termios-like mode flags (canonical/raw, echo, erase, intr)
+  - Sessions / process groups / controlling terminal
+  - PTYs for userland shells
 - **Observability & tooling**
   - Better memory stats (`mem` shell command)
   - Debug facilities (panic backtraces, symbolization, structured logs)

diff --git a/docs/POSIX_ROADMAP.md b/docs/POSIX_ROADMAP.md
new file mode 100644 (file)
index 0000000..f6d3713
--- /dev/null
+++ b/docs/POSIX_ROADMAP.md
@@ -0,0 +1,177 @@
+# AdrOS POSIX Roadmap (Checklist)
+
+This document tracks **what is already implemented** versus **what is missing** to reach a practical Unix-like system with increasing POSIX compatibility.
+
+Notes:
+- This is intentionally pragmatic: items are ordered to unlock userland capabilities quickly.
+- Checkboxes reflect the current state of the `master` branch.
+
+## Status Legend
+- `[x]` implemented (works end-to-end)
+- `[~]` partial (exists but incomplete/limited)
+- `[ ]` not implemented
+
+---
+
+## 0) Current Baseline (Already in tree)
+
+### Boot / platform / core kernel
+- [x] x86 (i386) boot via GRUB2 Multiboot2
+- [x] Higher-half kernel mapping
+- [x] IDT + IRQ enable
+- [x] Basic scheduler / kernel threads
+- [x] Timer tick
+- [x] Kernel heap (`kmalloc`/`kfree`)
+- [~] Multi-arch stubs (ARM/RISC-V/MIPS) (not functionally brought up)
+
+### InitRD + filesystem basics
+- [x] InitRD format: TAR/USTAR
+- [x] InitRD directory tree support
+- [x] `fs_node_t` abstraction with `read/finddir` for InitRD nodes
+- [x] `vfs_lookup()` absolute path resolver
+- [~] VFS is currently “single-root tree” (no mounts, no multiple fs)
+- [ ] Writable filesystem support
+
+### Userspace bring-up
+- [x] ELF32 userspace loader from VFS (`/bin/init.elf`)
+- [~] Process model is minimal (no fork/exec/wait lifecycle)
+- [x] `int 0x80` syscall entry (x86)
+
+### Syscalls (current)
+- [x] `write(fd=1/2)`
+- [x] `exit()` (currently halts in kernel)
+- [x] `getpid()` (placeholder)
+- [x] `open()` (read-only)
+- [x] `read()` (files + stdin)
+- [x] `close()`
+
+### FD layer
+- [x] Per-process fd table (fd allocation starts at 3)
+- [x] File read offset tracking
+- [~] No `dup/dup2`, no `pipe`, no `lseek`
+
+### TTY
+- [x] TTY canonical input (line-buffered until `\n`)
+- [x] Echo + backspace handling
+- [x] Blocking reads (process `BLOCKED`) + wait queue (multiple waiters)
+- [x] `fd=0` wired to `tty_read`, `fd=1/2` wired to `tty_write`
+- [ ] Termios-like configuration
+- [ ] PTY
+
+---
+
+## 1) Milestone A1 — Process lifecycle: `waitpid` + cleanup on `exit`
+
+Goal: make process termination and waiting work reliably; unblock shells and service managers.
+
+### Kernel process lifecycle
+- [ ] Introduce parent/child relationship tracking
+- [ ] Track exit status per process
+- [ ] Transition to `PROCESS_ZOMBIE` on exit
+- [ ] Reap zombie processes and free resources
+
+### `exit()` cleanup
+- [ ] Close all open file descriptors for the process
+- [ ] Release process memory resources (as applicable in current model)
+- [ ] Remove process from run queues safely
+
+### `waitpid()` syscall
+- [ ] Add syscall number + userland wrapper
+- [ ] `waitpid(-1, ...)` wait for any child
+- [ ] `waitpid(pid, ...)` wait for specific child
+- [ ] Non-blocking mode (optional early): `WNOHANG`
+- [ ] Return semantics consistent with POSIX (pid on success, -1 on error)
+
+### Tests
+- [ ] Userspace test: parent spawns child, child exits, parent waits, validates status
+- [ ] Regression: ensure keyboard/TTY still works
+
+---
+
+## 2) Milestone A2 — Address spaces per process
+
+Goal: move from a shared address space to per-process virtual memory, required for real isolation and POSIX process semantics.
+
+### Core VM changes
+- [ ] Per-process page directory / page tables
+- [ ] Context switch also switches address space
+- [ ] Kernel mapped in all address spaces
+- [ ] User/kernel separation rules enforced
+
+### Syscall/uaccess hardening
+- [ ] Ensure `user_range_ok` is robust across per-process mappings
+- [ ] Page-fault handling for invalid user pointers (deliver `SIGSEGV` later)
+
+### Userspace loader
+- [ ] ELF loader targets the new process address space
+- [ ] User stack per process
+
+### Tests
+- [ ] Smoke: boot + run `/bin/init.elf`
+- [ ] Two-process test: verify isolation (write to memory in one does not affect other)
+
+---
+
+## 3) Milestone B1 — POSIX-ish file API basics (`lseek`, `stat/fstat`)
+
+Goal: unlock standard libc-style IO patterns.
+
+### Syscalls
+- [ ] `lseek(fd, off, whence)`
+- [ ] `stat(path, struct stat*)`
+- [ ] `fstat(fd, struct stat*)`
+
+### Kernel data model
+- [ ] Define minimal `struct stat` ABI (mode/type/size/inode)
+- [ ] Map InitRD node metadata to `stat`
+
+### Error model
+- [ ] Start introducing `errno`-style error returns (strategy decision: negative errno vs -1 + errno)
+
+### Tests
+- [ ] Userspace test: open -> fstat -> read -> lseek -> read
+
+---
+
+## 4) Milestone C1 — Mounts + `tmpfs` (writable)
+
+Goal: get a writable filesystem (even if volatile) and a real VFS layout.
+
+### VFS mounts
+- [ ] Mount table support
+- [ ] `vfs_lookup` resolves across mounts
+- [ ] Mount InitRD at `/` or at `/initrd` (decision)
+
+### `tmpfs`
+- [ ] In-memory inode/dentry model
+- [ ] Create/unlink
+- [ ] Read/write
+- [ ] Directories
+
+### Devices (minimum Unix feel)
+- [ ] `/dev` mount
+- [ ] `/dev/tty`
+- [ ] `/dev/null`
+
+### Tests
+- [ ] Userspace test: create file in tmpfs, write, read back
+
+---
+
+## 5) Later milestones (not started)
+
+### Process / POSIX expansion
+- [ ] `fork()`
+- [ ] `execve()`
+- [ ] `getppid()`
+- [ ] Signals + basic job control
+
+### Pipes + IO multiplexing
+- [ ] `pipe()`
+- [ ] `dup/dup2`
+- [ ] `select/poll`
+
+### TTY advanced
+- [ ] termios flags (canonical/raw/echo)
+- [ ] controlling terminal, sessions, pgrp
+- [ ] PTY for userland shells