Ramulator V2.0a

Ramulator V2.1 Pre-Release Note

We have pre-released Ramulator 2.1 as a major overhaul to Ramulator 2.0 in the v2.1 branch! We recommend you to switch to Ramulator 2.1 and let us know your thoughts (through the Discussions tab on Github) and/or if you find any new bugs (through issues and PRs). We will soon make v2.1 the default on Github and v2.0a will be archived.

What has changed from Ramulator 2.0:

• Aggregated bug fixes (identified from both Github issues and internal testing)
• More comprehensive support for newer DRAM & controller features
• More comprehensive sets of test and validation workflows
• Significantly improved the ease of use, configuration, and extension
• Overall code quality improvements

Introduction

Ramulator 2.0 is a modern, modular, and extensible cycle-accurate DRAM simulator. It is the successor of Ramulator 1.0 [Kim+, CAL'16], achieving both fast simulation speed and ease of extension. The goal of Ramulator 2.0 is to enable rapid and agile implementation and evaluation of design changes in the memory controller and DRAM to meet the increasing research effort in improving the performance, security, and reliability of memory systems. Ramulator 2.0 abstracts and models key components in a DRAM-based memory system and their interactions into shared interfaces and independent implementations, enabling easy modification and extension of the modeled functions of the memory controller and DRAM.

This Github repository contains the public version of Ramulator 2.0. From time to time, we will synchronize improvements of the code framework, additional functionalities, bug fixes, etc. from our internal version. Ramulator 2.0 is in its early stage and welcomes your contribution as well as new ideas and implementations in the memory system!

Currently, Ramulator 2.0 provides the DRAM models for the following standards:

• DDR3, DDR4, DDR5
• LPDDR5
• GDDR6
• HBM(2), HBM3

Ramulator 2.0 also provides implementations for the following RowHammer mitigation techniques:

• PARA [Kim+, ISCA'14]
• TWiCe [Lee+, ISCA'19]
• Graphene [Park+, MICRO'20]
• BlockHammer [Yağlıkçı+, HPCA'21]
• Hydra [Qureshi+, ISCA'22]
• Randomized Row Swap (RRS) [Saileshwar+, ASPLOS'22]
• AQUA [Saxena+, MICRO'22]
• An "Oracle" Refresh Mitigation [Kim+, ISCA'20]

A quick glance at Ramulator 2.0's other key features:

• Modular and extensible software architecture: Ramulator 2.0 provides an explicit separation of implementations from interfaces. Therefore new ideas can be implemented without intrusive changes.
• Self-registering factory for interface and implementation classes: Ramulator 2.0 automatically constructs the correct class of objects by their names as you specify in the configuration. Do not worry about boilerplate code!
• YAML-based configuration file: Ramulator 2.0 is configured via human-readable and machine-friendly configuration files. Sweeping parameters is as easy as editing a Python dictionary!

The initial release of Ramulator 2.0 is described in the following paper:

Haocong Luo, Yahya Can Tugrul, F. Nisa Bostancı, Ataberk Olgun, A. Giray Yaglıkcı, and Onur Mutlu, "Ramulator 2.0: A Modern, Modular, and Extensible DRAM Simulator," arXiv, 2023.

If you use Ramulator 2.0 in your work, please use the following citation:

@misc{luo2023ramulator2,
  title={{Ramulator 2.0: A Modern, Modular, and Extensible DRAM Simulator}}, 
  author={Haocong Luo and Yahya Can Tu\u{g}rul and F. Nisa Bostancı and Ataberk Olgun and A. Giray Ya\u{g}l{\i}k\c{c}{\i} and and Onur Mutlu},
  year={2023},
  archivePrefix={arXiv},
  primaryClass={cs.AR}
}

Using Ramulator 2.0

Dependencies

Ramulator uses some C++20 features to achieve both high runtime performance and modularity and extensibility. Therefore, a C++20-capable compiler is needed to build Ramulator 2.0. We have tested and verified Ramulator 2.0 with the following compilers:

• g++-12
• clang++-15

Ramulator 2.0 uses the following external libraries. The build system (CMake) will automatically download and configure these dependencies.

• argparse
• spdlog
• yaml-cpp

Getting Started

Clone the repository

  $ git clone https://github.com/CMU-SAFARI/ramulator2

Configure the project and build the executable

  $ mkdir build
  $ cd build
  $ cmake ..
  $ make -j
  $ cp ./ramulator2 ../ramulator2
  $ cd ..

This should produce a ramulator2 executable that you can execute standalone and a libramulator.so dynamic library that can be used as a memory system library by other simulators.

Running Ramulator 2.0 in Standalone Mode

Ramulator 2.0 comes with two independent simulation frontends: A memory-trace parser and a simplistic out-of-order core model that can accept instruction traces. To start a simulation with these frontends, just run the Ramulator 2.0 executable with the path to the configuration file specified through the -f argument

  $ ./ramulator2 -f ./example_config.yaml

To support easy automation of experiments (e.g., evaluate many different traces and sweep parameters), Ramulator 2.0 can accept the configurations as a string dump of the YAML document, which is usually produced by a scripting language that can easily parse and manipulate YAML documents (e.g., python). We provide an example python snippet to demonstrate an experiment of sweeping the nRCD timing constraint:

import os
import yaml  # YAML parsing provided with the PyYAML package

baseline_config_file = "./example_config.yaml"
nRCD_list = [10, 15, 20, 25]

base_config = None
with open(base_config_file, 'r') as f:
  base_config = yaml.safe_load(f)

for nRCD in nRCD_list:
  config["MemorySystem"]["DRAM"]["timing"]["nRCD"] = nRCD
  cmds = ["./ramulator2", str(config)]
  # Run the command with e.g., os.system(), subprocess.run(), ...

Using Ramulator 2.0 as a Library (gem5 Example)

Ramulator 2.0 packs all the interfaces and implementations into a dynamic library (libramulator.so). This can be used as a memory system library providing extensible cycle-accurate DRAM simulation to another simulator. We use gem5 as an example to show how to use Ramulator 2.0 as a library. We have tested and verified the integration of Ramulator 2.0 into gem5 as a library.

1. Clone Ramulator 2.0 into gem5/ext/ramulator2/ directory.
2. Build Ramulator 2.0. You should have libramulator.so at gem5/ext/ramulator2/ramulator2/libramulator.so
3. Create a file SConscript at gem5/ext/ramulator2/, with the following contents to add Ramulator 2.0 to gem5's build system

import os

Import('env')

if not os.path.exists(Dir('.').srcnode().abspath + '/ramulator2'):
  env['HAVE_RAMULATOR2'] = False
  Return()

env['HAVE_RAMULATOR2'] = True
ramulator2_path = os.path.join(Dir('#').abspath, 'ext/ramulator2/ramulator2/')
env.Prepend(CPPPATH=Dir('.').srcnode())
env.Append(
  LIBS=['ramulator'],
  LIBPATH=[ramulator2_path],
  RPATH=[ramulator2_path],
  CPPPATH=[
  ramulator2_path+'/src/', 
  ramulator2_path+'/ext/spdlog/include',
  ramulator2_path+'/ext/yaml-cpp/include'
])

4. Put the Ramulator2 wrapper code to gem5/src/mem/
5. Add the code to gem5/src/mem/SConscript to register the Ramulator2 SimObjects to gem5

if env['HAVE_RAMULATOR2']:
  SimObject('Ramulator2.py', sim_objects=['Ramulator2'])
  Source('ramulator2.cc')
  DebugFlag("Ramulator2")

6. Create the Ramulator2 SimObject as the memory controller and specify the path to the Ramulator 2.0 configuration file in your gem5 configuration script, e.g.,

import m5
from m5.objects import *

system = System()
system.mem_ctrl = Ramulator2()
system.mem_ctrl.config_path = "<path-to-config>.yaml" # Don't forget to specify GEM5 as the implementation of the frontend interface!

# Continue your configuration of gem5 ...

General Instructions for Writing Your Own Wrapper of Ramulator 2.0 for Another (including Your Own) Simulator

We describe the key steps and cover the key interfaces involved in using Ramulator 2.0 as a library for your own simulator.

1. Add Ramulator 2.0's key header files to your build system:

• ramulator2/src/base/base.h
• ramulator2/src/base/request.h
• ramulator2/src/base/config.h
• ramulator2/src/frontend/frontend.h
• ramulator2/src/memory_system/memory_system.h

2. Parse the YAML configuration for Ramulator 2.0 and instantiate the interfaces of the two top-level components, e.g.,

// MyWrapper.h
std::string config_path;
Ramulator::IFrontEnd* ramulator2_frontend;
Ramulator::IMemorySystem* ramulator2_memorysystem;

// MyWrapper.cpp
YAML::Node config = Ramulator::Config::parse_config_file(config_path, {});
ramulator2_frontend = Ramulator::Factory::create_frontend(config);
ramulator2_memorysystem = Ramulator::Factory::create_memory_system(config);

ramulator2_frontend->connect_memory_system(ramulator2_memorysystem);
ramulator2_memorysystem->connect_frontend(ramulator2_frontend);

3. Communicate the necessary memory system information from Ramulator 2.0 to your system (e.g., memory system clock):

float memory_tCK = ramulator2_memorysystem->get_tCK();

4. Send the memory requests from your simulator to Ramulator 2.0, with the correspoding ca