# openeuler-mirror/stratovirt architecture

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

- Interactive diagram: https://gitdiagram.com/openeuler-mirror/stratovirt
- Repository: https://github.com/openeuler-mirror/stratovirt

## Overview

#### Purpose and entry points
StratoVirt is a Rust virtualization platform for cloud datacenters, supporting standard VMs, lightweight microVMs, and container/Serverless-adjacent runtimes. The primary `stratovirt` process starts at `src/main.rs`, parses VM configuration, creates the selected machine model, and exposes management over QMP. Auxiliary executables include the image tool at `image/src/main.rs`, OCI-oriented `ozonec/src/main.rs`, and sandbox helper `ozone/src/main.rs`.

#### Startup, configuration, and management plane
CLI arguments and device definitions are parsed into machine configuration by `machine_manager/src/cmdline.rs` and `machine_manager/src/config/mod.rs`. `machine_manager/src/machine.rs` coordinates lifecycle creation and runtime operations; its event loop and notifier layer (`machine_manager/src/event_loop.rs`, `machine_manager/src/notifier.rs`) bridge host file descriptors/events to VM components. QMP is a Unix-socket control boundary implemented under `machine_manager/src/qmp/qmp_socket.rs` and `machine_manager/src/qmp/qmp_schema.rs`.

#### Machine construction and guest boot
The `machine` crate realizes architecture- and model-specific virtual hardware: x86 standard/micro machines live in `machine/src/x86_64/standard.rs` and `machine/src/x86_64/micro.rs`; AArch64 equivalents are in `machine/src/aarch64/standard.rs` and `machine/src/aarch64/micro.rs`. Boot loading is separated into `boot_loader/src/x86_64/mod.rs` and `boot_loader/src/aarch64/mod.rs`. Firmware-facing metadata is generated through ACPI for x86 (`acpi/src/acpi_table.rs`) or device trees for AArch64 (`machine/src/aarch64/fdt.rs`).

#### CPU, memory, and KVM boundary
Guest execution uses Linux KVM through `hypervisor/src/kvm/mod.rs`, with architecture-specific register/capability handling in `hypervisor/src/kvm/x86_64/mod.rs` and `hypervisor/src/kvm/aarch64/mod.rs`. Guest physical-memory layout, RAM regions, host mappings, and address-space listener notifications are owned by `address_space/src/address_space.rs`, `address_space/src/region.rs`, and `address_space/src/host_mmap.rs`. This is the primary boundary between VM abstractions and host kernel APIs, including userfaultfd support (`address_space/src/uffd.rs`).

#### Virtual devices and I/O data paths
The device model is divided by bus and protocol. PCI topology, configuration, interrupts, and hotplug are under `devices/src/pci/bus.rs`, `devices/src/pci/config.rs`, and `devices/src/pci/hotplug.rs`; platform/sysbus devices are rooted in `devices/src/sysbus/mod.rs`. Virtio supplies the main paravirtual I/O path: common queues/transports are in `virtio/src/queue/split.rs` and `virtio/src/transport/virtio_pci.rs`, while block and network devices are in `virtio/src/device/block.rs` and `virtio/src/device/net.rs`. Host-backed storage supports raw and qcow2 images via `block_backend/src/raw.rs` and `block_backend/src/qcow2/mod.rs`.

#### Host integrations and advanced lifecycle
Host I/O relies on Linux facilities including TAP networking (`util/src/tap.rs`), asynchronous I/O (`util/src/aio/mod.rs`), seccomp (`util/src/seccomp.rs`), VFIO passthrough (`vfio/src/vfio_pci.rs`), and vhost kernel/user backends (`virtio/src/vhost/kernel/mod.rs`, `virtio/src/vhost/user/mod.rs`). Migration and snapshots are centralized in `migration/src/manager.rs`, `migration/src/protocol.rs`, and `migration/src/snapshot.rs`; they form a lifecycle boundary requiring machine, memory, CPU, and device state coordination.

#### Observability and user-facing access
Tracing is generated from event definitions and emitted through `trace/src/lib.rs`, `trace/src/ftrace.rs`, and `trace/src/hitrace.rs`; system events use `hisysevent/src/interface.rs`. Guest display/input can use VNC (`ui/src/vnc/mod.rs`), GTK (`ui/src/gtk/mod.rs`), or OHUI server channels (`ui/src/ohui_srv/mod.rs`). These remain optional peripheral front ends rather than the core VM control path.

Main entry points: [`machine_manager/src/machine.rs`](https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/machine.rs) (Machine manager), [`machine/src/x86_64/standard.rs`](https://github.com/openeuler-mirror/stratovirt/blob/master/machine/src/x86_64/standard.rs) (Standard and micro machines), [`migration/src/manager.rs`](https://github.com/openeuler-mirror/stratovirt/blob/master/migration/src/manager.rs) (Migration and snapshots), [`virtio/src/device/block.rs`](https://github.com/openeuler-mirror/stratovirt/blob/master/virtio/src/device/block.rs) (Virtio block and net)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_stratovirt["stratovirt process<br/>Rust binary<br/>[main.rs]"]
  node_aux_tools["Auxiliary tools<br/>Rust binaries<br/>[main.rs]"]
end

subgraph group_control["Control Plane"]
  node_config["CLI and VM config<br/>configuration<br/>[cmdline.rs]"]
  node_machine_manager["Machine manager<br/>lifecycle coordinator<br/>[machine.rs]"]
  node_event_loop["Event loop and notifiers<br/>host event bridge<br/>[event_loop.rs]"]
  node_qmp{{"QMP control socket<br/>Unix-socket API<br/>[qmp_socket.rs]"}}
end

subgraph group_machine["Machine Construction"]
  node_machine_models["Standard and micro machines<br/>machine models<br/>[standard.rs]"]
  node_boot_loader["Boot loader<br/>guest boot<br/>[mod.rs]"]
  node_firmware_metadata["ACPI / device tree<br/>firmware metadata<br/>[acpi_table.rs]"]
end

subgraph group_runtime["Execution Core"]
  node_kvm{{"KVM backend<br/>Linux hypervisor<br/>[mod.rs]"}}
  node_address_space["Guest address space<br/>memory manager<br/>[address_space.rs]"]
end

subgraph group_io["I/O and Devices"]
  node_pci["PCI and sysbus<br/>device buses<br/>[bus.rs]"]
  node_virtio["Virtio transport and queues<br/>paravirtual bus<br/>[virtio_pci.rs]"]
  node_virtio_devices["Virtio block and net<br/>paravirtual devices<br/>[block.rs]"]
  node_block_backend[("Block backends<br/>image storage<br/>[mod.rs]")]
  node_host_io["Host I/O facilities<br/>Linux integration<br/>[mod.rs]"]
  node_vfio_vhost["VFIO and vhost<br/>accelerated I/O<br/>[vfio_pci.rs]"]
end

subgraph group_lifecycle["Lifecycle and Access"]
  node_migration["Migration and snapshots<br/>state lifecycle<br/>[manager.rs]"]
  node_tracing["Tracing and system events<br/>observability<br/>[lib.rs]"]
  node_ui["Display and input front ends<br/>optional UI<br/>[mod.rs]"]
end

node_stratovirt -->|"parses"| node_config
node_stratovirt -->|"starts"| node_machine_manager
node_config -->|"supplies VM definition"| node_machine_manager
node_qmp -->|"management commands"| node_machine_manager
node_machine_manager -->|"drives"| node_event_loop
node_event_loop -->|"socket events"| node_qmp
node_machine_manager -->|"creates"| node_machine_models
node_machine_models -->|"boots guest"| node_boot_loader
node_machine_models -->|"publishes hardware metadata"| node_firmware_metadata
node_machine_models -->|"creates vCPUs"| node_kvm
node_machine_models -->|"maps guest RAM"| node_address_space
node_machine_models -->|"realizes buses"| node_pci
node_pci -->|"hosts PCI transport"| node_virtio
node_virtio -->|"carries queues"| node_virtio_devices
node_virtio_devices -->|"block I/O"| node_block_backend
node_virtio_devices -->|"network and async I/O"| node_host_io
node_pci -->|"passthrough attachment"| node_vfio_vhost
node_virtio -->|"vhost acceleration"| node_vfio_vhost
node_address_space -->|"memory slots"| node_kvm
node_machine_manager -->|"lifecycle operations"| node_migration
node_migration -->|"machine state"| node_machine_models
node_migration -->|"memory state"| node_address_space
node_migration -->|"CPU state"| node_kvm
node_migration -->|"device state"| node_virtio_devices
node_machine_manager -.->|"emits events"| node_tracing
node_machine_manager -.->|"optional guest access"| node_ui

click node_stratovirt "https://github.com/openeuler-mirror/stratovirt/blob/master/src/main.rs"
click node_aux_tools "https://github.com/openeuler-mirror/stratovirt/blob/master/image/src/main.rs"
click node_config "https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/cmdline.rs"
click node_machine_manager "https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/machine.rs"
click node_event_loop "https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/event_loop.rs"
click node_qmp "https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/qmp/qmp_socket.rs"
click node_machine_models "https://github.com/openeuler-mirror/stratovirt/blob/master/machine/src/x86_64/standard.rs"
click node_boot_loader "https://github.com/openeuler-mirror/stratovirt/blob/master/boot_loader/src/x86_64/mod.rs"
click node_firmware_metadata "https://github.com/openeuler-mirror/stratovirt/blob/master/acpi/src/acpi_table.rs"
click node_kvm "https://github.com/openeuler-mirror/stratovirt/blob/master/hypervisor/src/kvm/mod.rs"
click node_address_space "https://github.com/openeuler-mirror/stratovirt/blob/master/address_space/src/address_space.rs"
click node_pci "https://github.com/openeuler-mirror/stratovirt/blob/master/devices/src/pci/bus.rs"
click node_virtio "https://github.com/openeuler-mirror/stratovirt/blob/master/virtio/src/transport/virtio_pci.rs"
click node_virtio_devices "https://github.com/openeuler-mirror/stratovirt/blob/master/virtio/src/device/block.rs"
click node_block_backend "https://github.com/openeuler-mirror/stratovirt/blob/master/block_backend/src/qcow2/mod.rs"
click node_host_io "https://github.com/openeuler-mirror/stratovirt/blob/master/util/src/aio/mod.rs"
click node_vfio_vhost "https://github.com/openeuler-mirror/stratovirt/blob/master/vfio/src/vfio_pci.rs"
click node_migration "https://github.com/openeuler-mirror/stratovirt/blob/master/migration/src/manager.rs"
click node_tracing "https://github.com/openeuler-mirror/stratovirt/blob/master/trace/src/lib.rs"
click node_ui "https://github.com/openeuler-mirror/stratovirt/blob/master/ui/src/vnc/mod.rs"

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_stratovirt,node_aux_tools toneBlue
class node_config,node_machine_manager,node_event_loop,node_qmp toneAmber
class node_machine_models,node_boot_loader,node_firmware_metadata toneMint
class node_kvm,node_address_space toneRose
class node_pci,node_virtio,node_virtio_devices,node_block_backend,node_host_io,node_vfio_vhost toneIndigo
class node_migration,node_tracing,node_ui toneTeal
```

## Components

### Entrypoints

- [stratovirt process](https://github.com/openeuler-mirror/stratovirt/blob/master/src/main.rs): Rust binary · Primary VM launcher. · `src/main.rs`
- [Auxiliary tools](https://github.com/openeuler-mirror/stratovirt/blob/master/image/src/main.rs): Rust binaries · Image and OCI/sandbox executables. · `image/src/main.rs`

### Control Plane

- [CLI and VM config](https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/cmdline.rs): configuration · `machine_manager/src/cmdline.rs`
- [Machine manager](https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/machine.rs): lifecycle coordinator · `machine_manager/src/machine.rs`
- [Event loop and notifiers](https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/event_loop.rs): host event bridge · `machine_manager/src/event_loop.rs`
- [QMP control socket](https://github.com/openeuler-mirror/stratovirt/blob/master/machine_manager/src/qmp/qmp_socket.rs): Unix-socket API · `machine_manager/src/qmp/qmp_socket.rs`

### Machine Construction

- [Standard and micro machines](https://github.com/openeuler-mirror/stratovirt/blob/master/machine/src/x86_64/standard.rs): machine models · Architecture-specific x86 and AArch64 hardware realization. · `machine/src/x86_64/standard.rs`
- [Boot loader](https://github.com/openeuler-mirror/stratovirt/blob/master/boot_loader/src/x86_64/mod.rs): guest boot · Loads architecture-specific guest boot state. · `boot_loader/src/x86_64/mod.rs`
- [ACPI / device tree](https://github.com/openeuler-mirror/stratovirt/blob/master/acpi/src/acpi_table.rs): firmware metadata · Exposes virtual hardware to the guest. · `acpi/src/acpi_table.rs`

### Execution Core

- [KVM backend](https://github.com/openeuler-mirror/stratovirt/blob/master/hypervisor/src/kvm/mod.rs): Linux hypervisor · CPU virtualization and KVM capability handling. · `hypervisor/src/kvm/mod.rs`
- [Guest address space](https://github.com/openeuler-mirror/stratovirt/blob/master/address_space/src/address_space.rs): memory manager · RAM regions, host mappings, listeners, and userfaultfd. · `address_space/src/address_space.rs`

### I/O and Devices

- [PCI and sysbus](https://github.com/openeuler-mirror/stratovirt/blob/master/devices/src/pci/bus.rs): device buses · PCI topology, interrupts, hotplug, and platform devices. · `devices/src/pci/bus.rs`
- [Virtio transport and queues](https://github.com/openeuler-mirror/stratovirt/blob/master/virtio/src/transport/virtio_pci.rs): paravirtual bus · PCI transport and split virtqueues. · `virtio/src/transport/virtio_pci.rs`
- [Virtio block and net](https://github.com/openeuler-mirror/stratovirt/blob/master/virtio/src/device/block.rs): paravirtual devices · `virtio/src/device/block.rs`
- [Block backends](https://github.com/openeuler-mirror/stratovirt/blob/master/block_backend/src/qcow2/mod.rs): image storage · Raw and qcow2 host-backed images. · `block_backend/src/qcow2/mod.rs`
- [Host I/O facilities](https://github.com/openeuler-mirror/stratovirt/blob/master/util/src/aio/mod.rs): Linux integration · TAP networking, async I/O, and seccomp. · `util/src/aio/mod.rs`
- [VFIO and vhost](https://github.com/openeuler-mirror/stratovirt/blob/master/vfio/src/vfio_pci.rs): accelerated I/O · Passthrough and kernel/user vhost backends. · `vfio/src/vfio_pci.rs`

### Lifecycle and Access

- [Migration and snapshots](https://github.com/openeuler-mirror/stratovirt/blob/master/migration/src/manager.rs): state lifecycle · Coordinates machine, CPU, memory, and device state. · `migration/src/manager.rs`
- [Tracing and system events](https://github.com/openeuler-mirror/stratovirt/blob/master/trace/src/lib.rs): observability · `trace/src/lib.rs`
- [Display and input front ends](https://github.com/openeuler-mirror/stratovirt/blob/master/ui/src/vnc/mod.rs): optional UI · VNC, GTK, and OHUI access paths. · `ui/src/vnc/mod.rs`

## Connections

- stratovirt process → CLI and VM config: parses
- stratovirt process → Machine manager: starts
- CLI and VM config → Machine manager: supplies VM definition
- QMP control socket → Machine manager: management commands
- Machine manager → Event loop and notifiers: drives
- Event loop and notifiers → QMP control socket: socket events
- Machine manager → Standard and micro machines: creates
- Standard and micro machines → Boot loader: boots guest
- Standard and micro machines → ACPI / device tree: publishes hardware metadata
- Standard and micro machines → KVM backend: creates vCPUs
- Standard and micro machines → Guest address space: maps guest RAM
- Standard and micro machines → PCI and sysbus: realizes buses
- PCI and sysbus → Virtio transport and queues: hosts PCI transport
- Virtio transport and queues → Virtio block and net: carries queues
- Virtio block and net → Block backends: block I/O
- Virtio block and net → Host I/O facilities: network and async I/O
- PCI and sysbus → VFIO and vhost: passthrough attachment
- Virtio transport and queues → VFIO and vhost: vhost acceleration
- Guest address space → KVM backend: memory slots
- Machine manager → Migration and snapshots: lifecycle operations
- Migration and snapshots → Standard and micro machines: machine state
- Migration and snapshots → Guest address space: memory state
- Migration and snapshots → KVM backend: CPU state
- Migration and snapshots → Virtio block and net: device state
- Machine manager → Tracing and system events: emits events
- Machine manager → Display and input front ends: optional guest access
