# tukl-msd/dramsys architecture

> Architecture diagram of the GitHub repository tukl-msd/dramsys, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tukl-msd/dramsys
- Repository: https://github.com/tukl-msd/dramsys

## Overview

##### Project Type and Purpose
- DRAMSys is not a traditional full‐stack web application but a modular simulation framework and analysis tool.
- It consists of:
- A SystemC/TLM-2.0 library (“libdramsys”) exposing cycle-accurate DRAM subsystem models
- A standalone CLI simulator that exercises the library with traffic generators or trace playback
- A Qt-based Trace Analyzer GUI that visualizes and analyzes recorded simulation traces stored in SQLite
- Users supply JSON configuration files (in configs/) to parameterize device models, address mapping, memory controller policies, and simulators.

##### File Structure Analysis
- Top‐level directories:
- cmake: CMake find scripts and build helpers
- configs: JSON files for address mapping, memspec, controller policies, simulation setups, traces
- lib/sqlite3: embedded SQLite for trace storage
- src/configuration: configuration‐file parser wrapping JSON → C++ objects
- src/libdramsys: core library implementing DRAMSysConfiguration, MemSpec, AddressMapping, Controller, Scheduler, Refresh, PowerDown managers, TLM recorders, and the simulation orchestrator
- src/simulator: CLI application linking libdramsys and configuration layer, invoking the TLM simulation
- src/traceAnalyzer: Qt5 GUI and Python facade that reads the SQLite trace DB, computes metrics via SQL/Python, and renders plots/widgets
- Configuration is decoupled from simulation logic; the simulator and Trace Analyzer both consume it via the configuration layer.

##### Main Components and Interactions
- Configuration Layer
→ Reads JSON configs → Instantiates MemSpec, McConfig, AddressMapping, SimConfig, TraceSetup objects
- DRAMSys Core Library (SystemC/TLM-2.0)
- MemSpec modules model DRAM device timing parameters
- AddressDecoder maps transactions to DRAM addresses
- Controller submodules (BankMachine, Scheduler, RefreshManager, PowerDownManager, CmdMux, Checker) implement protocol behavior
- TLM recorders capture requests/responses/commands (DramATRecorder, TlmRecorder)
- Arbiter, DRAM model, and SimConfig glue logic drive the simulation loop
→ Exposes TLM-2.0 sockets for integration or standalone use
- Simulator CLI (main.cpp)
→ Initializes SystemC, loads configuration, instantiates DRAMSys top module, runs simulation, writes trace DB
- Trace Analyzer GUI
→ Qt frontend loads the SQLite trace, uses businessObjects to map DB rows → in-memory objects
→ Python caller computes custom metrics, GUI widgets render plots, trees, navigators
- External Integration
- Coupling to gem5 (via TLM sockets or shared‐library interface)
- Optional DRAMPower for power estimation

##### Architectural Patterns and Principles
- Layered pattern: Configuration → Core library → Front-ends (CLI, GUI)
- Plugin-style or policy‐based design for controller schedulers and refresh strategies (interfaces + multiple implementations)
- Separation of concerns:
- Model (libdramsys) vs. Presentation (Trace Analyzer Qt UI) vs. Configuration
- Storage (SQLite) decoupled from analysis (Python/Qt)
- Use of SystemC TLM-2.0 for module interconnect and timed simulation

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration Layer
    JSON["JSON Config Files"]:::config
    click JSON "https://github.com/tukl-msd/dramsys/tree/master/configs/"

    Parser["Configuration Parser"]:::config
    click Parser "https://github.com/tukl-msd/dramsys/tree/master/src/configuration/DRAMSys/config"

    JSON -->|"JSON"| Parser

    CMake["CMake Build & Find Scripts"]:::config
    click CMake "https://github.com/tukl-msd/dramsys/tree/master/cmake/"
    click CMake "https://github.com/tukl-msd/dramsys/blob/master/CMakeLists.txt"

    CMake --> Parser

    %% Core Library
    subgraph "DRAMSys Core Library"
        direction TB

        subgraph "Common Utilities & Recorders"
            Utils["Common Utilities & Recorders"]:::core
            click Utils "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/common/"
        end

        subgraph "Configuration-to-Object Mapping"
            ConfigMap["Configuration-to-Object Mapping"]:::core
            click ConfigMap "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/configuration/"
        end

        subgraph "Controller Submodules"
            direction TB
            Checker["Checker Policies"]:::core
            click Checker "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/controller/checker/"
            CmdMux["Command Multiplexer Policies"]:::core
            click CmdMux "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/controller/cmdmux/"
            Powerdown["Power-down Managers"]:::core
            click Powerdown "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/controller/powerdown/"
            Refresh["Refresh Managers"]:::core
            click Refresh "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/controller/refresh/"
            RespQueue["Response Queues"]:::core
            click RespQueue "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/controller/respqueue/"
            Scheduler["Schedulers"]:::core
            click Scheduler "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/controller/scheduler/"
        end

        subgraph "Simulation Orchestrator & Models"
            SimEngine["Simulation Orchestrator & Models"]:::core
            click SimEngine "https://github.com/tukl-msd/dramsys/tree/master/src/libdramsys/DRAMSys/simulation/"
        end
    end

    Parser -->|"instantiates objects"| ConfigMap
    ConfigMap --> Utils
    ConfigMap --> Checker
    ConfigMap --> CmdMux
    ConfigMap --> Powerdown
    ConfigMap --> Refresh
    ConfigMap --> RespQueue
    ConfigMap --> Scheduler
    ConfigMap --> SimEngine

    %% Simulator CLI
    Simulator["Simulator CLI"]:::core
    click Simulator "https://github.com/tukl-msd/dramsys/blob/master/src/simulator/main.cpp"

    subgraph "Simulator Internals"
        direction TB
        TrafficGen["Traffic Generators & Initiators"]:::core
        click TrafficGen "https://github.com/tukl-msd/dramsys/tree/master/src/simulator/simulator/generator/"
        TracePlayer["Trace Playback (STL Player)"]:::core
        click TracePlayer "https://github.com/tukl-msd/dramsys/tree/master/src/simulator/simulator/player/"
        SimClasses["Simulator Core Classes"]:::core
        click SimClasses "https://github.com/tukl-msd/dramsys/tree/master/src/simulator/simulator/"
    end

    Simulator --> TrafficGen
    Simulator --> TracePlayer
    Simulator --> SimClasses

    SimEngine -->|"TLM-2.0 socket"| Simulator

    CMake --> Simulator

    %% Database Storage
    DB["SQLite Trace DB"]:::db
    click DB "https://github.com/tukl-msd/dramsys/tree/master/lib/sqlite3/"

    SimEngine -->|"writes trace records"| DB

    %% Trace Analyzer GUI
    subgraph "Trace Analyzer GUI"
        direction TB
        QtUI["Qt Frontend & UI Files"]:::gui
        click QtUI "https://github.com/tukl-msd/dramsys/blob/master/src/traceAnalyzer/main.cpp"
        Business["Business Objects"]:::gui
        click Business "https://github.com/tukl-msd/dramsys/tree/master/src/traceAnalyzer/businessObjects/"
        DataAccess["Data Access Layer (SQLite queries)"]:::gui
        click DataAccess "https://github.com/tukl-msd/dramsys/tree/master/src/traceAnalyzer/data/"
        Presentation["Presentation Widgets & Plotting"]:::gui
        click Presentation "https://github.com/tukl-msd/dramsys/tree/master/src/traceAnalyzer/presentation/"
        PythonCaller["Python Integration for Metrics"]:::gui
        click PythonCaller "https://github.com/tukl-msd/dramsys/blob/master/src/traceAnalyzer/businessObjects/pythoncaller.*"
    end

    DB -->|"SQL queries"| DataAccess
    DataAccess --> Business
    Business --> PythonCaller
    PythonCaller --> Presentation
    Presentation --> QtUI

    CMake --> QtUI

    %% External Integrations
    subgraph "External Integrations"
        gem5["gem5"]:::external
        DRAMPower["DRAMPower"]:::external
    end

    gem5 -.->|"TLM-2.0 socket"| SimEngine
    DRAMPower -.->|"power estimation"| SimEngine

    %% Styles
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef gui fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
