gem5.simulate.exit_handler module

class gem5.simulate.exit_handler.AfterBootExitHandler(payload: Dict[str, str])

Bases: ExitHandler

get_handler_description()

class gem5.simulate.exit_handler.AfterBootScriptExitHandler(payload: Dict[str, str])

Bases: ExitHandler

get_handler_description()

class gem5.simulate.exit_handler.CheckpointExitHandler(payload: Dict[str, str])

Bases: ExitHandler

class gem5.simulate.exit_handler.ClassicGeneratorExitHandler(payload: Dict[str, str])

Bases: ExitHandler

A handler designed to be the default for the classic exit event.

on_exit_event usage notes

With Generators

The on_exit_event parameter specifies a Python generator for each exit event. next(<generator>) is run each time an exit event. The generator may yield a boolean. If this value of this boolean is True the Simulator run loop will exit, otherwise the Simulator run loop will continue execution. If the generator has finished (i.e. a StopIteration exception is thrown when next(<generator>) is executed), then the default behavior for that exit event is run.

As an example, a user may specify their own exit event setup like so:

def unique_exit_event():
    processor.switch()
    yield False
    m5.stats.dump()
    yield False
    yield True

simulator = Simulator(
    board=board
    on_exit_event = {
        ExitEvent.Exit : unique_exit_event(),
    },
)

This will execute processor.switch() the first time an exit event is encountered, will dump gem5 statistics the second time an exit event is encountered, and will terminate the Simulator run loop the third time.

With a list of functions

Alternatively, instead of passing a generator per exit event, a list of functions may be passed. Each function must take no mandatory arguments and return True if the simulator is to exit after being called.

An example:

def stop_simulation() -> bool:
    return True

def switch_cpus() -> bool:
    processor.switch()
    return False

def print_hello() -> None:
    # Here we don't explicitly return a boolean, but the simulator
    # treats a None return as False. Ergo the Simulation loop is not
    # terminated.
    print("Hello")


simulator = Simulator(
    board=board,
    on_exit_event = {
        ExitEvent.Exit : [
            print_hello,
            switch_cpus,
            print_hello,
            stop_simulation
        ],
    },
)

Upon each EXIT type exit event the list will function as a queue, with the top function of the list popped and executed. Therefore, in this example, the first EXIT type exit event will cause print_hello to be executed, and the second EXIT type exit event will cause the switch_cpus function to run. The third will execute print_hello again before finally, on the forth exit event will call stop_simulation which will stop the simulation as it returns False.

With a function

A single function can be passed. In this case every exit event of that type will execute that function every time. The function should not accept any mandatory parameters and return a boolean specifying if the simulation loop should end after it is executed. An example:

def print_hello() -> bool:
    print("Hello")
    return False
simulator = Simulator(
    board=board,
    on_exit_event = {
        ExitEvent.Exit : print_hello
    },
)

The above will print “Hello” on every Exit type Exit Event. As the function returns False, the simulation loop will not end on these events.

Exit Event defaults

Each exit event has a default behavior if none is specified by the user. These are as follows:

• ExitEvent.EXIT: exit simulation

• ExitEvent.CHECKPOINT: take a checkpoint

• ExitEvent.FAIL : exit simulation

• ExitEvent.SWITCHCPU: call switch on the processor

• ExitEvent.WORKBEGIN: reset stats

• ExitEvent.WORKEND: dump stats

• 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

These generators can be found in the exit_event_generator.py module.

classmethod set_exit_event_map(on_exit_event: Dict[ExitEvent, Generator[bool | None, None, None] | List[Callable] | Callable] | None, expected_execution_order: List[ExitEvent] | None, board: Board | None) → None

class gem5.simulate.exit_handler.ExitHandler(payload: Dict[str, str])

Bases: object

get_handler_description() → str

classmethod get_handler_id() → int

Returns the ID of the exit handler

classmethod get_handler_map() → Dict[str, Type[ExitHandler]]

Returns the mapping of exit handler IDs to handler classes

handle(simulator: Simulator) → bool

class gem5.simulate.exit_handler.ExitHandlerMeta(name, bases, attrs, hypercall_num: int = None)

Bases: ABCMeta

Metaclass for ExitHandler that automatically registers subclasses

class gem5.simulate.exit_handler.KernelBootedExitHandler(payload: Dict[str, str])

Bases: ExitHandler

get_handler_description()

class gem5.simulate.exit_handler.OrchestratorExitHandler(payload: Dict[str, str])

Bases: ExitHandler

class gem5.simulate.exit_handler.ScheduledExitEventHandler(payload: Dict[str, str])

Bases: ExitHandler

A handler designed to be the default for an Exit scheduled to occur at a specified tick. For example, these Exit exits can be triggered through be src/python/m5/simulate.py’s scheduleTickExitFromCurrent and scheduleTickExitAbsolute functions.

It will exit the simulation loop by default.

The justification and scheduled_at_tick methods are provided to give richer information about this schedule exit.

justification() → str | None

Returns the justification for the scheduled exit event.

This information may be passed to when scheduling the event event to remind the user why the event was scheduled, or used in cases where lots of scheduled events are used and there is a need to differentiate them.

Returns “None” if this information was not set.

scheduled_at_tick() → int | None

Returns the tick in which the event was scheduled on (not scheduled to occur, but the tick the event was created).

Returns “None” if this information is not available.

class gem5.simulate.exit_handler.WorkBeginExitHandler(payload: Dict[str, str])

Bases: ExitHandler

get_handler_description()

class gem5.simulate.exit_handler.WorkEndExitHandler(payload: Dict[str, str])

Bases: ExitHandler

get_handler_description()

gem5.simulate.exit_handler.register_exit_handler(hypercall_num: int, func: Callable[[Simulator, dict], bool], description: str) → Type[ExitHandler]

This function registers a new exit handler with a specific hypercall number. Whenever this hypercall is encountered, the provided function will be called with the simulator instance and the payload of the hypercall. The function should return a boolean indicating whether the simulation should exit.

Args:

hypercall_num (int): The hypercall number associated with the exit handler. func (Callable[[“Simulator”, dict], bool]): A callable that takes a Simulator

instance and a dictionary containing the payload of the hypercall, and returns a boolean indicating whether the simulation should exit.

description (str): A description of the exit handler.

Returns:

Type[ExitHandler]: A new ExitHandler class with the specified hypercall number, processing function, and description.