# adamozh/cache-coherence-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/adamozh/cache-coherence-simulator
- Repository: https://github.com/adamozh/cache-coherence-simulator

## Overview

This is a trace-driven cache-coherence simulator: a command-line run selects a protocol and cache parameters, loads benchmark trace files as processor inputs, advances processors and the bus cycle by cycle, then reports per-processor and bus statistics. MESI, MOESI, and Dragon are distinct coherence strategies; the bus handles shared requests and coherence activity, while the cache hierarchy models stored lines. The source index supports the module relationships shown, but several implementation excerpts were not provided, so uncertain internal calls are omitted.

Main entry points: [`coherence.cpp`](https://github.com/adamozh/cache-coherence-simulator/blob/master/coherence.cpp) (Simulation driver), [`processor_impl.cpp`](https://github.com/adamozh/cache-coherence-simulator/blob/master/processor_impl.cpp) (Processor execution), [`bus_impl.cpp`](https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl.cpp) (Bus processing), [`cache.cpp`](https://github.com/adamozh/cache-coherence-simulator/blob/master/cache.cpp) (Cache lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation runtime"]
  node_entry["Simulation driver<br/>[coherence.cpp]"]
  node_trace["Benchmark traces"]
  node_processor["Processor execution<br/>[processor_impl.cpp]"]
  node_request["Bus requests<br/>[request.hpp]"]
  node_bus["Bus processing<br/>[bus_impl.cpp]"]
  node_busbase["Bus interface<br/>[bus.hpp]"]
end

subgraph group_coherence["Coherence protocols"]
  node_mesi_bus["Dragon bus"]
  node_moesi_bus["MOESI bus<br/>[bus_impl_moesi.cpp]"]
  node_protocol["Protocol interface<br/>[protocol.hpp]"]
  node_mesi["MESI protocol<br/>[mesi.cpp]"]
  node_moesi["MOESI protocol<br/>[moesi.cpp]"]
  node_dragon["Dragon protocol<br/>[dragon.cpp]"]
end

subgraph group_storage["Cache storage"]
  node_cache["Cache lookup<br/>[cache.cpp]"]
  node_set["Cache sets<br/>[cache_set.cpp]"]
  node_line["Cache lines<br/>[cache_line.cpp]"]
  node_state["Coherence states<br/>[state.hpp]"]
end

node_user(("Simulator user"))

node_user -->|"runs"| node_entry
node_entry -->|"reads traces"| node_trace
node_entry -->|"creates processors"| node_processor
node_entry -->|"selects bus"| node_bus
node_entry -->|"selects protocol"| node_mesi
node_entry -->|"selects protocol"| node_moesi
node_entry -->|"selects protocol"| node_dragon
node_entry -->|"advances cycles"| node_processor
node_entry -->|"advances cycles"| node_bus
node_processor -->|"dispatches loads/stores"| node_protocol
node_processor -->|"uses cache"| node_cache
node_processor -->|"issues requests"| node_bus
node_processor -.->|"creates requests"| node_request
node_bus -->|"processes requests"| node_request
node_bus -->|"queries processors"| node_processor
node_bus -->|"implements"| node_busbase
node_mesi_bus -->|"extends"| node_bus
node_moesi_bus -->|"extends"| node_bus
node_mesi -->|"implements"| node_protocol
node_moesi -->|"implements"| node_protocol
node_dragon -->|"implements"| node_protocol
node_mesi -->|"uses cache"| node_cache
node_moesi -->|"uses cache"| node_cache
node_dragon -->|"uses cache"| node_cache
node_cache -->|"organizes sets"| node_set
node_set -->|"stores lines"| node_line
node_cache -->|"tracks states"| node_state
node_processor -->|"reads and updates"| node_state
node_entry -->|"reports statistics"| node_processor
node_entry -->|"reports statistics"| node_bus

click node_entry "https://github.com/adamozh/cache-coherence-simulator/blob/master/coherence.cpp"
click node_processor "https://github.com/adamozh/cache-coherence-simulator/blob/master/processor_impl.cpp"
click node_request "https://github.com/adamozh/cache-coherence-simulator/blob/master/request.hpp"
click node_bus "https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl.cpp"
click node_busbase "https://github.com/adamozh/cache-coherence-simulator/blob/master/bus.hpp"
click node_mesi_bus "https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl_dragon.cpp"
click node_moesi_bus "https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl_moesi.cpp"
click node_protocol "https://github.com/adamozh/cache-coherence-simulator/blob/master/protocol.hpp"
click node_mesi "https://github.com/adamozh/cache-coherence-simulator/blob/master/mesi.cpp"
click node_moesi "https://github.com/adamozh/cache-coherence-simulator/blob/master/moesi.cpp"
click node_dragon "https://github.com/adamozh/cache-coherence-simulator/blob/master/dragon.cpp"
click node_cache "https://github.com/adamozh/cache-coherence-simulator/blob/master/cache.cpp"
click node_set "https://github.com/adamozh/cache-coherence-simulator/blob/master/cache_set.cpp"
click node_line "https://github.com/adamozh/cache-coherence-simulator/blob/master/cache_line.cpp"
click node_state "https://github.com/adamozh/cache-coherence-simulator/blob/master/state.hpp"

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_entry,node_trace,node_processor,node_request,node_bus,node_busbase,node_user toneBlue
class node_mesi_bus,node_moesi_bus,node_protocol,node_mesi,node_moesi,node_dragon toneAmber
class node_cache,node_set,node_line,node_state toneMint
```

## Components

### Simulation runtime

- [Simulation driver](https://github.com/adamozh/cache-coherence-simulator/blob/master/coherence.cpp): `coherence.cpp`
- **Benchmark traces**
- [Processor execution](https://github.com/adamozh/cache-coherence-simulator/blob/master/processor_impl.cpp): `processor_impl.cpp`
- [Bus requests](https://github.com/adamozh/cache-coherence-simulator/blob/master/request.hpp): `request.hpp`
- [Bus processing](https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl.cpp): `bus_impl.cpp`
- [Bus interface](https://github.com/adamozh/cache-coherence-simulator/blob/master/bus.hpp): `bus.hpp`

### Coherence protocols

- [Dragon bus](https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl_dragon.cpp): `bus_impl_dragon.cpp`
- [MOESI bus](https://github.com/adamozh/cache-coherence-simulator/blob/master/bus_impl_moesi.cpp): `bus_impl_moesi.cpp`
- [Protocol interface](https://github.com/adamozh/cache-coherence-simulator/blob/master/protocol.hpp): `protocol.hpp`
- [MESI protocol](https://github.com/adamozh/cache-coherence-simulator/blob/master/mesi.cpp): `mesi.cpp`
- [MOESI protocol](https://github.com/adamozh/cache-coherence-simulator/blob/master/moesi.cpp): `moesi.cpp`
- [Dragon protocol](https://github.com/adamozh/cache-coherence-simulator/blob/master/dragon.cpp): `dragon.cpp`

### Cache storage

- [Cache lookup](https://github.com/adamozh/cache-coherence-simulator/blob/master/cache.cpp): `cache.cpp`
- [Cache sets](https://github.com/adamozh/cache-coherence-simulator/blob/master/cache_set.cpp): `cache_set.cpp`
- [Cache lines](https://github.com/adamozh/cache-coherence-simulator/blob/master/cache_line.cpp): `cache_line.cpp`
- [Coherence states](https://github.com/adamozh/cache-coherence-simulator/blob/master/state.hpp): `state.hpp`

### Other components

- **Simulator user**

## Connections

- Simulator user → Simulation driver: runs (evidence: `README.md`)
- Simulation driver → Benchmark traces: reads traces (evidence: `coherence.cpp`)
- Simulation driver → Processor execution: creates processors (evidence: `coherence.cpp`)
- Simulation driver → Bus processing: selects bus (evidence: `coherence.cpp`)
- Simulation driver → MESI protocol: selects protocol (evidence: `coherence.cpp`)
- Simulation driver → MOESI protocol: selects protocol (evidence: `coherence.cpp`)
- Simulation driver → Dragon protocol: selects protocol (evidence: `coherence.cpp`)
- Simulation driver → Processor execution: advances cycles (evidence: `coherence.cpp`)
- Simulation driver → Bus processing: advances cycles (evidence: `coherence.cpp`)
- Processor execution → Protocol interface: dispatches loads/stores (evidence: `processor_impl.cpp`)
- Processor execution → Cache lookup: uses cache
- Processor execution → Bus processing: issues requests
- Processor execution → Bus requests: creates requests
- Bus processing → Bus requests: processes requests (evidence: `bus_impl.cpp`)
- Bus processing → Processor execution: queries processors (evidence: `bus_impl.cpp`)
- Bus processing → Bus interface: implements
- Dragon bus → Bus processing: extends
- MOESI bus → Bus processing: extends
- MESI protocol → Protocol interface: implements
- MOESI protocol → Protocol interface: implements
- Dragon protocol → Protocol interface: implements
- MESI protocol → Cache lookup: uses cache
- MOESI protocol → Cache lookup: uses cache
- Dragon protocol → Cache lookup: uses cache
- Cache lookup → Cache sets: organizes sets
- Cache sets → Cache lines: stores lines
- Cache lookup → Coherence states: tracks states
- Processor execution → Coherence states: reads and updates
- Simulation driver → Processor execution: reports statistics (evidence: `coherence.cpp`)
- Simulation driver → Bus processing: reports statistics (evidence: `coherence.cpp`)