Merge pull request #6 from muditbhargava66/release/v1.4.0

Release v1.4.0: L3 Cache, MSI/MOESI Protocols, Ring/Torus Interconnects

Author: muditbhargava66

CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to the Cache Simulator project will be documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-01-08
+
+### Added
+- **L3 Cache Support**
+  - Optional third cache level in `MemoryHierarchy`
+  - Configurable via JSON with `l3` section
+  - Inclusive L3 policy for multi-core coherence
+  - Statistics: `getL3Misses()`, `getL3HitRate()`, `getL3MissRate()`
+
+- **MSI/MOESI Coherence Protocols**
+  - `CoherenceProtocolBase` abstract interface
+  - `MSIProtocol`: 3-state protocol (Modified, Shared, Invalid)
+  - `MOESIProtocol`: 5-state protocol (Modified, Owned, Exclusive, Shared, Invalid)
+  - Factory pattern: `CoherenceProtocolBase::create(type)`
+  - State transition tracking and statistics
+
+- **Ring and Torus Interconnects**
+  - `RingInterconnect`: Bidirectional ring with shortest path routing
+  - `TorusInterconnect`: 2D torus with wrap-around connections
+  - Proper latency modeling based on hop count
+  - Full implementation of `InterconnectInterface`
+
+- **CLI Parser Module**
+  - Extracted from main.cpp to `utils/cli_parser.h/cpp`
+  - `CLIParser` class with static methods
+  - Improved code organization and testability
+
+- **Cache Visualization Module**
+  - Extracted from main.cpp to `utils/cache_visualization.h/cpp`
+  - `CacheVisualization` class with cache state extraction and ASCII rendering
+  - `CacheBlockState` struct for block metadata
+
+- **New Unit Tests**
+  - `tests/unit/core/coherence_protocol_test.cpp` - MSI/MOESI protocol tests
+  - `tests/unit/core/l3_cache_test.cpp` - L3 cache tests
+  - `tests/unit/multiprocessor/interconnect_test.cpp` - Ring/Torus tests
+  - `tests/unit/utils/cli_parser_test.cpp` - CLI parsing tests
+
+- **Multiprocessor Protocol Selection**
+  - Added `coherenceProtocol` and `interconnectType` to `MultiProcessorSystem::Config`
+  - Supports MSI, MESI, MOESI protocol selection
+  - Supports Bus, Crossbar, Mesh, Ring, Torus interconnect selection
+
+### Changed
+- **Refactored main.cpp**: Reduced from 822 to 442 lines (-46%)
+  - Now uses `CLIParser` for command-line parsing
+  - Now uses `CacheVisualization` for cache state display
+- Updated `memory_hierarchy.h` with L3 configuration support
+- Updated `CMakeLists.txt` with new source files and tests
+- Made Doxygen configuration conditional on file existence
+- Updated documentation for all new features
+
+### New Files
+- `src/core/coherence_protocol.h/cpp` - Protocol base class and factory
+- `src/core/msi_protocol.h/cpp` - MSI implementation
+- `src/core/moesi_protocol.h/cpp` - MOESI implementation
+- `src/utils/cli_parser.h/cpp` - CLI parsing module
+- `src/utils/cache_visualization.h/cpp` - Cache visualization module
+- `docs/features/l3-cache.md` - L3 cache documentation
+- `docs/features/coherence-protocols.md` - Protocol documentation
+- `docs/features/interconnects.md` - Interconnect documentation
+
+### Technical Details
+- MOESI Owned state enables dirty sharing without memory writeback
+- Ring latency: `min(clockwise, counterclockwise) * hopLatency`
+- Torus latency: `(wrapDx + wrapDy) * hopLatency`
+- L3 inclusive policy maintains copy of all L1/L2 data
+- All 18 tests pass (unit, integration, performance)
+
+---
+
 ## [1.3.0] - 2026-01-07
 
 ### Added
@@ -106,6 +177,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The fixes ensure compatibility across Windows (GCC/MSVC), macOS (Clang/GCC), and Linux (GCC/Clang)
 - No functional changes - only build and compatibility improvements
 
+---
+
 ## [1.2.1] - 2025-09-02
 
 ### Fixed
@@ -126,6 +199,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [x] Compatible with all existing configuration files
 - [x] No performance regression
 
+---
+
 ## [1.2.0] - 2025-07-19
 
 ### Added
@@ -193,6 +268,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed lambda capture warnings in victim_cache.h
 - Improved const-correctness throughout the codebase
 
+---
+
 ## [1.1.0] - 2025-05-27
 
 ### Added
@@ -230,6 +307,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Reduced memory footprint by 15% through better data structures
 - Optimized prefetcher reduces unnecessary memory traffic by 30%
 
+---
+
 ## [1.0.0] - 2025-03-12
 
 ### Overview
@@ -290,7 +369,9 @@ This release marks the first stable version of the Cache Simulator, featuring a
 - Nodiscard attribute handling for method return values
 - String_view temporary object lifetime issues
 
-### Future Development
+---
+
+## Future Development
 - Identified TODOs for future enhancements (see TODO.md for details):
   - Multi-processor simulation
   - Additional replacement policies

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.14)
-project(CacheSimulator VERSION 1.3.0 LANGUAGES CXX)
+project(CacheSimulator VERSION 1.4.0 LANGUAGES CXX)
 
 # Set C++20 as the required standard (required for designated initializers)
 set(CMAKE_CXX_STANDARD 20)
@@ -54,6 +54,15 @@ list(APPEND CORE_SOURCES "src/core/write_policy.cpp")
 list(APPEND CORE_SOURCES "src/core/multiprocessor/processor_core.cpp")
 list(APPEND CORE_SOURCES "src/core/multiprocessor/coherence_controller.cpp")
 list(APPEND CORE_SOURCES "src/core/multiprocessor/interconnect.cpp")
+
+# coherence protocols
+list(APPEND CORE_SOURCES "src/core/coherence_protocol.cpp")
+list(APPEND CORE_SOURCES "src/core/msi_protocol.cpp")
+list(APPEND CORE_SOURCES "src/core/moesi_protocol.cpp")
+
+# CLI parser module
+list(APPEND UTILS_SOURCES "src/utils/cli_parser.cpp")
+
 # Note: victim_cache.h, parallel_executor.h are header-only
 
 # Define header files
@@ -128,6 +137,16 @@ foreach(TEST_SOURCE ${MODELS_TEST_SOURCES})
     add_test(NAME unit_models_${TEST_NAME} COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tests/unit/models/${TEST_NAME})
 endforeach()
 
+# Add unit tests - Multiprocessor
+file(GLOB MULTIPROCESSOR_TEST_SOURCES "tests/unit/multiprocessor/*.cpp")
+foreach(TEST_SOURCE ${MULTIPROCESSOR_TEST_SOURCES})
+    get_filename_component(TEST_NAME ${TEST_SOURCE} NAME_WE)
+    add_executable(${TEST_NAME} ${TEST_SOURCE})
+    target_link_libraries(${TEST_NAME} cachesim_lib)
+    set_target_properties(${TEST_NAME} PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tests/unit/multiprocessor)
+    add_test(NAME unit_multiprocessor_${TEST_NAME} COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/tests/unit/multiprocessor/${TEST_NAME})
+endforeach()
+
 # Add integration tests
 file(GLOB INTEGRATION_TEST_SOURCES "tests/integration/*.cpp")
 foreach(TEST_SOURCE ${INTEGRATION_TEST_SOURCES})
@@ -165,8 +184,8 @@ install(DIRECTORY scripts/
 )
 
 # Documentation target if Doxygen is available
-find_package(Doxygen)
-if(DOXYGEN_FOUND)
+find_package(Doxygen QUIET)
+if(DOXYGEN_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/docs/Doxyfile.in")
     set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src)
     set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs)
     set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Mudit Bhargava
+Copyright (c) 2026 Mudit Bhargava
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-# 🚀 Cache Simulator
+# Cache Simulator
 
-![Version](https://img.shields.io/badge/version-1.3.0-blue)
+![Version](https://img.shields.io/badge/version-1.4.0-blue)
 ![C++20](https://img.shields.io/badge/C%2B%2B-20-orange)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
@@ -21,13 +21,14 @@
 
 </div>
 
-## What's New in v1.3.0
+## What's New in v1.4.0
 
-- **Power Modeling**: CACTI-inspired energy analysis (dynamic + leakage)
-- **Area Estimation**: Silicon footprint breakdown by component
-- **Technology Nodes**: Support for 7nm, 14nm, 22nm, 32nm, 45nm
-- **CLI Integration**: `--power` and `--tech-node` flags
-- **Visualization Fix**: ASCII-safe table rendering for cross-platform console
+- **L3 Cache Support**: Optional third level cache with inclusive policy
+- **MSI/MOESI Protocols**: Extended coherence protocol support
+- **Ring/Torus Interconnects**: New network topologies with hop-based latency
+- **CLI Parser Module**: Refactored command-line parsing for maintainability
+- **Cache Visualization Module**: Extracted visualization code for reusability
+- **Main.cpp Refactoring**: Reduced from 822 to 442 lines (-46%)
 
 ## Key Features
 
@@ -51,9 +52,9 @@
 - **Configurable Aggressiveness**: Tunable prefetch distance and accuracy
 
 ### Multi-Processor Features
-- **MESI Protocol**: Full Modified-Exclusive-Shared-Invalid implementation
+- **MESI/MSI/MOESI Protocol**: Full coherence protocol implementations
 - **Directory-Based Coherence**: Scalable coherence tracking
-- **Interconnect Models**: Bus, crossbar, and mesh topologies
+- **Interconnect Models**: Bus, Crossbar, Mesh, Ring, and Torus topologies
 - **Atomic Operations**: Support for synchronization primitives
 - **False Sharing Detection**: Identifies and reports cache line conflicts
 
@@ -271,11 +272,11 @@ We welcome contributions! Please see our [Contributing Guide](contributing.md) f
 If you use this simulator in your research, please cite:
 
 ```bibtex
-@software{CacheSimulator2025,
+@software{CacheSimulator2026,
   author = {Mudit Bhargava},
   title = {Cache Simulator: A C++20 Cache and Memory Hierarchy Simulator},
-  version = {1.3.0},
-  year = {2025},
+  version = {1.4.0},
+  year = {2026},
   url = {https://github.com/muditbhargava66/CacheSimulator}
 }
 ```
@@ -301,7 +302,7 @@ This simulator is ideal for:
 
 <div align="center">
 
-**⭐ Star this repo if you find it useful!**
+**Star this repo if you find it useful!**
 
 [![Star History Chart](https://api.star-history.com/svg?repos=muditbhargava66/CacheSimulator&type=Date)](https://star-history.com/#muditbhargava66/CacheSimulator&Date)
 

build.ps1

@@ -7,7 +7,7 @@ $ErrorActionPreference = "Stop"
 $NUM_CORES = [Environment]::ProcessorCount
 if ($NUM_CORES -eq 0) { $NUM_CORES = 4 }
 
-Write-Host "Building Cache Simulator v1.2.2" -ForegroundColor Cyan
+Write-Host "Building Cache Simulator v1.4.0" -ForegroundColor Cyan
 Write-Host "Detected $NUM_CORES CPU cores" -ForegroundColor Gray
 
 # Create build directory if it doesn't exist

contributing.md

@@ -3,7 +3,7 @@
 ## Development Setup
 
 ### Prerequisites
-- C++17 compatible compiler
+- C++20 compatible compiler (GCC 10+, Clang 10+, MSVC 2019+)
 - CMake 3.14+
 - Git
 - Doxygen (for documentation)
@@ -31,7 +31,7 @@
 ## Code Style Guidelines
 
 ### C++ Standards
-- Use C++17 features appropriately
+- Use C++20 features appropriately
 - Follow RAII principles
 - Use smart pointers for memory management
 - Prefer const-correctness

docs/README.md

@@ -27,10 +27,13 @@ Comprehensive documentation for the Cache Simulator.
 
 | Document | Description |
 |----------|-------------|
+| [L3 Cache](features/l3-cache.md) | Third-level cache with inclusive policy |
+| [Coherence Protocols](features/coherence-protocols.md) | MSI, MESI, MOESI protocol implementations |
+| [Interconnects](features/interconnects.md) | Bus, Crossbar, Mesh, Ring, Torus topologies |
 | [Power Modeling](features/power-modeling.md) | CACTI-inspired power and area analysis |
 | [Replacement Policies](features/replacement-policies.md) | LRU, FIFO, NRU, PLRU, Random |
 | [Victim Cache](features/victim-cache.md) | Victim cache implementation |
-| [Multiprocessor](features/multiprocessor.md) | MESI coherence and multi-core simulation |
+| [Multiprocessor](features/multiprocessor.md) | Multi-core simulation and coherence |
 | [Prefetching](features/prefetching.md) | Stream buffer and stride prefetching |
 
 ### Platform Documentation

docs/developer/architecture.md

@@ -109,7 +109,7 @@ The `Cache` class provides a clean `access()` method that handles all the comple
 
 The `MemoryHierarchy` class orchestrates the entire cache hierarchy, managing:
 
-- Multiple cache levels (L1, L2)
+- Multiple cache levels (L1, L2, L3) - L3 support added in v1.4.0
 - Memory access flow through the hierarchy
 - Prefetching configuration and coordination
 - Statistics aggregation
@@ -118,6 +118,28 @@ The `MemoryHierarchy` class orchestrates the entire cache hierarchy, managing:
 
 This class serves as the main API for applications interacting with the simulator, providing methods to access memory, process traces, and retrieve statistics.
 
+#### L3 Cache Support
+
+The `MemoryHierarchy` now supports an optional L3 cache with:
+- Configurable size, associativity, and block size
+- Inclusive or non-inclusive policy
+- Statistics tracking (hit rate, miss rate)
+- Proper access flow: L1 miss → L2 access → L2 miss → L3 access
+
+#### Coherence Protocol Framework
+
+Abstract `CoherenceProtocolBase` class with implementations:
+- **MSIProtocol**: 3-state (Modified, Shared, Invalid)
+- **MESIProtocol**: 4-state with Exclusive
+- **MOESIProtocol**: 5-state with Owned for dirty sharing
+
+#### Interconnect Topologies
+
+The `InterconnectFactory` supports:
+- Bus, Crossbar, Mesh (existing)
+- **RingInterconnect**: Bidirectional ring with wrap-around
+- **TorusInterconnect**: 2D torus with minimal path routing
+
 ### StreamBuffer
 
 The `StreamBuffer` class implements a simple hardware prefetching mechanism: