# chathuranus/gpu-rowhammer architecture

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

- Interactive diagram: https://gitdiagram.com/chathuranus/gpu-rowhammer
- Repository: https://github.com/chathuranus/gpu-rowhammer

## Overview

This is a research simulator project evaluating RowHammer defenses for shared-bank GDDR6 GPU memory. The main workflow generates synthetic request traces, runs them through a Ramulator-based experiment harness under selected mitigation policies, and analyzes the resulting safety, timing, fairness, and performance metrics. Separate suites cover baseline comparisons, hypotheses, and constrained-hardware defenses. The README documents DBIM-RR and other major defense capabilities, but the simulator fork’s controller implementation is not present in the supplied tree, so its internals are represented only at the documented level.

Main entry points: [`results`](https://github.com/chathuranus/gpu-rowhammer/tree/main/results) (Experiment Results), [`configs/run_experiment.py`](https://github.com/chathuranus/gpu-rowhammer/blob/main/configs/run_experiment.py) (Experiment Harness), [`scripts/run_hypothesis_suite.py`](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_hypothesis_suite.py) (Hypothesis Suite), [`scripts/run_minor_hardware_defenses.py`](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_minor_hardware_defenses.py) (Hardware Defense Suite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workloads["Synthetic Workloads"]
  node_tracegen["Trace Generators"]
  node_hyptrace["Hypothesis Traces"]
  node_stressgen["Hardware Stress Traces"]
  node_tracefiles["Request Traces"]
end

subgraph group_simulation["Simulation"]
  node_runner["Experiment Harness<br/>[run_experiment.py]"]
  node_ramulator["Ramulator Simulator"]
  node_dbim["DBIM-RR Defense"]
end

subgraph group_evaluation["Evaluation Suites"]
  node_defense_suite["Defense Suite"]
  node_hyp_suite["Hypothesis Suite"]
  node_hardware_suite["Hardware Defense Suite"]
  node_comparison["Approach Comparison"]
end

subgraph group_analysis["Results Analysis"]
  node_resultfiles["Experiment Results"]
  node_defense_analysis["Defense Analysis"]
  node_hyp_analysis["Hypothesis Analysis"]
  node_hardware_analysis["Hardware Analysis"]
  node_comparison_analysis["Comparison Summary"]
  node_demo["Result Demonstration"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs evaluation"| node_defense_suite
node_researcher -->|"runs evaluation"| node_hyp_suite
node_researcher -->|"runs evaluation"| node_hardware_suite
node_researcher -->|"runs evaluation"| node_comparison
node_tracegen -->|"includes"| node_hyptrace
node_tracegen -->|"includes"| node_stressgen
node_hyp_suite -->|"generates"| node_hyptrace
node_hardware_suite -->|"generates"| node_stressgen
node_tracegen -->|"writes traces"| node_tracefiles
node_defense_suite -->|"launches runs"| node_runner
node_hyp_suite -->|"launches runs"| node_runner
node_hardware_suite -->|"launches runs"| node_runner
node_runner -->|"reads traces"| node_tracefiles
node_runner -->|"runs simulation"| node_ramulator
node_runner -.->|"configures defense"| node_dbim
node_ramulator -.->|"produces metrics"| node_resultfiles
node_defense_suite -->|"records results"| node_resultfiles
node_hyp_suite -->|"records results"| node_resultfiles
node_hardware_suite -->|"records results"| node_resultfiles
node_resultfiles -->|"supplies metrics"| node_defense_analysis
node_resultfiles -->|"supplies metrics"| node_hyp_analysis
node_resultfiles -->|"supplies metrics"| node_hardware_analysis
node_resultfiles -->|"supplies metrics"| node_comparison_analysis
node_resultfiles -->|"supplies summary"| node_demo

click node_tracegen "https://github.com/chathuranus/gpu-rowhammer/tree/main/scripts"
click node_hyptrace "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/generate_hypothesis_traces.py"
click node_stressgen "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/generate_hardware_stress_traces.py"
click node_tracefiles "https://github.com/chathuranus/gpu-rowhammer/tree/main/traces"
click node_runner "https://github.com/chathuranus/gpu-rowhammer/blob/main/configs/run_experiment.py"
click node_defense_suite "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_defense_suite.py"
click node_hyp_suite "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_hypothesis_suite.py"
click node_hardware_suite "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_minor_hardware_defenses.py"
click node_comparison "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_approach_comparison.py"
click node_resultfiles "https://github.com/chathuranus/gpu-rowhammer/tree/main/results"
click node_defense_analysis "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/analyze_defense_suite.py"
click node_hyp_analysis "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/analyze_hypotheses.py"
click node_hardware_analysis "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/analyze_minor_hardware_defenses.py"
click node_comparison_analysis "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/summarize_approach_comparison.py"
click node_demo "https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/show_supervisor_demo.py"

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_tracegen,node_hyptrace,node_stressgen,node_tracefiles toneBlue
class node_runner,node_ramulator,node_dbim toneAmber
class node_defense_suite,node_hyp_suite,node_hardware_suite,node_comparison toneMint
class node_resultfiles,node_defense_analysis,node_hyp_analysis,node_hardware_analysis,node_comparison_analysis,node_demo toneRose
class node_researcher toneIndigo
```

## Components

### Synthetic Workloads

- [Trace Generators](https://github.com/chathuranus/gpu-rowhammer/tree/main/scripts): `scripts`
- [Hypothesis Traces](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/generate_hypothesis_traces.py): `scripts/generate_hypothesis_traces.py`
- [Hardware Stress Traces](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/generate_hardware_stress_traces.py): `scripts/generate_hardware_stress_traces.py`
- [Request Traces](https://github.com/chathuranus/gpu-rowhammer/tree/main/traces): `traces`

### Simulation

- [Experiment Harness](https://github.com/chathuranus/gpu-rowhammer/blob/main/configs/run_experiment.py): `configs/run_experiment.py`
- **Ramulator Simulator**
- **DBIM-RR Defense**

### Evaluation Suites

- [Defense Suite](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_defense_suite.py): `scripts/run_defense_suite.py`
- [Hypothesis Suite](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_hypothesis_suite.py): `scripts/run_hypothesis_suite.py`
- [Hardware Defense Suite](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_minor_hardware_defenses.py): `scripts/run_minor_hardware_defenses.py`
- [Approach Comparison](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/run_approach_comparison.py): `scripts/run_approach_comparison.py`

### Results Analysis

- [Experiment Results](https://github.com/chathuranus/gpu-rowhammer/tree/main/results): `results`
- [Defense Analysis](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/analyze_defense_suite.py): `scripts/analyze_defense_suite.py`
- [Hypothesis Analysis](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/analyze_hypotheses.py): `scripts/analyze_hypotheses.py`
- [Hardware Analysis](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/analyze_minor_hardware_defenses.py): `scripts/analyze_minor_hardware_defenses.py`
- [Comparison Summary](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/summarize_approach_comparison.py): `scripts/summarize_approach_comparison.py`
- [Result Demonstration](https://github.com/chathuranus/gpu-rowhammer/blob/main/scripts/show_supervisor_demo.py): `scripts/show_supervisor_demo.py`

### Other components

- **Researcher**

## Connections

- Researcher → Defense Suite: runs evaluation (evidence: `scripts/run_defense_suite.py`)
- Researcher → Hypothesis Suite: runs evaluation (evidence: `scripts/run_hypothesis_suite.py`)
- Researcher → Hardware Defense Suite: runs evaluation (evidence: `scripts/run_minor_hardware_defenses.py`)
- Researcher → Approach Comparison: runs evaluation (evidence: `scripts/run_approach_comparison.py`)
- Trace Generators → Hypothesis Traces: includes (evidence: `scripts/generate_hypothesis_traces.py`)
- Trace Generators → Hardware Stress Traces: includes (evidence: `scripts/generate_hardware_stress_traces.py`)
- Hypothesis Suite → Hypothesis Traces: generates (evidence: `scripts/run_hypothesis_suite.py`)
- Hardware Defense Suite → Hardware Stress Traces: generates (evidence: `scripts/run_minor_hardware_defenses.py`)
- Trace Generators → Request Traces: writes traces (evidence: `scripts/generate_hypothesis_traces.py`)
- Defense Suite → Experiment Harness: launches runs (evidence: `scripts/run_defense_suite.py`)
- Hypothesis Suite → Experiment Harness: launches runs (evidence: `scripts/run_hypothesis_suite.py`)
- Hardware Defense Suite → Experiment Harness: launches runs (evidence: `scripts/run_minor_hardware_defenses.py`)
- Experiment Harness → Request Traces: reads traces (evidence: `configs/run_experiment.py`)
- Experiment Harness → Ramulator Simulator: runs simulation (evidence: `configs/run_experiment.py`)
- Experiment Harness → DBIM-RR Defense: configures defense (evidence: `README.md`)
- Ramulator Simulator → Experiment Results: produces metrics
- Defense Suite → Experiment Results: records results (evidence: `scripts/run_defense_suite.py`)
- Hypothesis Suite → Experiment Results: records results (evidence: `scripts/run_hypothesis_suite.py`)
- Hardware Defense Suite → Experiment Results: records results (evidence: `scripts/run_minor_hardware_defenses.py`)
- Experiment Results → Defense Analysis: supplies metrics (evidence: `scripts/analyze_defense_suite.py`)
- Experiment Results → Hypothesis Analysis: supplies metrics (evidence: `scripts/analyze_hypotheses.py`)
- Experiment Results → Hardware Analysis: supplies metrics (evidence: `scripts/analyze_minor_hardware_defenses.py`)
- Experiment Results → Comparison Summary: supplies metrics (evidence: `scripts/summarize_approach_comparison.py`)
- Experiment Results → Result Demonstration: supplies summary (evidence: `scripts/show_supervisor_demo.py`)
