# 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: ```c 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 ```c /* * 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/ │ └── ... ```