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:
| Project | Due |
|---|---|
| Lab 0: Getting Real | 09/09 11:59 am EDT |
| Lab 1: Threads | 09/28 11:59 pm EDT |
| Lab 2: User Programs | 10/17 11:59 pm EDT |
| Lab 3a: Virtual Memory | 11/07 11:59 pm EST |
| Lab 3b: Virtual Memory | 11/14 11:59 pm EST |
| Optional Lab 4: File Systems | 12/05 11:59 pm EST |
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!
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!
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.
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.
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.
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.
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.
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).
The basic policies for the project assignments are as follows.
On the other hand, we encourage collaboration in the following form:
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.