Difference between revisions of "Running gem5"

From gem5
Jump to: navigation, search
(Restoring from a checkpoint)
(Update kernel repo URL)
 
(38 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
 
== Usage ==
 
== Usage ==
The m5 command line has two parts: (1) the simulator section which includes the simulator executable and its options, and (2) the script section, which includes the script file and its options. The usage is:
+
The gem5 command line has four parts, the gem5 binary, options for the binary, a simulation script, and options for the script. The options that are passed to the gem5 binary and those passed to the script are handled separately, so be sure any options you use are being passed to the right component.
  
 
<pre>
 
<pre>
% m5 [m5 options] <script.py> [script options]
+
% <gem5 binary> [gem5 options] <simulation script> [script options]
 
</pre>
 
</pre>
  
The m5 executable is any of the version you may have built (See [[Compiling M5]]) such as ALPHA_SE/m5.debug or m5.opt, and the [m5 options] part are all of the options that the simulator itself understands. 
+
== gem5 Options ==
 
+
Running gem5 with the "-h" flag prints a help message that includes all of the supported simulator options. Here's a snippet:
=== M5 Options ===
 
Running m5 with the "-h" flag prints a help message that includes all of the supported simulator options. Here's a snippet:
 
  
 
<pre>
 
<pre>
% build/ALPHA_SE/m5.debug -h
+
% build/ALPHA/gem5.debug -h
 
Usage
 
Usage
 
=====
 
=====
   m5.debug [m5 options] script.py [script options]
+
   gem5.debug [gem5 options] script.py [script options]
  
  Copyright (c) 2001-2006 The Regents of The University of Michigan All Rights
+
  Copyright (c) 2001-2008 The Regents of The University of Michigan All Rights
 
Reserved
 
Reserved
 +
gem5 is copyrighted software; use the --copyright option for details.
  
options
+
Options
 
=======
 
=======
 
--version              show program's version number and exit
 
--version              show program's version number and exit
 
--help, -h              show this help message and exit
 
--help, -h              show this help message and exit
--authors, -A          Show author information
+
--build-info, -B        Show build information
 
--copyright, -C        Show full copyright information
 
--copyright, -C        Show full copyright information
 
--readme, -R            Show the readme
 
--readme, -R            Show the readme
--release-notes, -N    Show the release notes
+
--outdir=DIR, -d DIR    Set the output directory to DIR [Default: m5out]
--outdir=DIR, -d DIR    Set the output directory to DIR [Default: .]
+
--redirect-stdout, -r  Redirect stdout (& stderr, without -e) to file
 +
--redirect-stderr, -e  Redirect stderr to file
 +
--stdout-file=FILE      Filename for -r redirection [Default: simout]
 +
--stderr-file=FILE      Filename for -e redirection [Default: simerr]
 
--interactive, -i      Invoke the interactive interpreter after running the
 
--interactive, -i      Invoke the interactive interpreter after running the
 
                         script
 
                         script
Line 37: Line 39:
 
                         script
 
                         script
 
--quiet, -q            Reduce verbosity
 
--quiet, -q            Reduce verbosity
--verbose, -v          Increase verbosity
 
 
...
 
...
 
</pre>
 
</pre>
  
=== Script Options ===
+
The default options that gem5 uses to run can be set by creating an <code>~/.m5/options.py</code> file and placing options that you are interested in there. For example, if you would like to always redirect standard error and out to a file you could add: <code>options.stdout_file=simout</code> to <code>options.py</code>.
 +
 
 +
== Script Options ==
 
The script section of the command line begins with a path to your script file and includes any options that you'd like to pass to that script. Most Example scripts allow you to pass a '-h' or '--help' flag to the script to see script specific options. An example is as follows:
 
The script section of the command line begins with a path to your script file and includes any options that you'd like to pass to that script. Most Example scripts allow you to pass a '-h' or '--help' flag to the script to see script specific options. An example is as follows:
 
<pre>
 
<pre>
M5 compiled Apr  2 2011 00:57:11
+
gem5 compiled Apr  2 2011 00:57:11
M5 started Apr  3 2011 21:16:02
+
gem5 started Apr  3 2011 21:16:02
M5 executing on zooks
+
gem5 executing on zooks
command line: build/ALPHA_SE/m5.opt configs/example/se.py -h
+
command line: build/ALPHA/gem5.opt configs/example/se.py -h
 
Usage: se.py [options]
 
Usage: se.py [options]
  
Line 71: Line 74:
 
   --num-dirs=NUM_DIRS   
 
   --num-dirs=NUM_DIRS   
 
   --num-l2caches=NUM_L2CACHES
 
   --num-l2caches=NUM_L2CACHES
  --num-l3caches=NUM_L3CACHES
 
 
   --l1d_size=L1D_SIZE   
 
   --l1d_size=L1D_SIZE   
 
   --l1i_size=L1I_SIZE   
 
   --l1i_size=L1I_SIZE   
   --l2_size=L2_SIZE    
+
   --l2_size=L2_SIZE      
  --l3_size=L3_SIZE   
 
 
   --l1d_assoc=L1D_ASSOC
 
   --l1d_assoc=L1D_ASSOC
 
   --l1i_assoc=L1I_ASSOC
 
   --l1i_assoc=L1I_ASSOC
 
   --l2_assoc=L2_ASSOC   
 
   --l2_assoc=L2_ASSOC   
  --l3_assoc=L3_ASSOC 
 
 
...
 
...
 
</pre>
 
</pre>
  
Since M5 runs the script in a way similar to python itself (i.e. it's similar to running "python myscript.py [ options ]"), you can pass your script options on the command line to make your script flexible.  The script file documentation page ([[Simulation Scripts Explained]]) has details on how to write scripts for M5, and the [[Simulation Scripts Explained#Options|Options]] section of that page gives a bit of detail on how your scripts can have their own options.
+
The script file documentation page ([[Configuration / Simulation Scripts]]) describes how to write your own simulation scripts, and the [[Configuration / Simulation Scripts#Options | Options]] section explains how to add your own command line options. The simulation scripts that are most commonly used are se.py and fs.py. These scripts are present in configs/examples directory. se.py is meant for simulation using the system call emulation mode, while fs.py is for full-system simulations. In most cases, it should be possible to use either of these two scripts without any modifications. Understanding how these two scripts work can help you decide on what modifications are required for your particular case.
  
 +
== System Call Emulation (SE) Mode ==
 +
In this mode,  one only needs to specify the binary file to be simulated.  This binary file can be statically/dynamically linked.  configs/examples/se.py is used for configuring and running simulations in this mode. What follows is probably the simplest example of how to use se.py.  The binary file to simulated is specified with option '''-c'''.
 +
<pre>
 +
$ ./build/ALPHA/gem5.opt ./configs/example/se.py -c ./tests/test-progs/hello/bin/alpha/linux/hello
 +
gem5 Simulator System.  http://gem5.org
 +
gem5 is copyrighted software; use the --copyright option for details.
  
==Syscall Emulation (SE) Mode ==
+
gem5 compiled Mar  2 2014 00:06:39
=== Static Binaries ===
+
gem5 started Mar  4 2014 10:52:10
=== Example Scripts ===
+
gem5 executing on $
In the <code> configs/examples </code> directory there are example scripts <code>fs.py</code> and <code>se.py</code> for running full system and syscall emulation benchmarks respectively. Each of these also takes a <code>--help</code> parameter and lists some parameters we think may be useful to get running quickly. Note the position of <code>--help</code> changes what help you get. <code>./build/ALPHA_SE/m5.opt --help</code> provides you help for M5 and <code>./build/ALPHA_SE/m5.opt configs/example/se.py --help</code> provides help on the <code>se.py</code> script. See [[Simulation Scripts Explained]] for more information. The sample scripts we distribute work for ALPHA, SPARC, and MIPS. However only ALPHA and SPARC are supported for full system simulation.
+
command line: ./build/ALPHA/gem5.opt ./configs/example/se.py -c ./tests/test-progs/hello/bin/alpha/linux/hello
 
+
Global frequency set at 1000000000000 ticks per second
=== Output Files ===
+
0: system.remote_gdb.listener: listening for remote gdb #0 on port 7000
=== Command Line Arguments ===
+
**** REAL SIMULATION ****
=== m5Threads ===
+
info: Entering event queue @ 0. Starting simulation...
=== Benchmark Suite Templates ===
+
info: Increasing stack size by one page.
==== SPEC2000 (spec2k) ====
+
Hello world!
To run SPEC 2000 binaries on m5 you should use the cpu2000.py configuration script.
+
Exiting @ tick 3233000 because target called exit()
 
 
===== Input sets and Binaries =====
 
Several of the cpu2000 benchmarks for our regression tests. Unfortunately because of licensing restrictions we can't provide the binaries or input files, however  to make this a bit easier we have created cpu2000.py. Currently the script is tailored to our particular organization of the binaries and input files. To make the python work for you you'll minimally have to change <code>spec_dist</code> to point to wherever you keep your cpu2000 binaries/input sets.  We have our binaries and input sets organized in the following directory structure:
 
cpu2000/binaries/ARCH/OPSYS/BENCHMARK
 
cpu2000/data/BENCHMARK/INPUTSET/FILES
 
 
 
Where ARCH is alpha or sparc, OPSYS is linux or tru64, BENCHMARK is the name of the spec binary (e.g gzip), INPUTSET is the input files (e.g. smred), and FILES are the specific input files. If you can't create this structure you'll have to mess with cpu2000.py to change how it finds files.
 
 
 
===== How to use it =====
 
The cpu2000.py configuration file takes this data and creates an m5 workload parameter based on benchmark name, isa, operating system, and input set. If you take a look at tests/long/00.gzip/test.py you can see an example of this, but in brief:
 
 
 
<pre>
 
from cpu2000 import gzip_log
 
workload = gzip_log('alpha', 'tru64', 'smred')
 
root.system.cpu.workload = workload.makeLiveProcess()
 
 
</pre>
 
</pre>
  
Assuming you have a machine configured normally above that blob would correctly run the gzip log spec2000 benchmark for alpha/tru64 with the smred input set.
+
====Specifying Command-Line Arguments====
  
===== SPEC2K Command Lines (Syscall Emulation) =====
+
In order to pass command line arguments to a binary you can use <code>--options="arg1 arg2 ..."</code> to specify them as a script option in your simulation command.
If you would like to run SPEC2K using syscall-emulation mode, a good reference for the correct command line options can be found here:
 
* [http://kbarr.net/specint2000-commandlines SPEC2K INT Command Lines]
 
* [http://kbarr.net/specfp2000-commandlines SPEC2K FP Command Lines]
 
(Note: these example command lines aren't for reduced/minimized input sets.)
 
  
Then, if you are unable to use some of the aforementioned cpu2000.py scripts, you could try something like this to run statically-linked, ALPHA, eon binary:
+
== Full System (FS) Mode ==
<pre>
+
This mode simulates a complete system which provides an operating system based simulation environment.
$ build/ALPHA_SE/m5.debug configs/example/se.py --cmd=eon00 --options="chair.control.cook
+
For full system mode, you can use the file configs/example/fs.py for configuration and simulation.  Sensible default values have been set for the options that this script uses. We provide examples for ALPHA and ARM based full system simulations.
chair.camera chair.surfaces chair.cook.ppm ppm pixels_out.cook"
 
</pre>
 
  
==== SPEC 2006 (spec2k6) ====
+
{{#ev:youtube|gd_DtxQD5kc|400|center|Example video showing gem5 full system simulation for ARM. Host system is x86 64bit Ubuntu 12.04.  Video resolution can be set to 1080}}
We need to get bits of info from [[SPEC2006_benchmarks]] and commit some of the code mentioned there.
 
  
==== SPLASH ====
 
 
 
== Full System (FS) Mode ==
 
=== Full System Files ===
 
=== Example Scripts ===
 
=== Output Files ===
 
 
=== Booting Linux ===
 
=== Booting Linux ===
We'll assume that you've already [[Compiling M5|built]] an ALPHA_FS version of the M5 simulator, and [[Compiling_M5#Installing_full_system_files|downloaded and installed]] the full-system binary and disk image files.
+
We'll assume that you've already [[Build System|built]] an ALPHA version of the gem5 simulator, and [[Introduction#Getting Additional Tools and Files|downloaded and installed]] the full-system binary and disk image files.
Then you can just run the fs.py configuration file in the m5/configs/examples directory. For example:
+
Then you can run the fs.py configuration file in the gem5/configs/examples directory. For example:
 
<pre>
 
<pre>
% build/ALPHA_FS/m5.debug -d /tmp/output configs/example/fs.py
+
% build/ALPHA/gem5.debug -d /tmp/output configs/example/fs.py
M5 Simulator System
+
gem5 Simulator System
  
 
Copyright (c) 2001-2006
 
Copyright (c) 2001-2006
Line 150: Line 127:
  
  
M5 compiled Aug 16 2006 18:51:57
+
gem5 compiled Aug 16 2006 18:51:57
M5 started Wed Aug 16 21:53:38 2006
+
gem5 started Wed Aug 16 21:53:38 2006
M5 executing on zeep
+
gem5 executing on zeep
command line: ./build/ALPHA_FS/m5.debug configs/example/fs.py
+
command line: ./build/ALPHA/gem5.debug configs/example/fs.py
 
       0: system.tsunami.io.rtc: Real-time clock set to Sun Jan  1 00:00:00 2006
 
       0: system.tsunami.io.rtc: Real-time clock set to Sun Jan  1 00:00:00 2006
 
Listening for console connection on port 3456
 
Listening for console connection on port 3456
Line 167: Line 144:
 
   % telnet localhost 3456
 
   % telnet localhost 3456
  
Telnet's echo behavior doesn't work well with m5, so if you are using the console regularly, you probably want to use [[M5term]] instead of telnet.  By default m5 will try to use port 3456, as in the example above.  However, if that port is already in use, it will increment the port number until it finds a free one.  The actual port number used is printed in the m5 output.   
+
Telnet's echo behavior doesn't work well with gem5, so if you are using the console regularly, you probably want to use [[M5term]] instead of telnet.  By default gem5 will try to use port 3456, as in the example above.  However, if that port is already in use, it will increment the port number until it finds a free one.  The actual port number used is printed in the gem5 output.   
  
In addition to loading a Linux kernel, M5 mounts one or more disk images for its filesystems.  At least one disk image must be mounted as the root filesystem. Any application binaries that you want to run must be present on these disk images. To begin running benchmarks without requiring an interactive shell session, M5 can load .rcS files that replace the normal Linux boot scripts to directly execute from after booting the OS. These .rcS files can be used to configure ethernet interfaces, execute special m5 instructions, or begin executing a binary on the disk image. The pointers for the linux binary, disk images, and .rcS files are all set in the simulation script.  (To see how these files work, see [[Simulation Scripts Explained]].)
+
In addition to loading a Linux kernel, gem5 mounts one or more disk images for its filesystems.  At least one disk image must be mounted as the root filesystem. Any application binaries that you want to run must be present on these disk images. To begin running benchmarks without requiring an interactive shell session, gem5 can load .rcS files that replace the normal Linux boot scripts to directly execute from after booting the OS. These .rcS files can be used to configure ethernet interfaces, execute special gem5 instructions, or begin executing a binary on the disk image. The pointers for the linux binary, disk images, and .rcS files are all set in the simulation script.  (To see how these files work, see [[Configuration / Simulation Scripts]].)
 
Examples: Going into / of root filesystem and typing ls will show:
 
Examples: Going into / of root filesystem and typing ls will show:
 
<pre>
 
<pre>
Line 189: Line 166:
  
 
====m5term====
 
====m5term====
The m5term program allows the user to connect to the simulated console interface that full-system m5 provides. Simply change into the util/term directory and build m5term:
+
The m5term program allows the user to connect to the simulated console interface that full-system gem5 provides. Simply change into the util/term directory and build m5term:
  
 
<pre>
 
<pre>
% cd m5/util/term  
+
% cd gem5/util/term  
 
% make
 
% make
 
gcc  -o m5term term.c
 
gcc  -o m5term term.c
Line 203: Line 180:
 
./m5term <host> <port>
 
./m5term <host> <port>
  
<host> is the host that is running m5
+
<host> is the host that is running gem5
  
<port> is the console port to connect to. m5 defaults to
+
<port> is the console port to connect to. gem5 defaults to
 
using port 3456, but if the port is used, it will try the next
 
using port 3456, but if the port is used, it will try the next
 
higher port until it finds one available.
 
higher port until it finds one available.
Line 251: Line 228:
 
====Full System Benchmarks====
 
====Full System Benchmarks====
  
We have several full-system benchmarks already up and running. The binaries are available in the disk images you can obtain/download from us, and the .rcS files are in the m5/configs/boot/ directory. To run any of them, you merely need to set the benchmark option to the name of the test you want to run. For example:
+
We have several full-system benchmarks already up and running. The binaries are available in the disk images you can obtain/download from us, and the .rcS files are in the gem5/configs/boot/ directory. To run any of them, you merely need to set the benchmark option to the name of the test you want to run. For example:
  
<pre>%./build/ALPHA_FS/m5.opt  configs/example/fs.py -b NetperfMaerts </pre>
+
<pre>%./build/ALPHA/gem5.opt  configs/example/fs.py -b NetperfMaerts </pre>
  
 
To see a comprehensive list of all benchmarks available:
 
To see a comprehensive list of all benchmarks available:
<pre>%./build/ALPHA_FS/m5.opt configs/examples/fs.py -h </pre>
+
<pre>%./build/ALPHA/gem5.opt configs/examples/fs.py -h </pre>
 
 
== Checkpoints ==
 
=== Creation ===
 
First of all, you need to create a checkpoint.
 
After booting the M5 simulator, execute the following command (in the shell):
 
<pre>
 
m5 checkpoint
 
</pre>
 
which will create a new directory with the checkpoint, named 'cpt.TICKNUMBER'
 
 
 
=== Restoring ===
 
With the new simulator (2.0 beta2), the restoring from a checkpoint can usually be easily done from the command line, e.g.:
 
<pre>
 
build/ALPHA_FS/m5.debug configs/example/fs.py -r N
 
OR
 
build/ALPHA_FS/m5.debug configs/example/fs.py --checkpoint-restore=N
 
</pre>
 
The number N is integer that represents checkpoint number, when they are order lexically (i.e. by the ticknumber) - oldest tick has number 1, next checkpoint has number 2, etc.
 
 
 
==Switchover/Fastforwarding==
 
===Sampling===
 
 
 
Sampling (switching between functional and detailed models) can be implemented via your Python script.  In your script you can direct the simulator to switch between two sets of CPUs.  To do this, in your script setup a list of tuples of (oldCPU, newCPU).  If there are multiple CPUs you wish to switch simultaneously, they can all be added to that list.  For example:
 
 
 
<pre>
 
run_cpu1 = SimpleCPU()
 
switch_cpu1 = DetailedCPU(defer_registration=True)
 
run_cpu2 = SimpleCPU()
 
switch_cpu2 = FooCPU(defer_registration=True)
 
switch_cpu_list = [(run_cpu1,switch_cpu1),(run_cpu2,switch_cpu2)]
 
</pre>
 
 
 
Note that the CPU that does not immediately run should have the parameter "defer_registration=True".  This keeps those CPUs from adding themselves to the list of CPUs to run; they will instead get added when you switch them in.
 
  
In order for M5 to instantiate all of your CPUs, you must make the CPUs that will be switched in a child of something that is in the configuration hierarchy.  Unfortunately at the moment some configuration limitations force the switch CPU to be placed outside of the System object.  The Root object is the next most convenient place to place the CPU, as shown below:
+
===Experimenting with DVFS===
 
 
<pre>
 
root1 = Root()
 
root1.system = System(cpu = run_cpu1)
 
root1.switch_cpu = switch_cpu1
 
root2 = Root()
 
root2.system = System(cpu = run_cpu2)
 
root2.switch_cpu = switch_cpu2
 
</pre>
 
 
 
This will add the swtich CPUs as children of each root object.  Note that switch_cpu is not an actual parameter for Root, but is just an assignment to indicate that it has a child, switch_cpu.
 
 
 
After the systems and the CPU list is setup, your script can direct M5 to switch the CPUs at the appropriate cycle.  This is achieved by calling switchCpus(cpus_list).  For example, assuming the code above, and a system that is setup running run_cpu1 and run_cpu2 initially:
 
 
 
<pre>
 
m5.simulate(500)  # simulate for 500 cycles
 
m5.switchCpus(switch_cpu_list)
 
m5.simulate(500)  # simulate another 500 cycles after switching
 
</pre>
 
  
Note that M5 may have to simulate for a few cycles prior to switching CPUs due to any outstanding state that may be present in the CPUs being switched out.
+
This is a quick hands-on tutorial to start a DVFS-enabled system where the Linux DVFS governors can change voltage and frequencies of the ongoing simulation.  Right now, the driver and interface components live in ARM-specific parts of the Linux kernel / gem5, but there is no fundamental reason why this could not be ported to work on other architectures, too.
  
 +
====Quick Instructions====
  
==Mutiprogrammed Workloads==
+
These instructions apply for a Ubuntu-based machine, but can be easily adapted / extended etc. for other use cases and systems.
===How to run multiprogrammed workloads===
 
In SE mode, simply create a system with multiple CPUs and assign a different workload object to each CPU's workload parameter.  If you're using the O3 model, you can also assign a vector of workload objects to one CPU, in which case the CPU will run all of the workloads concurrently in SMT mode. Note that SE mode has no thread scheduling; if you need a scheduler, run in FS mode and use the fine scheduler built into the Linux kernel.
 
  
=== How do I terminate multiprogram workloads? ===
+
<ul>
There are some very fundamental issues with whatever approach you choose. Here are your options:
+
<li>Get gem5 with the proper changesets added</li>
# Terminate as soon as any thread reaches a particular maximum number of instructions. This option is equivalent to max_insts_any_thread. The potential problem here is that because of the inherent non-determinism of multithreaded programs, there is no way to ensure that all experiments do the same work. You might also not get the same amount of work done. For example, if you have two threads, one of them must reach the maximum. The other could either execute no instructions, or could execute max-1 instructions. The benefit of this approach is that all threads are running fully until the simulation terminates (provided that none of the threads terminate early due to some other condition.)
+
* Anything after [http://repo.gem5.org/gem5/rev/d65768b9ffc2]
# Terminate once all threads have reached a maximum number of instructions. This option is equivalent to max_insts_all_threads. In this mode, we make sure all threads do at least a certain amount of work, but threads that reach the maximum continue executing. This has the same benefit as the previous example, but also suffers from the problem that non-determinism will cause you to potentially not do the same amount of total work.
+
<pre>hg clone http://repo.gem5.org/gem5</pre>
# In this '''unimplemented''' mode, all threads would run for exactly a specified number of instructions with some threads terminating early. All threads will do the same amount of work thus avoiding the problem of the previous options. The downside of this option is that the threads may not all be running for the entire simulation. For example, one thread might finish its instructions almost right away, while the other thread has quite a bit left to do. When this happens, you're only running a multiprogram workload for a fraction of the total time.
+
<li>Build gem5</li>
# Another '''unimplemented''' option could be to specify how many instructions each thread has to complete before exiting. This is not implemented, but would allow a balance to be struck between options 1 and 2 if the user experimented to figure out what a good mix was.
+
<pre>scons build/ARM/gem5.opt -j 8</pre>
 +
<li>Get a DVFS-enabled Linux kernel</li>
 +
* From here: [https://gem5.googlesource.com/arm/linux-arm-legacy/]
 +
* Anything after / including [https://gem5.googlesource.com/arm/linux-arm-legacy/+/a75e551a89819c96bb762c25fa104b32eda7b99b]
 +
<pre>git clone --depth 10 https://gem5.googlesource.com/arm/linux-arm-legacy</pre>
 +
<li>Get a cross-compile tool chain</li>
 +
<pre>sudo apt-get install gcc-arm-linux-gnueabihf</pre>
 +
<li>Build the kernel</li>
 +
* See also [[Linux_kernel]]
 +
<pre>make ARCH=arm vexpress_gem5_dvfs_defconfig
 +
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j8</pre>
 +
<li>Check / select the right DTS / DTB file</li>
 +
<pre>ls arch/arm/boot/dts/vexpress-v2*dvfs*</pre>
 +
<li>Get / prepare a disk image</li>
 +
<pre>wget http://www.gem5.org/dist/current/arm/arm-system-2013-07.tar.bz2
 +
tar xvjf arm-system-2013-07.tar.bz2</pre>
 +
<li>Add DVFS points to the configuration</li>
 +
<ul>
 +
<li>Enable and link the energy controller / DVFS handler
 +
<pre>patch -p1 << EOF
 +
diff --git a/configs/example/fs.py b/configs/example/fs.py
 +
--- a/configs/example/fs.py
 +
+++ b/configs/example/fs.py
 +
@@ -106,7 +106,11 @@
 +
    # Create a source clock for the CPUs and set the clock period
 +
    test_sys.cpu_clk_domain = SrcClockDomain(clock = options.cpu_clock,
 +
                                              voltage_domain =
 +
-                                            test_sys.cpu_voltage_domain)
 +
+                                            test_sys.cpu_voltage_domain,
 +
+                                            domain_id = 0)
 +
+
 +
+    test_sys.dvfs_handler.domains = test_sys.cpu_clk_domain
 +
+    test_sys.dvfs_handler.enable = 1
  
If you want to implement either of the unimplemented options, or if you have other ideas, please let us know!
+
    if options.kernel is not None:
===Combining multiple single-workload checkpoints into one multiprogrammed workload===
+
        test_sys.kernel = binary(options.kernel)
 +
EOF</pre>
 +
</ul>
 +
* Can also change the clock frequencies here, or from command line
 +
<li>Start a simple test simulation</li>
 +
<pre>M5_PATH=$(pwd)/.. ./build/ARM/gem5.opt --debug-flags=DVFS,EnergyCtrl \
 +
  --debug-file=dfvs_debug.log configs/example/fs.py --cpu-type=AtomicSimpleCPU \
 +
  -n 2 --machine-type=VExpress_EMM --kernel=../linux-linaro-tracking-gem5/vmlinux \
 +
  --dtb-filename=../linux-linaro-tracking-gem5/arch/arm/boot/dts/\
 +
vexpress-v2p-ca15-tc1-gem5_dvfs_2cpus.dtb \
 +
  --disk-image=../disks/arm-ubuntu-natty-headless.img \
 +
  --cpu-clock=\['1 GHz','750 MHz','500 MHz'\]</pre>
 +
<li>Test DVFS functionality</li>
 +
<pre>util/term/m5term 3456
 +
<login>
 +
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
 +
echo 750187 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq</pre>
 +
</ul>
 +
====Futher Experiments====
 +
<ul>
 +
<li>Set up different voltages for the operating points
 +
<pre>patch -p1 < EOF
 +
diff --git a/configs/example/fs.py b/configs/example/fs.py
 +
--- a/configs/example/fs.py
 +
+++ b/configs/example/fs.py
 +
@@ -101,12 +101,16 @@
 +
            voltage_domain = test_sys.voltage_domain)
 +
 +
    # Create a CPU voltage domain
 +
-    test_sys.cpu_voltage_domain = VoltageDomain()
 +
+    test_sys.cpu_voltage_domain = VoltageDomain(voltage = ['1V','0.9V','0.8V'])
 +
 +
    # Create a source clock for the CPUs and set the clock period
 +
    test_sys.cpu_clk_domain = SrcClockDomain(clock = options.cpu_clock,
 +
                                              voltage_domain =
 +
-                                             test_sys.cpu_voltage_domain)
 +
+                                            test_sys.cpu_voltage_domain,
 +
+                                            domain_id = 0)
 +
+
 +
+    test_sys.dvfs_handler.domains = test_sys.cpu_clk_domain
 +
+    test_sys.dvfs_handler.enable = 1
 +
 
 +
    if options.kernel is not None:
 +
        test_sys.kernel = binary(options.kernel)
 +
EOF</pre>
 +
<li>Per-core DVFS</li>
 +
<ul>
 +
<li>Set up separate clock (and voltage) domains per core</li>
 +
<li>Separate clock domains need separate clusters in the device tree
 +
<pre>diff -u linux-linaro-tracking-gem5/arch/arm/boot/dts/\
 +
vexpress-v2p-ca15-tc1-gem5_dvfs_{,per_core_}4cpus.dts</code></pre>
 +
<li>Change the <tt>socket_id</tt> to have a separate socket per CPU core
 +
</ul>

Latest revision as of 10:57, 18 February 2019

Usage

The gem5 command line has four parts, the gem5 binary, options for the binary, a simulation script, and options for the script. The options that are passed to the gem5 binary and those passed to the script are handled separately, so be sure any options you use are being passed to the right component.

% <gem5 binary> [gem5 options] <simulation script> [script options]

gem5 Options

Running gem5 with the "-h" flag prints a help message that includes all of the supported simulator options. Here's a snippet:

% build/ALPHA/gem5.debug -h
Usage
=====
  gem5.debug [gem5 options] script.py [script options]

 Copyright (c) 2001-2008 The Regents of The University of Michigan All Rights
Reserved
gem5 is copyrighted software; use the --copyright option for details.

Options
=======
--version               show program's version number and exit
--help, -h              show this help message and exit
--build-info, -B        Show build information
--copyright, -C         Show full copyright information
--readme, -R            Show the readme
--outdir=DIR, -d DIR    Set the output directory to DIR [Default: m5out]
--redirect-stdout, -r   Redirect stdout (& stderr, without -e) to file
--redirect-stderr, -e   Redirect stderr to file
--stdout-file=FILE      Filename for -r redirection [Default: simout]
--stderr-file=FILE      Filename for -e redirection [Default: simerr]
--interactive, -i       Invoke the interactive interpreter after running the
                        script
--pdb                   Invoke the python debugger before running the script
--path=PATH[:PATH], -p PATH[:PATH]
                        Prepend PATH to the system path when invoking the
                        script
--quiet, -q             Reduce verbosity
...

The default options that gem5 uses to run can be set by creating an ~/.m5/options.py file and placing options that you are interested in there. For example, if you would like to always redirect standard error and out to a file you could add: options.stdout_file=simout to options.py.

Script Options

The script section of the command line begins with a path to your script file and includes any options that you'd like to pass to that script. Most Example scripts allow you to pass a '-h' or '--help' flag to the script to see script specific options. An example is as follows:

gem5 compiled Apr  2 2011 00:57:11
gem5 started Apr  3 2011 21:16:02
gem5 executing on zooks
command line: build/ALPHA/gem5.opt configs/example/se.py -h
Usage: se.py [options]

Options:
  -h, --help            show this help message and exit
  -c CMD, --cmd=CMD     The binary to run in syscall emulation mode.
  -o OPTIONS, --options=OPTIONS
                        The options to pass to the binary, use " " around the
                        entire string
  -i INPUT, --input=INPUT
                        Read stdin from a file.
  --output=OUTPUT       Redirect stdout to a file.
  --errout=ERROUT       Redirect stderr to a file.
  --ruby                
  -d, --detailed        
  -t, --timing          
  --inorder             
  -n NUM_CPUS, --num-cpus=NUM_CPUS
  --caches              
  --l2cache             
  --fastmem             
  --clock=CLOCK         
  --num-dirs=NUM_DIRS   
  --num-l2caches=NUM_L2CACHES
  --l1d_size=L1D_SIZE   
  --l1i_size=L1I_SIZE   
  --l2_size=L2_SIZE       
  --l1d_assoc=L1D_ASSOC
  --l1i_assoc=L1I_ASSOC
  --l2_assoc=L2_ASSOC   
...

The script file documentation page (Configuration / Simulation Scripts) describes how to write your own simulation scripts, and the Options section explains how to add your own command line options. The simulation scripts that are most commonly used are se.py and fs.py. These scripts are present in configs/examples directory. se.py is meant for simulation using the system call emulation mode, while fs.py is for full-system simulations. In most cases, it should be possible to use either of these two scripts without any modifications. Understanding how these two scripts work can help you decide on what modifications are required for your particular case.

System Call Emulation (SE) Mode

In this mode, one only needs to specify the binary file to be simulated. This binary file can be statically/dynamically linked. configs/examples/se.py is used for configuring and running simulations in this mode. What follows is probably the simplest example of how to use se.py. The binary file to simulated is specified with option -c.

$ ./build/ALPHA/gem5.opt ./configs/example/se.py -c ./tests/test-progs/hello/bin/alpha/linux/hello 
gem5 Simulator System.  http://gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 compiled Mar  2 2014 00:06:39
gem5 started Mar  4 2014 10:52:10
gem5 executing on $
command line: ./build/ALPHA/gem5.opt ./configs/example/se.py -c ./tests/test-progs/hello/bin/alpha/linux/hello
Global frequency set at 1000000000000 ticks per second
0: system.remote_gdb.listener: listening for remote gdb #0 on port 7000
**** REAL SIMULATION ****
info: Entering event queue @ 0.  Starting simulation...
info: Increasing stack size by one page.
Hello world!
Exiting @ tick 3233000 because target called exit()

Specifying Command-Line Arguments

In order to pass command line arguments to a binary you can use --options="arg1 arg2 ..." to specify them as a script option in your simulation command.

Full System (FS) Mode

This mode simulates a complete system which provides an operating system based simulation environment. For full system mode, you can use the file configs/example/fs.py for configuration and simulation. Sensible default values have been set for the options that this script uses. We provide examples for ALPHA and ARM based full system simulations.

Example video showing gem5 full system simulation for ARM. Host system is x86 64bit Ubuntu 12.04. Video resolution can be set to 1080

Booting Linux

We'll assume that you've already built an ALPHA version of the gem5 simulator, and downloaded and installed the full-system binary and disk image files. Then you can run the fs.py configuration file in the gem5/configs/examples directory. For example:

% build/ALPHA/gem5.debug -d /tmp/output configs/example/fs.py
gem5 Simulator System

Copyright (c) 2001-2006
The Regents of The University of Michigan
All Rights Reserved


gem5 compiled Aug 16 2006 18:51:57
gem5 started Wed Aug 16 21:53:38 2006
gem5 executing on zeep
command line: ./build/ALPHA/gem5.debug configs/example/fs.py
      0: system.tsunami.io.rtc: Real-time clock set to Sun Jan  1 00:00:00 2006
Listening for console connection on port 3456
0: system.remote_gdb.listener: listening for remote gdb #0 on port 7000
warn: Entering event queue @ 0.  Starting simulation...
<...simulation continues...>

Basic Operation

By default, the fs.py script boots Linux and starts a shell on the system console. To keep console traffic separate from simulator input and output, this simulated console is associated with a TCP port. To interact with the console, you must connect to the port using a program such as telnet, for example:

 % telnet localhost 3456

Telnet's echo behavior doesn't work well with gem5, so if you are using the console regularly, you probably want to use M5term instead of telnet. By default gem5 will try to use port 3456, as in the example above. However, if that port is already in use, it will increment the port number until it finds a free one. The actual port number used is printed in the gem5 output.

In addition to loading a Linux kernel, gem5 mounts one or more disk images for its filesystems. At least one disk image must be mounted as the root filesystem. Any application binaries that you want to run must be present on these disk images. To begin running benchmarks without requiring an interactive shell session, gem5 can load .rcS files that replace the normal Linux boot scripts to directly execute from after booting the OS. These .rcS files can be used to configure ethernet interfaces, execute special gem5 instructions, or begin executing a binary on the disk image. The pointers for the linux binary, disk images, and .rcS files are all set in the simulation script. (To see how these files work, see Configuration / Simulation Scripts.) Examples: Going into / of root filesystem and typing ls will show:

  benchmarks  etc     lib         mnt      sbin  usr
  bin         floppy  lost+found  modules  sys   var
  dev         home    man         proc     tmp   z

Snippet of an .rcS file:

echo -n "setting up network..."
/sbin/ifconfig eth0 192.168.0.10 txqueuelen 1000
/sbin/ifconfig lo 127.0.0.1
echo -n "running surge client..."
/bin/bash -c "cd /benchmarks/surge && ./Surge 2 100 1 192.168.0.1 5.
echo -n "halting machine"
m5 exit

m5term

The m5term program allows the user to connect to the simulated console interface that full-system gem5 provides. Simply change into the util/term directory and build m5term:

	% cd gem5/util/term 
	% make
	gcc  -o m5term term.c
	% make install
	sudo install -o root -m 555 m5term /usr/local/bin

The usage of m5term is:

	./m5term <host> <port>

	<host> is the host that is running gem5

	<port> is the console port to connect to. gem5 defaults to
	using port 3456, but if the port is used, it will try the next
	higher port until it finds one available.

	If there are multiple systems running within one simulation,
	there will be a console for each one.  (The first system's
	console will be on 3456 and the second on 3457 for example)

	m5term uses '~' as an escape character.  If you enter
	the escape character followed by a '.', the m5term program
	will exit.

m5term can be used to interactively work with the simulator, though users must often set various terminal settings to get things to work

A slightly shortened example of m5term in action:

	% m5term localhost 3456
	==== m5 slave console: Console 0 ====
	M5 console
	Got Configuration 127 
	memsize 8000000 pages 4000 
	First free page after ROM 0xFFFFFC0000018000
	HWRPB 0xFFFFFC0000018000 l1pt 0xFFFFFC0000040000 l2pt 0xFFFFFC0000042000 l3pt_rpb 0xFFFFFC0000044000 l3pt_kernel 0xFFFFFC0000048000 l2reserv 0xFFFFFC0000046000
	CPU Clock at 2000 MHz IntrClockFrequency=1024 
	Booting with 1 processor(s) 
	...
	...
	VFS: Mounted root (ext2 filesystem) readonly.
	Freeing unused kernel memory: 480k freed
	init started:  BusyBox v1.00-rc2 (2004.11.18-16:22+0000) multi-call binary

	PTXdist-0.7.0 (2004-11-18T11:23:40-0500)

	mounting filesystems...
	EXT2-fs warning: checktime reached, running e2fsck is recommended
	loading script...
	Script from M5 readfile is empty, starting bash shell...
	# ls
	benchmarks  etc         lib         mnt         sbin        usr
	bin         floppy      lost+found  modules     sys         var
	dev         home        man         proc        tmp         z
	# 

Full System Benchmarks

We have several full-system benchmarks already up and running. The binaries are available in the disk images you can obtain/download from us, and the .rcS files are in the gem5/configs/boot/ directory. To run any of them, you merely need to set the benchmark option to the name of the test you want to run. For example:

%./build/ALPHA/gem5.opt  configs/example/fs.py -b NetperfMaerts 

To see a comprehensive list of all benchmarks available:

%./build/ALPHA/gem5.opt configs/examples/fs.py -h 

Experimenting with DVFS

This is a quick hands-on tutorial to start a DVFS-enabled system where the Linux DVFS governors can change voltage and frequencies of the ongoing simulation. Right now, the driver and interface components live in ARM-specific parts of the Linux kernel / gem5, but there is no fundamental reason why this could not be ported to work on other architectures, too.

Quick Instructions

These instructions apply for a Ubuntu-based machine, but can be easily adapted / extended etc. for other use cases and systems.

  • Get gem5 with the proper changesets added
    • Anything after [1]
    hg clone http://repo.gem5.org/gem5
  • Build gem5
  • scons build/ARM/gem5.opt -j 8
  • Get a DVFS-enabled Linux kernel
    • From here: [2]
    • Anything after / including [3]
    git clone --depth 10 https://gem5.googlesource.com/arm/linux-arm-legacy
  • Get a cross-compile tool chain
  • sudo apt-get install gcc-arm-linux-gnueabihf
  • Build the kernel
  • make ARCH=arm vexpress_gem5_dvfs_defconfig
    make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j8
  • Check / select the right DTS / DTB file
  • ls arch/arm/boot/dts/vexpress-v2*dvfs*
  • Get / prepare a disk image
  • wget http://www.gem5.org/dist/current/arm/arm-system-2013-07.tar.bz2
    tar xvjf arm-system-2013-07.tar.bz2
  • Add DVFS points to the configuration
    • Enable and link the energy controller / DVFS handler
      patch -p1 << EOF
      diff --git a/configs/example/fs.py b/configs/example/fs.py
      --- a/configs/example/fs.py
      +++ b/configs/example/fs.py
      @@ -106,7 +106,11 @@
           # Create a source clock for the CPUs and set the clock period
           test_sys.cpu_clk_domain = SrcClockDomain(clock = options.cpu_clock,
                                                    voltage_domain =
      -                                             test_sys.cpu_voltage_domain)
      +                                             test_sys.cpu_voltage_domain,
      +                                             domain_id = 0)
      +
      +    test_sys.dvfs_handler.domains = test_sys.cpu_clk_domain
      +    test_sys.dvfs_handler.enable = 1
      
           if options.kernel is not None:
               test_sys.kernel = binary(options.kernel)
      EOF
    • Can also change the clock frequencies here, or from command line
  • Start a simple test simulation
  • M5_PATH=$(pwd)/.. ./build/ARM/gem5.opt --debug-flags=DVFS,EnergyCtrl \
      --debug-file=dfvs_debug.log configs/example/fs.py --cpu-type=AtomicSimpleCPU \
      -n 2 --machine-type=VExpress_EMM --kernel=../linux-linaro-tracking-gem5/vmlinux \
      --dtb-filename=../linux-linaro-tracking-gem5/arch/arm/boot/dts/\
    vexpress-v2p-ca15-tc1-gem5_dvfs_2cpus.dtb \
      --disk-image=../disks/arm-ubuntu-natty-headless.img \
      --cpu-clock=\['1 GHz','750 MHz','500 MHz'\]
  • Test DVFS functionality
  • util/term/m5term 3456
    <login>
    cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
    echo 750187 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq

Futher Experiments

  • Set up different voltages for the operating points
    patch -p1 < EOF
    diff --git a/configs/example/fs.py b/configs/example/fs.py
    --- a/configs/example/fs.py
    +++ b/configs/example/fs.py
    @@ -101,12 +101,16 @@
                 voltage_domain = test_sys.voltage_domain)
     
         # Create a CPU voltage domain
    -    test_sys.cpu_voltage_domain = VoltageDomain()
    +    test_sys.cpu_voltage_domain = VoltageDomain(voltage = ['1V','0.9V','0.8V'])
     
         # Create a source clock for the CPUs and set the clock period
         test_sys.cpu_clk_domain = SrcClockDomain(clock = options.cpu_clock,
                                                  voltage_domain =
    -                                             test_sys.cpu_voltage_domain)
    +                                             test_sys.cpu_voltage_domain,
    +                                             domain_id = 0)
    +
    +    test_sys.dvfs_handler.domains = test_sys.cpu_clk_domain
    +    test_sys.dvfs_handler.enable = 1
      
         if options.kernel is not None:
             test_sys.kernel = binary(options.kernel)
    EOF
  • Per-core DVFS
    • Set up separate clock (and voltage) domains per core
    • Separate clock domains need separate clusters in the device tree
      diff -u linux-linaro-tracking-gem5/arch/arm/boot/dts/\
      vexpress-v2p-ca15-tc1-gem5_dvfs_{,per_core_}4cpus.dts</code>
    • Change the socket_id to have a separate socket per CPU core