# cmu-safari/ramulator architecture

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

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

## Overview

##### Project type and purpose
- Ramulator is a cycle-accurate DRAM simulator written in C++ (C++11).
- It can run in three modes: memory-trace–driven, CPU-trace–driven, and gem5-driven.
- There is an auxiliary Python-based test harness and a standalone trace-generator tool (Simpoint).

##### File structure
- Top level
- configs/: DRAM standard configuration files (DDR3, DDR4, LPDDR, HBM, etc.)
- src/: Core simulator source (Main.cpp, Config, MemoryFactory, Controllers, DRAM-model classes, Processor, Scheduler, Stats)
- cputraces/, dram.trace: Example input traces
- gem5-patch: gem5 integration patch + Gem5Wrapper.*
- mappings/: Address-interleaving maps
- test_*.py: Python scripts to automate cross-simulator comparisons and SPEC workloads
- plot.py: Post-processing and plotting of statistics
- trace_generator/: Standalone Simpoint-based trace generator (C++ and scripts)
- Patterns
- Factory (MemoryFactory) to instantiate DRAM model classes (DDR3, DDR4, etc.)
- Separation of concerns: Config parsing, request scheduling (Controller/Scheduler), memory model classes, statistics collection, external-simulator wrapper

##### README for additional insights
- Detailed description of the three usage modes
- gem5 integration via SWIG wrapper (Gem5Wrapper)
- Optional power-trace exports for DRAMPower/VAMPIRE
- References to academic papers & benchmarks (SPEC2006)

a. Main components
1. Input layer
- Configuration Parser (Config)
- Trace Loader
- Memory-trace loader (dram.trace)
- CPU-trace loader (cpu.trace, cputraces/*)
- gem5 interface (Gem5Wrapper)
- Mapping module (address-interleaving maps)
2. Core simulation engine
- MemoryFactory → instantiates concrete DRAM model (DDR3, DDR4, LPDDR, HBM, SALP, TL-DRAM, DSARP, etc.)
- Controller & Scheduler:
- Issues DRAM commands (activate, read, write, refresh)
- Implements scheduling policy (e.g., FR-FCFS, open-row)
- Processor model (for CPU-trace mode): counts non-memory instructions, generates requests
- Refresh logic (Refresh)
- Request queue management (in Cache or Controller classes)
3. Statistics & output
- Statistics collector (Statistics.h)
- Optional command-trace recorder (for power estimation)
- Python post-processing (plot.py)
- Python test harness (test_ddr3.py, test_spec.py, test_ramulator.py)
4. External integrations
- gem5 full-system simulator (via Gem5Wrapper; SWIG)
- DRAMPower / VAMPIRE power models (via recorded cmd trace)
5. Trace generator submodule
- Simpoint pipeline (trace_generator/Simpoint3.2)
- PinPoints instrumentation suite
- gettrace driver

b. Relationships and interactions
- Config → MemoryFactory → DRAM model classes
- Trace Loader → Processor (if CPU mode) or directly → Controller
- Controller ↔ DRAM model (calls into memory timing logic)
- Controller → Statistics collector (event hooks)
- Optional → Controller → cmd-trace writer → external power tools
- gem5Wrapper bridges gem5 memory requests → Controller
- test_* scripts drive Ramulator CLI → compare outputs
- plot.py reads output stats → generates visualizations
- trace_generator is a side module: independent pipeline producing cpu.trace inputs

c. Architectural patterns & design principles
- Modular DRAM models: one class per standard, all conforming to a DRAM interface
- Factory pattern for DRAM object creation based on config
- Clear separation: core engine vs. front-ends (trace loaders, gem5, power) vs. back-ends (stats, power tools)
- Extensibility: add new DRAM standard by dropping in new .cpp/.h and a config file

d. Key technologies, frameworks, and libraries
- C++11 (clang++, g++)
- Python 3 for test harness and plotting
- SWIG for gem5 integration
- Makefiles for build (root, trace_generator, Simpoint)
- Simpoint (PinPoints) for trace generation
- External DRAM power tools: VAMPIRE, DRAMPower

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        direction TB
        CP["Configuration Parser"]:::input
        TLm["Memory-Trace Loader"]:::input
        TLc["CPU-Trace Loader"]:::input
        G5["gem5 Interface"]:::input
        MM["Mapping Module"]:::input
    end

    %% Core Simulation Engine
    subgraph "Core Simulation Engine"
        direction TB
        MF["MemoryFactory"]:::core
        subgraph "DRAM Models"
            direction TB
            DRAMModel["DRAM Models\n(DDR3, DDR4, LPDDR3, LPDDR4, HBM,\nGDDR5, PCM, SALP, TL-DRAM, DSARP,\nSTT-MRAM, ALD-RAM, WideIO, WideIO2)"]:::core
        end
        CS["Controller & Scheduler"]:::core
        PM["Processor Model"]:::core
        RL["Refresh Logic"]:::core
        RQ["Request Queue Mgmt"]:::core
    end

    %% Outputs & Stats
    subgraph "Outputs & Stats"
        direction TB
        SC["Statistics Collector"]:::output
        CTR["Cmd-Trace Recorder"]:::output
        PPP["Python Post-Processing\n(plot.py)"]:::output
        PTH["Python Test Harness"]:::output
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        GEM5["gem5 Simulator"]:::external
        POWER["DRAMPower / VAMPIRE"]:::external
    end

    %% Trace Generator
    TraceGen["Trace Generator\n(Simpoint)"]:::tracegen

    %% Connections
    CP --> MF
    TLm --> MM
    TLc --> PM
    G5 --> MM
    MM --> CS
    MF --> DRAMModel
    DRAMModel --> CS
    PM --> CS
    CS --> RL
    CS --> RQ
    CS --> SC
    CS --> CTR
    CTR --> POWER
    SC --> PPP
    PTH --> CS
    PPP --> PTH
    GEM5 --> G5
    TraceGen --> TLc

    %% Click Events
    click CP "https://github.com/cmu-safari/ramulator/blob/master/src/Config.cpp"
    click CP "https://github.com/cmu-safari/ramulator/blob/master/src/Config.h"
    click TLm "https://github.com/cmu-safari/ramulator/blob/master/dram.trace"
    click TLm "https://github.com/cmu-safari/ramulator/blob/master/src/Main.cpp"
    click TLc "https://github.com/cmu-safari/ramulator/blob/master/src/Processor.cpp"
    click TLc "https://github.com/cmu-safari/ramulator/blob/master/src/Processor.h"
    click TLc "https://github.com/cmu-safari/ramulator/blob/master/cpu.trace"
    click TLc "https://github.com/cmu-safari/ramulator/tree/master/cputraces/*"
    click G5 "https://github.com/cmu-safari/ramulator/blob/master/src/Gem5Wrapper.cpp"
    click G5 "https://github.com/cmu-safari/ramulator/blob/master/src/Gem5Wrapper.h"
    click G5 "https://github.com/cmu-safari/ramulator/blob/master/gem5-0e86fac7254c-ramulator.patch"
    click MM "https://github.com/cmu-safari/ramulator/blob/master/mappings/*.map"
    click MM "https://github.com/cmu-safari/ramulator/blob/master/mappings/README.md"
    click MF "https://github.com/cmu-safari/ramulator/blob/master/src/MemoryFactory.cpp"
    click MF "https://github.com/cmu-safari/ramulator/blob/master/src/MemoryFactory.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/DDR3.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/DDR3.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/DDR4.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/DDR4.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/LPDDR3.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/LPDDR3.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/LPDDR4.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/LPDDR4.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/HBM.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/HBM.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/GDDR5.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/GDDR5.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/PCM.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/PCM.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/SALP.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/SALP.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/TLDRAM.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/TLDRAM.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/DSARP.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/DSARP.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/STTMRAM.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/STTMRAM.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/ALDRAM.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/ALDRAM.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/WideIO.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/WideIO.h"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/WideIO2.cpp"
    click DRAMModel "https://github.com/cmu-safari/ramulator/blob/master/src/WideIO2.h"
    click CS "https://github.com/cmu-safari/ramulator/blob/master/src/Controller.cpp"
    click CS "https://github.com/cmu-safari/ramulator/blob/master/src/Controller.h"
    click CS "https://github.com/cmu-safari/ramulator/blob/master/src/Scheduler.h"
    click CS "https://github.com/cmu-safari/ramulator/blob/master/src/SpeedyController.h"
    click RL "https://github.com/cmu-safari/ramulator/blob/master/src/Refresh.cpp"
    click RL "https://github.com/cmu-safari/ramulator/blob/master/src/Refresh.h"
    click RQ "https://github.com/cmu-safari/ramulator/blob/master/src/Cache.cpp"
    click RQ "https://github.com/cmu-safari/ramulator/blob/master/src/Cache.h"
    click RQ "https://github.com/cmu-safari/ramulator/blob/master/src/Request.h"
    click SC "https://github.com/cmu-safari/ramulator/blob/master/src/StatType.cpp"
    click SC "https://github.com/cmu-safari/ramulator/blob/master/src/StatType.h"
    click SC "https://github.com/cmu-safari/ramulator/blob/master/src/Statistics.h"
    click PPP "https://github.com/cmu-safari/ramulator/blob/master/plot.py"
    click PTH "https://github.com/cmu-safari/ramulator/blob/master/test_ddr3.py"
    click PTH "https://github.com/cmu-safari/ramulator/blob/master/test_spec.py"
    click PTH "https://github.com/cmu-safari/ramulator/blob/master/test_ramulator.py"
    click TraceGen "https://github.com/cmu-safari/ramulator/tree/master/trace_generator/"

    %% Styles
    classDef input fill:#a0c4ff,stroke:#0366d6,color:#000000,stroke-width:1px;
    classDef core fill:#c3f584,stroke:#2a7f2b,color:#000000,stroke-width:1px;
    classDef output fill:#ffadad,stroke:#d60000,color:#000000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke:#666666,color:#000000,stroke-width:1px;
    classDef tracegen fill:#ffd6a5,stroke:#e65c00,color:#000000,stroke-width:1px;
```
