# esos-lab/vssim architecture

> Architecture diagram of the GitHub repository esos-lab/vssim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/esos-lab/vssim
- Repository: https://github.com/esos-lab/vssim

## Overview

VSSIM is a real-time SSD simulator embedded in a QEMU/KVM virtual machine. The principal workflow is to configure modeled NAND and SSD parameters, run guest I/O through QEMU’s IDE-backed virtual SSD, buffer requests, translate them through an FTL, emulate NAND timing and operations, and report behavior to a monitor. Page mapping is the documented current FTL; BLOCK_MAP, FAST, and LAST are alternate implementations that the README says do not work with the current SSD module. Relationships among subsystems are documented at the README level; sampled excerpts do not establish their full call chains.

Main entry points: [`FTL/PAGE_MAP/ftl.c`](https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl.c) (Page-map FTL), [`QEMU`](https://github.com/esos-lab/vssim/tree/master/QEMU) (QEMU runtime), [`QEMU/hw/ide.c`](https://github.com/esos-lab/vssim/blob/master/QEMU/hw/ide.c) (IDE device model), [`SSD_MODULE/ssd_io_manager.c`](https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_io_manager.c) (NAND I/O timing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vm["Virtual machine"]
  node_qemu["QEMU runtime"]
  node_kvm["KVM integration<br/>[qemu-kvm.c]"]
  node_ide["IDE device model<br/>[ide.c]"]
end

subgraph group_ssd["SSD emulation"]
  node_config["SSD configuration"]
  node_firmbuf["I/O buffers"]
  node_ssd_io["NAND I/O timing<br/>[ssd_io_manager.c]"]
  node_trim["TRIM handling<br/>[ssd_trim_manager.c]"]
end

subgraph group_ftl["Flash translation"]
  node_page_ftl["Page-map FTL<br/>[ftl.c]"]
  node_page_map["Page mapping"]
  node_inverse[("Block state")]
  node_gc["Garbage collection<br/>[ftl_gc_manager.c]"]
  node_block_ftl["Block-map FTL<br/>[ftl.c]"]
  node_fast_ftl["FAST FTL<br/>[ftl.c]"]
  node_last_ftl["LAST FTL<br/>[ftl.c]"]
end

subgraph group_observe["Monitoring"]
  node_perf["Performance metrics<br/>[ftl_perf_manager.c]"]
  node_log["SSD event logging<br/>[ssd_log_manager.c]"]
  node_monitor["SSD monitor<br/>[monitorform.cpp]"]
end

node_user(("Experiment user"))

node_user -->|"sets parameters"| node_config
node_user -->|"runs guest"| node_qemu
node_config -->|"configures model"| node_ssd_io
node_qemu -->|"runs on"| node_kvm
node_qemu -->|"models SSD as IDE"| node_ide
node_ide -.->|"forwards I/O"| node_firmbuf
node_firmbuf -.->|"buffers I/O"| node_page_ftl
node_page_ftl -.->|"uses mapping"| node_page_map
node_page_ftl -.->|"tracks block state"| node_inverse
node_page_ftl -.->|"supports collection"| node_gc
node_page_ftl -.->|"emulates NAND I/O"| node_ssd_io
node_ide -.->|"handles TRIM"| node_trim
node_ssd_io -.->|"records operation metrics"| node_perf
node_perf -.->|"reports behavior"| node_log
node_log -->|"sends events"| node_monitor
node_user -.->|"may select"| node_block_ftl
node_user -.->|"may select"| node_fast_ftl
node_user -.->|"may select"| node_last_ftl

click node_config "https://github.com/esos-lab/vssim/blob/master/CONFIG/vssim_config_manager.c"
click node_qemu "https://github.com/esos-lab/vssim/tree/master/QEMU"
click node_kvm "https://github.com/esos-lab/vssim/blob/master/QEMU/qemu-kvm.c"
click node_ide "https://github.com/esos-lab/vssim/blob/master/QEMU/hw/ide.c"
click node_firmbuf "https://github.com/esos-lab/vssim/blob/master/FIRMWARE/firm_buffer_manager.c"
click node_ssd_io "https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_io_manager.c"
click node_trim "https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_trim_manager.c"
click node_page_ftl "https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl.c"
click node_page_map "https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl_mapping_manager.c"
click node_inverse "https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl_inverse_mapping_manager.c"
click node_gc "https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl_gc_manager.c"
click node_block_ftl "https://github.com/esos-lab/vssim/blob/master/FTL/BLOCK_MAP/ftl.c"
click node_fast_ftl "https://github.com/esos-lab/vssim/blob/master/FTL/FAST/ftl.c"
click node_last_ftl "https://github.com/esos-lab/vssim/blob/master/FTL/LAST/ftl.c"
click node_perf "https://github.com/esos-lab/vssim/blob/master/FTL/COMMON/ftl_perf_manager.c"
click node_log "https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_log_manager.c"
click node_monitor "https://github.com/esos-lab/vssim/blob/master/MONITOR/SSD_MONITOR_PM/monitorform.cpp"

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_qemu,node_kvm,node_ide,node_user toneBlue
class node_config,node_firmbuf,node_ssd_io,node_trim toneAmber
class node_page_ftl,node_page_map,node_inverse,node_gc,node_block_ftl,node_fast_ftl,node_last_ftl toneMint
class node_perf,node_log,node_monitor toneRose
```

## Components

### Virtual machine

- [QEMU runtime](https://github.com/esos-lab/vssim/tree/master/QEMU): `QEMU`
- [KVM integration](https://github.com/esos-lab/vssim/blob/master/QEMU/qemu-kvm.c): `QEMU/qemu-kvm.c`
- [IDE device model](https://github.com/esos-lab/vssim/blob/master/QEMU/hw/ide.c): `QEMU/hw/ide.c`

### SSD emulation

- [SSD configuration](https://github.com/esos-lab/vssim/blob/master/CONFIG/vssim_config_manager.c): `CONFIG/vssim_config_manager.c`
- [I/O buffers](https://github.com/esos-lab/vssim/blob/master/FIRMWARE/firm_buffer_manager.c): `FIRMWARE/firm_buffer_manager.c`
- [NAND I/O timing](https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_io_manager.c): `SSD_MODULE/ssd_io_manager.c`
- [TRIM handling](https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_trim_manager.c): `SSD_MODULE/ssd_trim_manager.c`

### Flash translation

- [Page-map FTL](https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl.c): `FTL/PAGE_MAP/ftl.c`
- [Page mapping](https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl_mapping_manager.c): `FTL/PAGE_MAP/ftl_mapping_manager.c`
- [Block state](https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl_inverse_mapping_manager.c): `FTL/PAGE_MAP/ftl_inverse_mapping_manager.c`
- [Garbage collection](https://github.com/esos-lab/vssim/blob/master/FTL/PAGE_MAP/ftl_gc_manager.c): `FTL/PAGE_MAP/ftl_gc_manager.c`
- [Block-map FTL](https://github.com/esos-lab/vssim/blob/master/FTL/BLOCK_MAP/ftl.c): `FTL/BLOCK_MAP/ftl.c`
- [FAST FTL](https://github.com/esos-lab/vssim/blob/master/FTL/FAST/ftl.c): `FTL/FAST/ftl.c`
- [LAST FTL](https://github.com/esos-lab/vssim/blob/master/FTL/LAST/ftl.c): `FTL/LAST/ftl.c`

### Monitoring

- [Performance metrics](https://github.com/esos-lab/vssim/blob/master/FTL/COMMON/ftl_perf_manager.c): `FTL/COMMON/ftl_perf_manager.c`
- [SSD event logging](https://github.com/esos-lab/vssim/blob/master/SSD_MODULE/ssd_log_manager.c): `SSD_MODULE/ssd_log_manager.c`
- [SSD monitor](https://github.com/esos-lab/vssim/blob/master/MONITOR/SSD_MONITOR_PM/monitorform.cpp): `MONITOR/SSD_MONITOR_PM/monitorform.cpp`

### Other components

- **Experiment user**

## Connections

- Experiment user → SSD configuration: sets parameters
- Experiment user → QEMU runtime: runs guest
- SSD configuration → NAND I/O timing: configures model
- QEMU runtime → KVM integration: runs on
- QEMU runtime → IDE device model: models SSD as IDE
- IDE device model → I/O buffers: forwards I/O
- I/O buffers → Page-map FTL: buffers I/O
- Page-map FTL → Page mapping: uses mapping
- Page-map FTL → Block state: tracks block state
- Page-map FTL → Garbage collection: supports collection
- Page-map FTL → NAND I/O timing: emulates NAND I/O
- IDE device model → TRIM handling: handles TRIM
- NAND I/O timing → Performance metrics: records operation metrics
- Performance metrics → SSD event logging: reports behavior
- SSD event logging → SSD monitor: sends events
- Experiment user → Block-map FTL: may select
- Experiment user → FAST FTL: may select
- Experiment user → LAST FTL: may select