[TOC]
The cache simulator is aimed at providing runtime metrics of a DSM processor to enhance education in computer architecture, wherein it enables students to compare a variety of caches and draw conclusions about the impact of the cache size, line size, associativity, coherence protocol and replacement policy.
- Course: NC State University CSC/ECE 506
- Instructor: Ed Gehringer
- Email: [email protected]
| Version | Programmer | Description |
|---|---|---|
| 1.0 | Ahmad Samih & Yan Solihin | Initial Version |
| 2.0 | Ed Gehringer | Revised for Spring 2015 |
| 3.0 | Anthony Spendlove | Complete rewrite for Spring 2025 |
| 3.1 | Anthony Spendlove | Add batch mode (parallel execution) |
| 3.1.1 | Anthony Spendlove | Trace file chunks are "double buffered" in batch mode |
| 3.2 | Anthony Spendlove | Added write timestamp debugging feature, consistency refactorings, bugfixes, portability and cross-platform edits |
| 3.3 | Anthony Spendlove | Added directory protocol program structure |
(Version history begins with v3.0)
This software operates under the GNU General Public License v3.0.
A copy of this documentation is hosted on my GitHub Pages.
- Implement Directory Protocols
- Compressed Trace Files
- More Protocols and Policies
This repository uses sub-modules to generate trace files for the simulation. If you do not wish to generate trace files, then the sub-modules can be left empty (uninitialized). If you do want to generate trace files, then:
- If you already downloaded this repo, then run
git submodule update --initfrom the root directory. - If not, then simply include the
--recurse-submodulesoption in thegit clonecommand.
The provided make file in the root directory is used to build the cache simulator. It currently has four targets:
all: (Incremental) build, default targetrebuild: Fully re-compile all source filesclean: Remove files generated by the build and run process*.bin: Run the simulator in batch metrics mode, usingconfigs.txtas the configuration list and*.binas the trace file
For more information on running the simulator and its modes of operation, see the cache simulator manual.
For further development, a development manual is included in this documentation.
The codebase and tool suite are documented using Doxygen style comments. As such, the Doxyfile is provided at the root directory and configured to generate HTML documentation of this software suite. To generate this documentation, simply issue doxygen on the command line in the same directory as this file. The resulting documentation will be available at docs/html/index.html.
The simulator was built to be extended, and thus template files and a template generator script are provided to automate the boilerplate code.
See the template file generation guide to learn how to create new source files using the provided templates.
The cache simulator reads in memory trace files to simulate cache behavior and record statistics. These are binary files comprised of a series of 5-byte memory accesses. Each memory access is structured as follows:
- The first 7 bits (7 high bits) are the CPU core ID that performs the memory access
- The 8th bit (LSB) is the operation (1 = write, 0 = read)
- The remaining 4 bytes are the 32-bit memory address accessed, stored in little endian byte ordering
For example, a trace of 09 70 7D 11 00 evaluates to a write operation by CPU core 4 at address 0x00117D70.
See the trace file generation guide to learn how to create your own trace files.
| Path | Description | ||
|---|---|---|---|
| 🗁 bin/ | Build directory | ||
| 📂 docs/ | Documentation files | ||
| 🗁 html/ | Generated HTML documentation | ||
| 📂 pages/ | Custom documentation pages | ||
| 📄 cache_sim.md | Cache simulator operation manual | ||
| 📄 development.md | Developer manual | ||
| 📄 exit_codes.md | Cache simulator exit code explanation | ||
| 📄 gen_traces.md | Trace file generation manual | ||
| 📄 templates.md | Template file generation manual | ||
| 📄 custom_doxygen.css | Stylesheet for doxygen documentation | ||
| 📂 src/ | Simulator source files (see file list) | ||
| 📂 template/ | Template files & generator script | ||
| 📄 coherence_c.tmplt | Coherence protocol source file template | ||
| 📄 coherence_h.tmplt | Coherence protocol header file template | ||
| 📄 directory_c.tmplt | Directory protocol source file template | ||
| 📄 directory_h.tmplt | Directory protocol header file template | ||
| 📜 mksrc.sh | Source file generator script | ||
| 📄 replacement_c.tmplt | Replacement policy source file template | ||
| 📄 replacement_h.tmplt | Replacement policy header file template | ||
| 📄 textbook_c.tmplt | Textbook mode source file template | ||
| 📄 textbook_h.tmplt | Textbook mode header file template | ||
| 📂 tools/ | First- and third-party tool suite for trace file generation | ||
| 📦 gem5/ | gem5 computer hardware simulator | ||
| 📦 parsec-benchmark/ | PARSEC benchmark suite | ||
| 📄 extractor.c | Translator program from gem5 output into trace file binary format | ||
| 📜 gem5_config.py | gem5 configuration for trace file generation | ||
| 📜 gen_trace.sh | Trace file generation script | ||
| 📜 get_platform.sh | Platform string generator | ||
| 🗁 traces/ | Generated trace files | ||
| 📄 .gitignore | Git ignore list | ||
| 📄 .gitmodules | Git sub-module list | ||
| 📄 configs.txt | Example configs file | ||
| 📜 Doxyfile | Doxygen script for generating documentation | ||
| 🔗 index.html | Link to generated HTML documentation | ||
| 📄 LICENSE | License file | ||
| 📜 Makefile | Make script for building and running the cache simulator | ||
| 📄 README.md | Readme file | ||
| 📄 sequence7.2.txt | Cache line access sequence from the textbook | ||
| 📄 sequence7.6.txt | Cache line access sequence from the textbook |
- 📂: Folder
- 🗁: Folder excluded by .gitignore
- 📦: GitHub sub-module
- 📄: File
- 📜: Script file
- 🔗: Link to file