# nguyentrongphuc552003/haven architecture

> Architecture diagram of the GitHub repository nguyentrongphuc552003/haven, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nguyentrongphuc552003/haven
- Repository: https://github.com/nguyentrongphuc552003/haven

## Overview

Haven is an ARM64 EL2 static-partitioning hypervisor: its principal workflow initializes isolation policy, configures hardware-backed memory, DMA, interrupt, and CPU-time controls, then transfers execution to partition guests. A separate research workflow reads enforced hardware state from outside Haven and compares it with a grant to detect drift. The graph preserves documented capabilities even where their implementation was not sampled; edges for those links rely on README statements rather than inspected call sites.

Main entry points: [`src/core/partition.c`](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/partition.c) (Partition launcher), [`tools/readback/readback.py`](https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/readback.py) (Hardware read-back), [`src/core/dma/smmu.c`](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/dma/smmu.c) (SMMUv3 DMA), [`src/core/init.c`](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/init.c) (Hypervisor init)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boot["Boot and platform"]
  node_efi_loader["EFI loader<br/>[boot.c]"]
  node_platform["Platform setup<br/>[platform.c]"]
end

subgraph group_hypervisor["Hypervisor enforcement"]
  node_init["Hypervisor init<br/>[init.c]"]
  node_partition["Partition launcher<br/>[partition.c]"]
  node_stage2["Stage-2 isolation<br/>[stage2.c]"]
  node_dma_policy["DMA policy<br/>[iommu_policy.c]"]
  node_smmu["SMMUv3 DMA<br/>[smmu.c]"]
  node_smmu_driver["SMMUv3 driver<br/>[smmu_v3.c]"]
  node_irq_ownership["IRQ ownership<br/>[ownership.c]"]
  node_vgic["Virtual interrupts<br/>[vgic.c]"]
  node_gic_driver["GICv3 driver<br/>[gic_v3.c]"]
  node_budget["CPU budgets<br/>[budget.c]"]
  node_timer["EL2 timer<br/>[timer.c]"]
end

subgraph group_guest["Partition guests"]
  node_guest_a["Partition A"]
  node_guest_b["Partition B"]
end

subgraph group_research["External verification"]
  node_grant["Isolation grant<br/>[grant.py]"]
  node_readback["Hardware read-back<br/>[readback.py]"]
  node_readback_report["Drift comparison<br/>[readback.py]"]
end

node_firmware(("UEFI firmware"))
node_qemu(("QEMU machine"))

node_firmware -->|"loads image"| node_efi_loader
node_efi_loader -->|"enters EL2"| node_init
node_platform -.->|"provides platform"| node_init
node_init -->|"launches partitions"| node_partition
node_partition -->|"sets memory"| node_stage2
node_partition -->|"applies DMA grants"| node_dma_policy
node_dma_policy -.->|"configures policy"| node_smmu
node_smmu -.->|"programs hardware"| node_smmu_driver
node_partition -->|"sets IRQ ownership"| node_irq_ownership
node_partition -->|"sets CPU budgets"| node_budget
node_budget -.->|"uses timer"| node_timer
node_irq_ownership -.->|"delivers virtual IRQs"| node_vgic
node_vgic -.->|"uses GICv3"| node_gic_driver
node_partition -->|"enters guest"| node_guest_a
node_partition -->|"starts via PSCI"| node_guest_b
node_qemu -->|"exposes state"| node_readback
node_grant -->|"supplies expected state"| node_readback_report
node_readback -->|"compares state"| node_readback_report
node_stage2 -.->|"state is inspected"| node_readback
node_smmu -.->|"state is inspected"| node_readback
node_gic_driver -.->|"state is inspected"| node_readback

click node_efi_loader "https://github.com/nguyentrongphuc552003/haven/blob/main/boot/efi/boot.c"
click node_platform "https://github.com/nguyentrongphuc552003/haven/blob/main/src/platform/qemu-virt/platform.c"
click node_init "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/init.c"
click node_partition "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/partition.c"
click node_stage2 "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/mm/stage2.c"
click node_dma_policy "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/iommu/iommu_policy.c"
click node_smmu "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/dma/smmu.c"
click node_smmu_driver "https://github.com/nguyentrongphuc552003/haven/blob/main/drivers/iommu/smmu_v3.c"
click node_irq_ownership "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/irq/ownership.c"
click node_vgic "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/irq/vgic.c"
click node_gic_driver "https://github.com/nguyentrongphuc552003/haven/blob/main/drivers/irqchip/gic_v3.c"
click node_budget "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/sched/budget.c"
click node_timer "https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/time/timer.c"
click node_guest_a "https://github.com/nguyentrongphuc552003/haven/blob/main/src/guest/rtos/freertos_integration.c"
click node_guest_b "https://github.com/nguyentrongphuc552003/haven/blob/main/src/guest/rtos/freertos_integration.c"
click node_grant "https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/grant.py"
click node_readback "https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/readback.py"
click node_readback_report "https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/readback.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_efi_loader,node_platform toneBlue
class node_init,node_partition,node_stage2,node_dma_policy,node_smmu,node_smmu_driver,node_irq_ownership,node_vgic,node_gic_driver,node_budget,node_timer toneAmber
class node_guest_a,node_guest_b toneMint
class node_grant,node_readback,node_readback_report toneRose
class node_firmware,node_qemu toneIndigo
```

## Components

### Boot and platform

- [EFI loader](https://github.com/nguyentrongphuc552003/haven/blob/main/boot/efi/boot.c): `boot/efi/boot.c`
- [Platform setup](https://github.com/nguyentrongphuc552003/haven/blob/main/src/platform/qemu-virt/platform.c): `src/platform/qemu-virt/platform.c`

### Hypervisor enforcement

- [Hypervisor init](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/init.c): `src/core/init.c`
- [Partition launcher](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/partition.c): `src/core/partition.c`
- [Stage-2 isolation](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/mm/stage2.c): `src/core/mm/stage2.c`
- [DMA policy](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/iommu/iommu_policy.c): `src/core/iommu/iommu_policy.c`
- [SMMUv3 DMA](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/dma/smmu.c): `src/core/dma/smmu.c`
- [SMMUv3 driver](https://github.com/nguyentrongphuc552003/haven/blob/main/drivers/iommu/smmu_v3.c): `drivers/iommu/smmu_v3.c`
- [IRQ ownership](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/irq/ownership.c): `src/core/irq/ownership.c`
- [Virtual interrupts](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/irq/vgic.c): `src/core/irq/vgic.c`
- [GICv3 driver](https://github.com/nguyentrongphuc552003/haven/blob/main/drivers/irqchip/gic_v3.c): `drivers/irqchip/gic_v3.c`
- [CPU budgets](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/sched/budget.c): `src/core/sched/budget.c`
- [EL2 timer](https://github.com/nguyentrongphuc552003/haven/blob/main/src/core/time/timer.c): `src/core/time/timer.c`

### Partition guests

- [Partition A](https://github.com/nguyentrongphuc552003/haven/blob/main/src/guest/rtos/freertos_integration.c): `src/guest/rtos/freertos_integration.c`
- [Partition B](https://github.com/nguyentrongphuc552003/haven/blob/main/src/guest/rtos/freertos_integration.c): `src/guest/rtos/freertos_integration.c`

### External verification

- [Isolation grant](https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/grant.py): `tools/readback/grant.py`
- [Hardware read-back](https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/readback.py): `tools/readback/readback.py`
- [Drift comparison](https://github.com/nguyentrongphuc552003/haven/blob/main/tools/readback/readback.py): `tools/readback/readback.py`

### Other components

- **UEFI firmware**
- **QEMU machine**

## Connections

- UEFI firmware → EFI loader: loads image (evidence: `boot/efi/boot.c`)
- EFI loader → Hypervisor init: enters EL2 (evidence: `boot/efi/boot.c`)
- Platform setup → Hypervisor init: provides platform
- Hypervisor init → Partition launcher: launches partitions (evidence: `src/core/partition.c`)
- Partition launcher → Stage-2 isolation: sets memory (evidence: `src/core/partition.c`)
- Partition launcher → DMA policy: applies DMA grants (evidence: `src/core/partition.c`)
- DMA policy → SMMUv3 DMA: configures policy
- SMMUv3 DMA → SMMUv3 driver: programs hardware
- Partition launcher → IRQ ownership: sets IRQ ownership (evidence: `src/core/partition.c`)
- Partition launcher → CPU budgets: sets CPU budgets (evidence: `src/core/partition.c`)
- CPU budgets → EL2 timer: uses timer
- IRQ ownership → Virtual interrupts: delivers virtual IRQs
- Virtual interrupts → GICv3 driver: uses GICv3
- Partition launcher → Partition A: enters guest (evidence: `src/core/partition.c`)
- Partition launcher → Partition B: starts via PSCI (evidence: `README.md`)
- QEMU machine → Hardware read-back: exposes state (evidence: `README.md`)
- Isolation grant → Drift comparison: supplies expected state (evidence: `README.md`)
- Hardware read-back → Drift comparison: compares state (evidence: `README.md`)
- Stage-2 isolation → Hardware read-back: state is inspected
- SMMUv3 DMA → Hardware read-back: state is inspected
- GICv3 driver → Hardware read-back: state is inspected