The purpose of this assignment is to familiarize you with OS/161, System/161 and the build environment you'll be using. Mostly you'll be reading code. It is intended as an easy assignment, but you should take care to do it well, and if possible go beyond what it asks of you. Time invested in understanding OS/161 now will pay off later.
This assignment has three parts: a somewhat lengthy preliminary, a written component, and a coding component. You may wish to skip ahead to those two components to get a feel for the work you have to do.
The written component is due at the beginning of class on Tuesday, September 18th, 2012. The coding component is due at 11:59 PM on the same day, Tuesday, September 18th.
Read the
AssignmentsSetup
Wiki page; you must have your path correctly set before you
undertake each CS 134 assignment. If you haven't done so already, put
the appropriate line(s) in your .bash_login or
.zlogin. Do it now!
The URL for your pair's CS 134 repository is
https://svn.cs.hmc.edu/cs134/fall12/ours/<group>
where <group> is the name of your group. Your group
name is formed by joining together each of your Knuth usernames, in
alphabetical order and lower case, with a hypen. Thus, if Mary Jones
(mjones) and John Smith (jsmith) were
working together, their group name would be
jsmith-mjones.
When you work with someone for the first time, your first step is to check out a working copy of your shared directory. You each only have to do this step once (unless you decide to completely delete your working copy and check out a fresh copy, or you choose to work on two unrelated machines, such as your dorm computer and one of the lab machines).
Have each partner log in to their own account and check out their own working copy of your shared repository by running the following commands:
mkdir -p ~/courses/cs134
chmod go-rwx ~/courses/cs134
cd ~/courses/cs134
svn checkout https://svn.cs.hmc.edu/cs134/fall12/ours/<group>
The Subversion server requires a username and password. These are simply your Knuth username and password.
You now have a shared directory space, but you don't yet have any of the files for the assignment—you need to copy them from my distribution area in the CS 134 repository.
To make your own copy of the assignment code, one of you should run:
cd ~/courses/cs134/<group>
svn copy https://svn.cs.hmc.edu/cs134/fall12/given/hw1 hw1
svn commit -m "Copied over Assignment 1 files"
(The -m option to svn commit provides a
quick way to provide a log message for the commit.)
The other person should then run the following commands for their working copy:
cd ~/courses/cs134/<group>
svn update
You might want to try running svn update before the other
person commits just to see what happens, which should be nothing. You
won't ever see changes until they have been committed to the
repository.
Now run the following commands
cd ~/courses/cs134/<group>/hw1
./setup
(svn checkout may wrongly guess the username; just press
return and it'll ask.)
If the above command is done in less than fifteen seconds, check over the compilation output for errors. If something went wrong at this stage, something is up with the fundamentals. Perhaps you didn't set your path?
Running ./setup can take several minutes depending on the
speed of the machine you are using. Remember that you can skip ahead
to some of the reading parts of the assignment while you are waiting
for parts to compile.
When ./setup finishes, it will have built all of the
user-level commands (such as /sbin/reboot) and libraries
for OS/161, but not the kernel itself. You can check that it
has compiled one of these files by running:
file root/sbin/reboot
which should print something along the lines of
root/sbin/reboot: ELF 32-bit MSB mips-1 executable, MIPS R3000_BE, version 1, statically linked, not stripped
Okay, now you're ready to work…
The OS/161 kernel uses a fairly complex but powerful build system. It uses a configuration file to specify which parts of the kernel need to be built, and provides separate build areas for each configuration.
Our first step in building a kernel is thus to configure the build
using a configuration file. Make sure your current directory is
~/cs134/<group>/hw1, and then run
cd src/kern/conf ./config INTRO
Now that the kernel is configured, we can build it. Type
cd ../compile/INTRO make install
Once it's built, change directory to your virtual root directory and test the kernel, as follows
cd ~/cs134/<group>/hw1/root
sys161 kernel
You can't do much with the kernel at this point. Two things you
can do are initiate a kernel panic with the
panic command, and run a user level program that performs
the “reboot” system call by typing p
/sbin/reboot. Try both of these now.
You can also use gdb. Open another terminal window, and
ensure both are in the directory
~/cs134/<group>/hw1/root. Then proceed as
follows:
| First Window | Second Window | |
|---|---|---|
| Run the command: | ⋮ | |
sys161 -w kernel | Run the command: | |
| os161-gdb kernel | ||
| The system should pause with a message that it is waiting for the debugger. | ||
Once gdb has started, give the following commands to gdb: | ||
| ⋮ | connect | |
OS161 should now start up. Enter the command:panic | ⋮ | |
| ⋮ | Gdb should have now stopped at the breakpoinit you set for panic. Type the following commands:backtrace | |
| Execution should resume, and the kerenel should exit with its panic message and shut down the machine. | ⋮ | |
| Quit gdb. |
src directory is the top-level directory of
OS/161. It contains a few files, along with subdirectories that hold
distinct parts of OS/161. The files are
autoconf). You shouldn't need to understand or
tamper with it. It is run by our setup
program.
Makefile, and
generated by the configure program.
defs.mk file in case
something goes wrong with configure. The idea
is that to allow developers to fix defs.mk
using the comments in this file. For us,
configure is run by our setup
script and should never fail.
In addition to these files, the src directory contains
the following subdirectories:
/bin tools; for example, cat,
cp, ls.
libc, the C library.
/sbin on a UNIX
machine (e.g. halt, reboot,
etc.).
Your focus during this code walkthrough should be on the kernel
sources. You won't need a detailed understanding of the utilities in
bin and sbin, but you should have a general
idea of how they work and where things are is useful. The same is true
of the lib and include directories.
kern Subdirectory
This directory and its subdirectories are where most (if not all) of
the action takes place. The only plain file in this directory is a
Makefile, which only installs various header files. It
does not actually build anything.
We strongly recommend that you set up and use CScope to explore the kernel; it will save you tons of time.
We will now examine the various subdirectories in detail. (The parenthetical comments provide hints on which directories are relvant for which written questions. However, they are only hints; sometimes the answer is elsewhere.)
mips.
mips/mips).
config script to configure a kernel.
kmalloc, and so forth.
vfs.h
and vnode.h before looking at this directory.
sp) in OS/161?
splhigh and
spl0?
typedefs like
u_int32_t instead of simply saying
int?
splx return?
vnode?
STDIN_FILENO defined?
kmain() do?
struct array be resized?
Put-your-group-name-here and edit it to print your
group's name.
svn commit.
src/kern/main there is an extra file,
hello.c, which is currently not compiled or used.
It defines a function complex_hello that is
intended to print “Hello World”. (The
code in this file is more complex than strictly necessary, but
you should not replace it with a simple call to
kprintf.)
complex_hello so that “Hello
World” will be printed once, just before the prompt
appears.
src/kern/conf/conf.kern appropriately to
include hello.c.
kern/conf (using the same
steps you used on page 2).
src/kern/compile/INTRO and
rebuild the kernel (again, using the same steps as you used on
page 2).
gdb to find the bug.
svn commit.