ruby — Coherence Protocol Simulation

Overview

Ruby is gem5's detailed coherence protocol simulator. Unlike the Classic cache system (which has coherence logic hardcoded in C++), Ruby uses SLICC (Specification Language for Implementing Cache Coherence) to define protocol state machines. This makes it straightforward to implement and test new coherence protocols — from Atomic and Timing Simple CPUs — gem5 Wiki" href="../../cpu_doc/simple/index.html">simple MI to complex MOESI_CMP_directory.

Key features:

• SLICC-generated controllers — Coherence logic defined in a high-level DSL, compiled to C++
• Network models — Simple network (abstract) and Garnet (detailed NoC with routers, VCs, flow control)
• Directory-based coherence — Scalable multiprocessor coherence via directory controllers
• GPU coalescer — Specialized memory interface for GPU compute units
• HTM support — Hardware Transactional Memory via HTMSequencer
• Profiling — Detailed coherence protocol statistics and event tracking

Architecture

flowchart TD
    CPU0["CPU 0"]
    CPU1["CPU 1"]
    GPU["GPU CU"]
    SEQ0["Sequencer 0"]
    SEQ1["Sequencer 1"]
    GPUC["GPUCoalescer"]
    L1C0["L1 Controller 0"]
    L1C1["L1 Controller 1"]
    L1CG["GPU L1 Controller"]
    NET["On-Chip Network\n(Simple / Garnet)"]
    L2C["L2 Controller"]
    DIR["Directory Controller"]
    MC["Memory Controller"]
    DRAM["DRAM"]

    CPU0 --> SEQ0
    CPU1 --> SEQ1
    GPU --> GPUC
    SEQ0 --> L1C0
    SEQ1 --> L1C1
    GPUC --> L1CG
    L1C0 -->|"MessageBuffer"| NET
    L1C1 -->|"MessageBuffer"| NET
    L1CG -->|"MessageBuffer"| NET
    NET --> L2C
    NET --> DIR
    L2C -->|"MessageBuffer"| NET
    DIR --> MC
    MC --> DRAM
  

SLICC Protocol System

SLICC (Specification Language for Implementing Cache Coherence) is a domain-specific language that compiles into C++ controller code. Each protocol defines:

• States — Cache line states (e.g., I, S, M, O, E and transient states)
• Events — Triggers (e.g., Load, Store, Fwd_GetS, Data_from_Dir)
• Transitions — State × Event → Actions + New State
• Actions — Atomic operations (send message, allocate TBE, set permissions)

stateDiagram-v2
    [*] --> I : Initial
    I --> IS_D : Load / send GetS
    IS_D --> S : Data_from_Dir
    I --> IM_AD : Store / send GetX
    IM_AD --> IM_A : Data_from_Dir
    IM_A --> M : Ack_all
    S --> SM_AD : Store / send Upgrade
    SM_AD --> SM_A : Data_from_Dir
    SM_A --> M : Ack_all
    M --> MI_A : Replacement / send PutX
    MI_A --> I : Put_Ack
    M --> S : Fwd_GetS / send data
    M --> I : Fwd_GetX / send data
    S --> I : Replacement / send PutS
  

SLICC Compilation Pipeline

Key Classes Reference

Network Models

Ruby provides two network implementations with different fidelity/speed trade-offs:

Simple Network

An abstract network model that delivers messages with fixed latency. No contention modeling — messages never block each other. Fast simulation for protocol debugging.

• Fixed per-hop latency
• Infinite bandwidth links
• No router microarchitecture
• Best for: protocol correctness testing, large-scale studies where network detail isn't critical

Garnet Network

A detailed on-chip network model with cycle-accurate router pipelines, virtual channels, credit-based flow control, and configurable topologies.

• 5-stage router pipeline (buffer write → route compute → VC allocate → switch allocate → switch traverse)
• Wormhole routing with virtual channels (VCs)
• Credit-based flow control
• Configurable link bandwidth, latency, and buffer depths
• Support for mesh, torus, custom topologies
• Fault injection modeling
• Best for: NoC research, detailed performance studies

flowchart LR
    subgraph Router["Garnet Router Pipeline"]
      BW["Buffer\nWrite"]
      RC["Route\nCompute"]
      VA["VC\nAllocate"]
      SA["Switch\nAllocate"]
      ST["Switch\nTraverse"]
      LT["Link\nTraverse"]
      BW --> RC --> VA --> SA --> ST --> LT
    end

    NI_IN["Network\nInterface\n(Inbound)"] --> Router
    Router --> NI_OUT["Network\nInterface\n(Outbound)"]
  

Ruby Structures

The structures/ directory contains storage components used by controllers:

Request Flow Walkthrough

Trace a CPU load through the Ruby coherence system:

Available Protocols

gem5 ships with several pre-defined SLICC protocols:

Sub-module Overview

Cross-Module Connections

flowchart TD
    subgraph gem5_Core["gem5 Core"]
      PKT["mem/packet.hh\nPacket"]
      PORT["mem/port.hh\nRequestPort / ResponsePort"]
    end
    subgraph Ruby["mem/ruby/"]
      RP["RubyPort\n(Port adapter)"]
      SEQ["Sequencer"]
      CTRL["AbstractController\n(SLICC-generated)"]
      CM["CacheMemory"]
      MB["MessageBuffer"]
      NET["Network"]
    end
    subgraph Memory["mem/"]
      MEMCTRL["MemCtrl\nDRAM Controller"]
    end

    PKT --> RP
    PORT --> RP
    RP --> SEQ
    SEQ --> CTRL
    CTRL --> CM
    CTRL --> MB
    MB --> NET
    NET --> MB
    CTRL --> MEMCTRL
  

Directory Map

Configuration Reference