CS5600: PintOS Setup and Use

Summary

The lab assumes that you are already have the class' VM setup and that you are comfortable with working in the terminal.

The lab covers

Download and install qemu 1.7.0
Donwload and install PintOS
Run PintOS tests

Download and install qemu 1.7.0

The qemu version installed in your VM has a couple of issues when used along with PintOS. We are going to install an older version of qemu that the staff has tested to work with PintOS.

Start your VM and login with the root account. The password is cs5600.
Open a terminal window and run the following command
```
adduser <login> sudo
```
where you should replace <login> with your login name that you use to login to your VM and work on CS5600 homework.
Logout as from the root account and login with your normal user account.
Open a terminal and run the following command to update your Debian’s available packages
```
sudo apt-get update
```
You will be asked for your user’s password.
Run the following command to install Debian packages needed by qemu
```
sudo apt-get install -y pkg-config zlibc zlib1g-dev libglib2.0-dev
```
Make sure you are in your home folder and download the source for qemu 1.7.0 using the following command
```
wget http://www.ccs.neu.edu/home/skotthe/classes/cs5600/fall/2015/labs/pintos-setup/qemu-1.7.0.tar.bz2
```
Extract the source code of qemu using the following command
```
tar xvjf qemu-1.7.0.tar.bz2
```
This will create a folder with the name qemu-1.7.0 in your home folder.
Enter the newly creates qemu-1.7. folder and configure qemu with the following command
```
./configure --target-list=i386-softmmu
```
Build qemu by running make
```
make
```
Install the newly build qemu by running the following command
```
sudo make install
```
The newly build qemu binary will be installed in /usr/local/bin
Navigate to /user/local/bin and create a softlink to the qemu binary with the name qemu using the following commands
```
cd /usr/local/bin; sudo ln -s qemu-system-i386 qemu
```

Verify that you have qemu pointing to qemy-system-i386 by running

ls -l

You should see something similar to

(therapon@vdebian) > ls -l
total 13544
lrwxrwxrwx 1 root staff      16 Oct 12 20:17 qemu -> qemu-system-i386
-rwxr-xr-x 1 root staff  985116 Oct 12 20:16 qemu-ga
-rwxr-xr-x 1 root staff 2553968 Oct 12 20:16 qemu-img
-rwxr-xr-x 1 root staff 2541500 Oct 12 20:16 qemu-io
-rwxr-xr-x 1 root staff 2497480 Oct 12 20:16 qemu-nbd
-rwxr-xr-x 1 root staff 5281420 Oct 12 20:16 qemu-system-i386

Check that qemu points to qemu-system-i386

Update your path so that typing qemu causes /usr/local/bin/qemu to run. To perform this step you will need to update your PATH variable in your profile’s initialization file. If you are using bash then open the file .bashrc in your home folder and add the following line at the end of the file.
```
PATH=/usr/local/bin:$PATH
```
Once you have made the addition to .bashrc go back to your terminal and re-load the file so that the shell updates itself with your new change.
```
source ~/.bashrc
```
If you are using a different shell then update the appropriate initialization file. Test that your shell now runs the correct installed version of qemu
```
(therapon@vdebian) > qemu -version                                                        ~
QEMU emulator version 1.7.0, Copyright (c) 2003-2008 Fabrice Bellard
```

Download and install PintOS

You will want to install the PintOS source code inside the repository that the class staff has created for you team.

You are now working in teams. You are free to choose any pattern you prefer for managing your repository. Be warned however that is your responsibility to deal with that process. The staff will not accept excuses like "my partner messed up the merge" or "my partner pushed some code that broke the code, it was working fine a minute ago". We treat you as a team. The whole team is responsible.

Download the pintos archive
```
wget http://www.ccs.neu.edu/home/skotthe/classes/cs5600/fall/2015/labs/pintos-setup/pintos-src.tgz
```
wget will store the file in the same directory that you run wget. We will refer to this directory as PINTOS_DOWNLOAD_PATH in the rest of this document.
Navigate to the folder (repo) that you would like to extract the PintOS source. We will refer to this folder as PINTOS_HOME in the rest of this document. Run the following command to extract the archive
```
tar xvzf PINTOS_DOWNLOAD_PATH/pintos-src.tgz
```
We need to add certain PintOS programs to our PATH. Open your shells initialization file (.bashrc if you are using bash) and add the PINTOS_HOME/pintos/src/utils to your PATH variable. Here is what it should look like once you are done
```
PATH=/usr/local/bin:$PATH:/home/therapon/cs5600-pintos-project1/pintos/src/utils
```
In my case PINTOS_HOME = /home/therapon/cs5600-pintos-project1/
In order to use gdb with PintOS we need to configure some gdb macros. The gdb macros are stored in the file PINTOS_HOME/pintos/src/misc/gdb-macros.
1. Go to the folder PINTOS_HOME/pintos/src/utils and using an editor open the file pintos-gdb.
2. Find the string GDBMACROS and change its definition to point to the full path of the file gdb-macros. For example
  GDBMACROS=/home/therapon/cs5600-pintos-project1/pintos/src/misc/gdb-macros
  where in my case PINTOS_HOME = /home/therapon/cs5600-pintos-project1/.
Navigate to the folder PINTOS_HOME/pintos/src/utils and build the remaining PintOS utilities by running
```
make
```
PintOS can use different emulators in order to run your code. We need to tell PintOS that we want to use qemu. Navigate to PINTOS_HOME/pintos/src/threads and use an editor to open the file called Make.vars. Search for the line that contains the following text
```
SIMULATOR = --bochs
```
and change it to say
```
SIMULATOR = --qemu
```

Running PintOS tests

The PintOS source code comes with a list of tests. The class staff will use these tests to grade your assignments. You cannot change these tests. The graders have a clean copy of the tests included in the PintOS and will run those against your submission.

You are however encouraged to add new tests of your own.

Running a single test

Open a terminal and navigate to the folder PINTOS_HOME/pintos/src/threads.
Build the threads project using make
```
make
```
Building the project will generate a new folder called build.
Tests for each project are locate in the folder PINTOS_HOME/pintos/src/tests/. Each project has a sub-folder that contains all its tests, for example, PINTOS_HOME/pintos/src/tests/threads contains all the tests for the threads project (or project 1 for our class).

Using your terminal, navigate to the threads build folder and run the following command

make tests/threads/alarm-single.result

The command will run the tests alarm-single and will generate the following files

PINTOS_HOME/pintos/src/threads/build/tests/threads/alarm-single.output contains anything that the test outputs during its run
PINTOS_HOME/pintos/src/threads/build/tests/threads/alarm-single.errors contains any errors that occurred during the tests' run

PINTOS_HOME/pintos/src/threads/build/tests/threads/alarm-single.results contains the tests' result, typically the word FAIL or PASS

If you would like to run the tests and see the output on your terminal, as well as store it in the .output file run your tests by passing VERBOSE=1, e.g.

make VERBOSE=1 tests/threads/alarm-single.result

Here is what the output on my screen looks like

test@vdebian:~/pintos/src/threads/build$ make VERBOSE=1 tests/threads/alarm-single.result
pintos -v -k -T 60 --qemu  -- -q  run alarm-single < /dev/null 2> tests/threads/alarm-single.errors |tee tests/threads/alarm-single.output
qemu -hda /tmp/ZtDyqkudCC.dsk -m 4 -net none -nographic -monitor null
PiLo hda1
Loading...........
Kernel command line: -q run alarm-single
Pintos booting with 4,088 kB RAM...
382 pages available in kernel pool.
382 pages available in user pool.
Calibrating timer...  104,755,200 loops/s.
Boot complete.
Executing 'alarm-single':
(alarm-single) begin
(alarm-single) Creating 5 threads to sleep 1 times each.
(alarm-single) Thread 0 sleeps 10 ticks each time,
(alarm-single) thread 1 sleeps 20 ticks each time, and so on.
(alarm-single) If successful, product of iteration count and
(alarm-single) sleep duration will appear in nondescending order.
(alarm-single) thread 0: duration=10, iteration=1, product=10
(alarm-single) thread 1: duration=20, iteration=1, product=20
(alarm-single) thread 2: duration=30, iteration=1, product=30
(alarm-single) thread 3: duration=40, iteration=1, product=40
(alarm-single) thread 4: duration=50, iteration=1, product=50
(alarm-single) end
Execution of 'alarm-single' complete.
Timer: 279 ticks
Thread: 0 idle ticks, 279 kernel ticks, 0 user ticks
Console: 986 characters output
Keyboard: 0 keys pressed
Powering off...
perl -I../.. ../../tests/threads/alarm-single.ck tests/threads/alarm-single tests/threads/alarm-single.result
pass tests/threads/alarm-single

Alternatively, if you just want to run a test without generating any files or checks,

pintos --qemu -k -T 60 -- -q run alarm-single

The pintos program takes a lot of options. Use pintos --help to see all the possible options.

Everything after the word pintos and before the double-dash -- are the arguments to the pintos program
Everything after the double-dash -- are the arguments passed to the PintOS kernel.

Running all the tests

Even before you add any code to the project, some of the existing test will pass and some will fail. Your goal is to make all the tests pass. Ensure that your code makes failing tests pass and makes passing test still pass.

To run all the tests for a project

Navigate to the projects folder
```
cd PINTOS_HOME/pintos/src/threads
```
Build the project
```
make
```
Navigate to the newly created build folder
```
cd build
```
Build all the test with the target check
```
make check
```
If you want to see the output on your terminal pass in the VERBOSE=1 argument to make Note that the tests take some time to complete depending on how fast your machine is.