cache_sim.cpp

/*
 * cache_sim.cpp — CS204 Cache Simulator (Phase 2)
 * IIT Ropar | 2025-26
 *
 * Build:
 *   g++ -O2 -std=c++17 -o cache_sim cache_sim.cpp
 *
 * Usage:
 *   ./cache_sim --trace <file>
 *               --size  <KB>
 *               --sets  <N>        (power of 2)
 *               --assoc <N>
 *               --line  <bytes>    (power of 2)
 *               --policy <name>    LRU | FIFO | LFU | RANDOM | OPT
 *               [--csv  <file>]    append results
 *
 * Constraint: size_kb == (sets * assoc * line) / 1024
 *
 * OPT note: policy OPT reads the trace TWICE — once to build
 *           the future-use table, once to simulate.
 *           It is the theoretical upper bound on hit rate.
 */

#include "cache.h"

#include <iostream>
#include <fstream>
#include <sstream>
#include <string>
#include <stdexcept>

// ─────────────────────────────────────────────
//  CLI
// ─────────────────────────────────────────────
struct Config {
    std::string trace_path;
    uint64_t    size_kb       = 0;
    uint64_t    sets          = 0;
    int         assoc         = 0;
    int         line          = 0;
    std::string policy        = "LRU";
    std::string csv_path;
    std::string heatmap_path;            // --heatmap <file.csv>
    bool        show_heatmap  = false;   // --show-heatmap
};

static void print_usage(const char* prog) {
    std::cout
        << "Usage: " << prog << " [OPTIONS]\n\n"
        << "Required:\n"
        << "  --trace  <file>    Memory trace file\n"
        << "  --size   <KB>      Total cache size in KB\n"
        << "  --sets   <N>       Number of sets (power of 2)\n"
        << "  --assoc  <N>       Associativity / ways\n"
        << "  --line   <bytes>   Line size in bytes (power of 2)\n\n"
        << "Optional:\n"
        << "  --policy <name>    LRU | FIFO | LFU | RANDOM | OPT  (default: LRU)\n"
        << "  --csv         <file>   Append results row to CSV\n"
        << "  --heatmap     <file>   Write per-set eviction CSV (for Python plot)\n"
        << "  --show-heatmap         Print ASCII heatmap to terminal\n\n"
        << "Policy descriptions:\n"
        << "  LRU    — evict least recently accessed line\n"
        << "  FIFO   — evict oldest inserted line\n"
        << "  LFU    — evict least frequently accessed line\n"
        << "  RANDOM — evict a random line (seed=42)\n"
        << "  OPT    — evict line used furthest in the future (theoretical best)\n\n"
        << "Constraint: sets * assoc * line / 1024 must equal size_kb\n\n"
        << "Examples:\n"
        << "  ./cache_sim --trace mem.trace --size 32 --sets 128 --assoc 4 --line 64 --policy LRU\n"
        << "  ./cache_sim --trace mem.trace --size 32 --sets 128 --assoc 4 --line 64 --policy OPT\n"
        << "  ./cache_sim --trace mem.trace --size 32 --sets 128 --assoc 4 --line 64 --policy RANDOM\n";
}

static Config parse_args(int argc, char* argv[]) {
    Config cfg;
    for (int i = 1; i < argc; ++i) {
        std::string a = argv[i];
        auto nxt = [&]() -> std::string {
            if (i + 1 >= argc)
                throw std::runtime_error("Missing value for " + a);
            return argv[++i];
        };
        if      (a == "--trace")  cfg.trace_path = nxt();
        else if (a == "--size")   cfg.size_kb    = std::stoull(nxt());
        else if (a == "--sets")   cfg.sets        = std::stoull(nxt());
        else if (a == "--assoc")  cfg.assoc       = std::stoi(nxt());
        else if (a == "--line")   cfg.line        = std::stoi(nxt());
        else if (a == "--policy") cfg.policy      = nxt();
        else if (a == "--csv")          cfg.csv_path      = nxt();
        else if (a == "--heatmap")      cfg.heatmap_path  = nxt();
        else if (a == "--show-heatmap") cfg.show_heatmap  = true;
        else if (a == "--help")         { print_usage(argv[0]); std::exit(0); }
        else throw std::runtime_error("Unknown argument: " + a + " (--help for usage)");
    }
    if (cfg.trace_path.empty()) throw std::runtime_error("--trace is required");
    if (cfg.size_kb == 0)       throw std::runtime_error("--size is required");
    if (cfg.sets    == 0)       throw std::runtime_error("--sets is required");
    if (cfg.assoc   == 0)       throw std::runtime_error("--assoc is required");
    if (cfg.line    == 0)       throw std::runtime_error("--line is required");
    return cfg;
}

// ─────────────────────────────────────────────
//  Trace reader
// ─────────────────────────────────────────────
static void run_trace(Cache& cache, const std::string& path) {
    std::ifstream f(path);
    if (!f.is_open())
        throw std::runtime_error("Cannot open trace: " + path);

    std::string line;
    uint64_t line_no = 0, skipped = 0;

    while (std::getline(f, line)) {
        ++line_no;
        if (line.empty() || line[0] == '#') { ++skipped; continue; }
        std::istringstream ss(line);
        char ch; uint64_t addr;
        if (!(ss >> ch >> std::hex >> addr)) {
            std::cerr << "  Warning: bad line " << line_no << "\n";
            ++skipped; continue;
        }
        cache.access(addr, ch);
    }

    std::cerr << "Trace lines : " << line_no
              << "  Skipped: " << skipped << "\n";
}

// ─────────────────────────────────────────────
//  Address layout banner
// ─────────────────────────────────────────────
static void print_layout(const Cache& c) {
    std::cout
        << "\nAddress decomposition (64-bit):\n"
        << "  [ TAG: bits 63.."  << (c.offset_bits()+c.index_bits())
        << " (" << c.tag_bits()  << " bits)"
        << " | INDEX: bits "     << (c.offset_bits()+c.index_bits()-1)
        << ".."                  << c.offset_bits()
        << " (" << c.index_bits()<< " bits)"
        << " | OFFSET: bits "    << (c.offset_bits()-1)
        << "..0 ("               << c.offset_bits() << " bits) ]\n\n";
}

// ─────────────────────────────────────────────
//  main
// ─────────────────────────────────────────────
int main(int argc, char* argv[]) {
    try {
        Config cfg = parse_args(argc, argv);

        std::cerr << "\n── CS204 Cache Simulator ─────────────────────────\n"
                  << "   Policy : " << cfg.policy << "\n"
                  << "   Trace  : " << cfg.trace_path << "\n\n";

        Cache cache(cfg.size_kb, cfg.sets, cfg.assoc, cfg.line, cfg.policy);
        print_layout(cache);

        // OPT needs a pre-scan of the trace to build future-use tables
        if (cfg.policy == "OPT" || cfg.policy == "opt") {
            std::cerr << "Running OPT pre-scan...\n";
            cache.opt_prescan(cfg.trace_path);
        }

        std::cerr << "Simulating...\n";
        run_trace(cache, cfg.trace_path);

        cache.print_stats();

        if (!cfg.csv_path.empty())
            cache.export_csv(cfg.csv_path);

        if (cfg.show_heatmap)
            cache.print_heatmap();

        if (!cfg.heatmap_path.empty())
            cache.export_heatmap_csv(cfg.heatmap_path);

    } catch (const std::exception& e) {
        std::cerr << "\nError: " << e.what() << "\n";
        return 1;
    }
    return 0;
}