From 0fe31664f3ed5779fb52974bd366eb3e8f944e9a Mon Sep 17 00:00:00 2001 From: Marleson Graf <9793033+hexengraf@users.noreply.github.com> Date: Thu, 19 Dec 2024 01:57:44 -0300 Subject: [PATCH 1/6] mem-ruby: Add missing option in ProtocolInfo (#1865) After the support for multiple ruby protocols was added, the macros PROTOCOL_MESI_Two_Level and PROTOCOL_MESI_Three_Level were removed. These macros are still being used to determine if Load_Linked requests are sent to the protocol, an information required by the fix that addresses LL/SC livelock. Replace the macros with a new option: useSecondaryLoadLinked. --- src/mem/ruby/protocol/MESI_Three_Level.slicc | 2 +- src/mem/ruby/protocol/MESI_Two_Level.slicc | 2 +- src/mem/ruby/slicc_interface/ProtocolInfo.hh | 8 ++++++++ src/mem/ruby/system/Sequencer.cc | 13 ++++++------- src/mem/slicc/parser.py | 1 + 5 files changed, 17 insertions(+), 9 deletions(-) diff --git a/src/mem/ruby/protocol/MESI_Three_Level.slicc b/src/mem/ruby/protocol/MESI_Three_Level.slicc index 7bcf2ab089..f24089a3aa 100644 --- a/src/mem/ruby/protocol/MESI_Three_Level.slicc +++ b/src/mem/ruby/protocol/MESI_Three_Level.slicc @@ -1,4 +1,4 @@ -protocol "MESI_Three_Level" use_secondary_store_conditional; +protocol "MESI_Three_Level" use_secondary_load_linked, use_secondary_store_conditional; include "MESI_Two_Level-msg.sm"; include "MESI_Three_Level-msg.sm"; include "MESI_Three_Level-L0cache.sm"; diff --git a/src/mem/ruby/protocol/MESI_Two_Level.slicc b/src/mem/ruby/protocol/MESI_Two_Level.slicc index e0f6ddae57..b3bfefea66 100644 --- a/src/mem/ruby/protocol/MESI_Two_Level.slicc +++ b/src/mem/ruby/protocol/MESI_Two_Level.slicc @@ -1,4 +1,4 @@ -protocol "MESI_Two_Level"; +protocol "MESI_Two_Level" use_secondary_load_linked; include "MESI_Two_Level-msg.sm"; include "MESI_Two_Level-L1cache.sm"; include "MESI_Two_Level-L2cache.sm"; diff --git a/src/mem/ruby/slicc_interface/ProtocolInfo.hh b/src/mem/ruby/slicc_interface/ProtocolInfo.hh index 76e9a58048..2691fc48be 100644 --- a/src/mem/ruby/slicc_interface/ProtocolInfo.hh +++ b/src/mem/ruby/slicc_interface/ProtocolInfo.hh @@ -45,13 +45,16 @@ class ProtocolInfo protected: const bool partialFuncReads; + const bool useSecondaryLoadLinked; const bool useSecondaryStoreConditional; public: ProtocolInfo(std::string name, bool partial_func_reads, + bool use_secondary_load_linked, bool use_secondary_store_conditional) : name(name), partialFuncReads(partial_func_reads), + useSecondaryLoadLinked(use_secondary_load_linked), useSecondaryStoreConditional(use_secondary_store_conditional) { } @@ -59,6 +62,11 @@ class ProtocolInfo std::string getName() const { return name; } bool getPartialFuncReads() const { return partialFuncReads; } bool + getUseSecondaryLoadLinked() const + { + return useSecondaryLoadLinked; + } + bool getUseSecondaryStoreConditional() const { return useSecondaryStoreConditional; diff --git a/src/mem/ruby/system/Sequencer.cc b/src/mem/ruby/system/Sequencer.cc index e7f6d39731..9307713571 100644 --- a/src/mem/ruby/system/Sequencer.cc +++ b/src/mem/ruby/system/Sequencer.cc @@ -959,12 +959,11 @@ Sequencer::makeRequest(PacketPtr pkt) // // The following logic works correctly with the semantics // of armV8 LDEX/STEX instructions. + const ProtocolInfo &protocol_info = m_ruby_system->getProtocolInfo(); if (pkt->isWrite()) { DPRINTF(RubySequencer, "Issuing SC\n"); primary_type = RubyRequestType_Store_Conditional; - const ProtocolInfo &protocol_info = - m_ruby_system->getProtocolInfo(); if (protocol_info.getUseSecondaryStoreConditional()) { secondary_type = RubyRequestType_Store_Conditional; } else { @@ -974,11 +973,11 @@ Sequencer::makeRequest(PacketPtr pkt) DPRINTF(RubySequencer, "Issuing LL\n"); assert(pkt->isRead()); primary_type = RubyRequestType_Load_Linked; -#if defined (PROTOCOL_MESI_Two_Level) || defined (PROTOCOL_MESI_Three_Level) - secondary_type = RubyRequestType_Load_Linked; -#else - secondary_type = RubyRequestType_LD; -#endif + if (protocol_info.getUseSecondaryLoadLinked()) { + secondary_type = RubyRequestType_Load_Linked; + } else { + secondary_type = RubyRequestType_LD; + } } } else if (pkt->req->isLockedRMW()) { // diff --git a/src/mem/slicc/parser.py b/src/mem/slicc/parser.py index c2bd7259a5..9c8d9369fe 100644 --- a/src/mem/slicc/parser.py +++ b/src/mem/slicc/parser.py @@ -75,6 +75,7 @@ class SLICC(Grammar): # Update slicc_interface/ProtocolInfo.cc/hh if updating this. self.options = { "partial_func_reads": False, + "use_secondary_load_linked": False, "use_secondary_store_conditional": False, } From b6c941c9cabdf6bd98be09addc6225c8a18d003b Mon Sep 17 00:00:00 2001 From: Marleson Graf <9793033+hexengraf@users.noreply.github.com> Date: Thu, 19 Dec 2024 01:59:47 -0300 Subject: [PATCH 2/6] mem-ruby: Fix missing RubySystem in PerfectCacheMemory's entries (#1864) MOESI_CMP_directory protocol crashes with one of the several assertions in NetDest.cc. It happens because the entry type used to instantiate a PerfectCacheMemory object in MOESI_CMP_directory-L2cache.sm contains a NetDest object, so it requires a RubySystem object to be manually set for it. Instead of just receiving the block size, change PerfectCacheMemory to receive a RubySystem object and use it to set the block size and call ENTRY::setRubySystem if the entries require it. --- src/mem/ruby/structures/PerfectCacheMemory.hh | 19 ++++++++++++++++++- src/mem/slicc/symbols/StateMachine.py | 4 ++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/src/mem/ruby/structures/PerfectCacheMemory.hh b/src/mem/ruby/structures/PerfectCacheMemory.hh index 0966ca80d2..9cf8e8de19 100644 --- a/src/mem/ruby/structures/PerfectCacheMemory.hh +++ b/src/mem/ruby/structures/PerfectCacheMemory.hh @@ -41,11 +41,13 @@ #ifndef __MEM_RUBY_STRUCTURES_PERFECTCACHEMEMORY_HH__ #define __MEM_RUBY_STRUCTURES_PERFECTCACHEMEMORY_HH__ +#include #include #include "base/compiler.hh" #include "mem/ruby/common/Address.hh" #include "mem/ruby/protocol/AccessPermission.hh" +#include "mem/ruby/system/RubySystem.hh" namespace gem5 { @@ -74,7 +76,7 @@ class PerfectCacheMemory public: PerfectCacheMemory(); - void setBlockSize(const int block_size) { m_block_size = block_size; } + void setRubySystem(RubySystem *rs); // tests to see if an address is present in the cache bool isTagPresent(Addr address) const; @@ -111,7 +113,11 @@ class PerfectCacheMemory // Data Members (m_prefix) std::unordered_map > m_map; + RubySystem *m_ruby_system = nullptr; int m_block_size = 0; + + static constexpr bool entryRequiresRubySystem = + std::is_member_function_pointer_v; }; template @@ -129,6 +135,14 @@ PerfectCacheMemory::PerfectCacheMemory() { } +template +inline +void PerfectCacheMemory::setRubySystem(RubySystem *rs) +{ + m_ruby_system = rs; + m_block_size = rs->getBlockSizeBytes(); +} + // tests to see if an address is present in the cache template inline bool @@ -153,6 +167,9 @@ PerfectCacheMemory::allocate(Addr address) PerfectCacheLineState line_state; line_state.m_permission = AccessPermission_Invalid; line_state.m_entry = ENTRY(); + if constexpr (entryRequiresRubySystem) { + line_state.m_entry.setRubySystem(m_ruby_system); + } Addr line_addr = makeLineAddress(address, floorLog2(m_block_size)); m_map.emplace(line_addr, line_state); } diff --git a/src/mem/slicc/symbols/StateMachine.py b/src/mem/slicc/symbols/StateMachine.py index 42f4c332d2..c1052086bf 100644 --- a/src/mem/slicc/symbols/StateMachine.py +++ b/src/mem/slicc/symbols/StateMachine.py @@ -833,11 +833,11 @@ $c_ident::init() # For objects that require knowing the cache line size, # set the value here. - if vtype.c_ident in ("TBETable", "PerfectCacheMemory"): + if vtype.c_ident in ("TBETable"): block_size_func = "m_ruby_system->getBlockSizeBytes()" code(f"(*{vid}).setBlockSize({block_size_func});") - if vtype.c_ident in ("NetDest"): + if vtype.c_ident in ("NetDest", "PerfectCacheMemory"): code(f"(*{vid}).setRubySystem(m_ruby_system);") for param in self.config_parameters: From e146f1b2bcfe07c8095c6529ac32d88c44f7c3cd Mon Sep 17 00:00:00 2001 From: Melissa Jost <50555529+mkjost0@users.noreply.github.com> Date: Tue, 12 Nov 2024 13:30:32 -0500 Subject: [PATCH 3/6] misc: Add sphinx stdlib documentation (#335) This PR adds documentation to the standard library using Sphinx. For details on how the documentation was generated, refer to https://gem5.atlassian.net/browse/GEM5-1314. Currently, some modules like `dramsys` and `mesi_three_level` appear as blank pages. To view the current state of the documentation locally, run: `cd docs/_build/html; python3 -m http.server 8000` --------- Co-authored-by: ivanaamit --- .gitignore | 1 + docs/Makefile | 20 ++++++++++++++++++++ docs/README | 37 ++++++++++++++++++++++++++++++++++++ docs/conf.py | 42 +++++++++++++++++++++++++++++++++++++++++ docs/gem5-sphinx | 1 + docs/gem5-sphinx-apidoc | 14 ++++++++++++++ 6 files changed, 115 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/README create mode 100644 docs/conf.py create mode 100644 docs/gem5-sphinx create mode 100644 docs/gem5-sphinx-apidoc diff --git a/.gitignore b/.gitignore index 36ba603fb6..dcc09fc1c6 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ cscope.out .*.swo m5out /src/doxygen/html +/docs/_build /ext/dramsim2/DRAMSim2 /ext/mcpat/regression/*/*.out /util/m5/*.o diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..d4bb2cbb9e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README b/docs/README new file mode 100644 index 0000000000..540829a614 --- /dev/null +++ b/docs/README @@ -0,0 +1,37 @@ +# How to build Sphinx documentation + +In order to build documentation for the standard library, first install sphinx. Run these commands in the `gem5` directory. + +```bash +python3 -m venv build/ +source build/bin/activate +pip install sphinx + +``` + +Next, build gem5, then cd to the `docs` directory. + +```bash +scons build/ALL/gem5.opt +cd docs +``` + +In the `docs` directory, run `../build/ALL/gem5.opt gem5-sphinx-apidoc -o . ../src/python/gem5 -F -e` in order to generate the RST files. + +To generate the documentation, run `SPHINXBUILD="../build/ALL/gem5.opt gem5-sphinx" make html` + +In order to view this documentation as a website, run the following commands while still in the `docs` directory: + +```bash +cd _build/html +python3 -m http.server 8000 +``` + +If you want to use a different Sphinx theme, follow these steps: + +- Install the desired theme, e.g., `pip install sphinx-rtd-theme` +- Update the `html_theme` in `docs/conf.py` by setting `html_theme = "sphinx_rtd_theme"` +- Run `SPHINXBUILD="../build/ALL/gem5.opt gem5-sphinx" make html` in the `docs` directory to apply the changes. + +Note: We are aware that some modules currently display a blank page in the documentation. +This will be addressed in the future. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..8bacc4dd85 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,42 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "gem5" +copyright = "" +author = "" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.todo", +] + +templates_path = ["_templates"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "build/lib64/python3.8/site-packages", + "build/lib/python3.8/site-packages", +] + +language = "en" + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_static_path = ["_static"] + +# -- Options for todo extension ---------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration + +todo_include_todos = True diff --git a/docs/gem5-sphinx b/docs/gem5-sphinx new file mode 100644 index 0000000000..5b4550e10d --- /dev/null +++ b/docs/gem5-sphinx @@ -0,0 +1 @@ +import sphinx.__main__ diff --git a/docs/gem5-sphinx-apidoc b/docs/gem5-sphinx-apidoc new file mode 100644 index 0000000000..6c2ac21f0d --- /dev/null +++ b/docs/gem5-sphinx-apidoc @@ -0,0 +1,14 @@ +import re +import sys + +extensions = ['myst_parser'] + +source_suffix = { + '.md': 'markdown', + '.py': 'markdown' +} + +from sphinx.ext.apidoc import main +if __name__ == '__m5_main__': + sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0]) + sys.exit(main()) From b5e27f5ed873c9fec53afa8925c7d578f77deaa3 Mon Sep 17 00:00:00 2001 From: Tommaso Marinelli Date: Thu, 12 Dec 2024 10:55:23 +0100 Subject: [PATCH 4/6] configs: Generalize class types in CHI RNF/MN generators (#1851) Classes CHI_RNF and CHI_MN can be specialized to override base class/subclass attributes, like it happens in CustomMesh with router_list (see configs/example/noc_config/2x4.py). To avoid missing these attributes, it is needed to generalize the class types when instantiating the objects in the recently added generators. --- configs/ruby/CHI_config.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configs/ruby/CHI_config.py b/configs/ruby/CHI_config.py index a205db17d6..aeac35ebf8 100644 --- a/configs/ruby/CHI_config.py +++ b/configs/ruby/CHI_config.py @@ -601,7 +601,7 @@ class CHI_RNF(CHI_Node): @classmethod def generate(cls, options, ruby_system, cpus): rnfs = [ - CHI_RNF( + cls( [cpu], ruby_system, L1ICache(size=options.l1i_size, assoc=options.l1i_assoc), @@ -724,7 +724,7 @@ class CHI_MN(CHI_Node): """ Creates one Misc Node """ - return [CHI_MN(ruby_system, [cpu.l1d for cpu in cpus])] + return [cls(ruby_system, [cpu.l1d for cpu in cpus])] class CHI_SNF_Base(CHI_Node): From 0e4c8487dd838bd08c2de4a18f775c80e2fb5f76 Mon Sep 17 00:00:00 2001 From: "Bobby R. Bruce" Date: Wed, 18 Dec 2024 21:21:52 -0800 Subject: [PATCH 5/6] misc: Update the gem5 version to v24.1.0.1 --- src/Doxyfile | 2 +- src/base/version.cc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Doxyfile b/src/Doxyfile index 333b3ee929..c5b219f37f 100644 --- a/src/Doxyfile +++ b/src/Doxyfile @@ -31,7 +31,7 @@ PROJECT_NAME = gem5 # This could be handy for archiving the generated documentation or # if some version control system is used. -PROJECT_NUMBER = v24.1.0.0 +PROJECT_NUMBER = v24.1.0.1 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) # base path where the generated documentation will be put. diff --git a/src/base/version.cc b/src/base/version.cc index 9dbe3a2f26..d6fb326988 100644 --- a/src/base/version.cc +++ b/src/base/version.cc @@ -32,6 +32,6 @@ namespace gem5 /** * @ingroup api_base_utils */ -const char *gem5Version = "24.1.0.0"; +const char *gem5Version = "24.1.0.1"; } // namespace gem5 From ea28fcee5b6c9435379f99b9a8708b75f186fbc3 Mon Sep 17 00:00:00 2001 From: "Bobby R. Bruce" Date: Thu, 19 Dec 2024 18:23:28 -0800 Subject: [PATCH 6/6] misc: Update RELEASE-NOTES.md for v24.1.0.1 --- RELEASE-NOTES.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 719a35af55..ca3a79288f 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -1,3 +1,22 @@ +# Version 24.1.0.1 + +**[HOTFIX]** This hotfix release applies the following: + +* Generalization of the class types in CHI RNF/MN generators thus fixing an issue with missing attributes when using the CHI protocol. +PR: . +* Add Sphinx documentation for the gem5 standard library. +This is largely generated from Python docstrings. +See "docs/README" for more information on building and deploying Sphinx documentation. +PR: . +* Add missing `RubySystem` member and related methods in `PerfectCacheMemory`'s entries. +This was causing assertions to trigger in "src/mem/ruby/commonNetDest.cc". +PR: . +* Add `useSecondaryLoadLinked` function to "src/mem/ruby/slicc_interface/ProtocolInfo.hh". +This fixes a bug which was introduced after the removal of the `PROTOCOL_MESI_Two_Level` and `PROTOCOL_MESI_Three_Level` MACROs in v24.1.0.0. +These MACROs were being used to infer if `Load_Linked` requests are sent to the Ruby protocol or not. +The `useSecondaryLoadLinked` function has been introduced to specify this directly where needed. +PR: . + # Version 24.1 ## User facing changes