A crucial component of the course is the labs. There will be two types of lab assignments: xv6 extensions and advanced systems programming.
xv6 is a simple, C/x86 reimplementation of an early Unix (v6). xv6 is very basic, and lacks many of the common features of modern-day OSes, such as Windows, Linux, or OS X. Nevertheless, it is a real operating system that will boot on a PC. It includes most key operating systems abstractions, including a bootloader, memory protection, memory relocation, multiprogramming and a rudimentary file system. Over the course of the semester, you will implement several features in xv6 to acquaint yourself with kernel-mode programming.
You will find the xv6 book to be a helpful organization and source code of the xv6 operating system. Reading it can significantly help you with the labs.
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.
The second set of lab assignments include systems programming exercises in which you use advanced OS API to develop programs and/or libraries similar to your CSE 320 assignments, but at a more advanced level.
Each student enrolled in the class will be given a Linux 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 in 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/fa17/cse306/xv6-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 xv6 labs in a subdirectory called xv6 in your home folder, this is one way to do it:
$ git clone -b lab1 http://compas.cs.stonybrook.edu/~nhonarmand/courses/fa17/cse306/xv6-labs.git xv6 Cloning into 'xv6'... Checking connectivity... done.
This will clone the repository and checkout the code handout for Lab1 in the xv6 folder. Now, you have a local git repo with your xv6 code in it. Take advantage of the wide variety of the features that Git provides. 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.
After checking out the xv6 repo, you should set your NETID in the conf/user.mk file. Make sure you commit your change.
In these labs, you will progressively build up your kernel. For each lab, we will provide you with some additional/modified 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.
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 new code. 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, GitHub, or similar services as your backup repo. Just remember that you ARE NOT allowed to put your code on publicly accessible repos.
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 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.) This file should contain a single line formatted as follows (where n is the number of late hours):
late hours taken: n
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 some labs, 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!