gem5.simulate.simulator module

class gem5.simulate.simulator.Simulator(board: AbstractBoard, full_system: bool | None = None, on_exit_event: Dict[ExitEvent, Generator[bool | None, None, None] | List[Callable] | Callable] | None = None, expected_execution_order: List[ExitEvent] | None = None, checkpoint_path: Path | None = None, max_ticks: int | None = 18446744073709551615, id: int | None = None)

Bases: object

This Simulator class is used to manage the execution of a gem5 simulation.

Example

Examples using the Simulator class can be found under configs/example/gem5_library.

The most basic run would be as follows:

simulator = Simulator(board=board)
 simulator.run()

This will run a simulation and execute default behavior for exit events.

add_json_stats_output(path: str) → None

This function is used to set an output location for JSON. If specified, when stats are dumped they will be output to this location as a JSON file, in addition to any other stats’ output locations specified.

Parameters:

path – That path in which the JSON should be output to.

add_text_stats_output(path: str) → None

This function is used to set an output location for text stats. If specified, when stats are dumped they will be output to this location as a text file file, in addition to any other stats’ output locations specified.

Parameters:

path – That path in which the file should be output to.

get_current_tick() → int

Returns the current tick.

get_exit_event_id_log() → Dict[int, str]

Returns a dictionary mapping tick at which an exit event was encountered to the exit event description.

get_exit_handler_id_map() → Dict[int, Type[ExitHandler]]

Returns the exit handler ID map. This is a dictionary mapping exit event IDs to the ExitEvent handler class responsible for handling them.

get_hypercall_id() → int

Returns the hypercall ID.

get_id() → str | None

Returns the ID of the simulation. This is particularly useful when running multiple simulations in parallel. The ID can be unique and descriptive of the simulation. It is set via the contructor or the set_id function. None if not set by either.

get_instruction_count() → int

Returns the number of instructions executed by all cores.

Note: This total is the sum since the last call to reset stats.

get_last_exit_event_cause() → str

Returns the last exit event cause.

get_last_exit_event_code() → int

Returns the last exit event status code

get_max_ticks() → int

get_roi_ticks() → List[int]

Returns a list of the tick counts for every ROI encountered (specified as a region of code between a Workbegin and Workend exit event).

get_simstats() → SimStat

Obtains the SimStat of the current simulation.

Raises:

Exception – An exception is raised if this function is called before run(). The board must be initialized before obtaining statistics.

get_stats() → Dict

Obtain the current simulation statistics as a Dictionary, conforming to a JSON-style schema.

Raises:

Exception – An exception is raised if this function is called before run(). The board must be initialized before obtaining statistics.

get_tick_stopwatch() → List[Tuple[ExitEvent, int]]

Returns a list of tuples, which each tuple specifying an exit event and the ticks at that event.

get_workload() → WorkloadResource

Returns the workload of the board.

override_outdir(new_outdir: Path) → None

This function can be used to override the output directory locatiomn Assiming the path passed is valid, the directory will be created and set as the new output directory, thus overriding what was set at the gem5 command line. Is there fore advised this function is used with caution. Its primary use is for swaning multiple gem5 processes from a gem5 process to allow the child processes their own output directory.

Parameters:

new_outdir – The new output directory to be used instead of that set at the gem5 command line.

run(max_ticks: int | None = None) → None

This function will start or continue the simulator run and handle exit events accordingly.

Parameters:

max_ticks – The maximum number of ticks to execute per simulation run. If this max_ticks value is met, a MAX_TICK exit event is received, if another simulation exit event is met the tick count is reset. This is the **maximum number of ticks per simulation run.

save_checkpoint(checkpoint_dir: Path) → None

This function will save the checkpoint to the specified directory.

Parameters:

checkpoint_dir – The path to the directory where the checkpoint will be saved.

schedule_max_insts(inst: int) → None

Schedule a MAX_INSTS exit event when any thread in any core reaches the given number of instructions.

Parameters:

insts – A number of instructions to run to.

schedule_simpoint(simpoint_start_insts: List[int]) → None

Schedule SIMPOINT_BEGIN exit events

Warning

SimPoints only work with one core.

Parameters:

simpoint_start_insts – A list of number of instructions indicating the starting point of the SimPoints.

set_id(id: str) → None

Set the ID of the simulator.

As, in the caae of multisim, this ID will be used to create an output subdirectory, there needs to be rules on what an ID can be. For now, this function encoures that IDs can only be alphanumeric characters with underscores and dashes. Uunderscores and dashes cannot be at the start or end of the ID and the ID must start with at least one letter.

Parameters:

id – The ID of the simulator.

set_max_ticks(max_tick: int) → None

Set the absolute (not relative) maximum number of ticks to run the simulation for. This is the maximum number of ticks to run the simulation for before exiting with a MAX_TICK exit event.

show_exit_event_messages() → None

Show exit event messages. This will print the exit event messages to the console.

switch_processor() → None

Switch the processor. This is a convenience function to call the processor’s switch function.