gem5.utils.multisim.multisim module

This module contains the gem5 MultiSim framework. The gem5 MultiSim work functions by allowing a user to specify multiple simulations to run from a single gem5 config script. The MuliSim framework will then run these simulations in parallel using the Python multiprocessing library.

The framework works by having the user add the simulators in a configuration via the add_simulator function, each with a unique, user specified, id. This adds the different simulations to run in parallel to a global list. The MultiSim framework then uses the Python multiprocessing library to run the simulations in parallel by loading the config script as a module in each child process and then selecting the simulation to run via the iid in the global set of scheduled simulators jobs to run. The only difference between the child processes is the id of the simulator.

Important notes

1. You cannot load/instantiate the simulators in the main process. You cannot even load the config script (i.e., import config_script). This means the config script is passed as a string referencing the config script as a module. This script is then passed to the child processes to load.

  1. The config script cannot accept parameters. It must be parameterless.

gem5.utils.multisim.multisim.add_simulator(simulator: Simulator) → None

Add a single simulator to the Multisim. Doing so informs the simulators to run this simulator via multiprocessing.

Note: If this function is not run using the MultiSim module then the user will be prompted to either do so if they desire multiple gem5 processes or to pass the id of the simulator to run. This function will attempt to run the simulation with the id passed as an argument. If such simulation exists the simulation will end without failure (or any simulations having been run).

Parameters:

  • simulator – The simulator to add to the multisim.

  • id – The id of the simulator. This is used to reference the

simulation. This is particularly important when referencing the correct m5out subdirectory.

gem5.utils.multisim.multisim.get_num_processes(config_module_path: Path) → int | None
gem5.utils.multisim.multisim.get_simulator_ids(config_module_path: Path) → list[str]

This is a hack to determine the IDs of the simulations we are to run. The only way we can know is by importing the module, which we can only do in the child processes. We therefore create a child process with the sole purpose of importing the module and returning the IDs via a multiprocessing.Manager dictionary.

This function handles the creation of the multiprocessing.Manager and the multiprocessing.Process. It then waits for the process to finish to then return the ids as a set of strings.

gem5.utils.multisim.multisim.num_simulators() → int

Returns the number of simulators added to the MultiSim.

gem5.utils.multisim.multisim.run(module_path: Path, processes: int | None = None) → None

Run the simulators specified in the module in parallel.

Parameters:

module_path – The path to the module containing the simulators to

run. :param processes: The number of processes to run in parallel. If not specified, the number of available threads will be used.

gem5.utils.multisim.multisim.set_num_processes(num_processes: int) → None

Set the max number of processes to run in parallel.

Parameters:

num_processes – The number of processes to run in parallel.