# lowrisc/ariane architecture

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

- Interactive diagram: https://gitdiagram.com/lowrisc/ariane
- Repository: https://github.com/lowrisc/ariane

## Overview

##### Project Context
- The Ariane CPU is a 6-stage, in-order RISC-V core. Its L1 cache subsystem lives under `src/cache_subsystem/`. There are two flavors:
- The “std” (standard) cache subsystem (`std_cache_subsystem.sv` + supporting files)
- The “serpent” cache subsystem (`serpent_cache_subsystem.sv` + supporting files) for OpenPiton integration

##### Identifying Main Components
- cache_ctrl.sv             – overall cache controller, coordinates requests and responses
- miss_handler.sv           – tracks outstanding misses, arbitration, refill logic
- tag_cmp.sv                – tag comparison logic for cache hits/misses
- std_cache_subsystem.sv    – top-level wrapper for the standard L1 D-cache
- serpent_cache_subsystem.sv – wrapper for the serpent variant (write-through)
- serpent_dcache.sv, serpent_dcache_mem.sv, serpent_dcache_ctrl.sv, serpent_dcache_wbuffer.sv, serpent_icache.sv – sub-blocks specialized for serpent flavor
- std_nbdcache.sv, std_no_dcache.sv – alternative modes (no cache, non-blocking)

##### Relationships & Data Flow
- CPU pipeline issues load/store requests → enters cache_ctrl
- cache_ctrl forwards to tag_cmp and data RAM (hit path)
- On a miss, cache_ctrl signals miss_handler
- miss_handler sends read/write bursts over AXI (through `axi_mem_if`)
- refill data returns into data RAM; tag_ram is updated
- cache_ctrl releases data back to pipeline

##### Architectural Patterns & Principles
- Hierarchical design: top-level subsystem instantiates controller, tag comparison, miss logic, line RAM modules
- Decoupled hit vs. miss paths for performance (non-blocking)
- AXI bus interface for memory coherence and external connectivity
- Parameterizable for line size, associativity

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External CPU
    CPU["CPU Pipeline"]:::external

    %% Cache Subsystem Wrapper
    subgraph "L1 D-Cache Subsystem"
        direction TB
        std["std_cache_subsystem"]:::subsys
        serpent["serpent_cache_subsystem"]:::subsys

        %% Standard Flavor Internals
        subgraph "Standard Cache Internals"
            direction TB
            cache_ctrl["Cache Controller"]:::control
            tag_cmp["Tag Comparator"]:::memory
            data_ram["Data RAM"]:::memory
            miss_handler["Miss Handler"]:::control
        end

        std --> cache_ctrl
        std --> tag_cmp
        std --> data_ram
        std --> miss_handler

        %% Serpent Flavor Internals (alternate branch)
        subgraph "Serpent Cache Internals"
            direction TB
            serpent_ctrl["Serpent Cache Ctrl"]:::control
            serpent_dcache["Serpent DCache"]:::memory
            serpent_mem["Serpent DCache Mem"]:::memory
            serpent_miss["Serpent Miss Unit"]:::control
            serpent_wbuf["Serpent WBuffer"]:::memory
        end

        serpent --> serpent_ctrl
        serpent --> serpent_dcache
        serpent --> serpent_mem
        serpent --> serpent_miss
        serpent --> serpent_wbuf
    end

    %% Hit Path
    CPU -->|"LD/ST addr, size, data_in"| cache_ctrl
    cache_ctrl -->|"tag read"| tag_cmp
    tag_cmp -->|"hit/miss flag"| cache_ctrl
    cache_ctrl -->|"read/write data (hit path)"| data_ram
    cache_ctrl -->|"data_out, response valid"| CPU

    %% Miss Path & AXI Interface
    cache_ctrl -->|"request miss"| miss_handler
    miss_handler -->|"AXI read/write bursts"| axi_if["AXI Memory Interface"]:::iface
    axi_if -->|"burst response"| miss_handler
    miss_handler -->|"write-back line"| data_ram
    miss_handler -->|"update tags"| tag_cmp

    %% Legend
    subgraph Legend
        direction TB
        ctrl["Control Blocks"]:::control
        mem["Memory Structures"]:::memory
        ifaceL["AXI Interface"]:::iface
        ext["External"]:::external
    end

    %% Click Events
    click cache_ctrl "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/cache_ctrl.sv"
    click miss_handler "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/miss_handler.sv"
    click tag_cmp "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/tag_cmp.sv"
    click std "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/std_cache_subsystem.sv"
    click serpent "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/serpent_cache_subsystem.sv"
    click serpent_dcache "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/serpent_dcache.sv"
    click serpent_ctrl "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/serpent_dcache_ctrl.sv"
    click serpent_mem "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/serpent_dcache_mem.sv"
    click serpent_miss "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/serpent_dcache_missunit.sv"
    click serpent_wbuf "https://github.com/lowrisc/ariane/blob/master/src/cache_subsystem/serpent_dcache_wbuffer.sv"
    click axi_if "https://github.com/lowrisc/ariane/tree/master/src/axi_mem_if/"

    %% Style Definitions
    classDef control fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef memory fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef iface fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef subsys fill:#D3D3D3,stroke:#333,stroke-width:1px
```
