From 40ce3b82ffc543e547776b0d490ca0288642e323 Mon Sep 17 00:00:00 2001 From: Tulio A M Mendes Date: Sat, 7 Feb 2026 17:39:46 -0300 Subject: [PATCH] docs: update POSIX roadmap and current kernel features --- BUILD_GUIDE.md | 10 +++ README.md | 42 +++++++--- docs/POSIX_ROADMAP.md | 177 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 218 insertions(+), 11 deletions(-) create mode 100644 docs/POSIX_ROADMAP.md diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md index 0572a44..fbe2490 100644 --- 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 f7ab93e..da917ab 100644 --- 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 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 -- 2.43.0