v24.1.0.1 Hotfix Release (#1875)

.gitignore

@@ -10,6 +10,7 @@ cscope.out
 .*.swo
 m5out
 /src/doxygen/html
+/docs/_build
 /ext/dramsim2/DRAMSim2
 /ext/mcpat/regression/*/*.out
 /util/m5/*.o

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: <https://github.com/gem5/gem5/pull/1851>.
+* 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: <https://github.com/gem5/gem5/pull/335>.
+* Add missing `RubySystem` member and related methods in `PerfectCacheMemory`'s entries.
+This was causing assertions to trigger in "src/mem/ruby/commonNetDest.cc".
+PR: <https://github.com/gem5/gem5/pull/1864>.
+* 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: <https://github.com/gem5/gem5/pull/1865>.
+
 # Version 24.1
 
 ## User facing changes

configs/ruby/CHI_config.py

@@ -601,7 +601,7 @@ def addPrivL2Cache(self, cache_type, pf_type=None):
     @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 @@ def generate(cls, options, ruby_system, cpus):
         """
         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):

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)

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.

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

docs/gem5-sphinx

@@ -0,0 +1 @@
+import sphinx.__main__

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())

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.

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

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";

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";

src/mem/ruby/slicc_interface/ProtocolInfo.hh

@@ -45,20 +45,28 @@ 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)
     {
     }
 
     std::string getName() const { return name; }
     bool getPartialFuncReads() const { return partialFuncReads; }
     bool
+    getUseSecondaryLoadLinked() const
+    {
+        return useSecondaryLoadLinked;
+    }
+    bool
     getUseSecondaryStoreConditional() const
     {
         return useSecondaryStoreConditional;

src/mem/ruby/structures/PerfectCacheMemory.hh

@@ -41,11 +41,13 @@
 #ifndef __MEM_RUBY_STRUCTURES_PERFECTCACHEMEMORY_HH__
 #define __MEM_RUBY_STRUCTURES_PERFECTCACHEMEMORY_HH__
 
+#include <type_traits>
 #include <unordered_map>
 
 #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<Addr, PerfectCacheLineState<ENTRY> > m_map;
 
+    RubySystem *m_ruby_system = nullptr;
     int m_block_size = 0;
+
+    static constexpr bool entryRequiresRubySystem =
+        std::is_member_function_pointer_v<decltype(&ENTRY::setRubySystem)>;
 };
 
 template<class ENTRY>
@@ -129,6 +135,14 @@ PerfectCacheMemory<ENTRY>::PerfectCacheMemory()
 {
 }
 
+template<class ENTRY>
+inline
+void PerfectCacheMemory<ENTRY>::setRubySystem(RubySystem *rs)
+{
+    m_ruby_system = rs;
+    m_block_size = rs->getBlockSizeBytes();
+}
+
 // tests to see if an address is present in the cache
 template<class ENTRY>
 inline bool
@@ -153,6 +167,9 @@ PerfectCacheMemory<ENTRY>::allocate(Addr address)
     PerfectCacheLineState<ENTRY> 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);
 }

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()) {
         //

src/mem/slicc/parser.py

@@ -75,6 +75,7 @@ def __init__(
         # 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,
         }
 

src/mem/slicc/symbols/StateMachine.py

@@ -833,11 +833,11 @@ def printControllerCC(self, path, includes):
 
                     # 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: