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

  1. Donwload and install PintOS

  2. 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 project called vm. 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.

  1. Download the pintos archive

    wget https://course.ccs.neu.edu/cs5600f17/pintos/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.

  2. 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

  3. 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/

  4. 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/.

  5. Navigate to the folder $PINTOS_HOME/pintos/src/utils and build the remaining PintOS utilities by running

    make

  6. 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/vm 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

  1. output - a text file with all of the console output created during the run of this test

  2. errors - a text file with all of the error output created during the run of this test

  3. 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

  1. Open a terminal and navigate to a project folder i.e., $PINTOS_HOME/pintos/src/vm.

  2. Build the vm project using make

    make

  3. Building the project will generate a new folder called build.

  4. 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/vm contains all the tests for this project. After building a project, all of its tests are copied over into the build folder.

  5. Using your terminal, navigate to the vm build folder and run the following command

    make tests/vm/mmap-clean.result

    The command will run the tests mmap-clean and will generate the following files

    • $PINTOS_HOME/pintos/src/vm/build/tests/vm/mmap-clean.output contains anything that the test outputs during its run

    • $PINTOS_HOME/pintos/src/vm/build/tests/vm/mmap-clean.errors contains any errors that occurred during the tests' run

    • $PINTOS_HOME/pintos/src/vm/build/tests/vm/mmap-clean.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/vm/mmap-clean.result

      Here is what the output on my screen looks like when I run the test mmap-clean in verbose mode.

       make VERBOSE=1 tests/vm/mmap-clean.result
perl -I../.. ../../tests/vm/mmap-clean.ck tests/vm/mmap-clean tests/vm/mmap-clean.result
FAIL tests/vm/mmap-clean
Test output failed to match any acceptable form.

Acceptable output:
  (mmap-clean) begin
  (mmap-clean) open "sample.txt"
  (mmap-clean) mmap "sample.txt"
  (mmap-clean) write "sample.txt"
  (mmap-clean) munmap "sample.txt"
  (mmap-clean) seek "sample.txt"
  (mmap-clean) read "sample.txt"
  (mmap-clean) file change was retained after munmap
  (mmap-clean) end
Differences in `diff -u' format:
  (mmap-clean) begin
  (mmap-clean) open "sample.txt"
  (mmap-clean) mmap "sample.txt"
- (mmap-clean) write "sample.txt"
- (mmap-clean) munmap "sample.txt"
- (mmap-clean) seek "sample.txt"
- (mmap-clean) read "sample.txt"
- (mmap-clean) file change was retained after munmap
- (mmap-clean) end

      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 mmap-clean

      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.

  1. Navigate to the projects folder

    cd $PINTOS_HOME/pintos/src/vm

  2. Build the project

    make

  3. Navigate to the newly created build folder

    cd build

  4. 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.