# chipsalliance/rocket-chip architecture

> Architecture diagram of the GitHub repository chipsalliance/rocket-chip, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chipsalliance/rocket-chip
- Repository: https://github.com/chipsalliance/rocket-chip

## Overview

##### Main Components
- Core Generator & Infrastructure: Represent the Scala-based generators found under src/main/scala. These include key packages such as:
– rocket: Implements the core Rocket pipeline (ALU, branch predictor, caches, etc).
– tile: Contains components that extend the core with additional functionality (e.g., FPUs, peripherals).
– subsystem & system: Assemble cores, buses, and interconnects into a full system-on-chip (SoC).
– diplomacy & tilelink: Handle parameter negotiation between modules and generate bus protocols.
– util, regmapper, and interrupts: Provide supporting utilities and interface definitions.
- External Submodules: Show the external Git submodules (chisel3, firrtl, hardfloat, rocket-tools, torture) as distinct components that feed into the generator.
- Simulation & Verification Infrastructure: Include directories like bootrom, regression, scripts, and csrc that support simulation (via Verilator, VCS, or other Verilog simulation tools) and testing.
- Build & Configuration Tools: Note files and directories for build scripts (Makefile, build.sc) and environment configuration (flake.lock, flake.nix, overlay.nix, etc).

##### Out Relationships and Data Flow
- SoC Assembly: Illustrate how individual hardware modules (rocket core, caches, debug units, peripheral devices, bus bridges) are interconnected using the diplomacy and TileLink/AMBA bus infrastructure. Indicate directional data/control flows between these modules.
- Testing & Simulation: Represent the simulation flow—where the generated RTL is passed on to test harnesses (found in directories like regression, unittest, bootrom, and scripts) to run verification through cycle-accurate simulations.

##### Architectural Patterns and Technologies
- Modularity & Reuse: Emphasize the separation between generator (Scala/Chisel code) and the hardware being generated. The design employs a “generator pattern” where highly parameterized modules get stitched together.
- Negotiation via Diplomacy: Point out that many bus interconnects and adapters (including AMBA, AXI4, AHB-lite, APB, TileLink) are created using a two-phase hardware elaboration pattern provided by the diplomacy package.
- Build & Test Automation: Include CI/CD aspects (GitHub workflows, CI scripts) and explain their integration with regression suites and simulation environments.
- Toolchain Integration: Note that a build system (using tools like Make and mill) coordinates code generation, simulation, and even integration with IDEs (via mill-bsp) and Nix-based environment management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Generator Frontend
    subgraph "Generator Frontend"
        CG["Core (Rocket Pipeline)"]:::code
        ET["Extended Tiles"]:::code
        SSA["SoC Assembly - Subsystem"]:::code
        SSY["SoC Assembly - System"]:::code
        DP["Diplomacy Code"]:::code
        TL["TileLink Code"]:::code
        UT["Utilities (util)"]:::code
        RM["Regmapper"]:::code
        IN["Interrupts"]:::code
    end

    %% External Submodules
    subgraph "External Submodules"
        CH["Chisel"]:::external
        DE["Diplomacy (External)"]:::external
        HF["HardFloat"]:::external
        RT["Rocket Tools"]:::external
        TO["Torture"]:::external
    end

    %% Code Transformation Pipeline
    subgraph "Code Transformation Pipeline"
        FIRRTL["FIRRTL (Intermediate)"]:::rtl
        VERILOG["Verilog RTL"]:::rtl
    end

    %% Simulation & Verification
    subgraph "Simulation & Verification"
        BR["BootROM"]:::simulation
        REG["Regression Tests"]:::simulation
        SSCR["Simulation Scripts"]:::simulation
        CC["C/C++ Models"]:::simulation
        VS["Verilator Sources"]:::simulation
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        MF["Makefile"]:::build
        BSC["Build.sc"]:::build
        CSC["Common.sc"]:::build
        FL["flake.lock"]:::build
        FN["flake.nix"]:::build
        ON["overlay.nix"]:::build
        CI["CI/CD Pipelines"]:::build
    end

    %% Connections between External Submodules and Generator Frontend
    CH --> CG
    DE --> DP
    HF --> ET

    %% Internal Code Module Flows
    CG --> DP
    DP --> TL
    UT --> CG
    RM --> CG
    IN --> CG
    ET --> SSA
    SSA --> SSY

    %% Generation Pipeline Flow from Generator Frontend to RTL
    CG & ET & SSA & SSY & DP & TL & UT & RM & IN --> FIRRTL
    FIRRTL --> VERILOG

    %% Simulation Flow: Verilog RTL feeds simulation components
    VERILOG --> BR
    VERILOG --> REG
    VERILOG --> SSCR
    VERILOG --> CC
    VERILOG --> VS

    %% Build & Configuration Flow: Build tools trigger code generation
    MF --> BSC
    BSC --> CSC
    CSC --> FIRRTL
    FL --> MF
    FN --> MF
    ON --> MF
    CI --> MF

    %% External Tools Dependencies
    RT --> CG
    TO --> ET

    %% Build support for Simulation
    CI --> REG

    %% Styles
    classDef code fill:#E6F7FF,stroke:#1f77b4,stroke-width:2px;
    classDef external fill:#FFF5E6,stroke:#ff7f0e,stroke-width:2px;
    classDef rtl fill:#FFE6E6,stroke:#D62728,stroke-width:2px;
    classDef simulation fill:#F0FFF0,stroke:#2ca02c,stroke-width:2px;
    classDef build fill:#F9E6FF,stroke:#9467bd,stroke-width:2px;

    %% Click Events for Core Generator & Infrastructure
    click CG "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/rocket"
    click ET "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/tile"
    click SSA "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/subsystem"
    click SSY "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/system"
    click DP "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/diplomacy"
    click TL "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/tilelink"
    click UT "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/util"
    click RM "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/regmapper"
    click IN "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/scala/interrupts"

    %% Click Events for External Submodules
    click CH "https://github.com/chipsalliance/rocket-chip/tree/master/dependencies/chisel"
    click DE "https://github.com/chipsalliance/rocket-chip/tree/master/dependencies/diplomacy"
    click HF "https://github.com/chipsalliance/rocket-chip/tree/master/dependencies/hardfloat"

    %% Click Events for Simulation & Verification Infrastructure
    click BR "https://github.com/chipsalliance/rocket-chip/tree/master/bootrom"
    click REG "https://github.com/chipsalliance/rocket-chip/tree/master/regression"
    click SSCR "https://github.com/chipsalliance/rocket-chip/tree/master/scripts"
    click CC "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/resources/csrc"
    click VS "https://github.com/chipsalliance/rocket-chip/tree/master/src/main/resources/vsrc"

    %% Click Events for Build & Configuration Tools
    click MF "https://github.com/chipsalliance/rocket-chip/tree/master/Makefile"
    click BSC "https://github.com/chipsalliance/rocket-chip/blob/master/build.sc"
    click CSC "https://github.com/chipsalliance/rocket-chip/blob/master/common.sc"
    click FL "https://github.com/chipsalliance/rocket-chip/blob/master/flake.lock"
    click FN "https://github.com/chipsalliance/rocket-chip/blob/master/flake.nix"
    click ON "https://github.com/chipsalliance/rocket-chip/blob/master/overlay.nix"
    click CI "https://github.com/chipsalliance/rocket-chip/tree/master/.github/workflows"
```
