David R. Cheriton School of Computer Science
University of Waterloo
This assignment is done individually
SLIP DAYS MAY NOT BE APPLIED 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 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:
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 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. Beginning with ASST2 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 A document the 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://www.cvshome.org/docs/manual/cvs-1.11.6/cvs_toc.html
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 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 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:
|Step 2: Running your kernel (hand me in)|
% scriptThe 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.
% cd ~/cs350-os161/root
% sys161 kernel
% mkdir ~/cs350 % mkdir ~/cs350/asst0 % mv typescript ~/cs350/asst0/run.script
|Step 3: Practice modifying your kernel (hand me in)|
You will probably find it helpful to read the document "Working with OS/161" before completing this step. You will find a link to this document from the CS350 Assignments web page.
#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
% cd ~/cs350-os161/root % script % sys161 kernel
% mv typescript ~/cs350/asst0/newbuild.script
|Step 4: 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
|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.
% cd ~/cs350-os161/os161-1.11/kern/main % cvs add hello.c
% cvs diff -c main.c
% cvs commit -m "added hello function to the boot sequence"
% rm main.c % cvs update -d main.c
% 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:
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 0Note that you must use the cs350_submit command, not the regular submit command, to submit your work. What cs350_submit is 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% 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.txtThis 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: