From: Tulio A M Mendes <tadryanom@hotmail.com>
Date: Sun, 15 Feb 2026 05:02:33 +0000 (-0300)
Subject: docs: update README, BUILD_GUIDE, TESTING_PLAN for MIPS + expanded tests
X-Git-Url: https://projects.tadryanom.me/docs/static/gitweb.css?a=commitdiff_plain;h=872e48025d4ca17a44cd02469aa2b3bc57adcf2d;p=AdrOS.git

docs: update README, BUILD_GUIDE, TESTING_PLAN for MIPS + expanded tests

- README.md: MIPS32 now boots on QEMU Malta, added run-mips instructions,
  updated test counts (41 smoke, 19 host), added src/arch/mips/ to directory
- BUILD_GUIDE.md: added section 6 (MIPS32 build & run), renumbered troubleshooting
- TESTING_PLAN.md: updated smoke test count to 41, added 6 new test descriptions,
  added qemu-system-mipsel to tools table, added make run-mips target
---

diff --git a/BUILD_GUIDE.md b/BUILD_GUIDE.md
index 909bc75..0dcbda0 100644
--- a/BUILD_GUIDE.md
+++ b/BUILD_GUIDE.md
@@ -245,7 +245,33 @@ Welcome to AdrOS (x86/ARM/RISC-V/MIPS)!
 - To quit: `Ctrl+A`, then `x`.
 - RISC-V boots with NS16550 UART at 0x10000000, M-mode, `-bios none`.
 
-## 6. Common Troubleshooting
+## 6. Building & Running (MIPS32)
+
+### Build
+```bash
+make ARCH=mips
+```
+This produces `adros-mips.bin`.
+
+### Run on QEMU
+```bash
+make run-mips
+# or manually:
+qemu-system-mipsel -M malta -m 128M -nographic \
+    -kernel adros-mips.bin -serial mon:stdio
+```
+
+Expected output:
+```
+[AdrOS/mips32] Booting on QEMU Malta...
+[CPU] No arch-specific feature detection.
+Welcome to AdrOS (x86/ARM/RISC-V/MIPS)!
+```
+
+- To quit: `Ctrl+A`, then `x`.
+- MIPS32 boots with 16550 UART at ISA I/O 0x3F8 (KSEG1 0xB80003F8), `-march=mips32r2`.
+
+## 7. Common Troubleshooting
 
 - **"Multiboot header not found"**: Check whether `grub-file --is-x86-multiboot2 adros-x86.bin` returns success (0). If it fails, the section order in `linker.ld` may be wrong.
 - **"Triple Fault (infinite reset)"**: Usually caused by paging (VMM) issues or a misconfigured IDT. Run `make ARCH=x86 run QEMU_DEBUG=1` and inspect `qemu.log`.
diff --git a/README.md b/README.md
index 0dd7093..eb98c29 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ AdrOS is a Unix-like, POSIX-compatible, multi-architecture operating system deve
 - **x86** (32-bit, PAE) — primary, fully functional target
 - **ARM64** (AArch64) — boots on QEMU virt, UART console, minimal kernel
 - **RISC-V 64** — boots on QEMU virt, UART console, minimal kernel
-- **MIPS** — build infrastructure only
+- **MIPS32** (little-endian) — boots on QEMU Malta, UART console, minimal kernel
 
 ## Technical Stack
 - **Language:** C and Assembly
@@ -183,6 +183,12 @@ make ARCH=riscv
 make run-riscv
 ```
 
+### MIPS32 (QEMU Malta)
+```
+make ARCH=mips
+make run-mips
+```
+
 QEMU debug helpers:
 - `make ARCH=x86 run QEMU_DEBUG=1`
 - `make ARCH=x86 run QEMU_DEBUG=1 QEMU_INT=1`
@@ -191,13 +197,14 @@ QEMU debug helpers:
 
 See [POSIX_ROADMAP.md](docs/POSIX_ROADMAP.md) for a detailed checklist.
 
-**All 31 planned POSIX tasks are complete**, plus 35 additional features (66 total). The kernel covers **~98%** of the core POSIX interfaces needed for a practical Unix-like system. All 35 smoke tests, 16 battery checks, and 47 host unit tests pass clean. ARM64 and RISC-V 64 boot on QEMU virt.
+**All 31 planned POSIX tasks are complete**, plus 35 additional features (66 total). The kernel covers **~98%** of the core POSIX interfaces needed for a practical Unix-like system. All 41 smoke tests, 16 battery checks, and 19 host unit tests pass clean. ARM64, RISC-V 64, and MIPS32 boot on QEMU.
 
 ## Directory Structure
 - `src/kernel/` — Architecture-independent kernel (VFS, syscalls, scheduler, tmpfs, diskfs, devfs, overlayfs, procfs, FAT12/16/32, ext2, PTY, TTY, shm, signals, networking, threads, vDSO, KASLR, permissions)
 - `src/arch/x86/` — x86-specific (boot, VMM, IDT, LAPIC, IOAPIC, SMP, ACPI, CPUID, SYSENTER, ELF loader, MTRR)
 - `src/arch/arm/` — ARM64-specific (boot, EL2→EL1, PL011 UART, stubs)
 - `src/arch/riscv/` — RISC-V 64-specific (boot, NS16550 UART, stubs)
+- `src/arch/mips/` — MIPS32-specific (boot, 16550 UART, stubs)
 - `src/hal/x86/` — HAL x86 (CPU, keyboard, timer, UART, PCI, ATA PIO/DMA, E1000 NIC, RTC)
 - `src/drivers/` — Device drivers (VBE, initrd, VGA, timer)
 - `src/mm/` — Memory management (PMM, heap, slab, arch-independent VMM wrappers)
diff --git a/docs/TESTING_PLAN.md b/docs/TESTING_PLAN.md
index e2a21fe..db107b2 100644
--- a/docs/TESTING_PLAN.md
+++ b/docs/TESTING_PLAN.md
@@ -5,12 +5,12 @@
 All testing layers are **implemented and operational**:
 
 - **Static analysis** (`make check`): cppcheck + sparse + gcc -fanalyzer
-- **QEMU smoke tests** (`make test`): expect-based, 35 checks (file I/O, signals, memory, IPC, devices, procfs, networking), 4-CPU SMP, 90s timeout
+- **QEMU smoke tests** (`make test`): expect-based, 41 checks (file I/O, signals, memory, IPC, devices, procfs, networking, umask, pipe capacity, waitid, setitimer/getitimer, select/poll on regular files), 4-CPU SMP, 120s timeout
 - **Test battery** (`make test-battery`): 16 checks across 5 QEMU scenarios — multi-disk ATA, VFS mount, ping, diskfs
-- **Host unit tests** (`make test-host`): 47 tests — `test_utils.c` (28) + `test_security.c` (19)
+- **Host unit tests** (`make test-host`): 19 tests — `test_utils.c` + `test_security.c`
 - **GDB scripted checks** (`make test-gdb`): heap/PMM/VGA integrity validation
 - **Full suite** (`make test-all`): runs check + test-host + test
-- **Multi-arch build verification**: `make ARCH=arm` and `make ARCH=riscv` compile and boot on QEMU virt
+- **Multi-arch build verification**: `make ARCH=arm`, `make ARCH=riscv`, and `make ARCH=mips` compile and boot on QEMU
 
 ## Available Tools (already installed)
 
@@ -22,6 +22,7 @@ All testing layers are **implemented and operational**:
 | qemu-system-i386 | /usr/bin/qemu-system-i386 | x86 emulation + smoke tests |
 | qemu-system-aarch64 | /usr/bin/qemu-system-aarch64 | ARM64 emulation |
 | qemu-system-riscv64 | /usr/bin/qemu-system-riscv64 | RISC-V 64 emulation |
+| qemu-system-mipsel | /usr/bin/qemu-system-mipsel | MIPS32 little-endian emulation |
 | gdb | /usr/bin/gdb | Debugging via QEMU `-s -S` |
 | expect | /usr/bin/expect | Scripted QEMU serial interaction |
 | python3 | /usr/bin/python3 | Test runner orchestration |
@@ -110,7 +111,7 @@ To run manually: boot AdrOS with `-vga std`, then execute `/bin/doom.elf` from t
 
 ```makefile
 make check        # cppcheck + sparse + gcc -fanalyzer
-make test         # QEMU + expect automated smoke test (35 checks incl. ICMP ping)
+make test         # QEMU + expect automated smoke test (41 checks incl. ICMP ping)
 make test-battery # Full test battery: multi-disk ATA, VFS mount, ping, diskfs (16 checks)
 make test-host    # Host-side unit tests for pure functions
 make test-gdb     # QEMU + GDB scripted checks (optional)
@@ -121,4 +122,6 @@ make ARCH=arm     # Build ARM64 kernel
 make run-arm      # Boot ARM64 on QEMU virt (aarch64, cortex-a57)
 make ARCH=riscv   # Build RISC-V 64 kernel
 make run-riscv    # Boot RISC-V 64 on QEMU virt
+make ARCH=mips    # Build MIPS32 kernel
+make run-mips     # Boot MIPS32 on QEMU Malta
 ```