# psnjk/simplecache architecture

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

- Interactive diagram: https://gitdiagram.com/psnjk/simplecache
- Repository: https://github.com/psnjk/simplecache

## Overview

##### Project Type and Purpose
- This is an FPGA-based hardware simulation project, written in Verilog, that implements and demonstrates a simple direct-mapped cache co-working with a RAM module.
- The goal is to simulate cache hits and misses: reads go through the cache (on miss it fetches from RAM), writes go to RAM (and update cache line if it’s present).

##### File Structure Analysis
- Top-level directory
- Completed/            ← Quartus project files (.mpf) and Verilog sources & testbenches
– cache.v
– ram.v
– cache_and_ram.v
– testbench.v, testbench2.v
– cache.v, cache_and_ram.v, ram.v under work/ for synthesis database
- LICENSE
- README.md
- Key observation: a single top-level module (cache_and_ram) instantiates two submodules (cache, ram) and is driven by testbench(es).

##### README Insights
- Three main modules:
- ram.v – 4096-word 32-bit RAM
- cache.v – 64-line direct-mapped cache with valid bits and tag storage
- cache_and_ram.v – glue logic: on read/write inputs, splits 32-bit address into tag & index, does hit/miss logic, updates cache or RAM
- Clocked always block triggers read or write on mode signal, outputs 32-bit data.

a. Main Components
- Testbench/CPU Interface (stimulus generator)
- cache_and_ram (Top-level)
- ↳ Cache submodule
- ↳ RAM submodule
b. Relationships and Data Flows
- Address bus (32-bit) and Data bus (32-bit) and control line (“mode”: read=0/write=1) flow from Testbench into cache_and_ram.
- cache_and_ram splits the address into index and tag:
– index → selects one of 64 cache lines
– tag  → compared against tag_array at that index
- On read: if valid & tag match → return cache.data[index] → out; else → read ram.data[address], update cache.data[index] & tag_array[index], set valid_array[index], then out.
- On write: always write ram.data[address] = data; if cache line matches index+tag → overwrite cache.data[index].
c. Architectural Patterns & Principles
- Hierarchical design: top-level module instantiates lower-level modules
- Single-port synchronous memories (cache, ram) as reg arrays
- Direct-mapped cache: fixed one-to-one mapping of memory blocks to cache lines
d. Technologies & Frameworks
- Verilog HDL modules, simulated in Quartus (project .mpf files)
- Testbench harness generates clock and stimuli

##### Details to Capture
- Hierarchical instantiation relationships
- Data width and bus labels
- Hit/miss logic flow (include small conditional symbol)
- Update rules for valid_array and tag_array
- Clock domain (all synchronous to clk)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Testbenches
    TB1["Testbench/CPU Interface"]:::external
    TB2["Secondary Testbench/Stimulus Generator"]:::external

    %% Top-Level Module
    subgraph "Top-Level Module" 
        CAR["cache_and_ram [top-level glue logic]"]:::logic
        subgraph "Internal Modules"
            Cache["cache [64×32 bits] + tag[6 bits] + valid[1 bit] arrays"]:::memory
            RAM["ram [4096×32-bit memory]"]:::memory
        end
        HitCheck{"Hit?"}:::decision
    end

    %% Documentation and Project Files
    subgraph "Project Files" 
        MPF["Quartus Project File"]:::doc
        README["Project Documentation"]:::doc
        LICENSENODE["License File"]:::doc
    end

    %% Connections - Stimulus to Top-Level
    TB1 -- "address[31:0], data_in[31:0], mode, clk" --> CAR
    TB2 -- "address[31:0], data_in[31:0], mode, clk" --> CAR

    %% Data Flow and Hit/Miss Logic
    CAR --> HitCheck
    HitCheck -- "yes (valid & tag match)" --> Cache
    HitCheck -- "no (miss)" --> RAM
    RAM -- "data_out → update cache" --> Cache
    Cache -- "data_out → CAR" --> CAR

    %% Write Operation Path
    CAR -- "write → ram.data[address]=data" --> RAM
    HitCheck -- "yes on write → update cache.data[index]" --> Cache

    %% Output to Testbench
    CAR -- "data_out[31:0]" --> TB1
    CAR -- "data_out[31:0]" --> TB2

    %% Documentation Links
    MPF
    README
    LICENSENODE

    %% Click Events
    click TB1 "https://github.com/psnjk/simplecache/blob/master/Completed/testbench.v"
    click TB2 "https://github.com/psnjk/simplecache/blob/master/Completed/testbench2.v"
    click CAR "https://github.com/psnjk/simplecache/blob/master/Completed/cache_and_ram.v"
    click Cache "https://github.com/psnjk/simplecache/blob/master/Completed/cache.v"
    click RAM "https://github.com/psnjk/simplecache/blob/master/Completed/ram.v"
    click MPF "https://github.com/psnjk/simplecache/blob/master/Completed/Completed parts.mpf"
    click README "https://github.com/psnjk/simplecache/blob/master/README.md"
    click LICENSENODE "https://github.com/psnjk/simplecache/tree/master/LICENSE"

    %% Styles
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#333,stroke-width:1px
    classDef memory fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef decision fill:#FFFFFF,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
    classDef doc fill:#D3D3D3,stroke:#333,stroke-width:1px

    class HitCheck decision
```
