# UniversalisOS — Safety-Critical Type-1 Hypervisor

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/Version-1.0.0--alpha.1-green.svg)](VERSION)

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

```bash
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

```bash
# 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

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

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

### AArch64

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

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

### RISC-V

```bash
cd kernel
make ARCH=riscv PLATFORM=polarfire
```

Output: `build/riscv/polarfire/universalisos.elf`

### AArch64 with Linux Guest

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

### Clean Builds

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

## Documentation

- [docs/API.md](docs/API.md) — Hypercall interface, toolchain CLI reference
- [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) — Build prerequisites, code style, PR process
- [COMPONENTS.md](COMPONENTS.md) — Component architecture and safety matrix
- [HYPERVISOR.md](HYPERVISOR.md) — Type-1 hypervisor design specifications
- [CHANGELOG.md](CHANGELOG.md) — Version history and release notes
- [kernel/README.md](kernel/README.md) — Kernel build and run guide
- [UNIVERSALISOS_VS_PIKEOS_5.0.md](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](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