To ensure you have deep understanding of how operating systems work, you will implement an x86 operating system kernel (sounds fun!). Since implementing such a kernel entirely from scratch is infeasible in a single quarter (and requires an in-depth knowledge of the x86 architecture), we will be using the Pintos instructional kernel (a minikernel). This kernel already implements most of the low-level functionality, allowing the student to concentrate on implementing higher-level operating system functionality, such as thread management, memory management, etc. while still allowing them to peek under the hood. This kernel also has the advantage of having been used in several OS courses at other universities, which means it has been thoroughly tested and documented. Pintos overall contains 26 KLOC; a real OS like Linux contains 15 millions LOC.
Pintos links are available on the main page.
All of the assignments will be in C. We assume that you have enough background in C programming. To successfully complete these projects, you must understand fundamental concepts in operating system design and implementation. The class meets two times a week for lectures that provide this conceptual scaffolding. All information necessary to complete the assignments will be available from the class web page.
Student: "Professor, I still don't get an idea of what we'll be doing in the projects."
That is a great question. Let's imagine this. In your current OS, you can create directories and subdirectories and store your data in the form of files. That is convenient for you, but we cannot take this for granted -- long time ago OS architects decided that files and directories are a good way to help users manage their data. In this class, you are given Pintos. Unfortunately, Pintos does not support directories, yet. Pintos users can only create files in the top directory, but you cannot create subdirectories. Thus, all files reside in the top directory). To make Pintos users happy, in one of the projects (P4) you will add subdirectory support in Pintos.
When many students run Pintos on a single machine, the machine can become slow, and students' productivity is reduced. Thus, we will give you a virtual machine (we name it "230-VM") that contains all the necessary simulator and tools to run the project. We will send you instructions on how to run the VM on VirtualBox on your personal laptop. This way you can work locally in your laptop. The nice thing is that your Pintos code can run with the same configuration on CSIL and 230-VM.
One important to note is that: NEVER run 230-VM on CSIL machines. If you do so, you are doing disservice to other users. (Imagine if tens of VMs running on a single CSIL machine). If you do so, the techstaff will kill your VM process.
If you wish to run Pintos directly on CSIL machine, that would be fine too. But we really encourage running Pintos on VM.
Every time you pass a test successfully and your code is compilable without any error, we recommend you to commit your code. It's a good habit to commit your code as often as you can. (You don't need to commit the outputted binary file). In the past, there were cases where student lost their code (or cannot revert to the last stable version because there was no prior commit). The fact that we use repository means you can commit as often as you can. If you lose your code, it's your responsibility and we don't tolerate this as we already warn you about this.
We provide a simple "gitc" script (a wrapper) to help you check that you've committed all the files properly. Please find the "gitc" script in the Project 1's guide folder (please go to the main page).
The projects are a fundamental part of this course (a high percentage of your grade!). Each of the project requires a significant amount of time, so please do NOT procrastinate! Arguably, these projects are some of the hardest projects you ever write in your undergraduate experience. It is likely that things will take longer than you expect. Do not wait until the day before the assignment is due to start. These assignments should be started pretty much when they are handed out, well before they are due.
If you don't trust what we say here, you can read previous course evaluations and read what previous students said about the projects.
Your projects will be graded on how well your implementation works. Your project will be automatically graded. We will test your program on a suite of input sets. Your grade will be based on how many of the tests your application passes. In fact, you can check by yourself how many tests you pass.
Each individual test has a weight which can be found in the Grading and Rubric files (e.g., for Project 2, please go to src/tests/userprog and open the Grading and Rubric.* files). If you pass all the tests and have a good design document, you will get 100 points.
In the original project description (from Stanford), it says that the design document accounts for half of the grade. That is wrong. In our cs230, your design document accounts for 10% of the project grade, and passing the tests accounts for 90% of the project grade.
When we grade your projects, we will run it on a CSIL machine (or the class VM that we will provide). We do not accept excuses such as "It works on my Linux laptop, but I don't know why the tests are failing on CSIL machines". You must make sure that your project implementation runs on CSIL machines.
You will work in pairs.
You should find one project partner. Feel free to give information about your major, standing, or technical background. After you form a group of two, you should inform the instructor AND the TAs (see below).
You should get a partner by Wednesday in week2. If you haven't declared your project partner, we will assume you work alone. Find a project partner as early as you can. If you're too late, there is a chance that there is no partners left.
If you wish to work alone, that would be fine too. (But I warn you there is a lot of work). Please email the instructor AND the TA if you decide to work alone, the TA will generate a special repo for you.
If things don't work out with your partner, you can break your partnership anytime in the middle of the quarter (but NOT within 4 days before a deadline). Let us know.
When you've found a partner, please email all of us (the instructor and the TAs) (cs230-uc at googlegroups.com) with the following format:
Email title: cs230 project partner (yourCNetID, partnerCNetID)
Email body:
yourFirstName yourLastName (yourCNetID)
partnerFirstname partnerLastName (partnerCNetID)
(and cc your partner as well).
Note that we need your CNetID, not your 6-digit ID.
It will take 24-48 hours for the group repository to be created (the nature of batch jobs in our GitLab platform). Meanwhile, you can proceed with the project using your individual repositories.
If you decide to work alone, your repo will look like this: https://proj.cs.uchicago.edu/firstFourLettersOfyYourFirstName------cs230-aut-YY/group_repo (where YY is this year, e.g. 23, 24, 25). If you believe your GitLab repository has not been created, please contact us.
If you work with a partner, in the design document, in the first line, please report the percentage of contribution of each member of the team. For example:
An ideal scenario: Jane ~50%, Joe ~50%
A not ideal, but honest scenario: Beth 90%, BusyBoy 10%
Please respect the exact date and time of each deadline. By default, the deadline time is 11:59:59pm, please submit before then. We will download your version of the code at midnight time. Any changes after that will be ignored.
Please be careful within minutes near the deadline; sometimes your latest edits give you a worse grade than your earlier version (e.g. your committed version at 11:15pm is better). It is your responsibility to revert the final version to the best version.
Do not commit any new updates within one hour after the deadline because we might check out your code few minutes after the deadline.
We allow students to submit late submission in this way:
- 1 day late: A total of 10% off from your project score
- 2 day late: A total of 20% off
- 3 day late: A total of 40% off
- 4 day late: A total of 80% off
- 5 day late: I guess there's no point to submit (?)
These are only applicable to P1 to P3. For P4, there will be no extension (we need to wrap up grading, etc. in the final week).
Other than these leniency, we will not provide any other exception.
Note that the TA will only help until the deadline day. After that, you are on your own. (We need to move on to the next project).
The TAs will provide a lot of office hours., but at the same time the TAs are not expected to debug every bug that you face So, we start having this policy:
In every project, the TA will let you know the score ranges where they can still help you. The score ranges are based on our grading script (not the original make file). That is, if you want to know the actual score of your project, run our grading script (the project README file will tell you how). Pintos is a big project that fits one full semester. But since we run a quarter system with only 10 weeks, we reduce the project size. In each project, the TA will let you know the tests that you need to pass to get to 100 points (based on our grading script). As long as you get 100 (run it multiple times please), you can enjoy your life.
So, for example, let's say for Project X, there will be three score ranges (again, based on the grading script):
(a) 1st range: 0-33 points: The TAs will prioritize helping students who are still within this range.
(b) 2nd range: 33-66 points: If the TA's queue is empty, the TAs will also help debug issues for students that currently have a project score of 33-66 points. If the TA's queue is not empty, the TAs will help prioritize those in the 1st range.
(c) 3rd range: 66-100 points: Students who have reached this range, i.e. a minimal of 66 points will not get any TA's help in debugging bugs. The TAs will still answer "design" questions though. We expect that students already learn from the TAs the debugging process in earlier ranges.
Note that all these numbers, 0, 33, and 66 are just sample numbers. The score ranges will vary in each project and the TA will let you know.
We have TA support for this course. The role of the TA is to help you with your projects. Remember that a TA has a maximum bandwidth; if you start your project too late and you ask questions near the deadline, then it's possible that the TA won't be able to help you due to the high number of requests the TA needs to help. So always start the project early, so you can ask for help early.
TA office hours can be found here: Contact Us.
The TA also has an office hour almost every day. So please make use of the TA's availability. If you cannot come during TA office hours (i.e. really conflicts with your other schedule) or his office hours were always full, then you can email the TA requesting a meeting time outside the normal office hours. If the TA does not respond to your email in 24 hours, please let the instructor know.
Since cs230 is not an introductory class, we expect your maturity in asking project-related questions. We cannot accept questions such as "I don't know where to start". We expect you to try everything first by yourself. If you have tried debugging a problem for hours and you feel you are stuck, then that is a good point where you can ask help from the TA. When asking questions, you need to prepare the details (e.g., "I tried this and that (be specific), but it does not work. You can get my code from this GitLab repository path: ..."). This way you are helping the TA to solve your problem faster.
IMPORTANT NOTE: For efficiency of troubleshooting time with the TA, before you meet the TA, we strongly suggest you to create a subdirectory in your GitLab reposity (e.g. p1-doesNotWork) that reflects the code that does not work. This way, the TA can easily checkout your non-working code and debug the problem in his/her own machine. You and the TA then can try out different fixes on this non-working version.
All technical questions about the projects should be directed to the TA.
We use GitLab entirely for projects. You should know how to use Git. If not, you must learn it by yourself (or get a project partner who knows Git).
Please read the "setup.txt" file carefully! The file is in the P1 guide directory (check the main page). Note that we expect to see pintos-p1, pintos-p2, pintos-p3 and pintos-p4 directories in your GitLab repository. These are the directories that we will grade.
We also provide a bonus script, "web", available inside the P1 guide directory. Have you ever wondered what's the fastest way to manage all the many links from all your classes and in your life? I provide you a simple "web" script. Open the file with your text editor so you know what to do with it.
Using this script is not mandatory. But if you do use it, you'll thank me for saving all those wasted time going to your browser, going to the bookmarks, click here, click there, etc. :)
Example:
Me: "Go to the class' videos directory in Canvas"
The old you: find your browser icon, click it, find the class site in your bookmark, find the Videos link, click it" (a total of ~10 seconds or more)
The new you (using "web"): just type "web 230-videos" in your shell (and boom! 2 seconds!)
I created this script and have been using this for more than five years, and now my web script has over 600 keyword-link pairs. Bookmarking 600 links in your web browser is not manageable.
Please make sure you read: Academic Honesty.