universalisos/kernel/GAP_ANALYSIS_PIKEOS_PARITY.md

# UniversalisOS Gap Analysis: PikeOS 3-Layer Parity
## Audit Date: 2026-07-14

---

## 1. CODEBASE OVERVIEW

| Metric | Value |
|--------|-------|
| **Total codebase** | 126,469 LOC (C/C++/H/S) |
| **Core kernel (src/core)** | 51,484 LOC |
| **ARMv7 arch** | 3,637 LOC |
| **AArch64 arch** | 15,883 LOC |
| **RISC-V arch** | 11,570 LOC |
| **x86_64 arch** | 20,916 LOC |
| **Tests** | 2,295 LOC (16 test files) |
| **ARMv7 ELF binary** | 1.9 MB (290KB text, 215KB data, 24MB BSS) |
| **Total TODO/stub markers** | 243 across core |

---

## 2. SYSCALL TABLE (119 Syscalls)

### Classification

| Category | Count | Status |
|----------|-------|--------|
| **REAL implementations** | 41 | Call into core subsystems with logic |
| **Stubs (return 0)** | 78 | No-op, no real implementation |
| **Not implemented (-8)** | 0 | All have at least a stub handler |

### Syscalls with REAL implementations (41)

| SC# | Name | Subsystem | Quality |
|-----|------|-----------|---------|
| 0 | FAST_GET_UID | Identity | Trivial (returns 0) |
| 1 | KERNEL_CONTROL | Control | Trivial (returns 0) |
| 2 | SLEEP | Task | ✅ Calls task_sleep_us() |
| 3 | FAST_GET_CPUID | Identity | ✅ Reads MPIDR/TP |
| 4 | TASK_ACTIVATE | Task | ✅ scheduler_add_task() |
| 5 | TASK_START | Task | ✅ scheduler_start() |
| 6 | TASK_TERMINATE | Task | ✅ task_destroy_complete() |
| 7 | TASK_GET_ATTR | Task | ⚠️ Partial (TODO: priority accessor) |
| 8 | TASK_DONATE | Task | ✅ scheduler_yield() |
| 9 | THREAD_CREATE | Thread | ✅ uos_task_create() |
| 10 | THREAD_DELETE | Thread | ✅ uos_task_delete() |
| 11 | THREAD_YIELD | Thread | ✅ scheduler_yield() |
| 12 | THREAD_EX_REGS | Thread | ✅ Get PC/SP/LR |
| 13 | THREAD_GET_ATTR | Thread | Delegates to TASK_GET_ATTR |
| 15 | THREAD_SET_REGS | Thread | ✅ uos_task_set_regs() |
| 18 | THREAD_RESUME | Thread | ✅ task_unblock() |
| 20 | COMM_GRANT | IPC | ✅ uos_ipc_shmem_create() |
| 21 | COMM_LINK | IPC | ✅ uos_ipc_channel_create() |
| 23 | IPC | IPC | ✅ Send/receive dispatch |
| 24 | EV_MASK | Event | ✅ uos_event_set_mask() |
| 25 | EV_WAIT | Event | ✅ uos_event_wait() |
| 26 | EV_SIGNAL | Event | ✅ uos_event_signal() |
| 27 | INT_ATTACH | Interrupt | ✅ uos_int_attach() |
| 30 | FAST_GET_PRIO | Priority | ✅ uos_task_get_priority() |
| 31 | FAST_SET_PRIO | Priority | ✅ uos_task_set_priority() |
| 32 | MEM_MAP | Memory | ✅ mm_map_page() |
| 33 | MEM_UNMAP | Memory | ✅ mm_unmap_page() |
| 36 | MEM_CREATE | Memory | ✅ mm_create_page_table() |
| 47 | MEMMAP_ALLOC_PHYS | Memory | ✅ uos_mm_ralloc_boot() |
| 48 | MEMMAP_ALLOC_ALIGNED | Memory | ✅ uos_mm_ralloc_boot() |
| 55 | GET_TIME | Time | ✅ uos_time_get_ticks() |
| 56 | MEM_READ | MemIO | ✅ Direct memory read |
| 57 | MEM_WRITE | MemIO | ✅ Direct memory write |
| 66 | MEM_CLEAR | MemIO | ✅ Zero-fill |
| 70 | THREAD_PREEMPT | Sched | ✅ scheduler_preempt() |
| 71 | TLS_REGISTER | TLS | ✅ uos_task_set_tls() |
| 72 | ULOCK_WAIT | Futex | ⚠️ Partial (needs wake_by_addr) |
| 73 | ULOCK_WAKE | Futex | ⚠️ TODO: iterate task list |
| 74 | GET_TS | Time | ✅ uos_time_get_ts() |
| 76 | RESPART_ALLOC | Memory | ✅ uos_mm_ralloc_boot() |
| 78 | KDEV_DISCOVER | KDEV | ✅ uos_kdev_init_all() |
| 80 | KDEV_OPEN | KDEV | ✅ uos_kdev_find() |
| 106 | WAITQ_WAIT | WaitQ | ✅ task_block() |

### Stubs returning 0 — grouped by subsystem (78)

**KDEV (19 stubs):** dup, alert_module, alert_part, close_all, ping, negotiate, close, pstat, read, write, discard, control, map_to, psync, test, descend, spawn, lseek, unlink, rename, dir_create, dir_read, statvfs, discover_gate

**Trace (7):** start, stop, get_attr, set_attr, write, read, control

**Monitoring (7):** mon_mem_list, mon_start, mon_stop, mon_get_attr, mon_set_attr, mon_control, mon_write

**Time Partitioning (5):** load, switch, switch_disable, switch_enable, window_get_attr

**HM (6):** inject, task_hm_set, task_hm_get, get_attr, set_attr, control, write

**IO Ports (3):** map, unmap, create

**Device (2):** dev_grant, dev_call

**Other (29):** thread_ex_sched, thread_ex_exh, thread_stop_syscall, thread_except, ipc_mask, int_wait, int_grant, mem_set_attr, mem_build_sglist, thread_get_regs, thread_ex_affinity, sysemu_enter, respart_get_kmem, thread_alarm, tls_sync_prio, waitq_init, waitq_wake, waitq_get_attr, cache, fast_get_timepart, mon_memreg_get_attr

---

## 3. SUBSYSTEM GAP ANALYSIS

### 3.1 Scheduler

| Metric | Value |
|--------|-------|
| **LOC** | sched_core: 314, scheduler.cpp: 1034, sched.cpp: 452 |
| **TODOs** | 11 (sched), 1 (scheduler) |
| **Status** | ✅ FUNCTIONAL |

**What works:**
- Cyclic partition scheduler with cooperative yield (sched_core.cpp)
- Timer-driven preemption demo: 2 tasks, interleaved A/B output proven on QEMU
- Priority-based scheduling framework (scheduler.cpp)
- EDF/RM policy framework
- MCS-style budget accounting
- Context switch (ARM assembly: ctx_switch.S + preempt_switch.S)
- Priority inheritance/ceiling protocols (API-level)

**Gaps vs PikeOS:**
- No multi-core scheduling (single-CPU only)
- No proper time-partition window enforcement (budget accounting present but not enforced at boundaries)
- No scheduler activations
- Priority inheritance not tested end-to-end

**Severity: MEDIUM** | **Effort: 2-3 weeks**

---

### 3.2 Memory Management

| Metric | Value |
|--------|-------|
| **LOC** | mm.cpp: 795, mm_list.cpp: 346, mm_store.cpp: 203, mm_kmem.cpp: 80, mm_balloc.cpp: 199, physmem.c: 323 |
| **TODOs** | 59 |
| **Status** | ⚠️ FRAMEWORK + BASIC |

**What works:**
- Boot-time physical memory allocator (mm_store.cpp)
- Flat 4GB section map MMU (ARMv7)
- Page table create/map/unmap
- Bitmap allocator (mm_balloc.cpp)
- Physical memory manager (physmem.c)

**Gaps vs PikeOS:**
- brk/mmap/sbrk all TODO (no user-space memory management)
- No page fault handling
- No COW (Copy-on-Write)
- No memory protection enforcement
- No per-partition memory isolation enforcement (framework present but not enforced)
- No demand paging
- No memory region API completion

**Severity: HIGH** | **Effort: 4-6 weeks**

---

### 3.3 IPC

| Metric | Value |
|--------|-------|
| **LOC** | 2,662 total across 11 files |
| **TODOs** | 0 |
| **Status** | ✅ FUNCTIONAL (multiple mechanisms) |

**What works:**
- Shared memory mailbox (uos_shmem.cpp: 152 LOC)
- Event flags (uos_event.cpp: 115 LOC)
- Blackboard/buffer/logbook ARINC 653 ports (uos_blackboard.cpp: 374 LOC)
- Sampling + queuing channels (uos_ipc_core.cpp, uos_queuing.cpp)
- IPC fastpath framework (uos_fastpath.cpp: 193 LOC)
- IVSHMEM inter-VM comm (uos_ivshmem.cpp: 152 LOC)
- PCI passthrough framework (uos_pci_passthru.cpp: 212 LOC)
- Secure vault (uos_secure_vault.cpp: 179 LOC)

**Gaps vs PikeOS:**
- No real multi-partition message passing (demos exist, not boot-tested end-to-end)
- IVSHMEM and PCI passthrough are framework-only
- No capability-checked IPC (seL4 caps compiled but not wired to IPC path)
- No priority inheritance on IPC blocking

**Severity: LOW-MEDIUM** | **Effort: 2-3 weeks**

---

### 3.4 Health Monitoring (HM)

| Metric | Value |
|--------|-------|
| **LOC** | uos_hm.cpp: 191, uos_hm.h: 106, uos_hm_demo.cpp: 75 |
| **TODOs** | 3 |
| **Status** | ⚠️ FRAMEWORK |

**What works:**
- 3-tier HM dispatch (uos_hm.cpp)
- Module/partition/task error levels
- Demo exercises error path

**Gaps vs PikeOS:**
- All 6 HM syscalls are stubs (return 0)
- No actual error recovery actions
- No HM table configuration from system model
- No partition restart/degradation modes

**Severity: HIGH** | **Effort: 3-4 weeks**

---

### 3.5 KDEV Framework

| Metric | Value |
|--------|-------|
| **LOC** | uos_kdev.cpp: 96, uos_kdev_prov.cpp: 297, uos_kdev_framework.h: 203 |
| **TODOs** | 0 |
| **Status** | ⚠️ SKELETON |

**What works:**
- Self-registering driver framework
- discover_prov + find + open (3 of 22 syscalls have real logic)
- Test driver demo passes

**Gaps vs PikeOS:**
- 19 of 22 KDEV syscalls are stubs
- No actual device read/write/control
- No filesystem operations (lseek, unlink, rename, dir_create, dir_read, statvfs)
- No provider negotiation
- No device sharing between partitions
- No KDEV alert system

**Severity: HIGH** | **Effort: 6-8 weeks**

---

### 3.6 VFS (Virtual File System)

| Metric | Value |
|--------|-------|
| **LOC** | vfs.cpp: 500, vfs.c: 353, vfs.h: 255 |
| **TODOs** | 17 |
| **Status** | ⚠️ FRAMEWORK ONLY |

**What works:**
- ISO 9660 read-only filesystem (iso9660.c)
- Block device abstraction (block_dev.c)
- VFS API surface (mount, open, read, write, close, stat, etc.)

**Gaps vs PikeOS:**
- ALL VFS operations have TODO bodies (mount, unmount, open, close, read, write, stat, unlink, rename, etc.)
- No actual filesystem implementation beyond ISO9660
- No RAM filesystem
- No proper fd table

**Severity: HIGH** | **Effort: 4-6 weeks**

---

### 3.7 Signals / Threading / TLS / Futex

| Metric | Value |
|--------|-------|
| **Status** | ⚠️ MINIMAL |

**Signals:**
- No POSIX signal framework
- task_kill() has TODO: "Implement signal handling"
- seL4 Notifications present (cap layer) but not wired to POSIX signals

**Threading:**
- Thread create/delete/yield/resume: ✅ functional via task.cpp
- Thread ex_regs/set_regs: ✅ basic register exchange
- Thread ex_sched, ex_exh, stop_syscall, except: stubs

**TLS:**
- sys_tls_register (SC 71): ✅ stores TLS pointer per task
- sys_tls_sync_prio (SC 97): stub
- No proper __thread support

**Futex:**
- sys_ulock_wait (SC 72): ⚠️ Partial — checks lock value, blocks with timeout
- sys_ulock_wake (SC 73): ⚠️ Stub — needs wake_by_addr scheduler API
- No proper futex hash table

**Severity: MEDIUM** | **Effort: 3-4 weeks**

---

### 3.8 Capability System (seL4-style)

| Metric | Value |
|--------|-------|
| **LOC** | 1,385 total (cap + sel4) |
| **TODOs** | 0 |
| **Status** | ✅ FUNCTIONAL (framework) |

**What works:**
- seL4 CNode/MDB implementation
- Capability derivation/revocation graph
- Untyped registration, Retype
- Notification capabilities
- Capability compiler from P4 config
- Demo passes

**Gaps vs PikeOS:**
- Caps not wired to syscall path (no cap check on IPC/memory)
- No CSpace management syscalls
- No cap transfer between partitions

**Severity: LOW** | **Effort: 1-2 weeks**

---

### 3.9 Device Emulation

| Metric | Value |
|--------|-------|
| **LOC** | devemu: 692, device.cpp: included |
| **TODOs** | 21 |
| **Status** | ⚠️ FRAMEWORK |

**What works:**
- MMIO dispatch framework
- IRQ routing structure
- Emulator registration API

**Gaps vs PikeOS:**
- No actual device emulators registered
- No virtio emulation
- No PCI/PCIe ECAM emulation

**Severity: MEDIUM** | **Effort: 4-6 weeks**

---

### 3.10 Partition Management

| Metric | Value |
|--------|-------|
| **LOC** | partition.cpp: ~500, respart.cpp: ~364 |
| **TODOs** | 13 |
| **Status** | ⚠️ FRAMEWORK |

**What works:**
- Partition config parsing from P4 manifest
- 2 partitions parsed in boot demo
- Resource partition API surface

**Gaps vs PikeOS:**
- No partition lifecycle enforcement (start/stop/suspend are framework)
- No partition restart on HM error
- No partition memory isolation enforcement

**Severity: MEDIUM** | **Effort: 3-4 weeks**

---

## 4. ARMv7 BUILD & BOOT STATUS

### Build
- ✅ **Compiles clean** with `arm-none-eabi-g++` (Cortex-A15 target)
- ✅ **Links successfully** — 1.9MB ELF
- ⚠️ Warnings: unused parameters in spinlock.h (cosmetic)
- ⚠️ Linker warning: RWX segment (no separate data/text pages)
- ⚠️ Cannot find entry `_start` (defaults to 0x40000000)

### Boot (QEMU virt)
- ✅ Boots to completion
- ✅ MMU enabled (flat 4GB map)
- ✅ GIC initialized (1024 IRQs)
- ✅ Timer subsystem: 62 MHz, 1ms tick, **ticker fires correctly**
- ✅ IRQ dispatch: 1024-slot table, SGI attach works
- ✅ KDEV: 1 test driver registered and found
- ✅ VFP/NEON: lazy enable works
- ✅ SMP framework: per-CPU + IPI (single CPU)
- ✅ **PREEMPT DEMO: INTERLEAVED A/B OUTPUT PROVEN** — genuine timer-driven preemption
- ✅ P4 config: 2 partitions parsed, 2 schedule windows, HM module, kdev pool, 2 connections, 1 shared memory

### What runs at boot
1. Exception handlers init
2. P4 manifest parsing (2 partitions)
3. Memory management (512MB total, 510MB free)
4. MMU flat map
5. GIC interrupt controller
6. IRQ dispatch demo ✅
7. Time subsystem demo ✅ (timer ticks)
8. KDEV framework demo ✅
9. VFP/NEON demo ✅
10. SMP demo ✅ (IPI weak on QEMU)
11. **Preemptive scheduler demo** ✅ (never returns — A/B interleaving)

---

## 5. GAP SEVERITY MATRIX

| PikeOS Feature | UOS Status | Gap Severity | Est. Effort |
|---------------|------------|-------------|-------------|
| **Cyclic partition scheduler** | ✅ Functional | LOW | 1w (enforce window boundaries) |
| **Preemptive scheduling** | ✅ Proven | LOW | 1w (multi-task, priority) |
| **Context switch (ARM)** | ✅ Assembly | NONE | Done |
| **Priority scheduling** | ✅ Framework | LOW | 1w (EDF/RM enforcement) |
| **Multi-core scheduling** | ❌ Single CPU | HIGH | 3-4w |
| **Physical memory allocator** | ✅ Boot allocator | LOW | 1w (runtime allocator) |
| **MMU/page tables** | ✅ Section map | MEDIUM | 2-3w (fine-grained pages) |
| **Memory protection** | ❌ Not enforced | HIGH | 3-4w |
| **Demand paging / COW** | ❌ TODO | HIGH | 4-6w |
| **Per-partition memory isolation** | ⚠️ Framework | HIGH | 2-3w |
| **IPC: shared memory** | ✅ Functional | LOW | 1w |
| **IPC: sampling/queuing ports** | ✅ Framework | MEDIUM | 2w |
| **IPC: blackboard/buffer** | ✅ Implemented | LOW | 1w |
| **IPC: fastpath** | ⚠️ Framework | MEDIUM | 2-3w |
| **IPC: IVSHMEM** | ⚠️ Framework | MEDIUM | 2-3w |
| **Health monitoring** | ⚠️ Framework only | HIGH | 3-4w |
| **HM error recovery** | ❌ Stubs | HIGH | 3-4w |
| **KDEV device framework** | ⚠️ Skeleton | HIGH | 6-8w |
| **KDEV filesystem ops** | ❌ All stubs | HIGH | 4-6w |
| **VFS** | ⚠️ Framework only | HIGH | 4-6w |
| **seL4 capabilities** | ✅ Implemented | LOW | 1-2w (wire to syscalls) |
| **Capability-checked IPC** | ❌ Not wired | MEDIUM | 2-3w |
| **Device emulation** | ⚠️ Framework | MEDIUM | 4-6w |
| **Partition lifecycle** | ⚠️ Framework | MEDIUM | 3-4w |
| **Time partitioning** | ❌ Stubs | HIGH | 3-4w |
| **Trace** | ❌ All stubs | MEDIUM | 2-3w |
| **Monitoring** | ❌ All stubs | MEDIUM | 2-3w |
| **Signals** | ❌ Not implemented | HIGH | 3-4w |
| **Futex (ULOCK)** | ⚠️ Partial | MEDIUM | 1-2w |
| **TLS** | ⚠️ Basic register | MEDIUM | 1-2w |
| **POSIX ABI** | ⚠️ Stub-heavy | HIGH | 6-8w |
| **Guest VM management** | ⚠️ Framework | MEDIUM | 3-4w |
| **Live migration** | ⚠️ Framework | MEDIUM | 4-6w |
| **SMP (multi-core)** | ⚠️ Framework | HIGH | 4-6w |
| **PCI/PCIe** | ⚠️ Framework | MEDIUM | 3-4w |
| **Virtio** | ❌ Not present | HIGH | 6-8w |
| **Network stack** | ❌ Socket stubs | HIGH | 8-10w |

---

## 6. SUMMARY SCORES

### Syscall Parity
- **119/119** syscalls have handlers (100% table coverage)
- **41/119** have real implementations (34.5%)
- **78/119** are return-0 stubs (65.5%)
- **0** are sys_not_implemented

### Subsystem Maturity

| Subsystem | Maturity | Ready for demo? | Ready for production? |
|-----------|----------|-----------------|----------------------|
| Scheduler | 75% | ✅ YES | ❌ No |
| Memory | 40% | ✅ Boot only | ❌ No |
| IPC | 65% | ✅ YES | ❌ No |
| HM | 25% | ⚠️ Demo only | ❌ No |
| KDEV | 15% | ⚠️ Skeleton | ❌ No |
| VFS | 10% | ❌ No | ❌ No |
| Capabilities | 80% | ✅ YES | ⚠️ Partial |
| Signals | 5% | ❌ No | ❌ No |
| Threading | 45% | ✅ Basic | ❌ No |
| TLS | 30% | ⚠️ Basic | ❌ No |
| Futex | 25% | ⚠️ Partial | ❌ No |
| Partition mgmt | 35% | ⚠️ Parse only | ❌ No |
| Device emu | 20% | ❌ No | ❌ No |
| VMM | 30% | ⚠️ Framework | ❌ No |

### Overall PikeOS 3-Layer Parity Estimate

| Layer | Coverage |
|-------|----------|
| **Layer 1: Microkernel (scheduler, IPC, memory, caps)** | ~55% |
| **Layer 2: System services (HM, KDEV, VFS, partitions)** | ~20% |
| **Layer 3: POSIX/runtime (signals, threading, futex, VFS)** | ~10% |
| **Overall weighted parity** | **~28%** |

### Prioritized Implementation Roadmap

1. **Sprint 1 (2 weeks):** Memory protection enforcement, futex wake_by_addr, wire caps to syscalls
2. **Sprint 2 (3 weeks):** HM error recovery, time partitioning enforcement, KDEV read/write
3. **Sprint 3 (4 weeks):** VFS implementation, KDEV filesystem ops, POSIX signal framework
4. **Sprint 4 (4 weeks):** Multi-core scheduling, device emulation, IVSHMEM/PCI live
5. **Sprint 5 (6 weeks):** POSIX ABI (fork/exec/wait), virtio, network stack

**Estimated total to production-grade PikeOS parity: 19-24 engineer-weeks**