docs: add 12-month implementation roadmap for resolving stubs

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "kernel/docs/doxygen-awesome-css"]
+	path = kernel/docs/doxygen-awesome-css
+	url = https://github.com/jothepro/doxygen-awesome-css.git

docs/UniversalisOS_Stubs_Resolution_Roadmap_12Months.md

@@ -0,0 +1,105 @@
+# 12-Month Implementation Plan for UniversalisOS
+
+This document outlines a strategic 12-month roadmap to implement all the currently stubbed and missing features in the `universalisos` codebase. The plan is structured into four quarters, prioritizing fundamental architectural foundations first, moving through driver implementations, and finalizing with higher-level APIs and POSIX conformance.
+
+---
+
+## Quarter 1: Architecture Foundations & Memory Management
+*Focus: Stabilizing the memory model, core boot paths, and architectural primitives.*
+
+### **Month 1: ARMv7 Core & Memory Management**
+- **Objective:** Establish robust memory management and exception handling for ARMv7.
+- **Tasks:**
+  - Implement platform-specific FIQ handling (`exceptions.cpp`).
+  - Complete MMU initializations in `uos_cmm.cpp`: `uos_arm_init_mmu`, `_activate_mmu`, and `_deactivate_mmu`.
+  - Finalize TTBR0/TTBR1 setup, translation table base control (TTBCR), and Domain Access Control (DACR).
+  - Implement Process Stack Pointer (PSP) initialization.
+
+### **Month 2: RISC-V Foundations & Virtualization Base**
+- **Objective:** Make the RISC-V port fully functional in terms of virtualization and loading.
+- **Tasks:**
+  - Implement ELF parsing in the guest loader (`guest_loader.cpp`).
+  - Implement demand paging and memory-mapped I/O (MMIO) emulation (`vm.cpp`).
+  - Implement hypervisor partition control: stop and restart partition mechanisms (`hm.cpp`).
+
+### **Month 3: Schedulers & Exceptions Cleanup**
+- **Objective:** Finalize the scheduler logic and ensure all traps/exceptions are handled.
+- **Tasks:**
+  - Implement proper blocking with timeouts in the core scheduler (`scheduler.cpp`).
+  - Address and implement all unhandled/stubbed exception pathways marked as "Not implemented for now" in both `arm_exceptions.cpp` and `riscv_exceptions.cpp`.
+
+---
+
+## Quarter 2: Apple M1 (AArch64) Enablement & SMP Support
+*Focus: Bringing the Apple M1 port up to parity and enabling symmetric multiprocessing across the board.*
+
+### **Month 4: Apple M1 Core Initialization**
+- **Objective:** Boot the Apple M1 platform with full memory layout awareness.
+- **Tasks:**
+  - Implement memory range parsing and build proper page tables (`main_apple.c`).
+  - Implement RVBAR spin table initialization for core awakening.
+  - Finalize the freestanding `linux_stub.c` functionality into a robust testing payload.
+
+### **Month 5: Symmetric Multiprocessing (SMP)**
+- **Objective:** Support multi-core execution environments.
+- **Tasks:**
+  - Implement SMP secondary CPUs bring-up specifically for the Apple M1 (`main_apple.c`).
+  - Implement standard secondary-CPU bringup via PSCI (SMC CPU_ON) for generic ARMv7/AArch64 (`uos_smp.cpp`).
+
+### **Month 6: Apple M1 Hypervisor & Base Display**
+- **Objective:** Establish EL2 virtualization and early visual feedback.
+- **Tasks:**
+  - Implement Hypervisor EL2 guest support (`SYS_IMP_APL_VM_CONFIG_EL1`).
+  - Begin platform initializations by implementing the Display driver for the Apple M1.
+
+---
+
+## Quarter 3: Device Drivers & Subsystems
+*Focus: Replacing driver stubs to enable storage, networking, and system interoperability.*
+
+### **Month 7: Core Driver Infrastructure**
+- **Objective:** Implement the infrastructure required for devices to generate and handle events.
+- **Tasks:**
+  - Implement real interrupt handlers for Storage, Human Interface (HMI), System Infrastructure, Advanced Interface, and Virtualization (`platform/drivers/driver.cpp`).
+  - Implement API endpoints for board reset (`usp_board_reset`) and board shutdown (`usp_board_shutdown`) in `uos_api.cpp`.
+
+### **Month 8: Primary Subsystem Drivers**
+- **Objective:** Build out the drivers required for standard I/O operations.
+- **Tasks:**
+  - Replace Storage and System driver stubs with functional implementations (`uos_drivers.cpp`).
+  - Implement Communication and Network driver foundations.
+  - Implement character availability checking on the UART (`usp_board.cpp`).
+
+### **Month 9: Advanced & Platform-Specific Drivers**
+- **Objective:** Complete the driver stack, especially for the M1 platform.
+- **Tasks:**
+  - Implement PCIe, NVMe, and USB initialization for the Apple M1 (`main_apple.c`).
+  - Complete the Advanced, Virtualization, HMI, and Watchdog driver stubs (`uos_drivers.cpp`).
+  - Ensure MMIO proxy stubs (`uos_pv_abi.cpp`) correctly forward read/writes.
+
+---
+
+## Quarter 4: POSIX ABI, VFS, & Finalization
+*Focus: Higher-level OS features, POSIX conformance (PikeOS parity), and final integration.*
+
+### **Month 10: POSIX Task Management**
+- **Objective:** Provide robust POSIX-like process semantics.
+- **Tasks:**
+  - Implement `task_fork` and `task_waitpid` in `uos_posix_abi.cpp`.
+  - Implement the "Halt partition" logic.
+  - Initialize POSIX subsystems properly in `posix_config.c`.
+  - Address the POSIX ABI memory management declarations (`mm.h`).
+
+### **Month 11: Virtual Filesystem (VFS) & Sockets**
+- **Objective:** Enable a fully functional virtual filesystem and networking endpoints.
+- **Tasks:**
+  - Flesh out the VFS implementation: Ensure `munmap` correctly frees memory resources (`vfs.cpp`).
+  - Implement VFS socket operations: `socket`, `bind`, `listen`, and `accept`.
+
+### **Month 12: Testing, Profiling & Hardening**
+- **Objective:** Achieve stability and complete the PikeOS 5.0 gap closure.
+- **Tasks:**
+  - Validate all PikeOS API parity interfaces against the reference implementations.
+  - Perform cross-architecture testing (ARMv7 QEMU, Apple M1, RISC-V Icicle Kit) to ensure regression-free boots.
+  - Conduct performance profiling, specifically on the new scheduler blocking and MMU logic.
+  - Security review of partition isolation and demand paging.

kernel/docs/doxygen-awesome-css

@@ -0,0 +1 @@
+Subproject commit 82d315e34ac419a81caccf470cc2fbc2ec8ee524