From: Tulio A M Mendes Date: Sat, 14 Mar 2026 12:58:41 +0000 (-0300) Subject: docs: add Tier 6 implementation plan — SMP, multi-arch, Rump, HDA, Bash/Busybox X-Git-Url: https://projects.tadryanom.me/docs/static/gitweb.js?a=commitdiff_plain;h=737c3bc4e49affa47a986517808d5273e2f5e02c;p=AdrOS.git docs: add Tier 6 implementation plan — SMP, multi-arch, Rump, HDA, Bash/Busybox Comprehensive plan for remaining large architectural features: - 6A: Full SMP scheduling (per-CPU current, AP activation, load balancing) - 6B: Multi-arch subsystems (ARM64/RISC-V/MIPS PMM+VMM+scheduler) - 6C: Rump Kernel integration (USB, production drivers) - 6D: Intel HDA audio driver - 6E: USTAR initrd format - 6F: Minor POSIX gaps (madvise, mntent, utmp) - 6G: Bash & Busybox ports (all blockers resolved) Recommended order: Bash/Busybox → minor gaps → SMP → Rump → USTAR → HDA → multi-arch --- diff --git a/docs/TIER6_PLAN.md b/docs/TIER6_PLAN.md new file mode 100644 index 0000000..5777ba6 --- /dev/null +++ b/docs/TIER6_PLAN.md @@ -0,0 +1,203 @@ +# AdrOS — Tier 6 Implementation Plan + +**Date:** 2026-03-14 +**Prerequisite:** Tiers 1-5 complete (commit aa5474a), audit updated (commit f3a652e) +**Current state:** ~99% POSIX, 139 syscalls, 101 smoke tests, all ulibc headers complete + +--- + +## Overview + +Tier 6 contains **large architectural features** that go beyond POSIX gap-filling. +Each sub-tier is independent and can be implemented in any order. + +--- + +## 6A. Full SMP Scheduling (Priority: High, Effort: Large — 1-2 weeks) + +**Current state:** 4 CPUs boot via INIT-SIPI-SIPI, per-CPU data via GS segment, +per-CPU runqueue infrastructure exists (load counters with atomics), but APs idle +(`sti; hlt` loop). BSP still uses global `current_process` (231+ references). + +### Steps: +1. **Per-CPU `current_process`** — Replace global with `percpu_data->current_process`. + Macro `current` reads from GS segment. ~231 call sites to update. +2. **AP scheduler activation** — Each AP enters `schedule()` loop after boot. + Timer interrupt on each AP drives preemption via per-CPU LAPIC timer. +3. **Load balancing** — Periodic task migration between runqueues (pull model). + `rq_active` bitmap per CPU; idle CPU steals from busiest. +4. **IPI for reschedule** — Send IPI to wake idle APs when new process enqueued. +5. **SMP-safe process lifecycle** — `fork()`, `exit()`, `waitpid()` with proper + locking across CPUs. Process state transitions need atomic CAS. +6. **Testing** — Stress test with multiple CPU-bound processes, verify no deadlocks. + +### Risks: +- Global `current_process` refactor is the biggest risk (231+ sites). +- Race conditions in scheduler are subtle — need extensive testing. +- LAPIC timer calibration must be per-CPU. + +--- + +## 6B. Multi-Architecture Subsystems (Priority: Medium, Effort: Very Large — 4-8 weeks) + +**Current state:** ARM64, RISC-V, MIPS all boot + UART output. No PMM/VMM/scheduler/syscalls. + +### Per-architecture milestones: + +#### ARM64 (AArch64) +1. **PMM** — Page frame allocator using DTB memory map +2. **VMM** — 4-level page tables (TTBR0/TTBR1), kernel at upper half +3. **Exception vectors** — EL1 vector table, SVC handler for syscalls +4. **Timer** — ARM generic timer (CNTPCT_EL0) +5. **Scheduler** — Context switch via `stp`/`ldp` of callee-saved regs +6. **Syscall dispatch** — SVC #0 with register convention + +#### RISC-V (RV64) +1. **PMM** — Sv39/Sv48 page tables from DTB +2. **VMM** — SATP register, kernel mapping +3. **Trap handler** — `stvec`, `scause`-based dispatch +4. **Timer** — CLINT timer interrupt (mtime/mtimecmp) +5. **Scheduler** — Context switch via `csrrw` + register save +6. **Syscall dispatch** — `ecall` from U-mode + +#### MIPS32 +1. **PMM** — Physical memory detection from boot arguments +2. **VMM** — TLB-based (software TLB refill handler) +3. **Exception handler** — General exception vector at 0x80000180 +4. **Timer** — CP0 Count/Compare +5. **Scheduler + syscalls** — `syscall` instruction dispatch + +### Approach: +- Implement one arch fully (ARM64 recommended — most useful) before starting others. +- Share as much kernel code as possible via arch-agnostic interfaces + (`arch_process.h`, `arch_signal.h`, HAL layer). + +--- + +## 6C. Rump Kernel Integration (Priority: Medium, Effort: Large — 4-6 weeks) + +**Current state:** All prerequisites met (mutex, semaphore, condvar, threads, nanosecond +clock, IRQ chaining, PCI scanner). Roadmap documented in `RUMP_KERNEL_ROADMAP.md`. + +### Stages: +1. **Phase 1-3 hypercalls** (1 week) — Memory, console, threads, sync, clocks. + Implement `librumpuser_adros.c` with ~35 functions mapping to AdrOS primitives. +2. **Cross-compile Rump components** (1 week) — Build `librump.a`, `librumpvfs.a`, + `librumpfs_ext2fs.a` using `buildrump.sh` with AdrOS target. +3. **Stage 1: ext2 via Rump** (1 week) — Mount ext2 image using NetBSD driver. + Compare with native AdrOS ext2 driver for correctness. +4. **Stage 2: Network via Rump** (1-2 weeks) — Replace lwIP with NetBSD TCP/IP. + Wire E1000 via rumpdev PCI passthrough. +5. **Stage 3: USB** (2 weeks) — xHCI/EHCI host controller + mass storage. + +### Deliverables: +- USB mass storage support (major capability gap) +- Production-quality ext2/network without maintaining custom drivers + +--- + +## 6D. Intel HDA Audio Driver (Priority: Low, Effort: Medium — 1-2 weeks) + +**Current state:** PCI scanner exists, DMA infrastructure exists (circular ring buffers +for ATA and E1000). No audio support. + +### Steps: +1. **PCI probe** — Detect HDA controller (class 0x0403, vendor Intel) +2. **CORB/RIRB** — Command outbound/response inbound ring buffers (DMA) +3. **Codec discovery** — Walk codec tree, find audio output widget +4. **Stream setup** — BDL (Buffer Descriptor List) for PCM output +5. **PCM playback** — `/dev/dsp` or `/dev/audio` device node, simple WAV playback +6. **Mixer** — Volume control via codec verbs + +### Alternative: Use Rump kernel's HDA driver (Stage 4 in 6C) instead of writing from scratch. + +--- + +## 6E. USTAR InitRD Format (Priority: Low, Effort: Small — 2-3 days) + +**Current state:** Custom binary initrd format with LZ4 decompression. Works well but +non-standard. + +### Steps: +1. **USTAR parser** — Parse 512-byte USTAR headers in initrd blob +2. **File extraction** — Create VFS entries from tar entries (files, directories, symlinks) +3. **Tool update** — Modify `tools/mkinitrd.c` to produce USTAR or keep both formats +4. **LZ4 integration** — Support `.tar.lz4` compressed USTAR archives + +### Benefits: +- Standard format — can use host `tar` to create initrd +- Easier debugging — `tar tvf` to inspect contents + +--- + +## 6F. Remaining Minor POSIX Gaps (Priority: Low, Effort: Small — 1-2 days) + +### Kernel syscalls: +| Syscall | Description | Effort | +|---------|-------------|--------| +| `madvise` | Memory advice (can be no-op) | Trivial | +| `mremap` | Remap virtual memory pages | Medium | +| `execveat` | Execute relative to dirfd | Small | + +### ulibc stubs: +| Feature | Description | Effort | +|---------|-------------|--------| +| `mntent` functions | Mount table parsing (`getmntent`, `setmntent`) | Small | +| `utmp`/`wtmp` | Login records (`getutent`, `pututline`) | Small | +| Full network `ioctl` | `SIOCGIFADDR`, `SIOCGIFFLAGS`, etc. | Medium | + +### Type upgrades (breaking changes): +| Change | Impact | Effort | +|--------|--------|--------| +| `time_t` → 64-bit | Y2038 fix | Medium (audit all uses) | +| `off_t` → 64-bit | Large file support | Medium | +| `ssize_t` returns | POSIX compliance for read/write | Small | + +--- + +## 6G. Bash & Busybox Ports (Priority: High, Effort: Medium — 1-2 weeks) + +**Current state:** All kernel/library blockers resolved. Native toolchain (GCC 13.2 + +Binutils 2.42) and Newlib port are complete. + +### Bash: +1. Cross-compile with `i686-adros-gcc` + Newlib +2. Configure with `--without-bash-malloc --disable-nls` +3. Package in initrd as `/bin/bash` +4. Test: interactive shell, pipes, redirects, job control, globbing + +### Busybox: +1. Cross-compile with minimal config (start with ~20 applets) +2. Enable iteratively: `ls`, `cat`, `cp`, `mv`, `rm`, `mkdir`, `grep`, `sed`, `awk` +3. Replace individual `/bin/*` utilities with Busybox symlinks +4. Test each applet against AdrOS smoke test expectations + +--- + +## Recommended Implementation Order + +| Priority | Sub-tier | Rationale | +|----------|----------|-----------| +| 1 | **6G** Bash/Busybox | Highest user-visible impact, all blockers resolved | +| 2 | **6F** Minor POSIX gaps | Quick wins, improves compatibility | +| 3 | **6A** Full SMP | Major architectural milestone | +| 4 | **6C** Rump Kernel | Unlocks USB, better drivers | +| 5 | **6E** USTAR initrd | Small, improves developer experience | +| 6 | **6D** HDA Audio | Nice-to-have | +| 7 | **6B** Multi-arch | Very large, low urgency | + +--- + +## Summary + +| Sub-tier | Description | Effort | Priority | +|----------|-------------|--------|----------| +| 6A | Full SMP scheduling | 1-2 weeks | High | +| 6B | Multi-arch (ARM64/RV/MIPS) subsystems | 4-8 weeks | Medium | +| 6C | Rump Kernel integration | 4-6 weeks | Medium | +| 6D | Intel HDA audio driver | 1-2 weeks | Low | +| 6E | USTAR initrd format | 2-3 days | Low | +| 6F | Minor POSIX gaps (madvise, mntent, utmp) | 1-2 days | Low | +| 6G | Bash & Busybox ports | 1-2 weeks | High | + +**Total estimated effort:** 12-22 weeks (if done sequentially; many items are parallel).