v1.4.3

v1.4.3

Fixed

• Cache Associativity Bug (Critical)

  • findVictim() now prefers empty (invalid) blocks before consulting the replacement policy
  • Previously the cache used only 1 way per set regardless of associativity, causing hit ratio to decrease with increasing associativity
  • getTagAndSet() now uses standard tag decomposition (tag = blockNumber / numSets) instead of storing the full block number as the tag, fixing incorrect writeback addresses

• PLRU Replacement Policy

  • Replaced floating-point std::log2() with integer bit-scan loop to prevent silent truncation (e.g. log2(8) returning 2.999 → 2)
  • Added power-of-2 assertion in constructor since the tree structure requires it
  • Added missing #include <cassert>

• Victim Cache getAllValidAddresses()

  • Replaced std::transform + std::remove(0) with a simple validity-checked loop
  • Previously, a legitimate cache block at address 0 would be silently dropped

• Victim Cache invalidateBlocksInRange()

  • Changed from std::remove_if + erase (which physically removes elements) to in-place invalidation
  • The old approach corrupted fifoQueue and addressToIndex indices, causing incorrect evictions or crashes on subsequent operations

Changed

• Dead Code Removal: Removed unused lruOrder, fifoOrder, and nextFifoIndex fields from CacheSet in cache_block.h and their initialization in cache.cpp — all replacement logic uses ReplacementPolicyBase instances
• Namespace Cleanup: Moved VictimBlock and VictimCache into namespace cachesim; removed dead CacheSimulator demo class from victim_cache.h
• Code Simplification: Removed stale "FIXED"/"SOLUTION" comments from victim_cache.h per code-simplifier guidelines
• Version updated to v1.4.3 in CLI, CMakeLists.txt, CITATION.cff, and documentation

Added

• Associativity Test: New tests/unit/core/associativity_test.cpp verifying that hit ratio is monotonically non-decreasing as associativity increases
• Cache Analysis Tool: New tools/cache_analysis.cpp to visualize hit rate vs associativity and verify fix effectiveness

Documentation

• Updated README.md "What's New" section for v1.4.3
• Updated docs/developer/architecture.md — corrected CacheSet description and refreshed Future Extensions
• Updated docs/features/replacement-policies.md — added PLRU power-of-2 requirement note
• Updated docs/features/victim-cache.md — code examples now reflect cachesim namespace

Technical Details

• All coherence protocols (MSI, MESI, MOESI) were audited and verified correct
• All 20 tests pass (unit, integration, performance)

v1.4.2

v1.4.2 - Fix MESI Statistics and Multiprocessor Enhancements

This release fixes a critical bug in MESI statistics reporting and adds enhanced
multiprocessor simulation support.

Fixed

• MESI statistics always showing zero in multiprocessor simulations (Issue #16)

Added

• Multiprocessor trace format support (PX r/w 0xADDR)
• Trace generator --processors option for multiprocessor output
• MESI statistics unit test

Changed

• Code quality improvements in config_utils.cpp
• Updated version references across codebase

Full Changelog: v1.4.1...v1.4.2

v1.4.1

What's New

License Change

This release changes the project license from MIT to Apache License 2.0, providing better protection and clearer contribution terms.

Citation Support

Added CITATION.cff file for proper academic citation. GitHub now shows a "Cite this repository" button with APA and BibTeX formats.

Config Parsing Improvements

• snake_case Support: Config keys like block_size are now automatically converted to blockSize
• Helpful Error Messages: Unrecognized keys now suggest similar valid keys
• Schema Validation: Added recognized key validation with warnings

Side-Channel Attack Research

New documentation for security researchers:

• Flush+Reload attack simulation
• Prime+Probe attack modeling
• Spectre-like pattern analysis
• Recommended configurations for security research

User-Defined Profiler Regions

New ProfilerRegionConfig allows defining custom memory address ranges for targeted profiling.

Compatibility

Fully backward compatible with existing configuration files and trace formats.

Installation

git clone https://github.com/muditbhargava66/CacheSimulator.git
cd CacheSimulator
mkdir build && cd build
cmake ..
cmake --build . --parallel

Requirements

• C++20 compatible compiler (GCC 10+, Clang 10+, MSVC 2019+)
• CMake 3.14+

Full Changelog

See CHANGELOG.md for complete details.

v1.4.0

Cache Simulator v1.4.0

Release Date: 2026-01-08

Highlights

This release introduces L3 cache support, extended coherence protocols (MSI/MOESI), new interconnect topologies (Ring/Torus), and significant code quality improvements through modularization.

New Features

L3 Cache Support

• Optional third cache level in MemoryHierarchy with inclusive policy
• Configurable via JSON configuration with l3 section
• Full statistics support: getL3Misses(), getL3HitRate(), getL3MissRate()
• Proper inclusive cache behavior for multi-core coherence

Extended Coherence Protocols

• MSI Protocol: 3-state coherence (Modified, Shared, Invalid)
• MOESI Protocol: 5-state coherence (Modified, Owned, Exclusive, Shared, Invalid)
• Abstract CoherenceProtocolBase interface with factory pattern
• MOESI Owned state enables dirty sharing without memory writeback
• State transition tracking and comprehensive statistics

New Interconnect Topologies

• Ring Interconnect: Bidirectional ring with shortest path routing
  • Latency: min(clockwise, counterclockwise) * hopLatency
• Torus Interconnect: 2D torus with wrap-around connections
  • Latency: (wrapDx + wrapDy) * hopLatency
• Full implementation of InterconnectInterface

Modular Code Organization

• CLI Parser Module: Extracted command-line parsing to utils/cli_parser.h/cpp
• Cache Visualization Module: Extracted cache state visualization to utils/cache_visualization.h/cpp
• Refactored main.cpp from 822 to 442 lines (-46%)

Multiprocessor Configuration

• Added coherenceProtocol selection: MSI, MESI, MOESI
• Added interconnectType selection: Bus, Crossbar, Mesh, Ring, Torus
• Configuration via MultiProcessorSystem::Config struct

Documentation

• Added docs/features/l3-cache.md
• Added docs/features/coherence-protocols.md
• Added docs/features/interconnects.md
• Updated docs/README.md with new feature links
• Updated user/configuration.md with L3 and protocol options

Testing

• 4 new unit test files added
• All 18 tests passing (100%)
• Test coverage for:
  • MSI/MOESI protocol state transitions
  • L3 cache access patterns
  • Ring/Torus interconnect routing
  • CLI parsing functionality

Installation

git clone https://github.com/muditbhargava66/CacheSimulator.git
cd CacheSimulator
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

Requirements

• C++20 compatible compiler (GCC 10+, Clang 10+, MSVC 2019+)
• CMake 3.14+

Full Changelog

See CHANGELOG.md for complete details.

v1.3.0

What's New

Power and Area Modeling

• CACTI-inspired PowerModel and AreaModel classes
• Dynamic energy calculation (read/write per access)
• Static leakage power with temperature scaling
• Technology node support: 7nm, 14nm, 22nm, 32nm, 45nm
• Energy-Delay Product (EDP) metric

CLI Integration

• --power flag to enable power and energy analysis
• --tech-node <nm> flag to specify technology node

Documentation Restructure

• Redesigned docs folder with 16 organized files
• New: analysis.md, building.md, api-reference.md, prefetching.md, power-modeling.md
• Removed version-specific feature files
• Updated architecture.md for C++20

Bug Fixes

• ASCII visualization for Windows console compatibility
• Consistent table alignment

Testing

• 14/14 tests passing
• New unit tests for PowerModel and AreaModel

See CHANGELOG.md for complete details.

v1.2.2

Cache Simulator v1.2.2 Release Notes

Release Date: January 6, 2026
Type: Feature & Bugfix Release
PR: #4

Windows Platform Support

This release adds full Windows support with native PowerShell build scripts:

Script	Purpose
build.ps1	Quick build for Windows
scripts/build_all.ps1	Full build with -Debug, -Clean, -NoTests options
scripts/run_benchmarks.ps1	Benchmark runner with CSV output

See docs/WINDOWS.md for comprehensive Windows documentation.

Bug Fixes

Replacement Policy Parsing (Community Report)

• Issue: JSON/INI config files only recognized LRU and NRU policies
• Fix: Added support for FIFO, Random, and PLRU policies

Trace Parser Inline Comments

• Issue: Lines like r 0x1000 # comment caused errors
• Fix: Parser now strips inline comments before processing

Cross-Platform Fixes

• Added missing standard library headers
• Fixed Windows file locking in tests

Breaking Change

C++ Standard: C++17 → C++20 (GCC 10+, Clang 10+, MSVC 2019+)

Verification

• All 13 tests pass on Windows, macOS, and Linux

---

Full Changelog: v1.2.1...v1.2.2

v1.2.1

Cache Simulator v1.2.1 Release Notes

Release Date: September 2, 2025
Type: Bugfix Release
GitHub Issue: #3

🐛 Bug Fixes

Critical Fix: Multiprocessor Configuration Support

Issue: Division by zero error when running multiprocessor configurations

• Command that was failing: ./build/bin/cachesim --config configs/multiprocessor_4core.json traces/multiprocessor_coherence.txt
• Error: numSets = size / (associativity * blockSize); resulted in division by zero at line 34 in cache.cpp

Root Cause Analysis

The issue had two main components:

1. JSON Parser Limitation: The configuration parser couldn't handle nested JSON objects like perCoreL1 and sharedL2
2. Trace Format Incompatibility: The trace parser expected 2-token format but multiprocessor traces use 3-token format with processor ID

Solutions Implemented

1. Enhanced JSON Configuration Parser (src/utils/config_utils.cpp)

• Added support for nested JSON objects in configuration files
• Handles both perCoreL1/sharedL2 and l1/l2 section formats
• Properly parses cache configuration parameters from nested structures
• Added comprehensive validation to prevent division by zero errors
• Maintains backward compatibility with existing configuration formats

2. Updated Trace Parser (src/utils/trace_parser.cpp)

• Modified parseLine() to handle both 2-token and 3-token trace formats
• Automatically detects multiprocessor format with processor ID prefix
• Maintains full backward compatibility with existing trace formats
• Supports format: <processor_id> <r/w> <address> and <r/w> <address>

Testing Results

Before Fix

$ ./build/bin/cachesim --config configs/multiprocessor_4core.json traces/multiprocessor_coherence.txt
libc++abi: terminating due to uncaught exception of type cachesim::CacheConfigError: 
Cache configuration error: Invalid configuration: number of sets must be positive
zsh: abort

After Fix

$ ./build/bin/cachesim --config configs/multiprocessor_4core.json traces/multiprocessor_coherence.txt
[INFO] Starting cache simulation
[INFO] Processing trace file...
[INFO] Finished processing 80 memory accesses in 0 ms

Cache Simulation Results
=======================
Total Memory Accesses: 80
L1 Hit Ratio: 52.50%
L2 Hit Ratio: 41.76%
✅ SUCCESS: Simulation completed successfully

Technical Details

Files Modified

• src/utils/config_utils.cpp - Enhanced JSON parsing for nested objects
• src/utils/trace_parser.cpp - Added multiprocessor trace format support

Configuration Formats Supported

• Standard format: {"l1": {...}, "l2": {...}}
• Multiprocessor format: {"perCoreL1": {...}, "sharedL2": {...}}
• Legacy flat format: {"l1_size": 32768, "l1_assoc": 4, ...}

Trace Formats Supported

• Standard format: r 0x10000 or w 0x20000
• Multiprocessor format: 0 r 0x10000 or 1 w 0x20000
• JSON format: {"type": "r", "address": "0x10000"}

Compatibility

Backward Compatibility

• All existing configuration files continue to work
• All existing trace files continue to work
• No breaking changes to API or command-line interface
• All existing functionality preserved

Tested Configurations

• configs/multiprocessor_4core.json - Original failing configuration
• configs/high_performance.json - Alternative nested format
• configs/full_features.json - Complex configuration
• All legacy configuration files

Performance Impact

• Parsing Performance: No significant impact on parsing performance
• Memory Usage: Minimal additional memory usage for enhanced parsing
• Simulation Speed: No impact on simulation execution speed
• Startup Time: Negligible increase in configuration loading time

Migration Guide

For Users

No migration required - this is a pure bugfix release that maintains full backward compatibility.

For Developers

If you were working around the multiprocessor configuration issue:

1. Remove any workarounds for nested JSON parsing
2. Update to use the standard multiprocessor configuration format
3. Multiprocessor trace files with processor IDs are now fully supported

Verification

To verify the fix is working:

# Test the original failing command
./build/bin/cachesim --config configs/multiprocessor_4core.json traces/multiprocessor_coherence.txt

# Test with other configurations
./build/bin/cachesim --config configs/high_performance.json traces/multiprocessor_coherence.txt
./build/bin/cachesim --config configs/full_features.json traces/multiprocessor_coherence.txt

All commands should complete successfully without division by zero errors.

Acknowledgments

• Issue Reporter: @SSFG1992 for reporting the detailed issue
• Testing: Comprehensive testing across multiple configuration formats

---

Full Changelog: v1.2.0...v1.2.1

v.1.2.0

Cache Simulator v1.2.0 - Production Release

🎉 Major Release Highlights

This is a major production release of the Cache Simulator with comprehensive feature implementation, extensive testing, and professional documentation.

✨ New Features

Advanced Cache Features

• NRU (Not Recently Used) Replacement Policy - Complete implementation with reference bit tracking
• Victim Cache - Fully associative cache for storing evicted blocks, reducing conflict misses by up to 25%
• No-Write-Allocate Policy - Support for both write-through and write-back variants
• Write Combining Buffer - Coalescing writes to improve memory bandwidth utilization by 40%

Parallel Processing & Multi-core

• Parallel Processing Framework - Thread pool and parallel trace processor with up to 4x speedup
• Multi-processor Simulation - Complete multi-core processor simulation with cache coherence
• MESI Protocol - Directory-based coherence controller implementing Modified-Exclusive-Shared-Invalid
• Multiple Interconnects - Bus, Crossbar, and Mesh topologies for different system architectures

Visualization & Analysis

• Statistical Charting - ASCII line charts, pie charts, and scatter plots for data visualization
• Enhanced Analysis Tools - Performance comparison and optimization recommendations
• Comprehensive Benchmarking - Parallel benchmarking with detailed metrics and CSV export

🧪 Testing Excellence

• 100% Test Pass Rate - All 13 tests passing (unit, integration, and performance)
• Comprehensive Coverage - Unit tests for core components, policies, and utilities
• Fixed Critical Issues - Resolved segmentation faults and hanging tests from previous versions
• Performance Validation - Extensive benchmarking of all features with validated metrics

Test Categories

• Unit Tests (8 tests): Core components, policies, and utilities
• Integration Tests (2 tests): End-to-end workflow validation
• Performance Tests (3 tests): Benchmarking and performance validation

📚 Documentation

• Complete User Guides - Step-by-step tutorials and getting started guide
• Developer Documentation - API reference and architecture documentation
• Feature Documentation - Detailed explanations of all v1.2.0 features
• Project Structure - Clear organization and maintenance guides

🛠️ Enhanced Tooling

Build & Development

• Advanced Build Script - Multiple configuration options (Debug/Release, with/without tests)
• Cross-platform Support - macOS and Linux compatibility with proper CMake integration

Benchmarking & Analysis

• Comprehensive Benchmark Runner - Automated testing with multiple configurations
• Simulation Runner - Colorized output with CSV export and chart generation
• Performance Comparison Tool - Parallel benchmarking across different configurations

Trace Management

• Advanced Trace Generator - Multiple access patterns (sequential, strided, random, looping, mixed)
• Trace Validation Tool - Format validation with error detection and automatic fixing
• Comprehensive Trace Library - Pre-built traces for various testing scenarios

Release Management

• Automated Release Creation - Cross-platform package generation script
• Version Management - Clean, maintainable versioning system without version-specific naming

⚡ Performance Metrics

Component	Performance	Improvement
Cache Operations	16-40M accesses/sec	Baseline performance
Victim Cache	21-48M operations/sec	25% conflict miss reduction
Multi-processor	13M+ messages/sec	Scalable to 64 cores
Trace Processing	1.5M+ accesses/sec	4x speedup with parallel processing

🔧 Project Structure

• Clean Organization - Logical directory structure with clear separation of concerns
• Version-agnostic Naming - Future-proof file and directory names for easy maintenance
• Standardized Conventions - Consistent naming and organization throughout the project
• Maintainable Codebase - Professional C++17 implementation with comprehensive error handling

📦 Installation

Quick Start

# Clone the repository
git clone https://github.com/yourusername/CacheSimulator.git
cd CacheSimulator

# Build the project
./scripts/build_all.sh

# Run a basic simulation
./build/bin/cachesim traces/trace1.txt

# Run comprehensive benchmarks
./scripts/run_benchmarks.sh

🚀 What's Next

• Enhanced visualization capabilities
• Additional replacement policies
• GPU acceleration support
• Web-based interface for results analysis

v.1.1.0

Cache Simulator v1.1.0 - Enhanced Features Release

🚀 Release Highlights

This release introduces several key enhancements to the cache simulator with improved performance and new features.

✨ New Features

• Enhanced Cache Policies: Improved LRU and FIFO implementations
• Better Configuration Support: More flexible configuration options
• Improved Statistics: Enhanced performance metrics and reporting
• Code Quality: Refactored codebase for better maintainability

🐛 Bug Fixes

• Fixed memory management issues
• Improved error handling
• Resolved compilation warnings

📈 Performance Improvements

• Optimized cache access patterns
• Reduced memory overhead
• Faster trace processing

🔧 Technical Changes

• Updated build system
• Improved code organization
• Enhanced documentation

📦 Installation

git clone https://github.com/yourusername/CacheSimulator.git
cd CacheSimulator
git checkout v1.1.0
mkdir build && cd build
cmake ..
make -j$(nproc)

This release builds upon v1.0.0 with significant improvements in performance and code quality.

v1.0.0

Cache Simulator v1.0.0

We're excited to announce the first official release of our Cache Simulator!

This release includes:

• Complete cache hierarchy simulation with L1 and L2 caches
• Advanced prefetching algorithms including:
  • Stream buffer prefetching
  • Stride-based prefetching
  • Adaptive prefetching with dynamic strategy adjustment
• Full MESI coherence protocol implementation
• Comprehensive statistics tracking
• Modular architecture with proper C++ design patterns
• Extensive unit tests and validation
• CMake build system

The simulator provides detailed insights into cache behavior and can be configured with various parameters to model different cache architectures.

See the CHANGELOG.md for complete details of what's included in this release.