stdlib,python: Allow setting of to tick exits via m5

This commit adds the following functions to the `m5` python module:

- setMaxTick(tick) -> None
- getMaxTick() -> int
- getTicksUntilMax() -> int
- scheduleTickExitFromCurrent(tick, exit_string) -> None
- scheduleTickExitAbsolute(tick, exit_string) -> None

Until this patch the only way to set an exit at a particular tick was
via `simulate.run` which would reschedule the maximum tick. This
functionality has been explicity exposed via the new `setMaxTick`
function. However, as this is only rescheduling the maximum tick, it
stops scheduling exits at multiple different ticks.

To get around this problem the `scheduleTickExit` functions have been
added. These allow a user to schedule multiple exit events. The
functions contain a `exit_string` parameter that provides the string
the simulator is to return when the specified tick is met. By default
this string is "Tick exit reached" which is used by the stdlib
Simulator module to declare a new `SCHEDULED_TICK` exit event (Note:
this has been deliberatly kept seperate from the `MAX_TICK` exit event.
This commit serves as an attempt to decouple these are two concepts).

Tests are provided in this patch to ensure these new functions work as
intended.

Additional notes:
- The `simulate` function has been fixed to match the documentation. If
  the `num_cycles` is -1 then the maximum ticks is set to MaxTicks.
  Otherwise the max ticks is set to `curTicks() + num_cycles`. The
  functionality of this function will remain unchanged to the end-user.
- Full integration into the Simulator module is not complete as of this
  patch. Users must us the m5 python module to set these exit events.

Change-Id: I6c92b31dd409dc866152224600ea8166cfcba38b
Issue-on: https://gem5.atlassian.net/browse/GEM5-1131
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/66231
Reviewed-by: Jason Lowe-Power <power.jg@gmail.com>
Tested-by: kokoro <noreply+kokoro@google.com>
Maintainer: Jason Lowe-Power <power.jg@gmail.com>
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/66331
Reviewed-by: Bobby Bruce <bbruce@ucdavis.edu>
Maintainer: Bobby Bruce <bbruce@ucdavis.edu>

src/python/gem5/simulate/exit_event.py

@@ -42,6 +42,7 @@ class ExitEvent(Enum):
     SWITCHCPU = "switchcpu"  # An exit needed to switch CPU cores.
     FAIL = "fail"  # An exit because the simulation has failed.
     CHECKPOINT = "checkpoint"  # An exit to load a checkpoint.
+    SCHEDULED_TICK = "scheduled tick exit"
     MAX_TICK = "max tick"  # An exit due to a maximum tick value being met.
     USER_INTERRUPT = (  # An exit due to a user interrupt (e.g., cntr + c)
         "user interupt"
@@ -75,6 +76,8 @@ class ExitEvent(Enum):
             return ExitEvent.EXIT
         elif exit_string == "simulate() limit reached":
             return ExitEvent.MAX_TICK
+        elif exit_string == "Tick exit reached":
+            return ExitEvent.SCHEDULED_TICK
         elif exit_string == "switchcpu":
             return ExitEvent.SWITCHCPU
         elif exit_string == "m5_fail instruction encountered":

src/python/gem5/simulate/simulator.py

@@ -157,6 +157,7 @@ class Simulator:
             * ExitEvent.WORKEND: exit simulation
             * ExitEvent.USER_INTERRUPT: exit simulation
             * ExitEvent.MAX_TICK: exit simulation
+            * ExitEvent.SCHEDULED_TICK: exit simulation
             * ExitEvent.SIMPOINT_BEGIN: reset stats
             * ExitEvent.MAX_INSTS: exit simulation
 
@@ -197,6 +198,7 @@ class Simulator:
             )(),
             ExitEvent.USER_INTERRUPT: exit_generator(),
             ExitEvent.MAX_TICK: exit_generator(),
+            ExitEvent.SCHEDULED_TICK: exit_generator(),
             ExitEvent.SIMPOINT_BEGIN: warn_default_decorator(
                 reset_stats_generator,
                 "simpoint begin",

src/python/m5/simulate.py

@@ -54,7 +54,7 @@ from . import params
 from m5.util.dot_writer import do_dot, do_dvfs_dot
 from m5.util.dot_writer_ruby import do_ruby_dot
 
-from .util import fatal
+from .util import fatal, warn
 from .util import attrdict
 
 # define a MaxTick parameter, unsigned 64 bit
@@ -205,6 +205,63 @@ def simulate(*args, **kwargs):
     return sim_out
 
 
+def setMaxTick(tick: int) -> None:
+    """Sets the maximum tick the simulation may run to. When when using the
+    stdlib simulator module, reaching this max tick triggers a
+    `ExitEvent.MAX_TICK` exit event.
+
+    :param tick: the maximum tick (absolute, not relative to the current tick).
+    """
+    if tick <= curTick():
+        warn("Max tick scheduled for the past. This will not be triggered.")
+    _m5.event.setMaxTick(tick=tick)
+
+
+def getMaxTick() -> int:
+    """Returns the current maximum tick."""
+    return _m5.event.getMaxTick()
+
+
+def getTicksUntilMax() -> int:
+    """Returns the current number of ticks until the maximum tick."""
+    return getMaxTick() - curTick()
+
+
+def scheduleTickExitFromCurrent(
+    ticks: int, exit_string: str = "Tick exit reached"
+) -> None:
+    """Schedules a tick exit event from the current tick. I.e., if ticks == 100
+    then an exit event will be scheduled at tick `curTick() + 100`.
+
+    The default `exit_string` value is used by the stdlib Simulator module to
+    declare this exit event as `ExitEvent.SCHEDULED_TICK`.
+
+    :param ticks: The simulation ticks, from `curTick()` to schedule the exit
+    event.
+    :param exit_string: The exit string to return when the exit event is
+    triggered.
+    """
+    scheduleTickExitAbsolute(tick=ticks + curTick(), exit_string=exit_string)
+
+
+def scheduleTickExitAbsolute(
+    tick: int, exit_string: str = "Tick exit reached"
+) -> None:
+    """Schedules a tick exit event using absolute ticks. I.e., if tick == 100
+    then an exit event will be scheduled at tick 100.
+
+    The default `exit_string` value is used by the stdlib Simulator module to
+    declare this exit event as `ExitEvent.SCHEDULED_TICK`.
+
+    :param tick: The absolute simulation tick to schedule the exit event.
+    :param exit_string: The exit string to return when the exit event is
+    triggered.
+    """
+    if tick <= curTick():
+        warn("Tick exit scheduled for the past. This will not be triggered.")
+    _m5.event.scheduleTickExit(tick=tick, exit_string=exit_string)
+
+
 def drain():
     """Drain the simulator in preparation of a checkpoint or memory mode
     switch.

src/python/pybind11/event.cc

@@ -107,6 +107,10 @@ pybind_init_event(py::module_ &m_native)
 
     m.def("simulate", &simulate,
           py::arg("ticks") = MaxTick);
+    m.def("setMaxTick", &set_max_tick, py::arg("tick"));
+    m.def("getMaxTick", &get_max_tick, py::return_value_policy::copy);
+    m.def("scheduleTickExit", &schedule_tick_exit, py::arg("tick"),
+        py::arg("exit_string"));
     m.def("terminateEventQueueThreads", &terminateEventQueueThreads);
     m.def("exitSimLoop", &exitSimLoop);
     m.def("getEventQueue", []() { return curEventQueue(); },

src/sim/simulate.cc

@@ -180,16 +180,14 @@ struct DescheduleDeleter
 };
 
 /** Simulate for num_cycles additional cycles.  If num_cycles is -1
- * (the default), do not limit simulation; some other event must
- * terminate the loop.  Exported to Python.
+ * (the default), we simulate to MAX_TICKS unless the max ticks has been set
+ * via the 'set_max_tick' function prior. This function is exported to Python.
  * @return The SimLoopExitEvent that caused the loop to exit.
  */
 GlobalSimLoopExitEvent *
 simulate(Tick num_cycles)
 {
     std::unique_ptr<GlobalSyncEvent, DescheduleDeleter> quantum_event;
-    const Tick exit_tick = num_cycles < MaxTick - curTick() ?
-                                        curTick() + num_cycles : MaxTick;
 
     inform("Entering event queue @ %d.  Starting simulation...\n", curTick());
 
@@ -197,11 +195,22 @@ simulate(Tick num_cycles)
         simulatorThreads.reset(new SimulatorThreads(numMainEventQueues));
 
     if (!simulate_limit_event) {
-        simulate_limit_event = new GlobalSimLoopExitEvent(
-            mainEventQueue[0]->getCurTick(),
-            "simulate() limit reached", 0);
+        // If the simulate_limit_event is not set, we set it to MaxTick.
+        set_max_tick(MaxTick);
+    }
+
+    if (num_cycles != -1) {
+        // If the user has specified an exit event after X cycles, do so here.
+        // Note: This will override any prior set max_tick behaviour (such as
+        // that above when it is set to MAxTick).
+        const Tick max_tick = num_cycles < MaxTick - curTick() ?
+                                    curTick() + num_cycles : MaxTick;
+
+        // This is kept to `set_max_tick` instead of `schedule_tick_exit` to
+        // preserve backwards functionality. It may be better to deprecate this
+        // behaviour at some point in favor of `schedule_tick_exit`.
+        set_max_tick(max_tick);
     }
-    simulate_limit_event->reschedule(exit_tick);
 
     if (numMainEventQueues > 1) {
         fatal_if(simQuantum == 0,
@@ -231,6 +240,34 @@ simulate(Tick num_cycles)
     return global_exit_event;
 }
 
+void set_max_tick(Tick tick)
+{
+    if (!simulate_limit_event) {
+        simulate_limit_event = new GlobalSimLoopExitEvent(
+            mainEventQueue[0]->getCurTick(),
+            "simulate() limit reached", 0);
+    }
+    simulate_limit_event->reschedule(tick);
+}
+
+
+Tick get_max_tick()
+{
+    if (!simulate_limit_event) {
+        /* If the GlobalSimLoopExitEvent has not been setup, the maximum tick
+         * is `MaxTick` as declared in "src/base/types.hh".
+         */
+        return MaxTick;
+    }
+
+    return simulate_limit_event->when();
+}
+
+void schedule_tick_exit(Tick tick, std::string exit_string)
+{
+    new GlobalSimLoopExitEvent(tick, exit_string, 0);
+}
+
 void
 terminateEventQueueThreads()
 {

src/sim/simulate.hh

@@ -45,7 +45,37 @@ namespace gem5
 
 class GlobalSimLoopExitEvent;
 
-GlobalSimLoopExitEvent *simulate(Tick num_cycles = MaxTick);
+GlobalSimLoopExitEvent *simulate(Tick num_cycles = -1);
+
+/**
+ * @brief Set the maximum tick.
+ *
+ * This function will schedule, or reschedule, the maximum tick for the
+ * simulation.
+ *
+ * This will setup the GlobalSimLoopExitEvent if it does not already exist.
+ *
+ * @param tick The maximum tick.
+ */
+void set_max_tick(Tick tick);
+
+/**
+ * @brief Get the maximum simulation tick.
+ *
+ *
+ * @returns The maximum simulation tick.
+ */
+Tick get_max_tick();
+
+/**
+ * @brief Schedule an exit event at a particular tick.
+ *
+ * Schedule a tick with a particular exit string.
+ *
+ * @param tick The tick at which the simulation loop should exit.
+ * @param exit_string The exit string explaining the exit.
+ */
+void schedule_tick_exit(Tick tick, std::string exit_string);
 
 /**
  * Terminate helper threads when running in parallel mode.