Pintos Project Guide

A significant element of this class are programming projects using Pintos. Pintos is a teaching operating system for 80x86. It is simple and small (compared to Linux). On the other hand, it is realistic enough to help you understand core OS concepts in depth. It supports kernel threads, virtual memory, user programs, and file system. But its original implementations are premature or incomplete. Through the projects, you will be strengthening all of these areas of Pintos to make it complete.

These projects are hard. They have a reputation of taking a lot of time. But they are also as rewarding as they are challenging. Since Pintos is designed for 80x86 architecture, at the end of the projects, you could run theoretically the OS that you built on a regular IBM-compatible PC! Of course, during development, running Pintos on bare metal machines each time could be time consuming. Instead, you will run the projects in an x86 emulator, in particular, Bochs or QEMU. Pintos has also been tested with VMWare Player.

We will start with a pre-project and then do four substantial projects:

Groups

Lab 0 is an individual project. From Lab 1 and onwards, you can work in groups of 1-3 people. We will overlap Lab 0 with the stage of forming groups. So start talking with your classmates around once the course begins!

Getting Started

To get started, you need to get a copy of the Pintos source code distribution:

$ git clone https://github.com/jhu-cs318/pintos.git

Before you can compile and develop on Pintos, you will need to have a machine with the appropriate environment setup. The CS department’s lab machines support Pintos development. You can also work on the projects on your own machine (e.g., Ubuntu, Fedora, Mac OS). Read the setup guide to setup the toolchain properly.

After your toolchain is ready, you can do a quick test:

$ cd pintos/src/threads
$ make
$ cd build
$ pintos --

If successful, you should see the QEMU window and a Boot complete message:

PiLo hda1
Loading...........
Kernel command line:
Pintos booting with 3,968 kB RAM...
367 pages available in kernel pool.
367 pages available in user pool.
Calibrating timer...  838,041,600 loops/s.
Boot complete.

Now, follow the more detailed instructions to browse the source tree, compile and run Pintos!

Documentation

• The complete Pintos document in HTML, PDF.
    Note

  The complete document is convenient to read all information in one place. However, for project descriptions, please refer to our lab0-4 pages linked in the top banner of this course website (e.g., Lab 1). They contain the latest information and tips.
• The reference page page lists the essential documents to refer to for working on the projects
• The original Pintos paper

Version Control

We will be using Git for version control in the class. If you are new to Git, there are plenty of tutorials online that you can read, e.g., this one.

Grading

We will grade your assignments based on test results (60% of your grade) as well as design quality (40% of your grade). Note that the testing grades are fully automated. So please turn in working code or there is no credit. The grading policy page lists detailed information about how grading is done.

Submission

We will be using GitHub classroom to distribute and collect assignments. You do not have to do anything special to submit your project. We will use a snapshot of your GitHub repository as it exists at the deadline, and grade that version. You can still make changes to your repository after the deadline. But we will be only using the snapshot of your code as of the deadline.

Late Policies

By default, each team will be given a 6-day^* late-tokens in total that can spread in the four labs. It can be used for team members to prepare interviews, attend conferences, etc. When you use the grace period tokens, you just need to let us know how much of the token you want to use. We won’t be asking why. We strongly recommend you to reserve these late tokens for use in later labs (especially lab 3 and lab4), which are much more challenging than earlier labs.

Late submissions without or exceeding grace period will receive penalties as follows: 1 day late, 15% deduction; 2 days late, 30% deduction; 3 days late, 60% deduction; after 4 days, no credit.

^*: In prior offerings, we give 72-hour late tokens. We give 6-day late-tokens this year to accommodate potential difficulties students might encounter due to the covid pandemic.

Tips

GDB Port

If you are using gdb on the lab machines to debug Pintos, you may encounter a port conflict error. That’s because pintos --gdb will invoke the -s option with QEMU, which in turn is a short-hand for -gdb tcp::1234. So multiple users might try to compete for the same port. We’ve modified the pintos script to add two options to work around this.

• --gdb-port to specify a port explicitly. You can choose any port that’s available to bind gdb, e.g., pintos --gdb --gdb-port=2430.
• --uport to calculate a port number deterministically based on the user id. So different users on the lab machines will get a different port. Example: pintos --gdb --uport. You can find the generated port in the command verbose output (e.g., qemu-system-i386 ... -gdb tcp::25501).

When you use these two options, you also need to change the target remote command in the gdb session to point to the specified/calculated port instead of 1234.

Mac Users

The original Pintos was mainly developed and tested for Linux (Debian and Ubuntu in particular) and Solaris. It has some issues to run on Mac OS. We have fixed a number of issues and provided scripts to make it run more smoothly with Mac OS. They should be working mostly. But one caveat that you should be aware of is that the setitimer system call (used by the pintos script to control runtime of tests) in Mac OS seems to have some bug, which may trigger premature timeout when using pintos with --qemu. To work around this, you can either use the Bochs simulator --bochs instead (modify the src/{threads,userprog,vm,filesys}/Make.vars) or increase the timeout passed to pintos (e.g., change TIMEOUT in src/tests/Make.tests to 400).

Cheating and Collaboration

The basic policies for the project assignments are as follows.

• Never copy project code or text found on the Internet, e.g., GitHub.
• Never share code or text on the project. That also means do not make your solutions public on the Internet.
• Never use other group's code or text in your solutions. This includes code/text from prior years or other institutions.
• You may read but not copy Linux or BSD source code. You must cite any document or code that inspired your code. As long as you cite what you used, it's not cheating. In the worst case, we deduct points if it undermines the assignment.

On the other hand, we encourage collaboration in the following form:

• Explain a concept to another student, or asking another student to explain a concept to you.
• Discuss algorithms or approaches for an exercise. But you should not exchange, look at, or copy each other's code.
• Discuss testing strategies and approaches
• Help someone else debug if they've got stuck. But you should not give that student code solutions.

The course staff will actively detect possible ethics violations. For each project submission, we will run automated cheating detection tools to check your submission against a comprehensive database of solutions including solutions on the Internet, past submissions, and solutions from other institutions.