# wyattvo/cheri-qemu-port architecture

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

- Interactive diagram: https://gitdiagram.com/wyattvo/cheri-qemu-port
- Repository: https://github.com/wyattvo/cheri-qemu-port

## Overview

This is CHERI QEMU 10.2: a system emulator fork adding CHERI-RISC-V and Arm Morello support. The principal workflow is to start a system emulator, execute guest instructions under the selected CPU/accelerator, and interact with emulated hardware; CHERI adds capability-aware instruction behavior and extension restrictions. The README also documents TestRIG/RVFI-DII validation and CheriBSD boot support. Sampled source is mostly QEMU infrastructure rather than the CHERI target implementation, so target-specific links rely on README statements; unsampled subsystem paths are omitted where the tree gives no exact source path.

Main entry points: [`accel/tcg/cpu-exec.c`](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/accel/tcg/cpu-exec.c) (TCG execution), [`system/main.c`](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/system/main.c) (System entry), [`hw/usb/dev-storage.c`](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/hw/usb/dev-storage.c) (USB mass storage), [`storage-daemon/qemu-storage-daemon.c`](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/storage-daemon/qemu-storage-daemon.c) (Storage daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Emulator runtime"]
  node_system_entry["System entry<br/>[main.c]"]
  node_tcg["TCG execution<br/>[cpu-exec.c]"]
  node_tcg_translate["Translation engine<br/>[tcg.c]"]
end

subgraph group_cheri["CHERI execution"]
  node_riscv_cheri["CHERI-RISC-V"]
  node_morello["Arm Morello"]
  node_unsafe_policy["Unsafe extensions"]
end

subgraph group_devices["Guest devices and storage"]
  node_usb_msd["USB mass storage<br/>[dev-storage.c]"]
  node_storage_daemon["Storage daemon"]
  node_nbd["NBD server<br/>[server.c]"]
  node_pr_helper["Reservation helper"]
end

subgraph group_operations["Operations and validation"]
  node_guest_agent["Guest agent<br/>[main.c]"]
  node_testrig(("TestRIG"))
  node_cheribsd(("CheriBSD guest"))
  node_morello_tests(("Morello tests"))
end

node_user(("Emulator operator"))

node_user -->|"starts"| node_system_entry
node_system_entry -.->|"runs guest"| node_tcg
node_tcg -.->|"translates"| node_tcg_translate
node_tcg -.->|"executes"| node_riscv_cheri
node_tcg -.->|"executes"| node_morello
node_riscv_cheri -->|"enforces policy"| node_unsafe_policy
node_user -.->|"configures device"| node_usb_msd
node_user -->|"starts"| node_storage_daemon
node_storage_daemon -.->|"serves exports"| node_nbd
node_usb_msd -.->|"uses reservations"| node_pr_helper
node_user -.->|"starts"| node_guest_agent
node_testrig -->|"checks instructions"| node_riscv_cheri
node_cheribsd -->|"boots on"| node_riscv_cheri
node_morello_tests -->|"tests execution"| node_morello

click node_system_entry "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/system/main.c"
click node_tcg "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/accel/tcg/cpu-exec.c"
click node_tcg_translate "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/tcg/tcg.c"
click node_usb_msd "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/hw/usb/dev-storage.c"
click node_storage_daemon "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/storage-daemon/qemu-storage-daemon.c"
click node_nbd "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/nbd/server.c"
click node_pr_helper "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/scsi/pr-manager-helper.c"
click node_guest_agent "https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/qga/main.c"

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_system_entry,node_tcg,node_tcg_translate toneBlue
class node_riscv_cheri,node_morello,node_unsafe_policy toneAmber
class node_usb_msd,node_storage_daemon,node_nbd,node_pr_helper toneMint
class node_guest_agent,node_testrig,node_cheribsd,node_morello_tests toneRose
class node_user toneIndigo
```

## Components

### Emulator runtime

- [System entry](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/system/main.c): `system/main.c`
- [TCG execution](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/accel/tcg/cpu-exec.c): `accel/tcg/cpu-exec.c`
- [Translation engine](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/tcg/tcg.c): `tcg/tcg.c`

### CHERI execution

- **CHERI-RISC-V**
- **Arm Morello**
- **Unsafe extensions**

### Guest devices and storage

- [USB mass storage](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/hw/usb/dev-storage.c): `hw/usb/dev-storage.c`
- [Storage daemon](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/storage-daemon/qemu-storage-daemon.c): `storage-daemon/qemu-storage-daemon.c`
- [NBD server](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/nbd/server.c): `nbd/server.c`
- [Reservation helper](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/scsi/pr-manager-helper.c): `scsi/pr-manager-helper.c`

### Operations and validation

- [Guest agent](https://github.com/wyattvo/cheri-qemu-port/blob/cheri-10.2/qga/main.c): `qga/main.c`
- **TestRIG**
- **CheriBSD guest**
- **Morello tests**

### Other components

- **Emulator operator**

## Connections

- Emulator operator → System entry: starts
- System entry → TCG execution: runs guest
- TCG execution → Translation engine: translates
- TCG execution → CHERI-RISC-V: executes
- TCG execution → Arm Morello: executes
- CHERI-RISC-V → Unsafe extensions: enforces policy
- Emulator operator → USB mass storage: configures device
- Emulator operator → Storage daemon: starts (evidence: `storage-daemon/qemu-storage-daemon.c`)
- Storage daemon → NBD server: serves exports
- USB mass storage → Reservation helper: uses reservations
- Emulator operator → Guest agent: starts
- TestRIG → CHERI-RISC-V: checks instructions
- CheriBSD guest → CHERI-RISC-V: boots on
- Morello tests → Arm Morello: tests execution
