# tpot/dos-vmm architecture

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

- Interactive diagram: https://gitdiagram.com/tpot/dos-vmm
- Repository: https://github.com/tpot/dos-vmm

## Overview

##### Project Purpose and Type
- The README states that dos-vmm is a “16-bit x86 real mode hypervisor/VMM” designed from scratch to run MS-DOS.
- It leverages Linux’s KVM as noted both in the source (src/kvm.rs) and the README’s pointers to the Linux KVM Documentation.
- The small file tree (with Cargo.toml, main.rs, and kvm.rs) confirms that it’s a Rust-based systems/low-level virtualization project.

##### Analyzing the File Structure
- Top-Level Files/Folders:
- Cargo.toml and Cargo.lock indicate a Rust project with dependency management.
- The src directory contains the core code, splitting between main.rs (the entry point) and kvm.rs (encapsulating KVM interactions).
- .github directory with workflows (like build.yaml) suggests automated testing/build pipelines.
- The division between main.rs and kvm.rs hints at a clear separation between the hypervisor’s initialization/control logic and its KVM-specific functionalities.

##### Main Components
- dos-vmm Hypervisor Application:
- Components:
▪ main.rs: The entry point where the application is initialized.
▪ kvm.rs: The module managing communications with the Linux KVM interface (handles VM creation, VCPU configuration, memory mapping, etc.).
- External and Underlying Systems:
- Linux Kernel with KVM: Illustrate the host operating system’s role, which provides virtualization services via the KVM module.
- MS-DOS (or DOS VM Image): Although not a file in the repository, note that the hypervisor is intended to run MS-DOS, so include an “MS-DOS VM” component representing the guest OS.
- CI/CD Pipeline:
- A note or a module for the GitHub workflows (.github/workflows/build.yaml), which automates builds and tests.

##### Relationships and Interactions
- Optionally, illustrate the CI/CD pipeline as a side process triggering builds and tests upon commits, ensuring the stability of the codebase.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The architecture clearly divides the hypervisor’s core control logic (main.rs) from the virtualization-specific interactions (kvm.rs).
- Abstraction over KVM Interface: The kvm.rs module abstracts away the complexities of dealing with Linux’s KVM APIs.
- Minimalistic and focused design: Given the size of the project, each module has a very focused role.
- Integration of external components (Linux KVM and MS-DOS) which are crucial for virtualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Project Components"
        mainEntry["Hypervisor Entry (main.rs)"]:::project
        kvmModule["KVM Integration Module (kvm.rs)"]:::project
        dependency["Dependency Management (Cargo.toml & Cargo.lock)"]:::project
    end

    subgraph "External Systems"
        linuxKvm["Linux KVM"]:::external
        dosVm["MS-DOS Virtual Machine"]:::external
    end

    cicd["CI/CD Pipeline (GitHub Workflows)"]:::ci

    mainEntry -->|"calls"| kvmModule
    kvmModule -->|"interfaces"| linuxKvm
    linuxKvm -->|"runsguest"| dosVm

    cicd ---|"triggersbuild"| dependency
    cicd ---|"triggersbuild"| mainEntry

    click mainEntry "https://github.com/tpot/dos-vmm/blob/master/src/main.rs"
    click kvmModule "https://github.com/tpot/dos-vmm/blob/master/src/kvm.rs"
    click dependency "https://github.com/tpot/dos-vmm/blob/master/Cargo.toml"
    click cicd "https://github.com/tpot/dos-vmm/blob/master/.github/workflows/build.yaml"

    classDef project fill:#f9f,stroke:#333,stroke-width:2px;
    classDef external fill:#bbf,stroke:#333,stroke-width:2px;
    classDef ci fill:#afa,stroke:#333,stroke-width:2px;
```
