# isclouder/microv architecture

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

- Interactive diagram: https://gitdiagram.com/isclouder/microv
- Repository: https://github.com/isclouder/microv

## Overview

##### Project Type and Purpose
- Type: A user-space hypervisor (written in C) that uses Linux KVM to run guest Linux.
- Purpose:
– Implements a BIOS-style boot path to load a Linux kernel and initrd without a real BIOS.
– Sets up basic CPU, memory, and I/O virtualization via KVM ioctls and software emulation (serial console, PCI bus, virtio-blk).
– Serves as an educational example for x86 real/protected mode, KVM internals, and device emulation.

##### File Structure
Top‐level C modules:
- main.c
– Parses command line, loads kernel/initrd/disk images, configures KVM VM and vCPUs, enters run loop.
- bootparams.c/h, mptable.c/h, gdt.c/h
– Build real-mode boot parameters, MP table and GDT for guest initialization.
- memory.c/h
– Allocates and maps guest physical memory into the VM, sets up e820 table.
- vcpu.c/h
– Wraps each vCPU: sets registers, handles KVM_RUN loop, dispatches exit reasons.
- ioeventfd.c/h
– Implements eventfd hookups for KVM MMIO/PIO notifications.
- iobus.c/h
– Abstract I/O bus: registers devices, routes port/MMIO operations.
- pci.c/h
– Implements a PCI bus and configuration space.
- virtio-blk.c/h, virtqueue.c/h
– Emulates a virtio block device on top of the PCI framework and virtqueue mechanism.
- serial.c/h
– Emulates a 16550-style serial port (console) via I/O exits and host stdio.
- string.c/h, list.h, global.h
– Utility routines and shared definitions.
- config/
– Kconfig for building Linux kernel and busybox used to produce initrd.

##### Key Insights from README
- Uses Linux kernel’s KVM API to create VM/fd, configure vCPUs, memory slots, interrupt controllers.
- Emulates only minimal hardware: serial console, PCI bus, virtio-blk block device.
- Educational focus: no BIOS; hypervisor itself synthesizes real-mode boot environment.

##### Components & Interactions
a. Main Components
1. Hypervisor User-Space Process (“microv” binary)
2. Linux KVM Kernel Module (/dev/kvm)
3. Guest Physical Memory (RAM + BIOS tables)
4. vCPU Threads
5. I/O Bus Abstraction
6. PCI Bus & Devices (serial, virtio-blk)
7. Host File Descriptors (disk image, eventfds)
8. Guest Linux Kernel & Initrd (running inside the VM)
b. Relationships & Data Flows
– microv ↔ /dev/kvm via ioctl calls: VM creation, memory mapping, vCPU setup, run.
– vCPU runs in KVM: on exit, returns to microv C code with exit reason.
– On I/O-exit: microv dispatches to I/O Bus → PCI → Device handler (serial or virtio-blk).
– virtio-blk ↔ Host disk.img via preopened file descriptor + eventfd notifications.
– Serial device ↔ Host stdio.
c. Architectural Patterns
– Layered virtualization: KVM for CPU/memory, user-space emulation for devices.
– Event-driven dispatch loop in main/vcpu: select on fds or threaded vCPUs.
– Modular device model: iobus → pci → device drivers → virtqueue.
d. Key Technologies
– C language, Linux KVM API, IOEventFd, eventfd, mmap guest RAM, PCI config space, virtio standard.

##### Essential Details to Capture
- Boot parameters & MP table construction (no BIOS)
- Memory slot registration with KVM
- vCPU thread model + exit reason dispatch
- I/O bus registry of PCI devices
- virtio-blk virtqueue and eventfd handshake
- Serial console emulation path

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "User-Space Hypervisor"
        direction TB
        Main["microv (Main Process)"]:::hypervisor
        Bootparams["bootparams.c/h"]:::hypervisor
        Mptable["mptable.c/h"]:::hypervisor
        Gdt["gdt.c/h"]:::hypervisor
        Memory["memory.c/h"]:::hypervisor
        VCPU["vcpu.c/h"]:::hypervisor
        IOEFD["ioeventfd.c/h"]:::hypervisor
        IOBUS["iobus.c/h"]:::hypervisor
        PCI["pci.c/h"]:::hypervisor
        VIRTPCI["virtio-pci.c/h"]:::hypervisor
        VBLK["virtio-blk.c/h"]:::hypervisor
        VQ["virtqueue.c/h"]:::hypervisor
        SERIAL["serial.c/h"]:::hypervisor
        UTIL["string.c/h, list.h, global.h"]:::hypervisor
        CONFIG["config/"]:::hypervisor
    end

    subgraph "KVM Kernel Module"
        KVM["/dev/kvm"]:::kvm
    end

    subgraph "Guest VM"
        direction TB
        GuestMem["Guest Physical Memory"]:::guest
        GuestKernel["Guest Linux Kernel & Initrd"]:::guest
    end

    HostDisk["Host Disk Image"]:::external
    HostStdio["Host stdio"]:::external

    %% Initialization Sequence
    Main -->|calls| Bootparams
    Main -->|calls| Mptable
    Main -->|calls| Gdt
    Bootparams -->|populate tables| GuestMem
    Mptable --> GuestMem
    Gdt --> GuestMem

    Main -->|mmap via KVM_SLOT_SET_MEMORY_REGION| Memory
    Memory -->|maps| GuestMem

    Main -->|ioctl VM_CREATE| KVM
    Main -->|ioctl SET_USER_MEMORY_REGION| KVM
    Main -->|ioctl CREATE_VCPU| KVM

    Main -->|load kernel/initrd| GuestKernel

    Main -->|init vCPU threads| VCPU
    VCPU -->|KVM_RUN| KVM
    KVM -->|exit reason| VCPU
    VCPU -->|EXIT_IO| Main

    %% I/O Dispatch
    Main -->|dispatch IO-exits| IOEFD
    IOEFD -->|notification| IOBUS
    IOBUS -->|route| PCI
    PCI -->|MMIO/PIO| SERIAL
    PCI -->|bridge| VIRTPCI
    VIRTPCI -->|enumerate| VBLK
    VBLK -->|use| VQ
    VQ -->|eventfd handshake| IOEFD
    VBLK -->|read/write| HostDisk
    SERIAL -->|stdio| HostStdio

    %% Guest interactions
    VCPU -->|executes| GuestKernel
    VCPU -->|accesses| GuestMem

    %% Click Events
    click Main "https://github.com/isclouder/microv/blob/main/main.c"
    click Bootparams "https://github.com/isclouder/microv/blob/main/bootparams.c"
    click Mptable "https://github.com/isclouder/microv/blob/main/mptable.c"
    click Gdt "https://github.com/isclouder/microv/blob/main/gdt.c"
    click Memory "https://github.com/isclouder/microv/blob/main/memory.c"
    click VCPU "https://github.com/isclouder/microv/blob/main/vcpu.c"
    click IOEFD "https://github.com/isclouder/microv/blob/main/ioeventfd.c"
    click IOBUS "https://github.com/isclouder/microv/blob/main/iobus.c"
    click PCI "https://github.com/isclouder/microv/blob/main/pci.c"
    click VIRTPCI "https://github.com/isclouder/microv/blob/main/virtio-pci.c"
    click VBLK "https://github.com/isclouder/microv/blob/main/virtio-blk.c"
    click VQ "https://github.com/isclouder/microv/blob/main/virtqueue.c"
    click SERIAL "https://github.com/isclouder/microv/blob/main/serial.c"
    click UTIL "https://github.com/isclouder/microv/blob/main/string.c"
    click CONFIG "https://github.com/isclouder/microv/tree/main/config/"

    %% Styles
    classDef hypervisor fill:#D6EAF8,stroke:#2980B9,color:#1B4F72
    classDef kvm fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef guest fill:#FCF3CF,stroke:#D68910,color:#7D6608
    classDef external fill:#F5B7B1,stroke:#C0392B,color:#641E16
```
