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

Donwload and install PintOS
Run PintOS tests

Download and install PintOS

You will want to install the PintOS source code inside the repository that the class staff has created for your team. The instructions below are for the first project called threads. You will have to follow these instructions for later projects. In later projects you will have to import the source code from your previous projects as some features will depend on your previous project’s solution.

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 tests, it was working fine a minute ago". We treat you as a team. The whole team is responsible for the repository and the quality of the code.

Download the pintos archive
```
wget http://www.ccs.neu.edu/home/skotthe/classes/cs5600/fall/2016/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/utils/pintos-gdb.
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=$PINTOS_HOME/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.

Each project contains it’s own tests folder that contains individual tests. Some of the tests are the same across projects and some vary. The tests are located inside your build folder under tests/<project_name>/<test_name>.

The execution of a test generates 3 files in the same folder as the test’s source. The files have the same name as the test but have a different extension

output - a text file with all of the console output created during the run of this test
errors - a text file with all of the error output created during the run of this test
result - a text file with the final outcome of the test’s run, should be one of two words PASS if the test succeeded and FAIL if the test failed.

Running a single test

Open a terminal and navigate to a project folder i.e., $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). After building a project, all of its tests are copied over into the build folder.

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.result contains the test’s 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 when I run the test alarm-single in verbose mode.

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

The testing scripts try to be clever and only run tests if the test’s 3 output files are not present. So if you want to run the tests again you should remove the 3 output files.

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, i.e., --qemu -k -T 60 in our example above.
Everything after the double-dash -- are the arguments passed to the PintOS kernel, i.e., -q run alarm-single in our example above.

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

Running all the tests for the project thread will take time.

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, i.e.
```
make VERBOSE=1 check
```
Note that the tests take some time to complete depending on how fast your machine is.