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_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_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.

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.