stdlib: Add beta simulate module to the gem5 stdlib

This module is used to semi-automate the running of gem5 simulation,
mostly by handling exit events automatically and removing instantiation
boilerplate code.

NOTE: This module is still in beta.

Change-Id: I4706119478464efcf4d92e3a1da05bddd0953b6a
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/50753
Maintainer: Bobby Bruce <bbruce@ucdavis.edu>
Reviewed-by: Jason Lowe-Power <power.jg@gmail.com>
Tested-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Bobby Bruce <bbruce@ucdavis.edu>

configs/example/gem5_library/arm-hello.py

@@ -41,9 +41,6 @@ scons build/ARM/gem5.opt
 ```
 """
 
-import m5
-from m5.objects import Root
-
 from gem5.isas import ISA
 from gem5.utils.requires import requires
 from gem5.resources.resource import Resource
@@ -52,6 +49,7 @@ from gem5.components.processors.cpu_types import CPUTypes
 from gem5.components.boards.simple_board import SimpleBoard
 from gem5.components.cachehierarchies.classic.no_cache import NoCache
 from gem5.components.processors.simple_processor import SimpleProcessor
+from gem5.simulate.simulator import Simulator
 
 # This check ensures the gem5 binary is compiled to the ARM ISA target. If not,
 # an exception will be thrown.
@@ -89,12 +87,13 @@ board.set_se_binary_workload(
     Resource("arm-hello64-static")
 )
 
-# Lastly we setup the root, instantiate the design, and run the simulation.
-root = Root(full_system=False, system=board)
+# Lastly we run the simulation.
+simulator = Simulator(board=board, full_system=False)
+simulator.run()
 
-m5.instantiate()
-
-exit_event = m5.simulate()
 print(
-    "Exiting @ tick {} because {}.".format(m5.curTick(), exit_event.getCause())
+    "Exiting @ tick {} because {}.".format(
+        simulator.get_current_tick(),
+        simulator.get_last_exit_event_cause(),
+    )
 )

configs/example/gem5_library/riscv-fs.py

@@ -39,9 +39,6 @@ Characteristics
   password: `root`)
 """
 
-import m5
-from m5.objects import Root
-
 from gem5.components.boards.riscv_board import RiscvBoard
 from gem5.components.memory import SingleChannelDDR3_1600
 from gem5.components.processors.simple_processor import SimpleProcessor
@@ -53,6 +50,7 @@ from gem5.components.processors.cpu_types import CPUTypes
 from gem5.isas import ISA
 from gem5.utils.requires import requires
 from gem5.resources.resource import Resource
+from gem5.simulate.simulator import Simulator
 
 # Run a check to ensure the right version of gem5 is being used.
 requires(isa_required=ISA.RISCV)
@@ -84,13 +82,10 @@ board.set_kernel_disk_workload(
                    disk_image=Resource("riscv-disk-img"),
 )
 
-root = Root(full_system=True, system=board)
-
-m5.instantiate()
-
+simulator = Simulator(board=board)
 print("Beginning simulation!")
 # Note: This simulation will never stop. You can access the terminal upon boot
 # using m5term (`./util/term`): `./m5term localhost <port>`. Note the `<port>`
 # value is obtained from the gem5 terminal stdout. Look out for
 # "system.platform.terminal: Listening for connections on port <port>".
-exit_event = m5.simulate()
+simulator.run()

configs/example/gem5_library/x86-ubuntu-run-with-kvm.py

@@ -35,14 +35,11 @@ Usage
 -----
 
 ```
-scons build/X86_MESI_Two_Level/gem5.opt
+scons build/X86/gem5.opt
 ./build/X86/gem5.opt configs/example/gem5_library/x86-ubuntu-run-with-kvm.py
 ```
 """
 
-import m5
-from m5.objects import Root
-
 from gem5.utils.requires import requires
 from gem5.components.boards.x86_board import X86Board
 from gem5.components.memory.single_channel import SingleChannelDDR3_1600
@@ -53,6 +50,8 @@ from gem5.components.processors.cpu_types import CPUTypes
 from gem5.isas import ISA
 from gem5.coherence_protocol import CoherenceProtocol
 from gem5.resources.resource import Resource
+from gem5.simulate.simulator import Simulator
+from gem5.simulate.exit_event import ExitEvent
 
 # This runs a check to ensure the gem5 binary is compiled to X86 and to the
 # MESI Two Level coherence protocol.
@@ -126,19 +125,14 @@ board.set_kernel_disk_workload(
     readfile_contents=command,
 )
 
-
-root = Root(full_system=True, system=board)
-root.sim_quantum = int(1e9)  # sim_quantum must be st if KVM cores are used.
-
-m5.instantiate()
-
-# This first stretch of the simulation runs using the KVM cores. In this setup
-# this will terminate until Ubuntu boot is complete.
-m5.simulate()
-
-# This will switch from the KVM cores to the Timing cores.
-processor.switch()
-
-# This final stretch of the simulation will be run using the Timing cores. In
-# this setup an echo statement will be executed prior to exiting.
-m5.simulate()
+simulator = Simulator(
+    board=board,
+    on_exit_event={
+        # Here we want override the default behavior for the first m5 exit
+        # exit event. Instead of exiting the simulator, we just want to
+        # switch the processor. The 2nd m5 exit after will revert to using
+        # default behavior where the simulator run will exit.
+        ExitEvent.EXIT : (func() for func in [processor.switch]),
+    },
+)
+simulator.run()

configs/example/gem5_library/x86-ubuntu-run.py

@@ -44,11 +44,10 @@ scons build/X86/gem5.opt
 ```
 """
 
-import m5
-from m5.objects import Root
-
-from gem5.resources.resource import Resource
 from gem5.prebuilt.demo.x86_demo_board import X86DemoBoard
+from gem5.resources.resource import Resource
+from gem5.simulate.simulator import Simulator
+
 
 # Here we setup the board. The prebuilt X86DemoBoard allows for Full-System X86
 # simulation.
@@ -62,6 +61,5 @@ board.set_kernel_disk_workload(
     disk_image=Resource("x86-ubuntu-img"),
 )
 
-root = Root(full_system=True, system=board)
-m5.instantiate()
-m5.simulate()
+simulator = Simulator(board=board)
+simulator.run()