A crucial component of the course is the labs. You will implement (the interesting pieces of) a real operating system that will boot on a PC. The operating system is called JOS. (JOS was developed at MIT and has been used in courses at several other schools.)
JOS is simpler than Linux and Windows, but it includes most key operating systems abstractions, including a bootloader, memory protection, memory relocation, multiprogramming, a rudimentary file system, and a command shell.
JOS can be thought of as an exokernel, where the kernel implements a minimal set of core functionality that safely exports hardware resources to applications. These low-level kernel interfaces may be inconvenient for user processes to use directly, so user processes will make use of a "library operating system" (libos) to abstract these low-level exported resources into more convenient programming abstractions.
Each lab in the series enhances the functionality of your operating system. Each lab builds on the previous one, so it is important that you design, build, and test carefully at each step. Carelessness in early labs will be costly down the road. There are not a lot of lines of code to write on this project; take the time to understand each phase before moving to the next one.
Each student enrolled in the class will be given a virtual machine on a departmental teaching cluster with the basic required software installed. You will have root access to this machine, and be able to install additional tools (editors, debuggers, etc) as you see fit.
You are also welcome to install the needed software on your own laptop. The course staff is not available to help you debug your personal laptop configuration.
Good citizenship. You have administrator access to this VM and can install anything you like. That said, to keep load down, DO NOT INSTALL A GRAPHICAL DESKTOP on the VM. You may tunnel the X protocol (ssh -X) to your local machine and display your editor in a window.
Student VMs are already provisioned with the basic set of software packages needed for the lab assignments, including compiler tool chain (gcc), Qemu system emulator and the GDB debugger). You can access your VMs over SSH. Your account's username is student but there is no password associated with that account. Instead, you will use public key authentication to access the machines.
You will receive your VM's IP address and authentication key pairs over a private email. The SSH server on the VM is configured to use port 130. Assuming you have saved your private key as vm506_id, you can SSH to your VM using the following command:
$ ssh student@<your_VM_IP_address> -i vm506_id -p 130
The files you will need for the labs are distributed using the Git version control system. Git is a powerful, but tricky, version control system. We highly recommend taking time to understand git so that you will be comfortable using it during the labs.
We recommend the following resources to learn more about Git:
Lab code will be handed out using a read-only git repo at http://compas.cs.stonybrook.edu/~nhonarmand/courses/sp17/cse506/jos-labs.git. The first thing you need to do after logging in to your VMs, is to clone this repo to get the code for Lab1. Assuming you want to keep your lab in a subdirectory called lab in your home folder, this is one way to do it:
$ git clone http://compas.cs.stonybrook.edu/~nhonarmand/courses/sp17/cse506/jos-labs.git lab Cloning into 'lab'... Checking connectivity... done.
This will clone the repository and checkout the code handout for Lab1 in the labs folder. Now, you have a local git repo with your JOS code in it. Take advantage of the wide variety of the features that Git provides. In particular, Git allows you to keep track of the changes you make to the code. For example, if you are finished with one of the exercises, and want to checkpoint your progress, you can commit your changes by running:
$ git commit -am 'my solution for lab1 exercise9' Created commit 60d2135: my solution for lab1 exercise9 1 files changed, 1 insertions(+), 0 deletions(-)
You can keep track of your changes by using the git diff command. Running git diff will display the changes to your code since your last commit, and git diff origin/lab1 will display the changes relative to the initial code supplied for this lab. Here, origin/lab1 is the name of the git branch with the initial code you downloaded from our server for this assignment.
In these labs, you will progressively build up your kernel. With each new lab, we will provide you with some additional source. Every new lab handout will be distributed on a different branch of the same read-only repo above: Lab1 handout will be on branch lab1, Lab2 on branch lab2 and so on.
At the beginning of each lab, you will need to pull the new code for that lab from the repo, and merge it with your code from the previous lab, before you can start working on the new lab. For example, once Lab2 handout is posted, you can do the following to pull and merge it with your existing Lab1 code (after making sure you have committed your Lab1 code on branch lab1:
$ git commit -am "final lab1 commit" $ git pull $ git checkout -b lab2 origin/lab2 Branch lab2 set up to track remote branch refs/remotes/origin/lab2. Switched to a new branch "lab2"
The git checkout -b command shown above actually does two things: it first creates a local branch lab2 that is based on the origin/lab2 branch provided by us, and second, it changes the contents of your lab directory to reflect the files stored on the lab2 branch. Git allows switching between existing branches using git checkout branch-name, though you should commit any outstanding changes on one branch before switching to a different one.
You will now need to merge the changes you made in your last lab (lab1) branch into the new (lab2) branch, as follows:
$ git merge lab1 Merge made by recursive. kern/kdebug.c | 11 +++++++++-- kern/monitor.c | 19 +++++++++++++++++++ lib/printfmt.c | 7 +++---- 3 files changed, 31 insertions(+), 6 deletions(-)
In some cases, Git may not be able to figure out how to merge your changes with the new lab assignment (e.g. if you modified some of the code that is changed in the second lab assignment). In that case, the git merge command will tell you which files are conflicted, and you should first resolve the conflict (by editing the relevant files) and then commit the resulting files with git commit -a.
It is highly recommended that you back up your lab code somewhere outside your VM so that you can recover your code in case you somehow manage to render your VM useless. The course staff can always reset your VM image to its pristine state at beginning of the semester, but that will obviously erase your lab directory. Therefore, you will need a backup of your local repo to let you recover your code under such circumstances.
Fortunately, the department provides git repos for student use. You can email <rt __at__ cs.stonybrook.edu> to have your repo activated. Once you get your repo, you can add it as a "remote" to your local repo and periodically push your local repo to it to keep your work safe.
Alternatively, you can use a private repo from BitBucket or similar services as your backup repo. Just remember that you ARE NOT allowed to put your code on publicly accessible repos (such as github).
We will be grading your solutions with a grading program. You can run make grade to test your solutions with the same grading program.
Labs will be handed in using the make handin command. When you are ready, commit all your code to the appropriate branch of your local repo, and then type make handin. This will pack and sign your code, and send it to a write-only departmental server used for assignment and exam handins.
You do not need to turn in answers to any of the questions in the text of the lab. Do answer them for yourself though! They will help with the rest of the lab. Note: lab questions may reappear as exam questions.
You get 72 free late hours during the semester. They are intended to let you manage incidents, holidays, travels, other deadlines, conferences, etc. without having to explain to the course staff. Use them wisely! After they are used up, each hour of late submission will cost 2% of the assignment grade.
When you are ready to hand in your lab, add an entry to slack.txt noting how many late hours you have used (or wish to use) both for this assignment, and in total over all assignments so far. (This is to help us agree on the number that you have used.) Then run make handin in the lab directory.
If you submit multiple times, we will take the latest submission and count late hours accordingly.
In each lab, you may complete challenge problems for extra credit. If you do this, please add entries to the file called challenge<X>.txt, where X is the lab number to which the challenge problem belongs (not necessarily the current lab). Each entry should include a short (e.g., one or two paragraph) description of what you did to solve your chosen challenge problem and how to test it. If you implement more than one challenge problem, you must describe each one. Be sure to list the challenge problem number.
You can do any challenge of any lab at any point during the semester. So, do not handin your lab late just to finish a challenge. You can do it later!