CS350 - University of Waterloo

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

Introduction

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:

CVS (Concurrent Versions System): CVS is a source code revision control system. It manages the source files of a software package so that multiple programmers may work simultaneously. Each programmer has a private copy of the source tree and makes modifications independently. CVS attempts to intelligently merge multiple people's modifications, highlighting potential conflicts when it fails.
GDB (GNU Debugger): GDB allows you to examine what is happening inside a program while it is running. It lets you execute programs in a controlled manner and view and set the values of variables. In the case of OS/161, it allows you to debug the operating system you are building instead of the machine simulator on which that operating system is running.

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:

OS/161: the operating system that you will augment in subsequent homework assignments.
System/161: the machine simulator which emulates the physical hardware on which your operating system will run. This course is about writing operating systems, not designing or simulating hardware. Therefore you may not change the machine simulator.

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:

ASST1 : Synchronization and concurrent programming
ASST2 : System calls and multiprogramming
ASST3 : Virtual memory

CS350 assignments are cumulative. This means you will build each assignment on top of your previous submission.

About CVS

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 .

About GDB

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 sys161

and 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)

Create your CVS repository directory.
```
  % mkdir ~/cvsroot
```
Throughout the rest of this assignment, we will assume that you created ~/cvsroot.
Set your CVSROOT environment variable. This will keep you from having to specify the -d argument every time you use CVS.
```
  % setenv CVSROOT ~/cvsroot/cs350
```
Add this setenv line to your .cshrc file as well (do not include that editing session in your script output.)
Script the following session using the script command.
```
  % script
```
Echo $CVSROOT and make sure that it is what you expect (~/cvsroot/cs350).
```
  % echo $CVSROOT
```
Initialize your repository by typing:
```
  % cvs init
```
This 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).
Change directories into the OS/161 distribution that you unpacked in the previous section and import your source tree.
```
 
  % cd ~/cs350-os161/os161-1.11
  % cvs import -m "Import of os161" os161-1.11 os161 os161-1_11    
```
You 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.
Now, remove the source tree that you just imported.
```
  % cd ..
  % rm -rf os161-1.11
```
Don'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.

Now, checkout a source tree in which you will work.

  % cd ~/cs350-os161
  % cvs checkout os161-1.11

End your script session by typing exit or by pressing Ctrl-D. Rename your typescript file to be ~/cs350/asst0/cvsinit.script.
```
  % mkdir ~/cs350
  % mkdir ~/cs350/asst0
  % mv typescript ~/cs350/asst0/cvsinit.script
```

Running your kernel (hand me in)
This step assume that you've already successfully followed the instructions for installing OS/161 and building and running the kernel, and still have a compiled version of the kernel in ~/cs350-os161/root.

Script the following session.

  % script

Change into your root directory.

  % cd ~/cs350-os161/root

Run the machine simulator on your operating system.

  % sys161 kernel

At the prompt, type ? <return>. This tells the kernel to print the kernel menu.

Now at the prompt, type ?t <return>. This tells the kernel to print the kernel's tests menu.

At the next prompt, type tt1 <return>. This tells the kernel to run thread test 1.

Finally, at the next prompt, type q <return>. This tells the kernel to quit and shutdown the system.

End your script session. Rename your script output to run.script.

  % mv typescript ~/cs350/asst0/run.script

Practice modifying your kernel (hand me in)

Create a file called kern/main/hello.c.
In this file, write a function called hello that uses kprintf() to print "Hello World\n".
Edit kern/main/main.c and add a call (in a suitable place) to hello(). Ensure that the hello call is only used for assignment 0. For example, be sure to add the following line to the list of included files in main.c.
```
#include "opt-A0.h"
```
And that hello is only called for assignment 0.
```
#if OPT_A0
   hello();
#endif /* OPT_A0 */
```
Edit kern/conf/conf.kern to include the new source file hello.c. For example by adding a line containing file main/hello.c as shown below:
```
#
# Main/toplevel stuff
#

file      main/main.c
file      main/menu.c
file      main/hello.c
```
Reconfigure (i.e., run config again and rebuild the kernel).
Make sure that your new kernel runs and displays the new message.
Once your kernel builds, script a session demonstrating a config and build of your modified kernel.
```
  % script
```
Call the output of this script session newbuild.script.
```
  % mv typescript ~/cs350/asst0/newbuild.script
```

Using GDB (hand me in)

Script the following gdb session (that is, you needn't script the session in the run window, only the session in the debug window). Be sure both your run window and your debug window are on the same machine.

Run the kernel in gdb by first running the kernel and then attaching to it from gdb.

  (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

End your script session. Rename your script output to gdb.script.
```
  % 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.

  % script

In a different window edit the file kern/main/main.c. Add a comment with your name in it.
Execute
```
  % cvs diff -c kern/main/main.c
```
to display the differences in your version of this file.
Now commit your changes using
```
  % cvs commit
```
In a different window remove the first 100 lines of kern/main/main.c.
Try to build your kernel (this ought to fail).
Realize the error of your ways and get back a good copy of the file.
```
  % rm main.c
  % cvs update -d main.c
```
Try to build your tree again.
End your script session by typing exit or by pressing Ctrl-D. Rename your typescript file to be cvs-use.script.
```
  % 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:

cvsinit.script
run.script
newbuild.script
gdb.script
cvs-use.script