stdlib,tests: Modify Simulator.run to return exit event obj

This gives the user access to the returned `GlobalSimLoopExitEvent`
object on the Python level. This allows managing of exit events at the
Python configuration script (assuming they aren't handled by the `run`
function by user-specified or default Exit Event generators/functions.

Tests have been updated to check this behavior.

Change-Id: I6de71c25acb335f7e89dcb8ca80656b407207c07

src/python/gem5/simulate/simulator.py

@@ -44,6 +44,8 @@
 from m5.stats import addStatVisitor
 from m5.util import warn
 
+from _m5.event import GlobalSimLoopExitEvent
+
 from ..components.boards.abstract_board import AbstractBoard
 from ..components.processors.switchable_processor import SwitchableProcessor
 from .exit_event import ExitEvent
@@ -557,10 +559,12 @@ def _instantiate(self) -> None:
             # any final things.
             self._board._post_instantiate()
 
-    def run(self, max_ticks: int = m5.MaxTick) -> None:
+    def run(self, max_ticks: int = m5.MaxTick) -> GlobalSimLoopExitEvent:
         """
         This function will start or continue the simulator run and handle exit
-        events accordingly.
+        events accordingly. If the the exit event is handled by returning to
+        the Python code (as opposed to re-entering the Simulation loop) the
+        function will return the GlobalSimLoopExitEvent object.
 
         :param max_ticks: The maximum number of ticks to execute per simulation
                           run. If this ``max_ticks`` value is met, a ``MAX_TICK``
@@ -630,9 +634,10 @@ def run(self, max_ticks: int = m5.MaxTick) -> None:
             self._exit_event_count += 1
 
             # If the generator returned True we will return from the Simulator
-            # run loop. In the case of a function: if it returned True.
+            # run loop with the ExitEvent. (In the case of a function, instead
+            # of a generator, : if it also returned True).
             if exit_on_completion:
-                return
+                return self._last_exit_event
 
     def save_checkpoint(self, checkpoint_dir: Path) -> None:
         """

tests/gem5/stdlib/configs/simulator_exit_event_run.py

@@ -158,4 +158,10 @@ def lone_function() -> bool:
         ExitEvent.EXIT: exit_event_handler,
     },
 )
-simulator.run()
+
+# The simulator's `run` method returns the exit event object triggered the
+# termination of the `run` method. Its state is printed below.
+exit_event_obj = simulator.run()
+
+print(f"Exit event object cause: '{exit_event_obj.getCause()}'")
+print(f"Exit event code '{exit_event_obj.getCode()}'")

tests/gem5/stdlib/simulator/ref/simout.txt

@@ -6,3 +6,5 @@ About to exit the simulation for the 2 st/nd/rd/th time
 Handled exit event.
 About to exit the simulation for the 3 st/nd/rd/th time
 Handling the final exit event. We'll exit now.
+Exit event object cause: 'm5_exit instruction encountered'
+Exit event code '0'