This assignment is to be 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 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:
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.
Revision control systems are very powerful, but for CS350 you only need to know a subset of the functionality of one of them. 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/
Some of you may have experience with SVN from CS 246. Some documentation can be found at http://subversion.apache.org/docs/
Here are some links to references for GIT in no particular order:
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 a CVS repository, can be obtained from the Assignments page in the course web space. You are free to use CVS, SVN, or GIT but you will need to follow the ideas for CVS and translate them to the revision control system you decide to use. 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 % scriptfix 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.)
#include <types.h> #include <lib.h> #include <test.h>
/* Kernel menu system. */ void menu(char *argstr);to look like this:
/* Kernel menu system. */ void menu(char *argstr); /* Boot time shout out */ void hello(void);
#if OPT_A0 hello(); #endif /* OPT_A0 */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 you wrapped your call to hello(). You'll notice that main.h already includes test.h, which includes the prototype for your hello function. This enables the compiler to ensure that you have invoked hello correctly when it compiles main.c.
# # Startup and initialization # file startup/main.c file startup/menu.cand change it to this:
# # Startup and initialization # file startup/main.c file startup/menu.c file startup/hello.c
./config ASST0in the kern/conf directory.
% cd ~/cs350-os161/root % script % sys161 kernel
% scriptfix 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.99/kern/compile/ASST0 (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
% scriptfix typescript > ~/cs350/asst0/gdb.script
|Step 5: Practice with Revision Control Software (hand me in)|
These instructions are provided for CVS. You are free to use CVS, SVN or GIT but be sure to use the file names specified in the assignment (even when they use cvs in the name).
This step asks you to script your use of some of the most common features of CVS/SVN/GIT.
% cd ~/cs350-os161/os161-1.99/kern/startup % cvs add hello.c
% cvs diff -c main.c
% cd .. % cvs commit -m "added hello function to the boot sequence"You should see the changes you have made to conf.kern, test.h, and main.c, as well as the new file hello.c, being committed to the CVS repository.
% rm main.c % cvs update -d main.c
% scriptfix 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. 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% 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: