# sha1v1/cache-simulator architecture

> Architecture diagram of the GitHub repository sha1v1/cache-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sha1v1/cache-simulator
- Repository: https://github.com/sha1v1/cache-simulator

## Overview

#### Purpose and Runtime
A C command-line cache simulator models reads and writes between a configurable cache and main memory. The executable is built via `Makefile` and run as `./build/cache_sim`; interactive control begins in `src/main.c`.

#### Startup and Configuration
`src/main.c` initializes simulator state, loads settings, and presents the read/write/display/exit menu. Configuration parsing is separated into `src/config.c`, with public configuration types and APIs in `include/config.h`. The repository-provided runtime configuration is `config.txt`.

#### Main Memory Boundary
Main memory is an in-process byte-addressable backing store, not an external service or persistent datastore. `src/memory.c` implements allocation and address-level read/write behavior exposed through `include/memory.h`. Cache misses fetch blocks from this layer; write-through operations propagate updates to it.

#### Cache Core
`src/cache.c` implements cache organization and operations defined by `include/cache.h`: mapping an address to a set/tag/block location, probing valid lines, loading blocks on misses, updating cached data, and rendering cache state. Its state is governed by configured set count, lines per set, and memory/block relationships.

#### Read Flow
A menu read request enters `src/main.c`, then the cache API in `src/cache.c`. The cache derives the target set and tag, returns data on a hit, or selects a line and fetches the relevant block from `src/memory.c` on a miss. The loaded block becomes a valid cache line before the requested byte is returned.

#### Write Flow and Policies
Write requests follow the same cache lookup path in `src/cache.c`. On hits, cached data is updated; under the documented `WRITE_THROUGH` policy, the corresponding main-memory address is also updated through `src/memory.c`. Miss handling and eviction are controlled by the configured replacement policy (`LRU` or `RANDOM`) from `src/config.c`/`config.txt`.

#### Replacement and Observability
Replacement policy is an architectural decision within cache-line selection in `src/cache.c`; it determines which conflicting line is overwritten when a set has no free line. The same module provides cache-state display used by the CLI, exposing valid bits, tags, sets, lines, and block contents for simulation inspection.

#### Verification Boundary
The project uses the embedded Unity C test runtime under `src/unity/`. Cache and memory behavior are independently exercised by `tests/test_cache.c` and `tests/test_memory.c`; these validate the core simulation layers beneath the interactive entry point.

Main entry points: [`src/cache.c`](https://github.com/sha1v1/cache-simulator/blob/main/src/cache.c) (Cache core), [`src/config.c`](https://github.com/sha1v1/cache-simulator/blob/main/src/config.c) (Configuration parser), [`src/main.c`](https://github.com/sha1v1/cache-simulator/blob/main/src/main.c) (Interactive CLI), [`src/memory.c`](https://github.com/sha1v1/cache-simulator/blob/main/src/memory.c) (Main memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulator Runtime"]
  node_makefile["Build<br/>Makefile"]
  node_cli["Interactive CLI<br/>C entry point<br/>[main.c]"]
  node_executable{{"cache_sim<br/>CLI executable"}}
  node_config_file["Runtime settings<br/>configuration<br/>[config.txt]"]
end

subgraph group_core["Simulation Core"]
  node_config_impl["Configuration parser<br/>C module<br/>[config.c]"]
  node_config_api["Configuration API<br/>C header<br/>[config.h]"]
  node_cache["Cache core<br/>C module<br/>[cache.c]"]
  node_cache_api["Cache API<br/>C header<br/>[cache.h]"]
  node_replacement(("Line selection<br/>cache policy<br/>[cache.c]"))
  node_memory[("Main memory<br/>in-process byte store<br/>[memory.c]")]
  node_memory_api["Memory API<br/>C header<br/>[memory.h]"]
end

subgraph group_verification["Verification"]
  node_unity["Unity runtime<br/>embedded C test framework"]
  node_cache_tests["Cache tests<br/>C tests<br/>[test_cache.c]"]
  node_memory_tests["Memory tests<br/>C tests<br/>[test_memory.c]"]
end

node_makefile -->|"builds"| node_executable
node_executable -->|"starts"| node_cli
node_cli -->|"loads settings"| node_config_impl
node_config_file -->|"parsed by"| node_config_impl
node_config_impl -->|"implements"| node_config_api
node_cli -->|"read / write / display"| node_cache
node_cache -->|"implements"| node_cache_api
node_cache -->|"uses on eviction"| node_replacement
node_config_impl -.->|"configures policy"| node_replacement
node_config_impl -.->|"configures geometry"| node_cache
node_cache -->|"miss block fill; write-through"| node_memory
node_memory -->|"implements"| node_memory_api
node_cache_tests -->|"exercises"| node_cache
node_memory_tests -->|"exercises"| node_memory
node_cache_tests -->|"runs with"| node_unity
node_memory_tests -->|"runs with"| node_unity

click node_makefile "https://github.com/sha1v1/cache-simulator/blob/main/Makefile"
click node_cli "https://github.com/sha1v1/cache-simulator/blob/main/src/main.c"
click node_config_file "https://github.com/sha1v1/cache-simulator/blob/main/config.txt"
click node_config_impl "https://github.com/sha1v1/cache-simulator/blob/main/src/config.c"
click node_config_api "https://github.com/sha1v1/cache-simulator/blob/main/include/config.h"
click node_cache "https://github.com/sha1v1/cache-simulator/blob/main/src/cache.c"
click node_cache_api "https://github.com/sha1v1/cache-simulator/blob/main/include/cache.h"
click node_replacement "https://github.com/sha1v1/cache-simulator/blob/main/src/cache.c"
click node_memory "https://github.com/sha1v1/cache-simulator/blob/main/src/memory.c"
click node_memory_api "https://github.com/sha1v1/cache-simulator/blob/main/include/memory.h"
click node_cache_tests "https://github.com/sha1v1/cache-simulator/blob/main/tests/test_cache.c"
click node_memory_tests "https://github.com/sha1v1/cache-simulator/blob/main/tests/test_memory.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_makefile,node_cli,node_executable,node_config_file toneBlue
class node_config_impl,node_config_api,node_cache,node_cache_api,node_replacement,node_memory,node_memory_api toneAmber
class node_unity,node_cache_tests,node_memory_tests toneMint
```

## Components

### Simulator Runtime

- [Build](https://github.com/sha1v1/cache-simulator/blob/main/Makefile): Makefile · Builds the simulator executable. · `Makefile`
- [Interactive CLI](https://github.com/sha1v1/cache-simulator/blob/main/src/main.c): C entry point · Initializes state and handles the read/write/display menu. · `src/main.c`
- **cache_sim**: CLI executable
- [Runtime settings](https://github.com/sha1v1/cache-simulator/blob/main/config.txt): configuration · `config.txt`

### Simulation Core

- [Configuration parser](https://github.com/sha1v1/cache-simulator/blob/main/src/config.c): C module · `src/config.c`
- [Configuration API](https://github.com/sha1v1/cache-simulator/blob/main/include/config.h): C header · `include/config.h`
- [Cache core](https://github.com/sha1v1/cache-simulator/blob/main/src/cache.c): C module · Maps addresses, probes lines, loads blocks, updates data, and renders state. · `src/cache.c`
- [Cache API](https://github.com/sha1v1/cache-simulator/blob/main/include/cache.h): C header · `include/cache.h`
- [Line selection](https://github.com/sha1v1/cache-simulator/blob/main/src/cache.c): cache policy · LRU or RANDOM selects an eviction target when a set is full. · `src/cache.c`
- [Main memory](https://github.com/sha1v1/cache-simulator/blob/main/src/memory.c): in-process byte store · Backing store for block fills and write-through updates. · `src/memory.c`
- [Memory API](https://github.com/sha1v1/cache-simulator/blob/main/include/memory.h): C header · `include/memory.h`

### Verification

- **Unity runtime**: embedded C test framework
- [Cache tests](https://github.com/sha1v1/cache-simulator/blob/main/tests/test_cache.c): C tests · `tests/test_cache.c`
- [Memory tests](https://github.com/sha1v1/cache-simulator/blob/main/tests/test_memory.c): C tests · `tests/test_memory.c`

## Connections

- Build → cache_sim: builds
- cache_sim → Interactive CLI: starts
- Interactive CLI → Configuration parser: loads settings
- Runtime settings → Configuration parser: parsed by
- Configuration parser → Configuration API: implements
- Interactive CLI → Cache core: read / write / display
- Cache core → Cache API: implements
- Cache core → Line selection: uses on eviction
- Configuration parser → Line selection: configures policy
- Configuration parser → Cache core: configures geometry
- Cache core → Main memory: miss block fill; write-through
- Main memory → Memory API: implements
- Cache tests → Cache core: exercises
- Memory tests → Main memory: exercises
- Cache tests → Unity runtime: runs with
- Memory tests → Unity runtime: runs with