CS350 - University of Waterloo

CS 350
Operating Systems

Spring 2009
Assignment 0: An Introduction to OS/161

This assignment is to be done individually
SLIP DAYS MAY NOT BE APPLIED 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 parts of this document briefly discusses the code on which you'll be working and the tools you'll be using. The remaining sections then describe what you must accomplish for this assignment. Each section marked (hand me in) describes a specific task that you will need to complete, document, and submit.

What are OS/161 and System/161?

The CS350 assignments are based on two software systems:

OS/161: the operating system that you will augment in subsequent 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 it allows everyone to have a private machine on which to test their operating system. In addition, debugging and testing the operating system on the simulator is easier than it would be on real hardware. 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

About CVS

Most programming you have probably done at UW 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.

Most of the 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.

CVS is very powerful, but for CS350 you only need to know a subset of its functionality. The A document that introduces CVS, available at http://www.student.cs.uwaterloo.ca/~cs350/common/cvs.html, contains all of the information you need to know and should serve as a reference throughout the term. If you'd like to learn more, there is comprehensive documentation available at http://ximbiot.com/cvs/manual/

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 it 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 Debugging OS/161 with GDB, which is available at http://www.student.cs.uwaterloo.ca/~cs350/common/gdb.html

Step 1: Get a copy of OS/161 and set up your CVS repository

Instructions for obtaining and installing OS/161, and for creating your CVS repository, can be obtained from the Assignments page in the course web space. The remaining steps make the following assumptions:

They assume that you have already installed OS/161 and created a CVS repository.
They assume that you have checked out a working copy of OS/161 from your repository, and the working copy lives in a directory named cs350-os161 under your home directory.
They assume that you have successfully followed the instructions for configuring your working copy of OS/161 and for building the OS/161 kernel, and that there is a compiled kernel in ~/cs350-os161/root.
They assume that you will create and use another directory, called cs350, under your home directory, as well as a subdirectory cs350/asst0 for collecting output the output that will be handed in.

Step 2: Running your kernel (hand me in)

Script the following session using the script command.

  % script

The script command will record the rest of your session (the commands you type, as well as the output from those commands) into a file called typescript in the current directory.

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 by typing exit or by pressing Ctrl-D. Have a look at your typescript file to ensure that it contains a recording of the commands you just finished executing. Rename your typescriptfile to be run.script, create the cs350/asst0 hand-in directory, and copy run.script to that directory:

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

Step 3: Practice modifying your kernel (hand me in)

You should read the document "Working with OS/161" before completing this step. (You will also find a link to this document from the CS350 Assignments web page.)

Create a file called kern/main/hello.c in your working copy of OS/161.
In this file, write a function called hello that uses kprintf() to print "Hello World\n". At the top of the file, you will need to include the header files lib.h (which defines the kprintf function's signature) and the file types.h, which should always be included before any other OS/161 header files. You need to include types.h before lib.h, like this:
```
#include <types.h>
#include <lib.h>
```
Edit kern/main/main.c and add a call to hello() in a suitable place, so that your Hello World message will be printed by the kernel during its boot process. Ensure that the call to the hello function is only used for assignment 0 by including it conditionally, like this:
```
#if OPT_A0
   hello();
#endif /* OPT_A0 */
```
Also, be sure to add the following line to the end of the list of included files at the top main.c, like this
```
#include "opt-A0.h"
```
Among other things, the opt-A0.h file defines the preprocessor symbol OPT_A0, which which you wrapped your call to hello()
Whenever you add a new source file to the OS/161 kernel, you need to add the new file's name to the kernel configuration file. Since you've added hello.c, edit the configuration file (kern/conf/conf.kern) to include the new source file. Do this 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
```
Now, since you've changed the kernel's configuration file, you should reconfigure the kernel. As is described in the Working with OS/161 document, do this by running
```
./config ASST0
```
in the kern/conf directory.
Now, build and your modified kernel. Do this by running make depend, then make, then make install in the directory kern/compile/ASST0. See Working with OS/161 for more details. Have a look at the output of the make command - you should see hello.c and main.c being compiled successfully. If there are any problems, you can edit those files and try building your kernel again.
Make sure that your new kernel runs and displays the new message. See Working with OS/161 if you need a reminder about how to run your kernel.

Once your kernel builds and runs, script a session demonstrating your kernel running and printing the Hello World message when it boots up.

  % cd ~/cs350-os161/root
  % script
  % sys161 kernel

 Call the output of this script session newbuild.script.
  % mv typescript ~/cs350/asst0/newbuild.script

Step 4: Using GDB (hand me in)
You should read the document "Working with OS/161" - in particular, the section on debugging - before completing this step.

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
```

Step 5: Practice with CVS (hand me in)

This step asks you to script your use of some of the most common features of CVS.

Create a script of the following session.
```
  % script
```
You have already created new file (hello.c) in your working copy of the kernel, in Step 3. Now tell CVS about it.
```
  % cd ~/cs350-os161/os161-1.11/kern/main
  % cvs add hello.c
```
You already edited main.c to include a call to your new hello() function, but perhaps you've forgotten exactly what changes you made. Ask CVS to tell you how your working copy of main.c differs from the copy in the repository:
```
  % cvs diff -c main.c
```
Commit your changes to main.c and your new file hello.c to the CVS repository:
```
  % cvs commit -m "added hello function to the boot sequence"
```
In a different window , wreck your main.c file by removing the first 100 lines of text from it. Be sure to do this in a separate window so that your editing session is not part of the script output.
Now, in the window in which you are creating your script, try to build your kernel. This should fail, because main.c has been wrecked. Be sure that your failed kernel build is captured in your script.
Realize the error of your ways. Fortunately, you still have a good copy of main.c in your CVS repository. Get it back. In your script window, in the kern/main directory, do this:
```
  % rm main.c
  % cvs update -d main.c
```
Now, in your script window, try to build your kernel again. This time, the build should succeed.
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
```

Step 6: Submit your Results

For this assignment, you are expected to submit the script files that you created in the previous steps. They are:

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

If you have followed the instructions above, these files should all be located in the cs350/asst0 directory below your home directory. To submit your work, run the cs350_submit program in the cs350/asst0 directory:

  % cd $HOME/cs350/asst0
  % /u/cs350/bin/cs350_submit 0

Note that you must use the cs350_submit command, not the regular submit command, to submit your work. cs350_submit checks the completeness of your submission, packages up your files, and then submits them to the course account using the regular submit command. For this assignment, the packaging is not very important since you are not submitting any code. However, for the remaining assignments it will be very important. Therefore, get used to using cs350_submit to submit your work.

When you run the cs350_submit command, you should see output that looks something like this:

@cpu20.student[116]% cs350_submit 0
This is /u/cs350/bin/cs350_submit for CS350 assignment 0.
/u/cs350/bin/cs350_submit: found required file run.script
/u/cs350/bin/cs350_submit: found required file newbuild.script
/u/cs350/bin/cs350_submit: found required file gdb.script
/u/cs350/bin/cs350_submit: found required file cvs-use.script
/u/cs350/bin/cs350_submit: submitting run.script newbuild.script gdb.script cvs-use.script to CS350 course account
############ OUTPUT FROM submit ###################
  |
  output from the regular submit command here
  |
############ END OF OUTPUT FROM submit ###################
/u/cs350/bin/cs350_submit: submission is complete!
    This submission *replaces* any previous submissions that
    you may have made for assignment 0.

Look carefully at the the output from cs350_submit. If it looks like this:

/u/cs350/bin/cs350_submit IS ABORTING!  No files are being submitted to the course account.

then there was some kind of problem with your submission. Hopefully, the output from cs350_submit will give you a pretty good idea of what went wrong. You will need to correct the problems and try cs350_submit again. It is a good idea to run the cs350_submit command like this:

 /u/cs350/bin/cs350_submit 0 | tee submitlog.txt

This will run the cs350_submit command and also save a copy of all of the output into a file called submitlog.txt, which you can inspect if there are problems. This is handy when there is more than a screen full of output.

Here are a couple of important things you should know about cs350_submit:

You may submit multiple times. Each submission completely replaces any previous submissions that you may have made. This will become particularly important in subsequent assignments.
Each submission must include all of the required files. cs350_submit will complain, and will refuse to submit if, for example, your gdb.script file is missing. Should you need to make a partial submission for some reason, you will need to create empty versions of any missing required files before you submit.

CS 350Operating Systems

CS 350
Operating Systems