universalisos/MICROKERNEL_UNIVERSAL_VISION.md

UniversalisOS Microkernel — Universal Architecture Vision

Date: 2026-07-14 Status: DRAFT — Awaiting deep RTOS audit results

---

The Vision

┌─────────────────────────────────────────────────────────────────────┐
│                    UniversalisOS Microkernel                        │
│                  "Runs on everything, hosts everything"             │
├──────────────┬──────────────┬──────────────┬───────────────────────┤
│  Cortex-M0   │  Cortex-M4   │  Cortex-A53  │  x86 (Pentium+)      │
│  (no MPU)    │  (MPU)       │  (MMU)       │  (VT-x if available) │
│  4KB RAM     │  64KB RAM    │  512MB RAM   │  4GB+ RAM             │
├──────────────┴──────────────┴──────────────┴───────────────────────┤
│                    Agnostic API Shell                               │
├──────────────┬──────────────┬──────────────┬───────────────────────┤
│  FreeRTOS    │  ThreadX     │  Zephyr      │  POSIX (PSE51)       │
│  personality │  personality │  personality │  personality          │
├──────────────┴──────────────┴──────────────┴───────────────────────┤
│                    uos_* Type System (universal)                    │
│  uos_task_t, uos_sem_t, uos_mutex_t, uos_queue_t, uos_timer_t     │
└─────────────────────────────────────────────────────────────────────┘

Design Principles

1. Universal Hardware Support

• ARMv-M (Cortex-M0/M0+/M3/M4/M7/M23/M33/M55/M85) — No MMU, optional MPU
• ARMv-A (Cortex-A5/A7/A8/A9/A53/A72/A76) — Full MMU
• ARMv-R (Cortex-R4/R5/R7/R8) — MPU only
• RISC-V (RV32/RV64, with/without H-extension) — Sv39/Sv48 or PMP
• x86 (Pentium+ with/without VT-x) — Protected mode, optional EPT
• Xtensa (ESP32/ESP32-S3) — No MMU, windowed registers
• MIPS (PIC32) — Simple MMU or no MMU
• AVR (megaAVR/AVR-DA) — 8-bit, no MMU, no MPU

2. Memory Model Tiers

Tier 0: No MMU, No MPU        (Cortex-M0, AVR, basic RISC-V)
  → Cooperative scheduling only
  → No memory isolation between tasks
  → Stack overflow detection via guard patterns
  → Static memory allocation only

Tier 1: MPU only               (Cortex-M3/M4/M7/M23/M33, Cortex-R)
  → Preemptive scheduling with MPU-based isolation
  → Fixed memory regions (8-16 regions typical)
  → Stack + data isolation per task
  → No virtual memory, no demand paging

Tier 2: Full MMU               (Cortex-A, RISC-V Sv39+, x86 protected)
  → Full type-1 hypervisor
  → Partition isolation (page-table-based)
  → Virtual memory, demand paging, COW
  → Guest OS boot (Linux, RTOS, etc.)

Tier 3: Hardware Virtualization (Cortex-A with VE, RISC-V H-ext, x86 VT-x)
  → Full hardware-assisted virtualization
  → Nested page tables (EPT/NPT/G-stage)
  → Guest OS runs unmodified
  → Device passthrough

3. Agnostic API Shell (Mbed OS Pattern)

The kernel exposes uos_* primitives. On top of that, personality
shells provide familiar APIs:

  uos_task_create()    ←  universal task creation
  uos_sem_init()       ←  universal semaphore
  uos_mutex_lock()     ←  universal mutex
  uos_queue_send()     ←  universal message queue
  uos_timer_start()    ←  universal timer
  
  ↓ Personality shells wrap these:

  xTaskCreate()        ←  FreeRTOS personality
  tx_thread_create()   ←  ThreadX personality
  k_thread_create()    ←  Zephyr personality
  pthread_create()     ←  POSIX personality
  osThreadNew()        ←  CMSIS-RTOS v2 personality

4. The Port Layer (inspired by ThreadX)

Each architecture gets a port directory with exactly 4 files:

kernel/ports/armv7m/
  uos_port_context.S    — Context save/restore (PendSV handler)
  uos_port_dispatch.S   — First task dispatch
  uos_port_timer.S      — SysTick/timer interrupt handler
  uos_port.h            — Port-specific defines, inline asm

The port layer exports exactly 5 functions:

void uos_port_init(void);              // Hardware init (NVIC, MPU, etc.)
void uos_port_start_first_task(void);  // Jump to first task
void uos_port_yield(void);             // Trigger context switch (PendSV/SVC/ECALL)
void uos_port_enter_critical(void);    // Disable interrupts
void uos_port_exit_critical(void);     // Re-enable interrupts

5. Target Hardware Matrix

Vendor	Chip Family	Arch	Tier	Port Priority
ST	STM32F0/G0	Cortex-M0/M0+	0	P0
ST	STM32F1/F4/F7	Cortex-M3/M4/M7	1	P0
ST	STM32H7	Cortex-M7 (MPU)	1	P0
ST	STM32MP1	Cortex-A7 + M4	2	P1
Nordic	nRF52832/840	Cortex-M4	1	P0
Nordic	nRF5340	Cortex-M33 (TrustZone)	1	P0
NXP	LPC55xx	Cortex-M33 (TrustZone)	1	P0
NXP	i.MX RT1060	Cortex-M7	1	P0
NXP	i.MX 8M	Cortex-A53 + M4	2	P1
Microchip	SAM D21/L21	Cortex-M0+/M23	0/1	P1
Microchip	PIC32MZ	MIPS32	1	P2
TI	CC2652	Cortex-M4	1	P1
TI	AM62x	Cortex-A53	2	P1
Espressif	ESP32	Xtensa LX6	1	P1
Espressif	ESP32-S3	Xtensa LX7	1	P1
Espressif	ESP32-C3	RISC-V RV32	0/1	P1
SiFive	HiFive1	RISC-V RV32	1	P1
GigaDevice	GD32VF103	RISC-V RV32	1	P2
Intel	Pentium+	x86 32-bit	2	P2
Intel	Atom/Core	x86_64 + VT-x	3	P0 (exists)
QEMU	virt	All arches	All	P0 (test)

6. Agnostic API Design

/*
 * UniversalisOS — Universal Kernel API
 * All types use uos_ prefix. All functions use uos_ prefix.
 * This is the ONE API that personality shells wrap.
 */

/* Task management */
uos_task_t*   uos_task_create(const uos_task_attr_t* attr, void (*entry)(void*), void* arg);
uos_status_t  uos_task_delete(uos_task_t* task);
uos_status_t  uos_task_yield(void);
uos_status_t  uos_task_suspend(uos_task_t* task);
uos_status_t  uos_task_resume(uos_task_t* task);
uos_task_t*   uos_task_self(void);
uos_status_t  uos_task_set_priority(uos_task_t* task, uos_prio_t prio);

/* Scheduling */
uos_status_t  uos_sched_start(void);  // Start the scheduler (never returns)
uos_policy_t  uos_sched_get_policy(void);

/* Semaphores */
uos_status_t  uos_sem_init(uos_sem_t* sem, uos_count_t count);
uos_status_t  uos_sem_destroy(uos_sem_t* sem);
uos_status_t  uos_sem_wait(uos_sem_t* sem, uos_tick_t timeout);
uos_status_t  uos_sem_post(uos_sem_t* sem);

/* Mutexes */
uos_status_t  uos_mutex_init(uos_mutex_t* mutex, const uos_mutex_attr_t* attr);
uos_status_t  uos_mutex_destroy(uos_mutex_t* mutex);
uos_status_t  uos_mutex_lock(uos_mutex_t* mutex, uos_tick_t timeout);
uos_status_t  uos_mutex_unlock(uos_mutex_t* mutex);

/* Message queues */
uos_queue_t*  uos_queue_create(uos_size_t msg_size, uos_size_t max_msgs);
uos_status_t  uos_queue_send(uos_queue_t* queue, const void* msg, uos_tick_t timeout);
uos_status_t  uos_queue_receive(uos_queue_t* queue, void* msg, uos_tick_t timeout);

/* Event flags */
uos_status_t  uos_event_init(uos_event_t* event);
uos_status_t  uos_event_set(uos_event_t* event, uos_flags_t flags);
uos_status_t  uos_event_wait(uos_event_t* event, uos_flags_t flags, uos_tick_t timeout);

/* Timers */
uos_timer_t*  uos_timer_create(uos_tick_t period, void (*callback)(void*), void* arg, bool periodic);
uos_status_t  uos_timer_start(uos_timer_t* timer);
uos_status_t  uos_timer_stop(uos_timer_t* timer);

/* Memory */
void*         uos_mem_alloc(uos_size_t size);
void*         uos_mem_aligned_alloc(uos_size_t align, uos_size_t size);
void          uos_mem_free(void* ptr);

/* Time */
uos_tick_t    uos_tick_get(void);
uos_status_t  uos_tick_delay(uos_tick_t ticks);
uos_status_t  uos_tick_delay_until(uos_tick_t* last_wake, uos_tick_t increment);

/* ISR-safe variants (from interrupt context) */
uos_status_t  uos_sem_post_from_isr(uos_sem_t* sem);
uos_status_t  uos_queue_send_from_isr(uos_queue_t* queue, const void* msg);
uos_status_t  uos_event_set_from_isr(uos_event_t* event, uos_flags_t flags);

7. Personality Shell Architecture

kernel/
├── src/
│   ├── core/              ← Universal kernel (uos_* API)
│   │   ├── uos_task.c
│   │   ├── uos_sched.c
│   │   ├── uos_sem.c
│   │   ├── uos_mutex.c
│   │   ├── uos_queue.c
│   │   ├── uos_event.c
│   │   ├── uos_timer.c
│   │   ├── uos_mem.c
│   │   └── uos_tick.c
│   ├── port/              ← Architecture ports (4 files each)
│   │   ├── armv6m/        ← Cortex-M0/M0+ (no MPU, PendSV)
│   │   ├── armv7m/        ← Cortex-M3/M4/M7 (MPU, PendSV)
│   │   ├── armv7a/        ← Cortex-A (MMU, SVC/IRQ)
│   │   ├── armv8m/        ← Cortex-M23/M33/M55 (TrustZone, PendSV)
│   │   ├── armv8a/        ← Cortex-A53/A72 (MMU, HVC)
│   │   ├── riscv32/       ← RV32IMC (PMP, ECALL)
│   │   ├── riscv64/       ← RV64GC (Sv39, ECALL)
│   │   ├── x86/           ← 32-bit protected mode (TSS, INT)
│   │   ├── x86_64/        ← 64-bit long mode (VT-x if available)
│   │   ├── xtensa/        ← ESP32 (windowed regs, level-1 int)
│   │   └── mips32/        ← PIC32 (simple exception handling)
│   ├── personality/       ← RTOS personality shells
│   │   ├── freertos/      ← xTaskCreate → uos_task_create
│   │   ├── threadx/       ← tx_thread_create → uos_task_create
│   │   ├── zephyr/        ← k_thread_create → uos_task_create
│   │   ├── posix/         ← pthread_create → uos_task_create
│   │   ├── cmsis_rtos2/   ← osThreadNew → uos_task_create
│   │   └── arduino/       ← xTaskCreate → uos_task_create
│   └── platform/          ← Board-specific BSP
│       ├── stm32f4/
│       ├── nrf52/
│       ├── esp32/
│       ├── imxrt1060/
│       └── ...