Using exit events with the new disk images in gem5 resources.

[Harshil2107]

What are Exit Events?

In gem5, exit events are a way to exit the simulation loop. Exit events can be used to perform operations outside the simulation when triggered, such as resetting stats, switching CPU types, dumping stats, taking checkpoints, etc. By default, the simulation will exit when an exit event is triggered, but we can modify this behavior by writing our own exit event handlers.

Writing Custom Exit Event Handlers

gem5 expects exit event handlers to be generators, and we can override them by passing our custom generator to the simulator object. Let’s say we have a resource that throws an m5 exit at some point during execution. Instead of stopping and exiting the simulation, we want to switch processors (assuming we are using the SimpleSwitchableProcessor). To do this, we would need to import ExitEvent from gem5.simulate.exit_event:

from gem5.simulate.exit_event import ExitEvent

Now, let's write our handler:

def exit_event_handler():
    # Switch the CPU type
    print("Switching CPU types")
    processor.switch()
    yield False  # Continue the simulation

This handler will print a message and switch CPU types. We yield False because we want the simulation to continue.

To add our handler to the simulator object, we do the following:

simulator = Simulator(
    board=board,
    on_exit_event={
        # Override the default behavior for the first m5 exit event
        ExitEvent.EXIT: exit_event_handler()
    },
)

NOTE: We pass a call to our handler (exit_event_handler()) and not the handler itself (exit_event_handler) to the simulator.

Exit Events Thrown by the New Disk Images

The new disk images on gem5 Resources generate various exit events, such as m5 exit, m5 workbegin, and m5 workend at different stages of the boot process. The generic Ubuntu disk images, like x86-ubuntu-22.04-img, arm-ubuntu-22.04-img, riscv-ubuntu-22.04-img, x86-ubuntu-24.04-img, arm-ubuntu-24.04-img, and riscv-ubuntu-24.04-img, trigger three m5 exit events, which occur at the following points:

• When the kernel is booted and sbin/init is executed.
• After systemd has started, and the after-boot.sh script is executed. The after-boot.sh script either runs a script passed via readfile or drops to an interactive shell if the kernel argument interactive=true is set.
• At the end of the after-boot.sh script, after running the readfile script (if provided). If no script is provided, only the exit is triggered.

All new disk images made after Ubuntu 22.04 on gem5 Resources will also throw these exit events. These disk images have corresponding boot workloads available on gem5 Resources.

In contrast, images like x86-ubuntu-24.04-npb-img and arm-ubuntu-24.04-npb-img generate the same three m5 exit events, but they also trigger m5 workbegin and m5 workend events at the start and end of the Region of Interest (ROI) in the benchmarks being run. The benchmark suites can be found on gem5 Resources at x86-ubuntu-24.04-npb-suite and arm-ubuntu-24.04-npb-suite.

Handling Exit Events Thrown by the Disk Images

To fully boot the above disk images, we need to write an exit event handler to prevent the simulation from ending after the first exit (when the kernel is booted). An example exit event handler that we can use with these disk images would look like this:

def exit_event_handler():
    print("First exit: kernel booted")
    yield False  # gem5 is now executing systemd startup
    print("Second exit: Started `after_boot.sh` script")
    # Switch to Timing CPU before running the script
    print("Switching to Timing CPU")
    processor.switch()
    yield False  # gem5 is now executing the `after_boot.sh` script
    print("Third exit: Finished `after_boot.sh` script")
    yield True  # Simulation ends

Here, we yield False until the readfile script has run. We also switch processors (assuming we are using the SimpleSwitchableProcessor) after the second exit event.

If using the NPB disk images, we must also handle the m5 workbegin and m5 workend exit events. A handler for those two events would look like this:

def handle_workbegin():
    print("Resetting stats at the start of ROI!")
    m5.stats.reset()
    yield False

def handle_workend():
    print("Dumping stats at the end of ROI!")
    m5.stats.dump()
    yield False

These simple handlers reset stats on workbegin and dump stats on workend. To add all three handlers to the simulator, we can use the following:

simulator = Simulator(
    board=board,
    on_exit_event={
        ExitEvent.WORKBEGIN: handle_workbegin(),
        ExitEvent.WORKEND: handle_workend(),
        ExitEvent.EXIT: exit_event_handler(),
    },
)

The above handlers provide examples of how to handle exit events, allowing the disk image to fully boot and run a readfile script.