# snu-csl/nvmevirt architecture

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

- Interactive diagram: https://gitdiagram.com/snu-csl/nvmevirt
- Repository: https://github.com/snu-csl/nvmevirt

## Overview

NVMeVirt is a Linux kernel module that emulates a PCI-attached NVMe device, supporting conventional SSD, NVM, ZNS, and key-value device configurations. The main workflow is an NVMe host submitting commands to the virtual controller; admin commands configure queues and expose device information, while I/O commands are dispatched to the selected storage model and completed through the queues. The README documents the supported device types; unsampled source means some internal dispatch wiring is not shown here.

Main entry points: [`io.c`](https://github.com/snu-csl/nvmevirt/blob/main/io.c) (I/O dispatch), [`zns_ftl.c`](https://github.com/snu-csl/nvmevirt/blob/main/zns_ftl.c) (ZNS FTL), [`pci.c`](https://github.com/snu-csl/nvmevirt/blob/main/pci.c) (PCI device), [`ssd.c`](https://github.com/snu-csl/nvmevirt/blob/main/ssd.c) (SSD model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controller["Virtual controller"]
  node_pci["PCI device<br/>[pci.c]"]
  node_main["Module runtime<br/>[main.c]"]
  node_admin["Admin commands<br/>[admin.c]"]
end

subgraph group_io["Request processing"]
  node_io["I/O dispatch<br/>[io.c]"]
  node_dma["DMA transfer<br/>[dma.c]"]
end

subgraph group_backends["Storage backends"]
  node_conv["Conventional FTL<br/>[conv_ftl.c]"]
  node_simple["Simple FTL<br/>[simple_ftl.c]"]
  node_kv["Key-value FTL<br/>[kv_ftl.c]"]
  node_zns["ZNS FTL<br/>[zns_ftl.c]"]
  node_znsrw["ZNS reads/writes<br/>[zns_read_write.c]"]
  node_znsmgmt["Zone management<br/>[zns_mgmt_send.c]"]
  node_znsmgmtrecv["Zone reports<br/>[zns_mgmt_recv.c]"]
  node_append["Append handling<br/>[append_only.c]"]
end

subgraph group_model["Device modeling"]
  node_storage[("Reserved storage<br/>[main.c]")]
  node_ssd["SSD model<br/>[ssd.c]"]
  node_channel["Channel timing<br/>[channel_model.c]"]
end

node_host(("NVMe host"))

node_host -->|"submits commands"| node_pci
node_main -->|"initializes device"| node_pci
node_pci -->|"dispatches admin"| node_admin
node_pci -->|"dispatches I/O"| node_io
node_io -->|"transfers data"| node_dma
node_io -->|"processes I/O"| node_conv
node_io -->|"processes I/O"| node_simple
node_io -->|"processes I/O"| node_kv
node_io -->|"processes I/O"| node_zns
node_zns -->|"handles reads/writes"| node_znsrw
node_zns -->|"handles management"| node_znsmgmt
node_zns -->|"handles reports"| node_znsmgmtrecv
node_conv -->|"models flash"| node_ssd
node_znsrw -->|"models flash"| node_ssd
node_ssd -->|"models timing"| node_channel
node_simple -->|"accesses data"| node_storage
node_kv -->|"stores values"| node_storage
node_append -->|"appends data"| node_storage

click node_pci "https://github.com/snu-csl/nvmevirt/blob/main/pci.c"
click node_main "https://github.com/snu-csl/nvmevirt/blob/main/main.c"
click node_admin "https://github.com/snu-csl/nvmevirt/blob/main/admin.c"
click node_io "https://github.com/snu-csl/nvmevirt/blob/main/io.c"
click node_dma "https://github.com/snu-csl/nvmevirt/blob/main/dma.c"
click node_conv "https://github.com/snu-csl/nvmevirt/blob/main/conv_ftl.c"
click node_simple "https://github.com/snu-csl/nvmevirt/blob/main/simple_ftl.c"
click node_kv "https://github.com/snu-csl/nvmevirt/blob/main/kv_ftl.c"
click node_zns "https://github.com/snu-csl/nvmevirt/blob/main/zns_ftl.c"
click node_znsrw "https://github.com/snu-csl/nvmevirt/blob/main/zns_read_write.c"
click node_znsmgmt "https://github.com/snu-csl/nvmevirt/blob/main/zns_mgmt_send.c"
click node_znsmgmtrecv "https://github.com/snu-csl/nvmevirt/blob/main/zns_mgmt_recv.c"
click node_append "https://github.com/snu-csl/nvmevirt/blob/main/append_only.c"
click node_storage "https://github.com/snu-csl/nvmevirt/blob/main/main.c"
click node_ssd "https://github.com/snu-csl/nvmevirt/blob/main/ssd.c"
click node_channel "https://github.com/snu-csl/nvmevirt/blob/main/channel_model.c"

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_pci,node_main,node_admin toneBlue
class node_io,node_dma toneAmber
class node_conv,node_simple,node_kv,node_zns,node_znsrw,node_znsmgmt,node_znsmgmtrecv,node_append toneMint
class node_storage,node_ssd,node_channel toneRose
class node_host toneIndigo
```

## Components

### Virtual controller

- [PCI device](https://github.com/snu-csl/nvmevirt/blob/main/pci.c): `pci.c`
- [Module runtime](https://github.com/snu-csl/nvmevirt/blob/main/main.c): `main.c`
- [Admin commands](https://github.com/snu-csl/nvmevirt/blob/main/admin.c): `admin.c`

### Request processing

- [I/O dispatch](https://github.com/snu-csl/nvmevirt/blob/main/io.c): `io.c`
- [DMA transfer](https://github.com/snu-csl/nvmevirt/blob/main/dma.c): `dma.c`

### Storage backends

- [Conventional FTL](https://github.com/snu-csl/nvmevirt/blob/main/conv_ftl.c): `conv_ftl.c`
- [Simple FTL](https://github.com/snu-csl/nvmevirt/blob/main/simple_ftl.c): `simple_ftl.c`
- [Key-value FTL](https://github.com/snu-csl/nvmevirt/blob/main/kv_ftl.c): `kv_ftl.c`
- [ZNS FTL](https://github.com/snu-csl/nvmevirt/blob/main/zns_ftl.c): `zns_ftl.c`
- [ZNS reads/writes](https://github.com/snu-csl/nvmevirt/blob/main/zns_read_write.c): `zns_read_write.c`
- [Zone management](https://github.com/snu-csl/nvmevirt/blob/main/zns_mgmt_send.c): `zns_mgmt_send.c`
- [Zone reports](https://github.com/snu-csl/nvmevirt/blob/main/zns_mgmt_recv.c): `zns_mgmt_recv.c`
- [Append handling](https://github.com/snu-csl/nvmevirt/blob/main/append_only.c): `append_only.c`

### Device modeling

- [Reserved storage](https://github.com/snu-csl/nvmevirt/blob/main/main.c): `main.c`
- [SSD model](https://github.com/snu-csl/nvmevirt/blob/main/ssd.c): `ssd.c`
- [Channel timing](https://github.com/snu-csl/nvmevirt/blob/main/channel_model.c): `channel_model.c`

### Other components

- **NVMe host**

## Connections

- NVMe host → PCI device: submits commands
- Module runtime → PCI device: initializes device
- PCI device → Admin commands: dispatches admin
- PCI device → I/O dispatch: dispatches I/O
- I/O dispatch → DMA transfer: transfers data
- I/O dispatch → Conventional FTL: processes I/O
- I/O dispatch → Simple FTL: processes I/O
- I/O dispatch → Key-value FTL: processes I/O
- I/O dispatch → ZNS FTL: processes I/O
- ZNS FTL → ZNS reads/writes: handles reads/writes
- ZNS FTL → Zone management: handles management
- ZNS FTL → Zone reports: handles reports
- Conventional FTL → SSD model: models flash
- ZNS reads/writes → SSD model: models flash
- SSD model → Channel timing: models timing
- Simple FTL → Reserved storage: accesses data
- Key-value FTL → Reserved storage: stores values
- Append handling → Reserved storage: appends data