mem-ruby,scons: Add scons option for multiple protocols

This change does many things, but they must all be atomically done.

**USER FACING CHANGE**: The Ruby protocols in Kconfig have changed names
(they are now the same case as the SLICC file names). So, after this
commit, your build configurations need to be updated. You can do so by
running `scons menuconfig <build dir>` and selecting the right ruby
options. Alternatively, if you're using a `build_opts` file, you can run
`scons defconfig build/<ISA> build_opts/<ISA>` which should update your
config correctly.

Detailed changes are described below.

Kconfig changes:

- Kconfig files in ruby now must all be declared in the ruby/Kconfig
  file
- All of the protocol names are changed to match their slicc file names
  including the case
- A new option is available called "Use multiple protocols" which should
  be selected if multiple protocols are selected. This is only used to
  set the PROTOCOL variable to "MULTIPLE" when in multiple mode.
- The PROTOCOL variable can now be "MULTIPLE" which means it will be
  ignored. If it's not "MULTIPLE" then it holds the "main" protocol,
  which is necessary for backwards compatibility with the Ruby.py files.

Ruby config changes:

To make this change backwards compatible with Ruby.py, this change adds
a new "protocol" config called MULTIPLE.py which is used to allow the
user to set a "--protocol" option on the command line. This is only
needed if you are using a gem5 binary with multiple protocols but need
to use Ruby.py.

stdlib changes:

- Make the coherence protocol file behave like the ISA file
- Add a function to get the coherence protocol from the `CacheHierarchy`
  like we do with the ISA in the `Processor`.
  - Use this function where `get_runtime_coherence_protocol` was used
- Update the requires code to work with the ne CoherenceProtocol
- Fix a typo in the AMD Hammer name and also add the missing MSI
  protocol

Scons changes:

- In Ruby we now gather up all of the protocols and build them all if
  there are multiple protocols
- There's some bending over backwards to tell the user if they are using
  an out of date gem5.build/config file and how to update it
- Note that multiple ruby protocols adds a significant amount of time to
  the build since we have to run slicc twice for each file.

build_opts:

- Update all files with new names
- Add a new NULL_All_Ruby that will be used for testing

Signed-off-by: Jason Lowe-Power <jason@lowepower.com>

src/python/gem5/coherence_protocol.py

@@ -28,18 +28,52 @@
 Specifies the coherence protocol enum
 """
 
+import os
 from enum import Enum
 
 
 class CoherenceProtocol(Enum):
-    MESI_THREE_LEVEL = 1
-    MESI_THREE_LEVEL_HTM = 2
-    ARM_MOESI_HAMMER = 3
-    GARNET_STANDALONE = 4
-    MESI_TWO_LEVEL = 5
-    MOESI_CMP_DIRECTORY = 6
-    MOESI_CMP_TOKEN = 7
-    MOESI_AMD_BASE = 8
-    MI_EXAMPLE = 9
-    GPU_VIPER = 10
-    CHI = 11
+    NULL = "no protocol (classic only)"
+    MESI_THREE_LEVEL = "MESI_Three_Level"
+    MESI_THREE_LEVEL_HTM = "MESI_Three_Level_HTM"
+    AMD_MOESI_HAMMER = "AMD_MOESI_hammer"
+    GARNET_STANDALONE = "Garnet_standalone"
+    MESI_TWO_LEVEL = "MESI_Two_Level"
+    MOESI_CMP_DIRECTORY = "MOESI_CMP_directory"
+    MOESI_CMP_TOKEN = "MOESI_CMP_token"
+    MOESI_AMD_BASE = "MOESI_AMD_Base"
+    MI_EXAMPLE = "MI_example"
+    GPU_VIPER = "GPU_VIPER"
+    CHI = "CHI"
+    MSI = "MSI"
+
+
+def get_protocols_str_set():
+    return {protocol.value for protocol in CoherenceProtocol}
+
+
+def get_protocol_from_str(protocol_str: str) -> CoherenceProtocol:
+    """
+    Will return the correct enum given the input string. This is matched on
+    the enum's value. E.g., "CHI" will return CoherenceProtocol.CHI. Throws
+    an exception if the input string is invalid.
+
+    ``get_protocols_str_set()`` can be used to determine the valid strings.
+
+    This is for parsing text inputs that specify protocol targets.
+
+    :param input: The protocol to return, as a string. Case-insensitive.
+    """
+
+    for protocol in CoherenceProtocol:
+        if protocol.value.lower() == protocol_str.lower():
+            return protocol
+
+    valid_protocols_str_list = ""
+    for isa_str in get_protocols_str_set():
+        valid_protocols_str_list += f"{os.linesep}{isa_str}"
+
+    raise Exception(
+        f"Value '{input}' does not correspond to a known ISA. Known protocols:"
+        f"{valid_protocols_str_list}"
+    )

src/python/gem5/components/cachehierarchies/abstract_cache_hierarchy.py

@@ -48,6 +48,7 @@ from m5.objects import (
 )
 from m5.util.fdthelper import *
 
+from ...coherence_protocol import CoherenceProtocol
 from ..boards.abstract_board import AbstractBoard
 
 
@@ -142,6 +143,15 @@ class AbstractCacheHierarchy(SubSystem):
         """
         raise NotImplementedError
 
+    @abstractmethod
+    def get_coherence_protocol(self) -> CoherenceProtocol:
+        """
+        Returns the coherence protocol used in the cache hierarchy.
+
+        :returns: The coherence protocol used in the cache hierarchy.
+        """
+        raise NotImplementedError
+
     def _pre_instantiate(self, root: Root) -> None:
         """Called in the `AbstractBoard`'s `_pre_instantiate` method. This is
         called after `connect_things`, after the creation of the root object

src/python/gem5/components/cachehierarchies/chi/private_l1_cache_hierarchy.py

@@ -80,6 +80,10 @@ class PrivateL1CacheHierarchy(AbstractRubyCacheHierarchy):
         self._size = size
         self._assoc = assoc
 
+    @overrides(AbstractCacheHierarchy)
+    def get_coherence_protocol(self):
+        return CoherenceProtocol.CHI
+
     @overrides(AbstractCacheHierarchy)
     def incorporate_cache(self, board: AbstractBoard) -> None:
         super().incorporate_cache(board)

src/python/gem5/components/cachehierarchies/classic/abstract_classic_cache_hierarchy.py

@@ -28,6 +28,7 @@ from abc import abstractmethod
 
 from m5.objects import Port
 
+from ....coherence_protocol import CoherenceProtocol
 from ....utils.override import overrides
 from ..abstract_cache_hierarchy import AbstractCacheHierarchy
 
@@ -46,6 +47,10 @@ class AbstractClassicCacheHierarchy(AbstractCacheHierarchy):
     def is_ruby(self) -> bool:
         return False
 
+    @overrides(AbstractCacheHierarchy)
+    def get_coherence_protocol(self) -> CoherenceProtocol:
+        return CoherenceProtocol.NULL
+
     @abstractmethod
     def get_mem_side_port(self) -> Port:
         raise NotImplementedError

src/python/gem5/components/cachehierarchies/ruby/caches/prebuilt/octopi_cache/octopi.py

@@ -30,7 +30,12 @@ from m5.objects import (
     RubySystem,
 )
 
-from ......coherence_protocol import CoherenceProtocol
+from ....coherence_protocol import CoherenceProtocol
+from ....utils.override import overrides
+from ....utils.requires import requires
+
+requires(coherence_protocol_required=CoherenceProtocol.MI_EXAMPLE)
+
 from ......components.boards.abstract_board import AbstractBoard
 from ......components.cachehierarchies.ruby.caches.mesi_three_level.directory import (
     Directory,
@@ -38,8 +43,7 @@ from ......components.cachehierarchies.ruby.caches.mesi_three_level.directory im
 from ......components.cachehierarchies.ruby.caches.mesi_three_level.dma_controller import (
     DMAController,
 )
-from ......utils.override import overrides
-from ......utils.requires import requires
+from ....abstract_cache_hierarchy import AbstractCacheHierarchy
 from ....abstract_three_level_cache_hierarchy import (
     AbstractThreeLevelCacheHierarchy,
 )
@@ -92,6 +96,10 @@ class OctopiCache(
         self._num_core_complexes = num_core_complexes
         self._is_fullsystem = is_fullsystem
 
+    @overrides(AbstractCacheHierarchy)
+    def get_coherence_protocol(self):
+        return CoherenceProtocol.MESI_THREE_LEVEL
+
     def incorporate_cache(self, board: AbstractBoard) -> None:
         requires(
             coherence_protocol_required=CoherenceProtocol.MESI_THREE_LEVEL

src/python/gem5/components/cachehierarchies/ruby/mesi_three_level_cache_hierarchy.py

@@ -40,6 +40,7 @@ requires(coherence_protocol_required=CoherenceProtocol.MESI_THREE_LEVEL)
 
 from ....isas import ISA
 from ...boards.abstract_board import AbstractBoard
+from ..abstract_cache_hierarchy import AbstractCacheHierarchy
 from ..abstract_three_level_cache_hierarchy import (
     AbstractThreeLevelCacheHierarchy,
 )
@@ -87,6 +88,10 @@ class MESIThreeLevelCacheHierarchy(
 
         self._num_l3_banks = num_l3_banks
 
+    @overrides(AbstractCacheHierarchy)
+    def get_coherence_protocol(self):
+        return CoherenceProtocol.MESI_THREE_LEVEL
+
     def incorporate_cache(self, board: AbstractBoard) -> None:
         super().incorporate_cache(board)
         cache_line_size = board.get_cache_line_size()

src/python/gem5/components/cachehierarchies/ruby/mesi_two_level_cache_hierarchy.py

@@ -40,6 +40,7 @@ requires(coherence_protocol_required=CoherenceProtocol.MESI_TWO_LEVEL)
 
 from ....isas import ISA
 from ...boards.abstract_board import AbstractBoard
+from ..abstract_cache_hierarchy import AbstractCacheHierarchy
 from ..abstract_two_level_cache_hierarchy import AbstractTwoLevelCacheHierarchy
 from .abstract_ruby_cache_hierarchy import AbstractRubyCacheHierarchy
 from .caches.mesi_two_level.directory import Directory
@@ -83,6 +84,10 @@ class MESITwoLevelCacheHierarchy(
 
         self._num_l2_banks = num_l2_banks
 
+    @overrides(AbstractCacheHierarchy)
+    def get_coherence_protocol(self):
+        return CoherenceProtocol.MESI_TWO_LEVEL
+
     def incorporate_cache(self, board: AbstractBoard) -> None:
         super().incorporate_cache(board)
         cache_line_size = board.get_cache_line_size()

src/python/gem5/components/cachehierarchies/ruby/mi_example_cache_hierarchy.py

@@ -64,6 +64,10 @@ class MIExampleCacheHierarchy(AbstractRubyCacheHierarchy):
         self._size = size
         self._assoc = assoc
 
+    @overrides(AbstractCacheHierarchy)
+    def get_coherence_protocol(self):
+        return CoherenceProtocol.MI_EXAMPLE
+
     @overrides(AbstractCacheHierarchy)
     def incorporate_cache(self, board: AbstractBoard) -> None:
         super().incorporate_cache(board)

src/python/gem5/runtime.py

@@ -33,7 +33,11 @@ from typing import Set
 from m5.defines import buildEnv
 from m5.util import warn
 
-from .coherence_protocol import CoherenceProtocol
+from .coherence_protocol import (
+    CoherenceProtocol,
+    get_protocol_from_str,
+    get_protocols_str_set,
+)
 from .isas import (
     ISA,
     get_isa_from_str,
@@ -60,30 +64,18 @@ def get_supported_isas() -> Set[ISA]:
     return supported_isas
 
 
-def get_runtime_coherence_protocol() -> CoherenceProtocol:
-    """Gets the cache coherence protocol.
-
-    This can be inferred at runtime.
-
-    :returns: The cache coherence protocol.
+def get_supported_protocols() -> Set[CoherenceProtocol]:
     """
-    protocol_map = {
-        "mi_example": CoherenceProtocol.MI_EXAMPLE,
-        "moesi_hammer": CoherenceProtocol.ARM_MOESI_HAMMER,
-        "garnet_standalone": CoherenceProtocol.GARNET_STANDALONE,
-        "moesi_cmp_token": CoherenceProtocol.MOESI_CMP_TOKEN,
-        "mesi_two_level": CoherenceProtocol.MESI_TWO_LEVEL,
-        "moesi_amd_base": CoherenceProtocol.MOESI_AMD_BASE,
-        "mesi_three_level_htm": CoherenceProtocol.MESI_THREE_LEVEL_HTM,
-        "mesi_three_level": CoherenceProtocol.MESI_THREE_LEVEL,
-        "gpu_viper": CoherenceProtocol.GPU_VIPER,
-        "chi": CoherenceProtocol.CHI,
-    }
+    Returns the set of all the coherence protocols compiled into the current
+    binary.
+    """
+    supported_protocols = set()
 
-    protocol_str = str(buildEnv["PROTOCOL"]).lower()
-    if protocol_str not in protocol_map.keys():
-        raise NotImplementedError(
-            "Protocol '" + buildEnv["PROTOCOL"] + "' not recognized."
-        )
+    if not buildEnv["RUBY"]:
+        return {CoherenceProtocol.NULL}
 
-    return protocol_map[protocol_str]
+    for key in get_protocols_str_set():
+        if buildEnv.get(f"RUBY_PROTOCOL_{key}", False):
+            supported_protocols.add(get_protocol_from_str(key))
+
+    return supported_protocols

src/python/gem5/utils/requires.py

@@ -31,8 +31,8 @@ from typing import Optional
 from ..coherence_protocol import CoherenceProtocol
 from ..isas import ISA
 from ..runtime import (
-    get_runtime_coherence_protocol,
     get_supported_isas,
+    get_supported_protocols,
 )
 
 
@@ -73,7 +73,7 @@ def requires(
     """
 
     supported_isas = get_supported_isas()
-    runtime_coherence_protocol = get_runtime_coherence_protocol()
+    supported_protocols = get_supported_protocols()
     kvm_available = os.access("/dev/kvm", mode=os.R_OK | os.W_OK)
 
     # Note, previously I had the following code here:
@@ -108,17 +108,13 @@ def requires(
     if (
         coherence_protocol_required != None
         and coherence_protocol_required.value
-        != runtime_coherence_protocol.value
+        not in (protocol.value for protocol in supported_protocols)
     ):
-        raise Exception(
-            _get_exception_str(
-                msg="The current coherence protocol is "
-                "'{}'. Required: '{}'".format(
-                    runtime_coherence_protocol.name,
-                    coherence_protocol_required.name,
-                )
-            )
-        )
+        msg = f"The required protocol is '{coherence_protocol_required.name}'."
+        msg += "Supported protocols: "
+        for protocol in supported_protocols:
+            msg += f"{os.linesep}{protocol.name}"
+        raise Exception(_get_exception_str(msg=msg))
 
     if kvm_required and not kvm_available:
         raise Exception(