# udosteinberg/nova architecture

> Architecture diagram of the GitHub repository udosteinberg/nova, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/udosteinberg/nova
- Repository: https://github.com/udosteinberg/nova

## Overview

##### Project Type and Purpose
- NOVA is a microhypervisor combining microkernel and hypervisor functionality.
- It provides a minimal trusted computing base (TCB) for user‐mode servers and guest VMs, implements capability‐based authorization, scheduling, IPC, and basic virtualization on ARMv8‐A and x86_64 platforms.

##### File Structure Analysis
- Top‐level:
- cmd/ — utility code (digest, CLI tools)
- inc/ — architecture‐independent and arch‐specific headers (aarch64, x86_64)
- src/ — implementation files, split into arch‐specific subdirs and common code
- doc/ — interface specification (boot protocol, API)
- Makefile, .gitlab-ci.yml — build and CI configuration
- Architecture modules: each arch subdirectory under inc/ and src/ contains low-level code for CPU bring-up, interrupt controllers (GIC, APIC), system tables (ACPI, FDT), memory management, virtualization extensions (VMX, SVM, PSCI).

##### README Insights
- Describes target platforms (ARMv8-A ACPI/FDT, x86 VT-x/VT-d, AMD-V)
- Explains capability model, multi‐server design, build variants (CFP, TXT), boot process (via UEFI or multiboot).

##### Main Components
a. Hardware Layer
- CPU(s) with virtualization extensions (EL2 on ARM, VMX/SVM on x86)
- Memory bus, interrupt controller (GIC/APIC), platform firmware (ACPI tables or FDT)
b. NOVA Microhypervisor Core (EL2 / Ring ‑1)
- Bootloader/U-EFI entry
- Kernel entry (arch-specific bootstrap)
- Memory Management (paging, EPT/NPT)
- Scheduler (temporal separation)
- Capability Manager (spatial separation)
- Interrupt handling (GIC driver / APIC driver)
- Hypercall interface
- ACPI/FDT parser
c. User‐Mode Servers (EL1 / Ring 0)
- Device drivers, protocol stacks, policy servers
- IPC channels to core and other servers
d. Guest Operating Systems (EL1 / Ring 1)
- Unmodified VMs running on top of the hypervisor
- Virtual devices mediated by the microhypervisor
e. Tools and Build System
- Cross‐toolchains (PREFIX_aarch64, PREFIX_x86_64) and build targets (Makefile)
- cmd/ utilities for image creation and signing

##### Relationships and Interactions
- Core ↔ Firmware tables (ACPI/FDT) for device discovery
- Core ↔ Memory → Guest VMs (EPT/NPT mappings)
- Core ↔ Interrupt Controller → dispatch to VMs or servers
- Core ↔ User Servers via IPC (capability‐protected endpoints)
- Guest VMs ↔ Virtual Devices mediated by Core
- cmd tools → build images → deployed to hardware/QEMU

##### Architectural Patterns and Technologies
- Microkernel pattern: separation of minimal core vs. user‐mode servers
- Capability‐based access control: fine‐grained resource rights
- Virtualization extensions: VMX/EPT on x86, PSCI on ARM
- Multi‐architecture code sharing: common core + arch plugins
- Build variants: CFP (CET IBT/SSS), TXT measured launch

##### Detailed Capture of Architectural Elements
- Memory regions: hypervisor, user‐servers, guest RAM
- Scheduling domain and capability manager as distinct core services
- Virtual device channels: VM → hypervisor → physical device via server

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        CPU["CPU (ARM EL2 / x86 VMX/SVM)"]:::hardware
        MemBus["Memory Bus"]:::hardware
        IntCtrl["Interrupt Controller (GIC/APIC)"]:::hardware
        Firmware["Firmware Tables (ACPI/FDT)"]:::hardware
    end

    subgraph "NOVA Microhypervisor Core (EL2 / Ring-1)"
        Boot["Bootloader / UEFI Entry"]:::core
        ArchBoot["Arch-Specific Bootstrap"]:::core
        MemMgmt["Memory Management<br/>(Paging, EPT/NPT)"]:::core
        Scheduler["Scheduler"]:::core
        CapManager["Capability Manager"]:::core
        IRQ["Interrupt Handling"]:::core
        Hypercall["Hypercall Interface"]:::core
        Parser["ACPI/FDT Parser"]:::core
        Integrity["Integrity & Security Services"]:::core
        VMExt["Virtualization Extensions"]:::core

        subgraph "Arch Plugins"
            ARMPlugin["ARM (aarch64) Modules"]:::core
            X86Plugin["x86_64 Modules"]:::core
        end
    end

    subgraph "User-Mode Servers (EL1 / Ring-0)"
        Servers["Device Drivers & Policy Servers"]:::server
        IPC["IPC Channels"]:::server
    end

    subgraph "Guest Operating Systems (EL1 / Ring-1)"
        GuestVM["Guest VMs"]:::vm
        VirtDev["Virtual Devices"]:::vm
    end

    subgraph "Tools & Build System"
        CLI["cmd Utilities"]:::tools
        Build["Makefile & CI"]:::tools
    end

    %% Control and data flows
    CPU -->|boots via| Boot
    MemBus --> MemMgmt
    IntCtrl --> IRQ
    Firmware --> Parser
    Boot --> ArchBoot
    ArchBoot --> MemMgmt
    ArchBoot --> Scheduler
    ArchBoot --> CapManager
    ArchBoot --> IRQ
    ArchBoot --> Hypercall
    Parser --> MemMgmt
    MemMgmt -->|maps| GuestVM
    IRQ -->|dispatch IRQs| Servers
    IRQ -->|inject IRQs| GuestVM
    Servers -->|IPC| IPC
    CapManager -->|authorize| IPC
    Hypercall -->|API| Servers
    Hypercall -->|API| GuestVM
    VMExt --> GuestVM
    CLI --> Build
    Build --> CPU

    %% Click Events
    click IntCtrl "https://github.com/udosteinberg/nova/blob/release/src/aarch64/gicc.cpp"
    click IntCtrl "https://github.com/udosteinberg/nova/blob/release/src/x86_64/lapic.cpp"
    click Firmware "https://github.com/udosteinberg/nova/blob/release/src/acpi.cpp"
    click Boot "https://github.com/udosteinberg/nova/blob/release/src/head_mbi.S"
    click Boot "https://github.com/udosteinberg/nova/blob/release/src/uefi.cpp"
    click ArchBoot "https://github.com/udosteinberg/nova/blob/release/src/aarch64/bootstrap.cpp"
    click ArchBoot "https://github.com/udosteinberg/nova/blob/release/src/x86_64/bootstrap.cpp"
    click MemMgmt "https://github.com/udosteinberg/nova/blob/release/src/ptab.cpp"
    click Scheduler "https://github.com/udosteinberg/nova/blob/release/src/scheduler.cpp"
    click CapManager "https://github.com/udosteinberg/nova/blob/release/src/sm.cpp"
    click IRQ "https://github.com/udosteinberg/nova/blob/release/src/aarch64/interrupt.cpp"
    click Hypercall "https://github.com/udosteinberg/nova/blob/release/src/syscall.cpp"
    click Parser "https://github.com/udosteinberg/nova/blob/release/src/acpi.cpp"
    click Integrity "https://github.com/udosteinberg/nova/blob/release/src/integrity.cpp"
    click VMExt "https://github.com/udosteinberg/nova/blob/release/src/aarch64/vmcb.cpp"
    click CLI "https://github.com/udosteinberg/nova/blob/release/cmd/digest.cpp"
    click Build "https://github.com/udosteinberg/nova/tree/release/Makefile"

    %% Styles
    classDef hardware fill:#eeeeee,stroke:#666666,color:#333333;
    classDef core fill:#ffdddd,stroke:#aa0000,color:#660000;
    classDef server fill:#ddddff,stroke:#0000aa,color:#000066;
    classDef vm fill:#ddffdd,stroke:#00aa00,color:#006600;
    classDef tools fill:#ffe0b3,stroke:#ff9900,color:#994d00;
```
