Running gem5

M5 uses script files to specify simulated system configurations and simulation options. Running M5 is as simple as giving the name of a script file (ending in '.py') as a command-line argument.

The script file documentation page (Configuration Files Explained) has details on script file format and interpretation. The easiest way to get started is to use an existing script file. A variety of script files are provided in the src/configs directory.

Simluation options can be specified directly on the command line as "--<option>=<value>". From the simulator's perspective, setting options in this fashion is indistinguishable from specifying them in a script file. A few options typically specified on the command line instead of in a script file are:

• --traceflags="SomeFlagString" - turn on event tracing for the specified classes of simulation events
• --tracestart=<start_cycle> - cycle at which the traces indicated by the trace.flags param are to begin dumping

Running m5 with the "-h" flag prints a help message, including basic command-line parameters. Here is what it looks like:

% build/ALPHA_SE/m5.debug -h
Usage:
m5.debug [-p <path>] [-i ] [-h] <config file>

 -p, --path <path>  prepends <path> to PYTHONPATH instead of using
                    built-in zip archive.  Useful when developing/debugging
                    changes to built-in Python libraries, as the new Python
                    can be tested without building a new m5 binary.

 -i, --interactive  forces entry into interactive mode after the supplied
                    script is executed (just like the -i option to  the
                    Python interpreter).

 -h                 Prints this help

 <configfile>       config file name which ends in .py. (Normally you can
                    run <configfile> --help to get help on that config files
                    parameters.

Additionally, running m5 with a config file and the "-h" flag prints out all options that are available. Here is a sample:

% build/ALPHA_SE/m5.debug configs/test/test.py -h
usage: test.py [options]

options:
  --outdir=OUTDIR
  --traceflags=TRACEFLAGS
  --tracestart=TRACESTART
  --tracefile=TRACEFILE
  --nopcsymbol          Disable PC symbols in trace output
  --noprintcycle        Don't print cycle numbers in trace output
  --noprintopclass      Don't print op class type in trace output
...