David R. Cheriton School of Computer Science
University of Waterloo
CS 350. Operating Systems
Assignment 0: An Introduction to OS/161
Last Modification: Mon Sep 10 23:31:49 EDT 2007 Changed #endif OPT_A0 to #endif /* OPT_A0 */ Prev Modification: Mon Sep 10 23:31:49 EDT 2007
This assignment is done individually
NO SLIP DAYS APPLY TO THIS ASSIGNMENT
This assignment will familiarize you with OS/161, the operating system with which you will be working this semester, and System/161, the machine simulator on which OS/161 runs. We also introduce tools that will make your work for this course easier:
The first part of this document briefly discusses the code on which you'll be working and the tools you'll be using. You can find more detailed information on CVS and GDB in separate handouts. The following sections provide precise instructions on exactly what you must do for the assignment. Each section with (hand me in) at the beginning indicates a section where there is something that you must do for the assignment.
|What are OS/161 and System/161?|
The code for this semester is divided into two main parts:
The OS/161 distribution contains a full operating system source tree, including some utility programs and libraries. After you build the operating system you boot, run, and test it on the simulator.
We use a simulator in CS350 because debugging and testing an operating system on real hardware is extremely difficult. The System/161 machine simulator has been found to be an excellent platform for rapid development of operating system code, while still retaining a high degree of realism. Apart from floating point support and certain issues relating to RAM cache management, it provides an accurate emulation of a MIPS R3000 processor.
There will be an OS/161 programming assignment for each of the following topics:
CS350 assignments are cumulative. This means you will build each assignment on top of your previous submission.
Most programming you have probably done at university has been in the form of 'one-off' assignments: you get an assignment, you complete it yourself, you turn it in, you get a grade, and then you never look at it again.
The commercial software world uses a very different paradigm: development continues on the same code base producing releases at regular intervals. This kind of development normally requires multiple people working simultaneously within the same code base, and necessitates a system for tracking and merging changes. Beginning with ASST1 you will work in teams on OS/161, and therefore it is imperative that you start becoming comfortable with CVS, the Concurrent Versions System.
CVS is very powerful, but for CS350 you only need to know a subset of its functionality. The Introduction to CVS handout contains all the information you need to know and should serve as a reference throughout the semester. If you'd like to learn more, there is comprehensive documentation available here .
In some ways debugging a kernel is no different from debugging an ordinary program. On real hardware, however, a kernel crash will crash the whole machine, necessitating a time-consuming reboot. The use of a machine simulator like System/161 provides several debugging benefits. First, a kernel crash will only crash the simulator, which only takes a few keystrokes to restart. Second, the simulator can sometimes provide useful information about what the kernel did to cause the crash, information that may or may not be easily available when running directly on top of real hardware.
You must use the CS350 version of GDB to debug OS/161. You can run on the UNIX systems used for the course as cs350-gdb. This copy of GDB has been configured for MIPS and has been patched to be able to communicate with your kernel through System/161.
An important difference between debugging a regular program and debugging an OS/161 kernel is that you need to make sure that you are debugging the operating system, not the machine simulator. Type
% cs350-gdb sys161and you are debugging the simulator. Detailed instructions on how to debug your operating system and a brief introduction to GDB are contained in the handout Introduction to GDB for CS350 .
|Get a copy of OS/161 and set up your account|
Go to the OS/161 Main page
Then follow the instructions for installing OS/161 and building and running the kernel. The instructions below assume you've done this successfully. We assume that your version of OS/161 lives in a directory named ~cs350-os161 . We also assume that you will create and use another directory ~cs350 and a subdirectory ~cs350/asst0 for collecting output that will be handed in.
|Setting up your CVS repository (hand me in)|
% mkdir ~/cvsrootThroughout the rest of this assignment, we will assume that you created ~/cvsroot.
% setenv CVSROOT ~/cvsroot/cs350
% echo $CVSROOT
% cvs initThis tells CVS to create all the files it uses to track stuff in your repository. (If it complains about "not known CVSROOT", you probably didn't finish Item 3).
% cd ~/cs350-os161/os161-1.11 % cvs import -m "Import of os161" os161-1.11 os161 os161-1_11You can alter the arguments as you like; here's a quick explanation.
-m "Initial import of os161" is the log message that CVS records. (If you don't specify it on the command line, it will start up a text editor). os161-1.11 is where CVS will put the files within your repository. It will also be the name that you specify when you check out your system. os161 is the "branch tag." You needn't worry about the full implications of this; think of it as giving CVS a name to help you remember from where you got this code. os161-1_11 is the name of the version of the code that you are importing. (Always use the actual version, whatever it is. Replace dots with underscores.) You can use this name later with cvs diff and other CVS commands.
% cd .. % rm -rf os161-1.11Don't worry - now that you have imported the tree in your repository, there is a copy saved away. In the next step, you'll get a copy of the source tree that is yours to work on. You can safely remove the original tree. You cannot ever remove your CVS repository located in $CVSROOT.
% cd ~/cs350-os161 % cvs checkout os161-1.11
% mkdir ~/cs350 % mkdir ~/cs350/asst0 % mv typescript ~/cs350/asst0/cvsinit.script
|Running your kernel (hand me in)|
% cd ~/cs350-os161/root
% sys161 kernel
% mv typescript ~/cs350/asst0/run.script
|Practice modifying your kernel (hand me in)|
#include "opt-A0.h"And that hello is only called for assignment 0.
#if OPT_A0 hello(); #endif /* OPT_A0 */
# # Main/toplevel stuff # file main/main.c file main/menu.c file main/hello.c
% scriptCall the output of this script session newbuild.script.
% mv typescript ~/cs350/asst0/newbuild.script
|Using GDB (hand me in)|
(In the run window:) % cd ~/cs350-os161/root % sys161 -w kernel (In the debug window:) % script % cd ~/cs350-os161/root % cs350-gdb kernel (gdb) dir ../os161-1.11 (gdb) target remote unix:.sockets/gdb (gdb) break menu (gdb) c [gdb will stop at menu() ...] (gdb) where [displays a nice back trace...] (gdb) detach (gdb) quit
% mv typescript ~/cs350/asst0/gdb.script
|Practice with CVS (hand me in)|
In order to build your kernel above, you already checked out a source tree. Now we'll demonstrate some of the most common features of CVS. Create a script of the following session (the script should contain everything except the editing sessions; do those in a different window). Call this file cvs-use.script.
% cvs diff -c kern/main/main.cto display the differences in your version of this file.
% cvs commit
% rm main.c % cvs update -d main.c
% mv typescript ~/cs350/asst0/cvs-use.script
|What (and how) to hand in|
Like most CS courses, we'll be using the online submit utility. Your asst0 directory should contain everything you need to submit, specifically: