sha1v1/cache-simulator

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.