# neethubal/bzsim architecture

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

- Interactive diagram: https://gitdiagram.com/neethubal/bzsim
- Repository: https://github.com/neethubal/bzsim

## Overview

BZSim combines ZSim’s execution-driven system simulation with BookSim’s detailed interconnect model. The main workflow is to launch a configured simulation, initialize cores and system resources, schedule simulated execution and memory activity, and collect statistics; BookSim models traffic through configurable networks and routers. The README documents optional DRAMSim2 integration. Several subsystem links reflect documented capability or header-level integration; unsampled implementation details are not assumed.

Main entry points: [`zsim/src/init.cpp`](https://github.com/neethubal/bzsim/blob/master/zsim/src/init.cpp) (System initialization), [`zsim/src/zsim.cpp`](https://github.com/neethubal/bzsim/blob/master/zsim/src/zsim.cpp) (ZSim runtime), [`booksim2/src/trafficmanager.cpp`](https://github.com/neethubal/bzsim/blob/master/booksim2/src/trafficmanager.cpp) (Traffic manager), [`booksim2/src/routers/iq_router.cpp`](https://github.com/neethubal/bzsim/blob/master/booksim2/src/routers/iq_router.cpp) (Router models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["ZSim Runtime"]
  node_zsim_entry["ZSim runtime<br/>[zsim.cpp]"]
  node_init["System initialization<br/>[init.cpp]"]
  node_config["Simulation configuration<br/>[config.cpp]"]
  node_scheduler["Thread scheduler<br/>[scheduler.h]"]
  node_process_tree["Process tracking<br/>[process_tree.h]"]
  node_allocator_core["Simulation allocator<br/>[galloc.h]"]
end

subgraph group_system["System Modeling"]
  node_core["Core models<br/>[core.h]"]
  node_decoder["Instruction decoder<br/>[decoder.cpp]"]
  node_memory["Memory hierarchy"]
  node_cache["Cache modeling<br/>[cache.cpp]"]
  node_detailed_mem["Detailed memory<br/>[detailed_mem.cpp]"]
  node_dram["DRAMSim2"]
end

subgraph group_interconnect["BookSim Interconnect"]
  node_booksim_bridge["Interconnect interface"]
  node_booksim_config["BookSim configuration<br/>[booksim_config.cpp]"]
  node_traffic["Traffic patterns<br/>[traffic.cpp]"]
  node_traffic_manager["Traffic manager<br/>[trafficmanager.cpp]"]
  node_network["Network topologies<br/>[network.hpp]"]
  node_router["Router models<br/>[iq_router.cpp]"]
  node_routing["Routing functions<br/>[routefunc.hpp]"]
  node_flits["Flits and credits<br/>[flit.hpp]"]
  node_allocator["Switch allocation<br/>[allocator.cpp]"]
  node_power["Power monitoring<br/>[power_module.cpp]"]
end

subgraph group_observability["Statistics and Tracing"]
  node_stats["Statistics<br/>[stats.h]"]
  node_logging["Logging<br/>[log.h]"]
  node_booksim_stats["Network statistics<br/>[stats.cpp]"]
end

node_user(("Simulation user"))

node_user -->|"launches"| node_zsim_entry
node_zsim_entry -->|"initializes"| node_init
node_init -->|"reads"| node_config
node_zsim_entry -->|"uses"| node_scheduler
node_zsim_entry -->|"tracks processes"| node_process_tree
node_init -->|"configures"| node_core
node_core -->|"decodes instructions"| node_decoder
node_init -->|"initializes"| node_memory
node_init -->|"configures"| node_cache
node_init -->|"configures"| node_detailed_mem
node_detailed_mem -.->|"may integrate"| node_dram
node_zsim_entry -.->|"includes interconnect control"| node_booksim_bridge
node_booksim_bridge -.->|"drives network traffic"| node_traffic_manager
node_traffic_manager -->|"transfers flits"| node_network
node_traffic_manager -->|"selects patterns"| node_traffic
node_network -->|"contains routers"| node_router
node_router -->|"computes routes"| node_routing
node_router -->|"receives flits"| node_flits
node_router -->|"uses allocation"| node_allocator
node_traffic_manager -->|"records results"| node_booksim_stats
node_traffic_manager -->|"aggregates metrics"| node_stats
node_init -->|"initializes"| node_allocator_core
node_zsim_entry -->|"uses"| node_logging
node_network -.->|"uses configuration"| node_booksim_config
node_router -.->|"may monitor"| node_power

click node_zsim_entry "https://github.com/neethubal/bzsim/blob/master/zsim/src/zsim.cpp"
click node_init "https://github.com/neethubal/bzsim/blob/master/zsim/src/init.cpp"
click node_config "https://github.com/neethubal/bzsim/blob/master/zsim/src/config.cpp"
click node_scheduler "https://github.com/neethubal/bzsim/blob/master/zsim/src/scheduler.h"
click node_process_tree "https://github.com/neethubal/bzsim/blob/master/zsim/src/process_tree.h"
click node_core "https://github.com/neethubal/bzsim/blob/master/zsim/src/core.h"
click node_decoder "https://github.com/neethubal/bzsim/blob/master/zsim/src/decoder.cpp"
click node_memory "https://github.com/neethubal/bzsim/blob/master/zsim/src/memory_hierarchy.cpp"
click node_cache "https://github.com/neethubal/bzsim/blob/master/zsim/src/cache.cpp"
click node_detailed_mem "https://github.com/neethubal/bzsim/blob/master/zsim/src/detailed_mem.cpp"
click node_booksim_bridge "https://github.com/neethubal/bzsim/blob/master/zsim/src/booksim_net_ctrl.cpp"
click node_booksim_config "https://github.com/neethubal/bzsim/blob/master/booksim2/src/booksim_config.cpp"
click node_traffic "https://github.com/neethubal/bzsim/blob/master/booksim2/src/traffic.cpp"
click node_traffic_manager "https://github.com/neethubal/bzsim/blob/master/booksim2/src/trafficmanager.cpp"
click node_network "https://github.com/neethubal/bzsim/blob/master/booksim2/src/networks/network.hpp"
click node_router "https://github.com/neethubal/bzsim/blob/master/booksim2/src/routers/iq_router.cpp"
click node_routing "https://github.com/neethubal/bzsim/blob/master/booksim2/src/routefunc.hpp"
click node_flits "https://github.com/neethubal/bzsim/blob/master/booksim2/src/flit.hpp"
click node_allocator "https://github.com/neethubal/bzsim/blob/master/booksim2/src/allocators/allocator.cpp"
click node_power "https://github.com/neethubal/bzsim/blob/master/booksim2/src/power/power_module.cpp"
click node_stats "https://github.com/neethubal/bzsim/blob/master/zsim/src/stats.h"
click node_logging "https://github.com/neethubal/bzsim/blob/master/zsim/src/log.h"
click node_booksim_stats "https://github.com/neethubal/bzsim/blob/master/booksim2/src/stats.cpp"
click node_allocator_core "https://github.com/neethubal/bzsim/blob/master/zsim/src/galloc.h"

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_zsim_entry,node_init,node_config,node_scheduler,node_process_tree,node_allocator_core,node_user toneBlue
class node_core,node_decoder,node_memory,node_cache,node_detailed_mem,node_dram toneAmber
class node_booksim_bridge,node_booksim_config,node_traffic,node_traffic_manager,node_network,node_router,node_routing,node_flits,node_allocator,node_power toneMint
class node_stats,node_logging,node_booksim_stats toneRose
```

## Components

### ZSim Runtime

- [ZSim runtime](https://github.com/neethubal/bzsim/blob/master/zsim/src/zsim.cpp): `zsim/src/zsim.cpp`
- [System initialization](https://github.com/neethubal/bzsim/blob/master/zsim/src/init.cpp): `zsim/src/init.cpp`
- [Simulation configuration](https://github.com/neethubal/bzsim/blob/master/zsim/src/config.cpp): `zsim/src/config.cpp`
- [Thread scheduler](https://github.com/neethubal/bzsim/blob/master/zsim/src/scheduler.h): `zsim/src/scheduler.h`
- [Process tracking](https://github.com/neethubal/bzsim/blob/master/zsim/src/process_tree.h): `zsim/src/process_tree.h`
- [Simulation allocator](https://github.com/neethubal/bzsim/blob/master/zsim/src/galloc.h): `zsim/src/galloc.h`

### System Modeling

- [Core models](https://github.com/neethubal/bzsim/blob/master/zsim/src/core.h): `zsim/src/core.h`
- [Instruction decoder](https://github.com/neethubal/bzsim/blob/master/zsim/src/decoder.cpp): `zsim/src/decoder.cpp`
- [Memory hierarchy](https://github.com/neethubal/bzsim/blob/master/zsim/src/memory_hierarchy.cpp): `zsim/src/memory_hierarchy.cpp`
- [Cache modeling](https://github.com/neethubal/bzsim/blob/master/zsim/src/cache.cpp): `zsim/src/cache.cpp`
- [Detailed memory](https://github.com/neethubal/bzsim/blob/master/zsim/src/detailed_mem.cpp): `zsim/src/detailed_mem.cpp`
- **DRAMSim2**

### BookSim Interconnect

- [Interconnect interface](https://github.com/neethubal/bzsim/blob/master/zsim/src/booksim_net_ctrl.cpp): `zsim/src/booksim_net_ctrl.cpp`
- [BookSim configuration](https://github.com/neethubal/bzsim/blob/master/booksim2/src/booksim_config.cpp): `booksim2/src/booksim_config.cpp`
- [Traffic patterns](https://github.com/neethubal/bzsim/blob/master/booksim2/src/traffic.cpp): `booksim2/src/traffic.cpp`
- [Traffic manager](https://github.com/neethubal/bzsim/blob/master/booksim2/src/trafficmanager.cpp): `booksim2/src/trafficmanager.cpp`
- [Network topologies](https://github.com/neethubal/bzsim/blob/master/booksim2/src/networks/network.hpp): `booksim2/src/networks/network.hpp`
- [Router models](https://github.com/neethubal/bzsim/blob/master/booksim2/src/routers/iq_router.cpp): `booksim2/src/routers/iq_router.cpp`
- [Routing functions](https://github.com/neethubal/bzsim/blob/master/booksim2/src/routefunc.hpp): `booksim2/src/routefunc.hpp`
- [Flits and credits](https://github.com/neethubal/bzsim/blob/master/booksim2/src/flit.hpp): `booksim2/src/flit.hpp`
- [Switch allocation](https://github.com/neethubal/bzsim/blob/master/booksim2/src/allocators/allocator.cpp): `booksim2/src/allocators/allocator.cpp`
- [Power monitoring](https://github.com/neethubal/bzsim/blob/master/booksim2/src/power/power_module.cpp): `booksim2/src/power/power_module.cpp`

### Statistics and Tracing

- [Statistics](https://github.com/neethubal/bzsim/blob/master/zsim/src/stats.h): `zsim/src/stats.h`
- [Logging](https://github.com/neethubal/bzsim/blob/master/zsim/src/log.h): `zsim/src/log.h`
- [Network statistics](https://github.com/neethubal/bzsim/blob/master/booksim2/src/stats.cpp): `booksim2/src/stats.cpp`

### Other components

- **Simulation user**

## Connections

- Simulation user → ZSim runtime: launches
- ZSim runtime → System initialization: initializes (evidence: `zsim/src/zsim.cpp`)
- System initialization → Simulation configuration: reads (evidence: `zsim/src/init.cpp`)
- ZSim runtime → Thread scheduler: uses (evidence: `zsim/src/zsim.cpp`)
- ZSim runtime → Process tracking: tracks processes (evidence: `zsim/src/zsim.cpp`)
- System initialization → Core models: configures (evidence: `zsim/src/init.cpp`)
- Core models → Instruction decoder: decodes instructions (evidence: `zsim/src/core.h`)
- System initialization → Memory hierarchy: initializes (evidence: `zsim/src/init.cpp`)
- System initialization → Cache modeling: configures (evidence: `zsim/src/init.cpp`)
- System initialization → Detailed memory: configures (evidence: `zsim/src/init.cpp`)
- Detailed memory → DRAMSim2: may integrate
- ZSim runtime → Interconnect interface: includes interconnect control
- Interconnect interface → Traffic manager: drives network traffic
- Traffic manager → Network topologies: transfers flits
- Traffic manager → Traffic patterns: selects patterns
- Network topologies → Router models: contains routers (evidence: `booksim2/src/networks/network.hpp`)
- Router models → Routing functions: computes routes (evidence: `booksim2/src/routers/iq_router.cpp`)
- Router models → Flits and credits: receives flits (evidence: `booksim2/src/routers/iq_router.cpp`)
- Router models → Switch allocation: uses allocation (evidence: `booksim2/src/routers/iq_router.cpp`)
- Traffic manager → Network statistics: records results
- Traffic manager → Statistics: aggregates metrics
- System initialization → Simulation allocator: initializes (evidence: `zsim/src/init.cpp`)
- ZSim runtime → Logging: uses (evidence: `zsim/src/zsim.cpp`)
- Network topologies → BookSim configuration: uses configuration
- Router models → Power monitoring: may monitor