The preparation contains several parts.

Installing Linux

This assignment requires Linux environment on your own computer. There are several ways to do that. We recommend the first and second way.
  1. Running Linux in a virtual machine. You need to first install a virtual machine, for example, VirtualBox, etc. in you Windows system. Then you can install Linux in the virtual machine. You can refer to a tutorial on "installing Ubuntu inside Windows XP using VirtualBox". The same method applies to Windows Vista, other Linux distributions, and other virtual machine software.
  2. Dual-booting Linux with Windows. You can refer to short tutorials on dual-booting Ubuntu with Windows Vista and dual-booting Ubuntu with Windows XP. If you are doing this for the first time, please backup your data.
  3. Installing Linux in a Windows partition using wubi. This method is not so stable. There are people reporting hard drive corruption caused by Linux installed in a Windows partition. If you decide to take you own risk to try it, the WubiGuide provides detailed instructions.
  4. Cygwin. Although the m5sim wiki mentions that cygwin works, we expect some twists are required. We have not tested m5sim on Cygwin.
We have tested m5sim on 32-bit Ubuntu 9.04, Ubuntu 9.10, Fedora 10, Fedora 11.
Ubuntu 9.04 is working out-of-the-box.
Fedora 10 is working out-of-the-box.
Ubuntu 9.10 may need small twists on the gcc problem. See "Known Issues" page for more detail.
Fedora 11 may need more twists on the gcc problem. See "Known Issues" page for more detail.
Other Linux distributions may or may not work.
Note: If you are doing a fresh installation of Linux, 32-bit Ubuntu 9.04 and Fedora 10 are highly recommended.

Compiling m5sim

This section provides the instructions to compile m5sim on our Linux system. For further information, you can also refer to "Compiling M5" wiki page.

Get prerequisite packages

Required packages include g++, python-dev, scons, swig, zlib-dev, m4, mercurial, and patch.
The commands below will install these packages for rpm-based and deb-based package installers.
The names of these packages may differ from one Linux distribution to the other.
Sometimes the package for 64-bit version may differ from 32-bit version.
If you are not using 32-bit Fedora or Ubuntu, please search for the correct names of these packages.

For Fedora, issue the following 'yum' command (su is needed to get superuser privileges; so you will be asked to enter the superuser password):
su -c 'yum install gcc-c++ python-devel scons swig zlib-devel m4 mercurial patch subversion'

For Ubuntu, issue the 'apt-get' command (also here we need 'sudo' to get superuser privileges):
sudo apt-get install g++ python-dev scons swig zlib1g-dev m4 mercurial patch subversion

Fetch a stable version of m5sim

Use the 'hg' command from the mercurial package to fetch a stable version of m5sim from the indicated website. The latest stable version is 2.0 beta 6.
cd /somewhere/to/compile/m5/
hg clone

GCC version problem

The m5sim can be compiled with gcc 4.3.x. Some earlier version of gcc may also work. Newer Linux distributions (e.g. Ubuntu 9.10, Fedora 11) use gcc 4.4.1 as the default compiler. It causes problems while compiling m5sim.

You can check which version of gcc you are using by running this command:
gcc --version

If your gcc version is 4.4.x, a workaround is to install an older version of gcc and g++. An alternative method is to patch the source code of m5sim 2.0 beta 6. You can check the detail in the known issues page.
You need to solve the gcc version problem before compiling m5sim.

Compile m5sim

After getting the prerequisite packages and solving the gcc version program, if any, we can go to the downloaded directory. Later we will use scons to compile m5.

cd m5-stable

First, add a few lines to file "m5-stable/.hg/hgrc". Change "/your/full/path/to/m5-stable" to the actual path in your system (this could be e.g. /home/your-login-name/m5-stable.

Original lines:
default =
Change above lines into:
default =

style = /your/full/path/to/m5-stable/util/

[hooks] = python:style.check_whitespace

There are 2 version of the simulator, called SE, syscall emulation, and FS, full system mode.
Compile both simulators: Syscall Emulation (SE) mode and Full System (FS) mode for ALPHA ISA, using scons, as shown below:
cd m5-stable
scons build/ALPHA_SE/m5.opt
scons build/ALPHA_FS/m5.opt

If you encounter errors, you can take a look at the known issues.

Test Syscall Emulation (SE) mode

There are two simulation modes in m5sim, the Syscall Emulation (SE) mode and the Full System (FS) mode. The SE mode does not simulate operating systems. It emulates system calls on the host machine. The FS mode simulates the whole Linux system. To test whether our installation is working. We can first test the SE mode. Because the FS mode requires additional efforts, we will test the FS mode in the next section. To test the FS mode, you can issue this command below. It executes m5 with '' as input. This latter file contains a configuration of the architecture and specifies the input code file. This configuration is written in Python. The simulator calls Python to translate this file and generating the configuration file for m5.

/your/path/to/m5-stable/build/ALPHA_SE/m5.opt /your/path/to/m5-stable/configs/example/

You will see the "Hello World!".

Running in full system (FS) mode

The Syscall Emulation (SE) mode can be used to simulate programs that do not use Linux pthread. If we want to simulate programs using pthread, we need to use the Full System (FS) mode.

Get system disk image 
Since the FS mode simulates a Linux OS, we need to have a pre-compiled (for the Alpha, i.e. the simulated architecture) Linux for m5sim. We can fetch a pre-compiled system disk image version 2.0 beta 3 from the m5sim website:

cd /somewhere/to/put/the/image
tar -jxvf m5_system_2.0b3.tar.bz2

In order to locate the disk image, change line 53 of the file "/your/path/to/m5-stable/configs/common/".
path = [ '/dist/m5/system', '/n/poolfs/z/dist/m5/system' ]
Change it into:
path = [ '/your/path/to/m5_system_2.0b3', '/n/poolfs/z/dist/m5/system' ]

Use terminal in FS mode 

Since the FS mode simulates a Linux OS, we would like to interact with the simulated Linux using a terminal. You can use m5term to create a terminal for the Linux system simulated in the FS mode.

Compile m5term

To compile m5term, issue the command:
cd /full/path/to/m5-stable/util/term

Use m5term in FS mode

You need to open two terminals in your host machine.

In the first terminal, issue the command:
/your/path/to/m5-stable/build/ALPHA_FS/m5.opt /your/path/to/m5-stable/configs/example/
The first terminal will hang at some point. Please do NOT kill the process. It is only waiting for the second terminal.

While the first terminal is hanging. In the second terminal, issue the command:
/full/path/to/m5-stable/util/term/m5term localhost 3456

You will see m5sim booting the Linux in the second terminal.
The figure below shows the first terminal (left) and the second terminal (right). You can click on the figure to enlarge.

The left terminal is a normal host terminal, displaying the information of m5sim running on the host. The right terminal is used as the terminal of the simulated Linux system on m5sim. In the right terminal, you can type commands to interact with it.

You can run (in the right terminal) a pre-compiled benchmark program by typing this command in m5term:
/benchmarks/pthread_mutex_test 4 1000
This program will display its result like this,
Using 4 threads for 1000 iters
Counter value is 4000

To quit the FS mode, you can issue the command from the right terminal:
/sbin/m5 exit


Since the host machine is i386, while the target machine simulated by m5sim is Alpha, we need a cross-compiler that can generate Alpha binary on a i386 host.

If you use the default image "m5_system_2.0b3", the pre-compiled gcc 3.4.3 cross compiler would be the choice.
cd /somewhere/to/put/the/crosscompiler/
tar -jxvf alpha_crosstool.tar.bz2

We can test the crosscompiler with a simple program "hello.c". You can create the "hello.c" in any directory of the host machine.
#include <stdio.h>
int main(){
    printf("hello crosscompiler!\n");
    return 0;

We will first run it in SE mode. Since SE emulates linux system calls, we need to crosscompile it with the "-static" flag. Static forces all used library binaries to be included into the generated binary (this in contrast to DLLs, dynamic linked libraries).
/your/path/to/crosscompiler/opt/crosstool/gcc-3.4.3-glibc-2.3.5/alpha-unknown-linux-gnu/bin/alpha-unknown-linux-gnu-gcc -static -o hello hello.c

Now we can run this program in Syscall Emulation (SE) Mode.
It is handy to reuse the script "m5-stable/configs/example/" by changing line 55.
default=joinpath(m5_root, "tests/test-progs/hello/bin/alpha/linux/hello"),
Change it into:

Issue the following command to run the new hello in SE mode.
/your/path/to/m5-stable/build/ALPHA_SE/m5.opt /your/path/to/m5-stable/configs/example/
Then you can see the "hello crosscompiler!".

Adding files to disk image

To run our cross-compiled programs in the FS mode, we need to add the binary of the program into the disk image. So that when the m5sim boots the Linux, the binary of the program can be found in the file systems of the simulated Linux OS.

Make a directory to mount the disk image.
mkdir /a/directory/to/mount

Mount the disk image to the above directory.
su -c '/bin/mount -o loop,offset=32256 /your/path/to/m5_system_2.0b3/disks/linux-latest.img /your/directory/to/mount'

Then you can add the crosscompiled hello binary into the disk image. Assume you add it to the benchmark directory.
su -c 'cp /your/full/path/to/the/new/hello /your/directory/to/mount/benchmarks/'

You have to umount the disk image before booting it in the FS mode.
su -c 'umount /your/directory/to/mount'

After umount, we can use m5term in FS mode to run the hello binary. We need to launch the FS mode and m5term again, as mentioned in the "Use m5term in FS mode" section. In the m5term, issue the command:

You can see the "hello crosscompiler!".

Linux pthread in FS mode

The SE mode can only emulate tru64 pthread, not Linux pthread.
On the other hand, we only have tool chains targeting Linux, not tru64.
Therefore, in the SE mode, neither Linux pthread nor tru64 pthread can "compile-and-run".

The FS mode can run Linux pthread.
We have the tool chain targeting Linux.
Therefore, in the FS mode, Linux pthread can "compile-and-run".

Unless specifically indicated differently, we assume FS mode and Linux pthread is used in the remainder of this lab.

Compile with pthread

We can create a simple program called "helloPthread.c".
#include <stdio.h>
#include <pthread.h>

void *thread(void *vargp);

int main(){
        pthread_t tid;
        printf("hello main thread!\n");
        pthread_create(&tid, NULL, thread, NULL);
        pthread_join(tid, NULL);
        return 0;

void *thread(void *vargp){
        printf("hello new thread!\n");
        pthread_exit((void *)NULL);
You can refer to a short tutorial on pthread to get started with your own pthread program.

We can compile it with the "-lpthread" flag. Since we can load libc in FS mode, we do not need the "-static" flag any more.
/boring/long/path/alpha-unknown-linux-gnu-gcc -lpthread -o helloPthread helloPthread.c

Run pthread program

Put the helloPthread binary into the disk image, as mentioned in the "Adding files to disk image" section. Launch the FS mode and m5term, as mentioned in the "Use m5term in FS mode" section. Run the helloPthread binary from m5term, you will see the following output.
hello main thread!
hello new thread!

Benchmarking your program

In the FS mode, the statistics includes OS launch overhead. Since we are only interested in the statistics of our program, we have to eliminate the OS launch overhead from the statistics. This can be done by adding your program into the given benchmark scripts.

Assume we have a helloPthread binary located under the directory of "/benchmarks/" in the disk image. Go to directory "/your/path/to/m5-stable/configs/boot" and create a file named "helloPthread.rcS" with the following contents.

cd /benchmarks/
/sbin/m5 resetstats    
/sbin/m5 exit

Insert the following line to the line 104 of the file "/your/path/to/m5-stable/configs/common/".
'helloPthread':        [SysConfig('helloPthread.rcS', '128MB')],

We can get the statistics of the helloPthread program by issue the command:
/your/path/to/m5-stable/build/ALPHA_FS/m5.opt /your/path/to/m5-stable/configs/example/ -b helloPthread
This command runs the "helloPthread.rcS" script after the Linux is booted in the FS mode. You can open m5term to see the output of helloPthread. You can also run helloPthread without m5term, because the "helloPthread.rcS" script will automatically run the helloPthread and then exit from m5sim. Unless you use scripts (like "helloPthread.rcS") to interact with the simulated Linux, you need to open m5term to launch your program or exit from m5sim.

The benchmark script will terminate m5sim after the benchmark binary is executed. The m5sim will display this message on its exit:
"exiting @ cycle xxxxxxxxxx because m5_exit instruction encountered"

The statistics obtained in this way excludes the OS launch overhead. We will take a look at the statistics in the "Example" page.