Package: gem5art-run
gem5art run packageThis package contains Python objects to wrap gem5 runs/experiments.Please cite thegem5art paperwhen using the gem5art packages.
This documentation can be found on thegem5 websiteEach gem5 experiment is wrapped inside a run object.
These run objects contain all of the information required to execute the gem5 experiments and can optionally be executed via the gem5art tasks library (or manually with therun()function.).gem5Run interacts with the Artifact class of gem5art to ensure reproducibility of gem5 experiments and also stores the current gem5Run object and the output results in the database for later analysis.SE and FS mode runsNext are two methods (for SE (system-emulation) and FS (full-system) modes of gem5) from gem5Run class which give an idea of the required arguments from a user's perspective to create a gem5Run object:@classmethoddefcreateSERun(cls,name:str,gem5_binary:str,run_script:str,outdir:str,gem5_artifact:Artifact,gem5_git_artifact:Artifact,run_script_git_artifact:Artifact,*params:str,timeout:int=60*15)->'gem5Run':.......@classmethoddefcreateFSRun(cls,name:str,gem5_binary:str,run_script:str,outdir:str,gem5_artifact:Artifact,gem5_git_artifact:Artifact,run_script_git_artifact:Artifact,linux_binary:str,disk_image:str,linux_binary_artifact:Artifact,disk_image_artifact:Artifact,*params:str,timeout:int=60*15)->'gem5Run':.......For the user it is important to understand different arguments passed to run objects:name: name of the run, can act as a tag to search the database to find the required runs (it is expected that user will use a unique name for different experiments)gem5_binary: path to the actual gem5 binary to be usedrun_script: path to the python run script that will be used with gem5 binaryoutdir: path to the directory where gem5 results should be writtengem5_artifact: gem5 binary git artifact objectgem5_git_artifact: gem5 source git repo artifact objectrun_script_git_artifact: run script artifact objectlinux_binary(only full-system): path to the actual linux binary to be used (used by run script as well)disk_image(only full-system): path to the actual disk image to be used (used by run script as well)linux_binary_artifact(only full-system): linux binary artifact objectdisk_image_artifact(only full-system): disk image artifact objectparams: other params to be passed to the run scripttimeout: longest time in seconds for which the current gem5 job is allowed to executeThe artifact parameters (gem5_artifact,gem5_git_artifact, andrun_script_git_artifact) are used to ensure this is reproducible run.
Apart from the above mentioned parameters, gem5Run class also keeps track of other features of a gem5 run e.g., the start time, the end time, the current status of gem5 run, the kill reason (if the run is finished), etc.While the user can write their own run script to use with gem5 (with any command line arguments), currently when agem5Runobject is created for a full-system experiment usingcreateFSRunmethod, it is assumed that the path to thelinux_binaryanddisk_imageis passed to the run script on the command line (as arguments of thecreateFSRunmethod).Running an experimentThegem5Runobject has everything needed to run one gem5 execution.
Normally, this will be performed by using the gem5arttaskspackage.
However, it is also possible to manually execute a gem5 run.Therunfunction executes the gem5 experiment.
It takes two optional parameters: a task associated with the run for bookkeeping and an optional directory to execute the run in.Therunfunction executes the gem5 binary by usingPopen.
This creates another process to execute gem5.
Therunfunction isblockingand does not return until the child process has completed.While the child process is running, every 5 seconds the parent python process will update the status in theinfo.jsonfile.Theinfo.jsonfile is the serializedgem5runobject which contains all of the run information and the current status.gem5Runobjects have 7 possible status states.
These are currently simple strings stored in thestatusproperty.Created: The run has been created. This is set in the constructor when eithercreateSRRunorcreateFSRunis called.Begin run: Whenrun()is called, after the database is checked, we enter theBegin runstate.Failed artifact check for ...: The status is set to this when the artifact check failsSpawning: Next, just beforePopenis called, the run enters theSpawningstateRunning: Once the parent process begins spinning waiting for the child to finish, the run enters theRunningstate.Finished: When the child finished with exit code0, the run enters theFinishedstate.Failed: When the child finished with a non-zero exit code, the run enters theFailedstate.Run Already in the DatabaseWhen starting a run with gem5art, it might complain that the run already exists in the database.
Basically, before launching a gem5 job, gem5art checks if this run matches an existing run in the database.
In order to uniquely identify a run, a single hash is made out of:the runscriptthe parameters passed to the runscriptthe artifacts of the run object which, for an SE run, include: gem5 binary artifact, gem5 source git artifact, run script (experiments repo) artifact. For an FS run, the list of artifacts also include linux binary artifact and disk image artifacts in addition to the artifacts of an SE run.If this hash already exists in the database, gem5art will not launch a new job based on this run object as a run with same parameters would have already been executed.
In case, user still wants to launch this job, the user will have to remove the existing run object from the database.Searching the Database to find RunsUtility scriptgem5art provides the utilitygem5art-getrunsto search the database and retrieve runs.
Based on the parameters,gem5art-getrunswill dump the results into a file in the json format.usage: gem5art-getruns [-h] [--fs-only] [--limit LIMIT] [--db-uri DB_URI]
                       [-s SEARCH_NAME]
                       filename

Dump all runs from the database into a json file

positional arguments:
  filename              Output file name

optional arguments:
  -h, --help            show this help message and exit
  --fs-only             Only output FS runs
  --limit LIMIT         Limit of the number of runs to return. Default: all
  --db-uri DB_URI       The database to connect to. Default
                        mongodb://localhost:27017
  -s SEARCH_NAME, --search_name SEARCH_NAME
                        Query for the name fieldManually searching the databaseOnce you start running the experiments with gem5 and want to know the status of those runs, you can look at the gem5Run artifacts in the database.
For this purpose, gem5art provides a methodgetRuns, which you can use as follows:importgem5art.runfromgem5art.artifactimportgetDBConnectiondb=getDBConnection()foriingem5art.run.getRuns(db,fs_only=False,limit=100):print(i)The documentation ongetRunsis available at the bottom of this page.Searching the Database to find Runs with Specific NamesAs discussed above, while creating a FS or SE mode Run object, the user has to pass a name field to recognize
a particular set of runs (or experiments).
We expect that the user will take care to use a name string which fully characterizes a set of experiments and can be thought of as aNonce.
For example, if we are running experiments to test linux kernel boot on gem5, we can use a name fieldboot_tests_v1orboot_tests_[month_year](where mont_year correspond to the month and year when the experiments were run).Later on, the same name can be used to search for relevant gem5 runs in the database.
For this purpose, gem5art provides a methodgetRunsByName, which can be used as follow:importgem5art.runfromgem5art.artifactimportgetDBConnectiondb=getDBConnection()foriingem5art.run.getRunsByName(db,name='boot_tests_v1',fs_only=True,limit=100):print(i)The documentation ongetRunsByNameis availablehere.Runs API DocumentationRun
---

.. automodule:: gem5art.run
    :members:
    :undoc-members: