Difference between revisions of "Running gem5"

Revision as of 21:37, 17 March 2011

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:

% m5 [m5 options] <script.py> [script options]

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. Running m5 with the "-h" flag prints a help message that includes all of the supported simulator options. Here's a snippet:

% build/ALPHA_SE/m5.debug -h
Usage
=====
  m5.debug [m5 options] script.py [script options]

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

options
=======
--version               show program's version number and exit
--help, -h              show this help message and exit
--authors, -A           Show author information
--copyright, -C         Show full copyright information
--readme, -R            Show the readme
--release-notes, -N     Show the release notes
--outdir=DIR, -d DIR    Set the output directory to DIR [Default: .]
--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
--verbose, -v           Increase verbosity
...

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. 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 Options section of that page gives a bit of detail on how your scripts can have their own options.

Example configuration files

In the configs/examples directory there are example scripts fs.py and se.py for running full system and syscall emulation benchmarks respectively. Each of these also takes a --help parameter and lists some parameters we think may be useful to get running quickly. Note the position of --help changes what help you get. ./build/ALPHA_SE/m5.opt --help provides you help for M5 and ./build/ALPHA_SE/m5.opt configs/example/se.py --help provides help on the se.py 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.

Simple SE binary

SPEC2k/2k6

m5threads

Booting Linux

We'll assume that you've already built an ALPHA_FS version of the M5 simulator, and 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:

% build/ALPHA_FS/m5.debug -d /tmp/output configs/example/fs.py
M5 Simulator System

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


M5 compiled Aug 16 2006 18:51:57
M5 started Wed Aug 16 21:53:38 2006
M5 executing on zeep
command line: ./build/ALPHA_FS/m5.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 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.

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.) 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 m5 provides. Simply change into the util/term directory and build m5term:

	% cd m5/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 m5

	<port> is the console port to connect to. m5 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 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:

%./build/ALPHA_FS/m5.opt  configs/example/fs.py -b NetperfMaerts 

To see a comprehensive list of all benchmarks available:

%./build/ALPHA_FS/m5.opt configs/examples/fs.py -h 

Restoring from a checkpoint

First of all, you need to create a checkpoint. After booting the M5 simulator, execute the following command (in the shell):

m5 checkpoint

which will create a new directory with the checkpoint, named 'cpt.TICKNUMBER'

With the new simulator (2.0 beta2), the restoring from a checkpoint can usually be easily done from the command line, e.g.:

build/ALPHA_FS/m5.debug configs/example/fs.py -r N
OR
build/ALPHA_FS/m5.debug configs/example/fs.py --checkpoint-restore=N

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