# bryansteiner/gpu-passthrough-tutorial architecture

> Architecture diagram of the GitHub repository bryansteiner/gpu-passthrough-tutorial, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bryansteiner/gpu-passthrough-tutorial
- Repository: https://github.com/bryansteiner/gpu-passthrough-tutorial

## Overview

This repository supports a Linux KVM Windows gaming VM with GPU passthrough. The documented workflow prepares IOMMU support, inspects device groups, and dynamically assigns the guest GPU to VFIO before launch, restoring host drivers when the VM stops. The tree includes VM configuration, a QEMU script, and lifecycle hooks for VFIO binding, huge pages, and CPU power mode. Source contents were not provided, so connections to individual runtime scripts are omitted or marked unverified.

Main entry points: [`kvm/scripts/qemu.sh`](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/scripts/qemu.sh) (QEMU launch), [`kvm/scripts/iommu.sh`](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/scripts/iommu.sh) (IOMMU discovery), [`kvm/win10.xml`](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/win10.xml) (VM configuration), [`kvm/kvm.conf`](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/kvm.conf) (KVM settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host_setup["Host preparation"]
  node_iommu_scan["IOMMU discovery<br/>[iommu.sh]"]
end

subgraph group_vm_runtime["Guest runtime"]
  node_vm_config["VM configuration<br/>[win10.xml]"]
  node_kvm_config["KVM settings<br/>[kvm.conf]"]
  node_qemu_launch["QEMU launch<br/>[qemu.sh]"]
end

subgraph group_lifecycle["Lifecycle hooks"]
  node_vfio_bind["VFIO binding<br/>[bind_vfio.sh]"]
  node_vfio_unbind["VFIO unbinding<br/>[unbind_vfio.sh]"]
  node_huge_alloc["Hugepage allocation<br/>[alloc_hugepages.sh]"]
  node_huge_dealloc["Hugepage release"]
  node_cpu_performance["Performance mode"]
  node_cpu_ondemand["On-demand mode"]
end

node_operator(("Host operator"))

node_operator -->|"inspects groups"| node_iommu_scan
node_operator -.->|"launches VM"| node_qemu_launch
node_qemu_launch -.->|"uses configuration"| node_vm_config
node_qemu_launch -.->|"uses settings"| node_kvm_config
node_qemu_launch -.->|"triggers before start"| node_vfio_bind
node_qemu_launch -.->|"triggers after stop"| node_vfio_unbind
node_qemu_launch -.->|"triggers before start"| node_huge_alloc
node_qemu_launch -.->|"triggers after stop"| node_huge_dealloc
node_qemu_launch -.->|"triggers before start"| node_cpu_performance
node_qemu_launch -.->|"triggers after stop"| node_cpu_ondemand

click node_iommu_scan "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/scripts/iommu.sh"
click node_vm_config "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/win10.xml"
click node_kvm_config "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/kvm.conf"
click node_qemu_launch "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/scripts/qemu.sh"
click node_vfio_bind "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/prepare/begin/bind_vfio.sh"
click node_vfio_unbind "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/release/end/unbind_vfio.sh"
click node_huge_alloc "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/prepare/begin/alloc_hugepages.sh"
click node_huge_dealloc "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/release/end/dealloc_hugepages.sh"
click node_cpu_performance "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/prepare/begin/cpu_mode_performance.sh"
click node_cpu_ondemand "https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/release/end/cpu_mode_ondemand.sh"

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_iommu_scan toneBlue
class node_vm_config,node_kvm_config,node_qemu_launch toneAmber
class node_vfio_bind,node_vfio_unbind,node_huge_alloc,node_huge_dealloc,node_cpu_performance,node_cpu_ondemand toneMint
class node_operator toneIndigo
```

## Components

### Host preparation

- [IOMMU discovery](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/scripts/iommu.sh): `kvm/scripts/iommu.sh`

### Guest runtime

- [VM configuration](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/win10.xml): `kvm/win10.xml`
- [KVM settings](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/kvm.conf): `kvm/kvm.conf`
- [QEMU launch](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/scripts/qemu.sh): `kvm/scripts/qemu.sh`

### Lifecycle hooks

- [VFIO binding](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/prepare/begin/bind_vfio.sh): `kvm/hooks/prepare/begin/bind_vfio.sh`
- [VFIO unbinding](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/release/end/unbind_vfio.sh): `kvm/hooks/release/end/unbind_vfio.sh`
- [Hugepage allocation](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/prepare/begin/alloc_hugepages.sh): `kvm/hooks/prepare/begin/alloc_hugepages.sh`
- [Hugepage release](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/release/end/dealloc_hugepages.sh): `kvm/hooks/release/end/dealloc_hugepages.sh`
- [Performance mode](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/prepare/begin/cpu_mode_performance.sh): `kvm/hooks/prepare/begin/cpu_mode_performance.sh`
- [On-demand mode](https://github.com/bryansteiner/gpu-passthrough-tutorial/blob/master/kvm/hooks/release/end/cpu_mode_ondemand.sh): `kvm/hooks/release/end/cpu_mode_ondemand.sh`

### Other components

- **Host operator**

## Connections

- Host operator → IOMMU discovery: inspects groups (evidence: `README.md`)
- Host operator → QEMU launch: launches VM
- QEMU launch → VM configuration: uses configuration
- QEMU launch → KVM settings: uses settings
- QEMU launch → VFIO binding: triggers before start
- QEMU launch → VFIO unbinding: triggers after stop
- QEMU launch → Hugepage allocation: triggers before start
- QEMU launch → Hugepage release: triggers after stop
- QEMU launch → Performance mode: triggers before start
- QEMU launch → On-demand mode: triggers after stop
