# cmu-safari/mqsim architecture

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

- Interactive diagram: https://gitdiagram.com/cmu-safari/mqsim
- Repository: https://github.com/cmu-safari/mqsim

## Overview

MQSim simulates SSD I/O from configured workloads through host protocols and device firmware to flash storage, with end-to-end timing and statistics. The README documents NVMe and SATA, synthetic or trace-based flows, caching, address-mapping options, transaction scheduling, and garbage collection/wear leveling. The sampled code confirms configuration and workload parsing, discrete-event scheduling, cache-to-FTL dispatch, and block allocation; some other subsystem connections below reflect documented product behavior rather than inspected implementation. Similar implementations are grouped by responsibility.

Main entry points: [`src/host/IO_Flow_Base.cpp`](https://github.com/cmu-safari/mqsim/blob/master/src/host/IO_Flow_Base.cpp) (I/O flows), [`src/ssd/FTL.cpp`](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/FTL.cpp) (Flash translation layer), [`src/main.cpp`](https://github.com/cmu-safari/mqsim/blob/master/src/main.cpp) (Program entry), [`src/exec/Execution_Parameter_Set.h`](https://github.com/cmu-safari/mqsim/blob/master/src/exec/Execution_Parameter_Set.h) (Execution settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and host"]
  node_config["Execution settings"]
  node_workload["Workload settings"]
  node_hostflow["I/O flows<br/>[IO_Flow_Base.cpp]"]
  node_flowtypes["Synthetic and trace flows"]
  node_hosttransport["PCIe and SATA host"]
end

subgraph group_device["SSD device"]
  node_hostif["NVMe and SATA interfaces"]
  node_deviceobj["SSD device<br/>[SSD_Device.cpp]"]
end

subgraph group_firmware["Firmware and policies"]
  node_cache["DRAM data cache"]
  node_firmwareobj["NVM firmware<br/>[NVM_Firmware.cpp]"]
  node_ftl["Flash translation layer<br/>[FTL.cpp]"]
  node_mapping["Address mapping"]
  node_scheduler["Transaction scheduler<br/>[TSU_Base.cpp]"]
  node_gc["GC and wear leveling"]
end

subgraph group_media["Flash media"]
  node_blockmgr["Flash block manager"]
  node_channel["ONFI channel"]
  node_phy["NVM PHY<br/>[NVM_PHY_Base.cpp]"]
  node_flash[("Flash chip and arrays<br/>[Flash_Chip.cpp]")]
end

subgraph group_runtime["Simulation and results"]
  node_main["Program entry<br/>[main.cpp]"]
  node_engine["Event engine<br/>[Engine.cpp]"]
  node_stats["Statistics<br/>[Stats.cpp]"]
end

node_operator(("User"))

node_operator -->|"runs"| node_main
node_operator -->|"provides"| node_config
node_operator -->|"provides"| node_workload
node_main -->|"parses"| node_config
node_main -->|"reads"| node_workload
node_workload -->|"defines flows"| node_flowtypes
node_flowtypes -->|"configures"| node_hostflow
node_hostflow -->|"sends I/O"| node_hosttransport
node_hosttransport -->|"transfers requests"| node_hostif
node_hostif -->|"services I/O"| node_cache
node_cache -->|"dispatches transactions"| node_ftl
node_ftl -->|"translates addresses"| node_mapping
node_ftl -->|"schedules transactions"| node_scheduler
node_mapping -->|"allocates pages"| node_blockmgr
node_scheduler -->|"issues transactions"| node_channel
node_gc -->|"requests block operations"| node_blockmgr
node_blockmgr -->|"provides page addresses"| node_channel
node_channel -->|"transfers commands"| node_phy
node_phy -->|"operates flash"| node_flash
node_engine -->|"dispatches events"| node_engine
node_hostflow -->|"records response times"| node_stats
node_config -->|"configures device"| node_deviceobj

click node_config "https://github.com/cmu-safari/mqsim/blob/master/src/exec/Execution_Parameter_Set.h"
click node_workload "https://github.com/cmu-safari/mqsim/blob/master/src/exec/IO_Flow_Parameter_Set.h"
click node_main "https://github.com/cmu-safari/mqsim/blob/master/src/main.cpp"
click node_hostflow "https://github.com/cmu-safari/mqsim/blob/master/src/host/IO_Flow_Base.cpp"
click node_flowtypes "https://github.com/cmu-safari/mqsim/blob/master/src/host/IO_Flow_Synthetic.cpp"
click node_hosttransport "https://github.com/cmu-safari/mqsim/blob/master/src/host/PCIe_Root_Complex.cpp"
click node_hostif "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Host_Interface_Base.cpp"
click node_deviceobj "https://github.com/cmu-safari/mqsim/blob/master/src/exec/SSD_Device.cpp"
click node_cache "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Data_Cache_Manager_Base.h"
click node_firmwareobj "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/NVM_Firmware.cpp"
click node_ftl "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/FTL.cpp"
click node_mapping "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Address_Mapping_Unit_Base.cpp"
click node_scheduler "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/TSU_Base.cpp"
click node_gc "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/GC_and_WL_Unit_Base.cpp"
click node_blockmgr "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Flash_Block_Manager.cpp"
click node_channel "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/ONFI_Channel_Base.cpp"
click node_phy "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/NVM_PHY_Base.cpp"
click node_flash "https://github.com/cmu-safari/mqsim/blob/master/src/nvm_chip/flash_memory/Flash_Chip.cpp"
click node_engine "https://github.com/cmu-safari/mqsim/blob/master/src/sim/Engine.cpp"
click node_stats "https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Stats.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_config,node_workload,node_hostflow,node_flowtypes,node_hosttransport,node_operator toneBlue
class node_hostif,node_deviceobj toneAmber
class node_cache,node_firmwareobj,node_ftl,node_mapping,node_scheduler,node_gc toneMint
class node_blockmgr,node_channel,node_phy,node_flash toneRose
class node_main,node_engine,node_stats toneIndigo
```

## Components

### Inputs and host

- [Execution settings](https://github.com/cmu-safari/mqsim/blob/master/src/exec/Execution_Parameter_Set.h): `src/exec/Execution_Parameter_Set.h`
- [Workload settings](https://github.com/cmu-safari/mqsim/blob/master/src/exec/IO_Flow_Parameter_Set.h): `src/exec/IO_Flow_Parameter_Set.h`
- [I/O flows](https://github.com/cmu-safari/mqsim/blob/master/src/host/IO_Flow_Base.cpp): `src/host/IO_Flow_Base.cpp`
- [Synthetic and trace flows](https://github.com/cmu-safari/mqsim/blob/master/src/host/IO_Flow_Synthetic.cpp): `src/host/IO_Flow_Synthetic.cpp`
- [PCIe and SATA host](https://github.com/cmu-safari/mqsim/blob/master/src/host/PCIe_Root_Complex.cpp): `src/host/PCIe_Root_Complex.cpp`

### SSD device

- [NVMe and SATA interfaces](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Host_Interface_Base.cpp): `src/ssd/Host_Interface_Base.cpp`
- [SSD device](https://github.com/cmu-safari/mqsim/blob/master/src/exec/SSD_Device.cpp): `src/exec/SSD_Device.cpp`

### Firmware and policies

- [DRAM data cache](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Data_Cache_Manager_Base.h): `src/ssd/Data_Cache_Manager_Base.h`
- [NVM firmware](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/NVM_Firmware.cpp): `src/ssd/NVM_Firmware.cpp`
- [Flash translation layer](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/FTL.cpp): `src/ssd/FTL.cpp`
- [Address mapping](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Address_Mapping_Unit_Base.cpp): `src/ssd/Address_Mapping_Unit_Base.cpp`
- [Transaction scheduler](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/TSU_Base.cpp): `src/ssd/TSU_Base.cpp`
- [GC and wear leveling](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/GC_and_WL_Unit_Base.cpp): `src/ssd/GC_and_WL_Unit_Base.cpp`

### Flash media

- [Flash block manager](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Flash_Block_Manager.cpp): `src/ssd/Flash_Block_Manager.cpp`
- [ONFI channel](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/ONFI_Channel_Base.cpp): `src/ssd/ONFI_Channel_Base.cpp`
- [NVM PHY](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/NVM_PHY_Base.cpp): `src/ssd/NVM_PHY_Base.cpp`
- [Flash chip and arrays](https://github.com/cmu-safari/mqsim/blob/master/src/nvm_chip/flash_memory/Flash_Chip.cpp): `src/nvm_chip/flash_memory/Flash_Chip.cpp`

### Simulation and results

- [Program entry](https://github.com/cmu-safari/mqsim/blob/master/src/main.cpp): `src/main.cpp`
- [Event engine](https://github.com/cmu-safari/mqsim/blob/master/src/sim/Engine.cpp): `src/sim/Engine.cpp`
- [Statistics](https://github.com/cmu-safari/mqsim/blob/master/src/ssd/Stats.cpp): `src/ssd/Stats.cpp`

### Other components

- **User**

## Connections

- User → Program entry: runs
- User → Execution settings: provides
- User → Workload settings: provides
- Program entry → Execution settings: parses
- Program entry → Workload settings: reads
- Workload settings → Synthetic and trace flows: defines flows
- Synthetic and trace flows → I/O flows: configures
- I/O flows → PCIe and SATA host: sends I/O
- PCIe and SATA host → NVMe and SATA interfaces: transfers requests
- NVMe and SATA interfaces → DRAM data cache: services I/O
- DRAM data cache → Flash translation layer: dispatches transactions
- Flash translation layer → Address mapping: translates addresses
- Flash translation layer → Transaction scheduler: schedules transactions
- Address mapping → Flash block manager: allocates pages
- Transaction scheduler → ONFI channel: issues transactions
- GC and wear leveling → Flash block manager: requests block operations
- Flash block manager → ONFI channel: provides page addresses
- ONFI channel → NVM PHY: transfers commands
- NVM PHY → Flash chip and arrays: operates flash
- Event engine → Event engine: dispatches events
- I/O flows → Statistics: records response times
- Execution settings → SSD device: configures device