|
CohereSim: A Bus-based Cache Simulator
v3.3
A tool for education in computing - learn about coherence protocols, replacement policies, and SMP vs DSM
|
CohereSim 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.
| 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.
The repo containing the full CohereSim implementation has been privated to allow coding assignments to be derived from its code. To request a copy of the full CohereSim implementation, please contact Dr. Ed Gehringer at the email above.
A copy of this documentation is hosted on my GitHub Pages.
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:
git submodule update --init from the root directory.--recurse-submodules option in the git clone command.The provided make file in the root directory is used to build CohereSim. 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 CohereSim in batch metrics mode, using configs.txt as the configuration list and *.bin as the trace fileFor more information on running CohereSim and its modes of operation, see the CohereSim 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.
CohereSim 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.
CohereSim 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:
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 | CohereSim operation manual | ||
| 📄 development.md | Developer manual | ||
| 📄 exit_codes.md | CohereSim exit code explanation | ||
| 📄 gen_traces.md | Trace file generation manual | ||
| 📄 templates.md | Template file generation manual | ||
| 📄 custom_doxygen.css | Stylesheet for doxygen documentation | ||
| 📂 src/ | CohereSim 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 | ||
| 📄 interactive_c.tmplt | Interactive mode source file template | ||
| 📄 interactive_h.tmplt | Interactive mode 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 | ||
| 📂 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 CohereSim | ||
| 📄 README.md | Readme file | ||
| 📄 sequence7.2.txt | Cache line access sequence from the textbook | ||
| 📄 sequence7.6.txt | Cache line access sequence from the textbook | ||
1.9.1