docs: update POSIX/Unix feature status

Refresh README, build guide, and POSIX roadmap to reflect implemented syscalls (dup/dup2/pipe/fork/execve), mounts/tmpfs/overlayfs, analysis targets, and remaining gaps.

diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md
index fbe2490f80de67f32bd09469f8692e605fe4afd0..7356448b6d3c18ae4f01569682cf7557c7ed1de0 100644 (file)
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -30,6 +30,11 @@ make ARCH=x86
 ```
 This produces `adros-x86.bin`.
 
+If you have an `i686-elf-*` cross toolchain installed, you can build using it via:
+```bash
+make ARCH=x86 CROSS=1
+```
+
 ### Create a bootable ISO (GRUB)
 For x86, the repository includes an `iso/` tree with GRUB already configured.
 
@@ -58,6 +63,12 @@ Static analysis helper:
 make ARCH=x86 cppcheck
 ```
 
+Additional analysis helpers:
+```bash
+make ARCH=x86 scan-build
+make ARCH=x86 mkinitrd-asan
+```
+
 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 da917ab5a66e4d86c9574d7f5f056d0676f1a08f..6e1e9090ea8fd49da9dbc53adbed54c634a5197c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -35,17 +35,22 @@ AdrOS is a multi-architecture operating system developed for research and academ
   - PIT timer + periodic tick
 - **Kernel services**
   - Simple scheduler / multitasking (kernel threads)
+  - Minimal process lifecycle: parent/child tracking, zombies, `waitpid`
   - Basic shell with built-in commands (fallback when userspace fails)
-- **InitRD + VFS (read-only)**
+- **InitRD + VFS + mounts**
   - 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")`)
+  - Mount table support (`vfs_mount`) + `tmpfs` and `overlayfs`
 - **File descriptors + syscalls (x86)**
   - `int 0x80` syscall gate
   - `SYSCALL_WRITE`, `SYSCALL_EXIT`, `SYSCALL_GETPID`, `SYSCALL_OPEN`, `SYSCALL_READ`, `SYSCALL_CLOSE`
+  - `SYSCALL_LSEEK`, `SYSCALL_STAT`, `SYSCALL_FSTAT`
+  - `SYSCALL_DUP`, `SYSCALL_DUP2`, `SYSCALL_PIPE`
+  - `SYSCALL_FORK`, `SYSCALL_EXECVE` (with minimal argv/envp stack setup)
   - Per-process fd table (starting at fd=3)
   - Centralized user-pointer access API (`user_range_ok`, `copy_from_user`, `copy_to_user`)
-  - Ring3 init program (`/bin/init.elf`) exercising open/read/close
+  - Ring3 init program (`/bin/init.elf`) exercising IO + process + exec smoke tests
 - **TTY (canonical line discipline)**
   - Keyboard -> TTY input path
   - Canonical mode input (line-buffered until `\n`)
@@ -72,22 +77,20 @@ QEMU debug helpers:
   - Implement VMM/interrupts/scheduler for ARM/RISC-V/MIPS
   - Standardize arch entrypoint behavior (`arch_early_setup`) across architectures
 - **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
+  - `getppid`, `brk`/`sbrk`
   - Signals (at least `SIGKILL`/`SIGSEGV` basics)
 - **Syscalls / ABI**
-  - `dup`, `dup2`, `pipe`, `ioctl` (TTY), `stat`, `fstat`, `lseek`, `getcwd`, `chdir`
+  - `ioctl` (TTY), `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)
+  - Real persisted storage (ATA/AHCI/virtio-blk or similar)
   - Persisted storage (ATA/AHCI/virtio-blk or similar)
   - 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)
+  - Real on-disk fs (ext2/fat)
 - **TTY / PTY**
   - Termios-like mode flags (canonical/raw, echo, erase, intr)
   - Sessions / process groups / controlling terminal
@@ -95,6 +98,7 @@ QEMU debug helpers:
 - **Observability & tooling**
   - Better memory stats (`mem` shell command)
   - Debug facilities (panic backtraces, symbolization, structured logs)
+  - CI-ish targets: `cppcheck`, `scan-build`, `mkinitrd-asan`
 
 ## Directory Structure
 - `src/kernel/` - Architecture-independent kernel code

diff --git a/docs/POSIX_ROADMAP.md b/docs/POSIX_ROADMAP.md
index f6d37137506d63d0ef4db19aa538c56294f26a7c..f15df61094a6ee9b39bdc48c8fd79c6d31559471 100644 (file)
--- a/docs/POSIX_ROADMAP.md
+++ b/docs/POSIX_ROADMAP.md
@@ -29,26 +29,36 @@ Notes:
 - [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
+- [x] VFS mount table support (`vfs_mount`)
+- [x] Writable filesystem support (`tmpfs`)
+- [x] `overlayfs` (copy-up overlay for root)
 
 ### Userspace bring-up
 - [x] ELF32 userspace loader from VFS (`/bin/init.elf`)
-- [~] Process model is minimal (no fork/exec/wait lifecycle)
+- [~] Process model is minimal, but Unix-like primitives exist (fork/exec/wait)
 - [x] `int 0x80` syscall entry (x86)
 
 ### Syscalls (current)
 - [x] `write(fd=1/2)`
-- [x] `exit()` (currently halts in kernel)
-- [x] `getpid()` (placeholder)
+- [x] `exit()` (closes FDs, marks zombie, notifies parent)
+- [~] `getpid()` (minimal)
 - [x] `open()` (read-only)
 - [x] `read()` (files + stdin)
 - [x] `close()`
+- [x] `waitpid()`
+- [x] `lseek()`
+- [x] `stat()` / `fstat()`
+- [x] `dup()` / `dup2()`
+- [x] `pipe()`
+- [x] `fork()`
+- [~] `execve()` (loads ELF from InitRD; minimal argv/envp)
 
 ### FD layer
 - [x] Per-process fd table (fd allocation starts at 3)
 - [x] File read offset tracking
-- [~] No `dup/dup2`, no `pipe`, no `lseek`
+- [x] `dup/dup2` with refcounted file objects
+- [x] `pipe()` with in-kernel ring buffer endpoints
+- [x] `lseek()`
 
 ### TTY
 - [x] TTY canonical input (line-buffered until `\n`)
@@ -65,25 +75,25 @@ Notes:
 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
+- [x] Introduce parent/child relationship tracking
+- [x] Track exit status per process
+- [x] Transition to `PROCESS_ZOMBIE` on exit
+- [x] 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
+- [x] Close all open file descriptors for the process
+- [x] Release process memory resources (kernel stack + user addr_space when reaped)
+- [~] Remove process from run queues safely (best-effort; continues improving)
 
 ### `waitpid()` syscall
-- [ ] Add syscall number + userland wrapper
-- [ ] `waitpid(-1, ...)` wait for any child
-- [ ] `waitpid(pid, ...)` wait for specific child
+- [x] Add syscall number + userland wrapper
+- [x] `waitpid(-1, ...)` wait for any child
+- [x] `waitpid(pid, ...)` wait for specific child
 - [ ] Non-blocking mode (optional early): `WNOHANG`
-- [ ] Return semantics consistent with POSIX (pid on success, -1 on error)
+- [~] Return semantics consistent with POSIX (pid on success, -1 on error)
 
 ### Tests
-- [ ] Userspace test: parent spawns child, child exits, parent waits, validates status
+- [x] Userspace test: parent forks children, children exit, parent waits, validates status
 - [ ] Regression: ensure keyboard/TTY still works
 
 ---
@@ -93,21 +103,21 @@ Goal: make process termination and waiting work reliably; unblock shells and ser
 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
+- [x] Per-process page directory / page tables
+- [x] Context switch also switches address space
+- [x] Kernel mapped in all address spaces
+- [~] User/kernel separation rules enforced (uaccess checks + no user mappings in kernel range)
 
 ### 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
+- [x] ELF loader targets the new process address space
+- [x] User stack per process
 
 ### Tests
-- [ ] Smoke: boot + run `/bin/init.elf`
+- [x] Smoke: boot + run `/bin/init.elf`
 - [ ] Two-process test: verify isolation (write to memory in one does not affect other)
 
 ---
@@ -117,19 +127,19 @@ Goal: move from a shared address space to per-process virtual memory, required f
 Goal: unlock standard libc-style IO patterns.
 
 ### Syscalls
-- [ ] `lseek(fd, off, whence)`
-- [ ] `stat(path, struct stat*)`
-- [ ] `fstat(fd, struct stat*)`
+- [x] `lseek(fd, off, whence)`
+- [x] `stat(path, struct stat*)`
+- [x] `fstat(fd, struct stat*)`
 
 ### Kernel data model
-- [ ] Define minimal `struct stat` ABI (mode/type/size/inode)
-- [ ] Map InitRD node metadata to `stat`
+- [x] Define minimal `struct stat` ABI (mode/type/size/inode)
+- [x] 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
+- [x] Userspace test: open -> fstat -> read -> lseek -> read
 
 ---
 
@@ -138,15 +148,15 @@ Goal: unlock standard libc-style IO patterns.
 Goal: get a writable filesystem (even if volatile) and a real VFS layout.
 
 ### VFS mounts
-- [ ] Mount table support
-- [ ] `vfs_lookup` resolves across mounts
+- [x] Mount table support
+- [x] `vfs_lookup` resolves across mounts
 - [ ] Mount InitRD at `/` or at `/initrd` (decision)
 
 ### `tmpfs`
-- [ ] In-memory inode/dentry model
-- [ ] Create/unlink
-- [ ] Read/write
-- [ ] Directories
+- [x] In-memory inode/dentry model
+- [~] Create/unlink (limited)
+- [x] Read/write
+- [x] Directories
 
 ### Devices (minimum Unix feel)
 - [ ] `/dev` mount
@@ -154,21 +164,21 @@ Goal: get a writable filesystem (even if volatile) and a real VFS layout.
 - [ ] `/dev/null`
 
 ### Tests
-- [ ] Userspace test: create file in tmpfs, write, read back
+- [x] Userspace test: create file in tmpfs, write, read back
 
 ---
 
 ## 5) Later milestones (not started)
 
 ### Process / POSIX expansion
-- [ ] `fork()`
-- [ ] `execve()`
+- [x] `fork()`
+- [~] `execve()`
 - [ ] `getppid()`
 - [ ] Signals + basic job control
 
 ### Pipes + IO multiplexing
-- [ ] `pipe()`
-- [ ] `dup/dup2`
+- [x] `pipe()`
+- [x] `dup/dup2`
 - [ ] `select/poll`
 
 ### TTY advanced