universalisos/README.md

UniversalisOS — Safety-Critical Type-1 Hypervisor

UniversalisOS is a safety-critical type-1 hypervisor for cyber-physical systems, implementing PikeOS 5.0 patterns. Supports ARMv7, AArch64 (EL2), and RISC-V (S-mode) with ARINC-653 partitioning, VirtIO paravirtualization, and live migration.

Quick Start

Prerequisites

• ARMv7: arm-none-eabi-gcc + qemu-system-arm
• AArch64: aarch64-linux-gnu-gcc + qemu-system-aarch64
• RISC-V: riscv64-linux-gnu-gcc + qemu-system-riscv64
• Mycelium: Rust toolchain (cargo)
• Tools: Python 3.11+

Build the Kernel

cd kernel

# ARMv7 (primary, fully tested)
make ARCH=armv7 PLATFORM=qemu-arm-virt

# AArch64 (EL2 hypervisor)
make ARCH=aarch64 PLATFORM=qemu-aarch64-virt

# RISC-V (Icicle Kit)
make ARCH=riscv PLATFORM=polarfire

Run in QEMU

# ARMv7
qemu-system-arm -M virt -cpu cortex-a15 -m 512M \
  -nographic -kernel build/armv7/qemu-arm-virt/universalisos.elf

# AArch64 (virtualization=on is mandatory)
qemu-system-aarch64 -M virt,gic-version=3,virtualization=on \
  -cpu cortex-a53 -m 512M -smp 4 -nographic \
  -kernel build/aarch64/qemu-aarch64-virt/universalisos.elf

# RISC-V (bare-metal, BSP only)
qemu-system-riscv64 -machine microchip-icicle-kit -smp 5 -m 2G \
  -nographic -bios none -kernel build/riscv/polarfire/universalisos.elf

Press Ctrl+A then X to exit QEMU.

Architecture

┌──────────────────────────────────────────────┐
│  Guest Partitions (ARINC-653, POSIX, Bare)   │
├──────────────────────────────────────────────┤
│  Hypercall Interface (HVC / ecall / SVC)     │
├──────────────────────────────────────────────┤
│  Hypervisor Core                             │
│  ├─ Scheduler (priority, time-partitioning)  │
│  ├─ Memory (MMU, stage-2, partitions)        │
│  ├─ IPC (sampling ports, mailbox)            │
│  ├─ VirtIO (blk, net, console)              │
│  ├─ Migration (checkpoint/restore)           │
│  └─ Health Monitor                           │
├──────────────────────────────────────────────┤
│  Hardware Abstraction (ARM GIC, PL011, etc.) │
└──────────────────────────────────────────────┘

Project Structure

Directory	Description
kernel/	Hypervisor kernel (C++, freestanding)
tools/uos-cover/	Coverage toolchain (8 tools, DO-178C)
tools/uos-pkg/	Package toolchain (RPM spec parser, build engine)
mycelium-tfw-extension/	VS Code extension for test framework
guests/	Guest OS payloads (Linux aarch64, RISC-V sampling)
src/	PikeOS source import (reference)
docs/	Documentation (extracted PikeOS manuals, parity specs)
third_party/	External deps (musl-uos-port, hardened_malloc)

What's Included

• 3 architecture backends: ARMv7 (SVC-based), AArch64 (EL2 HVC), RISC-V (S-mode ecall)
• ARINC-653 partitioning: Time-partitioned scheduling, sampling ports, error management
• VirtIO paravirtualization: Block, network, and console devices via hypercalls
• Live migration: Checkpoint/restore with guest state, memory, and device snapshots
• Coverage toolchain: Instrumentation, structural linking, report generation, justification, traceability
• Package toolchain: RPM 4.2-compatible spec parser and build engine
• ADT library port: PikeOS data structures (AVL, CRC32, list, lheap, kdev)
• Mycelium toolchain: XSD-to-C code generation (21 Rust crates replacing proprietary configconv)
• DO-178C certification support: Verification plans, evidence packaging, traceability matrices

Build Instructions

ARMv7

cd kernel
make ARCH=armv7 PLATFORM=qemu-arm-virt

Output: build/armv7/qemu-arm-virt/universalisos.elf

AArch64

cd kernel
make ARCH=aarch64 PLATFORM=qemu-aarch64-virt

Output: build/aarch64/qemu-aarch64-virt/universalisos.elf

RISC-V

cd kernel
make ARCH=riscv PLATFORM=polarfire

Output: build/riscv/polarfire/universalisos.elf

AArch64 with Linux Guest

cd kernel
make run-linux-real ROOTFS=<path-to-rootfs.img>

Clean Builds

make clean          # Clean current arch/platform
make clean-all      # Clean all build trees

Documentation

• docs/API.md — Hypercall interface, toolchain CLI reference
• docs/CONTRIBUTING.md — Build prerequisites, code style, PR process
• COMPONENTS.md — Component architecture and safety matrix
• HYPERVISOR.md — Type-1 hypervisor design specifications
• CHANGELOG.md — Version history and release notes
• kernel/README.md — Kernel build and run guide
• UNIVERSALISOS_VS_PIKEOS_5.0.md — PikeOS 5.0 parity roadmap

Safety Standards

UniversalisOS targets compliance with:

• DO-178C — Airborne software (DAL-A through DAL-E)
• ISO 26262 — Automotive functional safety (ASIL-D)
• MISRA C++ / MISRA C — Coding guidelines
• ARINC 653 — Avionics application standard

License

MIT License — see LICENSE for details.

Integration

UniversalisOS integrates with the PortugalFuturista ecosystem:

• nervura-electrica — Infrastructure platform and hosting
• Aurelio — Compiler, gateway, and cyber-physical brain platform
• mycelium — XSD-to-C configuration toolchain