Contents

1. Due Dates and Mark Distribution

Marks: Worth 10 marks (of the 100
available for the class mark component of the course)

This assignment is done as an individual.

No bonuses apply for this assignment.

2. Introduction

The aim of Assignment 0 is to have you familiarise yourself with the
environment you will be using for the remaining assignments. The
assignment consists of two parts, an assessable and a non-assessable
component. The non-assessable component consists of a set of directed
questions to guide you through the code. The answers to this code
reading Q & A component of the assignment will be entered in the
wiki (ideally, by you the students). The assessable part of this
assignment consists of you making a very minor change to the existing
OS. The change is conceptually trivial, so you can view this
assignment as us giving away marks as an incentive for you to get the
assignment environment up and running early in the session.

Note that this assignment is not indicative of the level of
difficulty of the later assignments. The later assignments will be
much more challenging.

The OS/161 Environment

This assignment will introduce you to the components of the
environment you will use during the semester:

OS/161, the educational operating system you will
modify to implement the assignments.

System/161, the machine simulator that OS/161 runs on.

GDB, a debugger that will make your life much easier.

The introduction to the OS/161 system
explains how the components of the OS/161 system fit together, and contains
important information about using the tools. You should take the time to
read it now.

Subversion

Subversion is a source code management system used to track changes to a piece of
software. We make use of Subversion in this course to allow you to manage the large
code base (compared to most previous assignments you have done), and recover
from potential problems. Subversion keeps a recoverable copy of specified versions of
all your OS/161 files. It allows you to track the changes you have made, and
more importantly, rollback to a known state if things get out of hand.

Subversion also enables you and your partner to work on the same code
repository in a coordinated way. You can even work on versions of your
code stored at home and at CSE.

Subversion is a large system of which you need to know only a
small subset. We will give you directions for the parts you need to
know. If you're curious, you can find detailed docs on Subversion
at subversion.apache.org,
in addtion to the resources indicated on the course web site.

3. Getting Started

For this assignment, you will be working by yourself (for later assignments, you will work with a partner).

First, you will need to set up various environment variables for you to
access the tools needed for the course. Simply run

% 3231

in
each new shell you use when working on the assignment. (If you know what
you're doing you can add /home/cs3231/bin and
/home/cs3231/bin-${ARCH} to your PATH).

Note: You must not have "." (or equivalent) prior
to "/bin" in your PATH. The build will fail later if you
do. Note: doing this is generally a bad idea for security
reasons anyway.

Obtaining and setting up the distribution with Subversion

Subversion is a "centralised" revision control system, which means that you
will be checking code out of, and committing code back into, a single
repository. In this section, you will be setting up the Subversion
(often abbreviated "svn") repositories that you will work on. For this assignment,
you will use a repository in your own home directory. For subsequent assignments,
you and your partner will share a repository in your group's directory.

Create a sub-directory off your home directory to contain your cs3231 work.

% cd ~
% mkdir cs3231

Create your repository directory using the svnadmin command.

% cd ~/cs3231
% svnadmin create repo

You will see that this has create a new directory named repo that contains
a few files and directories. This directory is managed by Subversion and you should
never have to touch it.

Import the OS/161 sources into your new repository (where $USER is your
login name, of course). By convention, Subversion users refer to the main version
of a project as the trunk:

4. Reading component

This component of this assignment aims to
guide you through the code base to help you comprehend its contents,
identify what functionality is implemented where, and be able to make
intelligent decisions on how to modify the code base to achieve the
goals of the assignments.

Note that while the code reading component is not assessable, we
view as the ideal opportunity to get to know your way around the
code. You will really struggle with the assignments if you fail to get
an understanding of the code base. The code reading component is there
to guide you towards acquiring that
understanding. Skip it at your own
risk.

5. Working with the Kernel

Now to the business end of this assignment. You will now build and
install a kernel.

You first have to configure your source tree. This step sets up some information
for later compilation, such as the location of various directories, the compiler to
use, and compilation flags to supply.

% cd ~/cs3231/asst0-src
% ./configure

Now you must configure the kernel itself. This step prepares for a compilation
of the specific set of files that make up the assignment 0 kernel.

% cd ~/cs3231/asst0-src/kern/conf
% ./config ASST0

The next task is to build the kernel. Note the bmake depend step. This
step works out which include files are required by which source files so the source
files can be recompiled if the include files change. Remember to "bmake depend"
whenever building a new kernel or when you have added or removed include files.
If you're not sure, just run it!

% cd ../compile/ASST0
% bmake depend
% bmake

Now install the kernel.

% bmake install

In addition to the kernel, you have to build the user-level
utilities (they will be installed automatically):

% cd ~/cs3231/asst0-src
% bmake

Running your Kernel

If you have made it this far, your have built and installed the entire
OS. Now it is time to run it.

We will now go through the steps required to modify and rebuild your
kernel. We will add a new file to the sources. The file contains a
function we will call from existing code. We need to add the file to
the kernel configuration, re-config the kernel, and the rebuild again.

Find an appropriate place the in the kernel code, and add a call
to complex_hello() (defined in hello.c) to print out a
greeting (Hint: one of the files in kern/startup/ is very appropriate).
It should appear immediately before the prompt.

Since we added new file to the kernel code, we need to add it to
the kernel configuration in order to build it. Edit
kern/conf/conf.kern appropriately to include
hello.c.

When we change the kernel config, we need to re-configure the
kernel again.

% cd ~/cs3231/asst0-src/kern/conf
% ./config ASST0

Now we can rebuild the kernel.

% cd ../compile/ASST0
% bmake depend
% bmake
% bmake install

Run your kernel as before. Note that the kernel will panic with
an error message.

Use GDB to find the bug (Hint: the display, break, and
step commands will be very useful).

Edit the file containing the bug, recompile as before and re-run to see the
welcome message.

Note: If you simply modify a file in an already configed source tree,
you can simply run bmake again to rebuild, followed by
bmake install. You only need to reconfigure it if you add or remove
a file from the config, and you only need to bmake depend if
you add (or modify) a #include directive.

Some practice with Subversion

Now we will perform some operations with svn.

Let's check what changes you have made to your sources.

% cd ~/cs3231/asst0-src
% svn diff | less

You should see a 'diff' of all the changes you made to your source tree. Note
that the build process may have added some blank lines to various "dependh.mk"
files, which is harmless.

Note that the new file you added was not included. This is because you have not
told svn to include it in the repository. Add it to the repository now.

% cd ~/cs3231/asst0-src/kern/startup
% svn add hello.c

Since your new kernel has reached a small milestone, it makes sense to
commit your changes to the repository to preserve this state. Note: Set the
EDITOR environment variable to your editor of choice (e.g. emacs, pico,
nedit).

% export EDITOR=nedit
% cd ~/cs3231/asst0-src
% svn commit

Subversion brings up your editor with a list of changed files and asks you to
make a comment on the changes. Notice that files you've added are prefixed with
A, and files you've modified are prefixed with M. Making a helpful comment here
will make tracking down changes easier later. Type in something explanatory, such
as "display a welcome message after booting", and exit the editor.

Inspect your changes by asking svn to print a change log.

% svn log -v -r HEAD

You should see your change message and the list of changed files.

Subversion assigns each commit a unique "revision number", which you may have
noticed after running svn commit ("Committed revision 3" or similar). Instead of
a revision number, you can also use the magic word HEAD, as you did above, which
means the most recent commit. You can also specify a range of revisions by
separating them with a colon. Try this to get a complete list of all changes:

% svn log -r 1:HEAD

Now edit kern/startup/main.c. Remove a large part of the
file. Try to rebuild your kernel, which should fail.

% cd ~/cs3231/asst0-src/kern/compile/ASST0
% bmake

Restore the previous version of main.c.

% cd ~/cs3231/asst0-src/kern/startup
% svn revert main.c

Subversion will revert main.c to the most recent committed version.

6. Your Task

Follow the above instructions to add the given
file to the operating system. Once you have found (using GDB) and
fixed the bugs, you have completed the assignment. Make sure you see
the Hello World!!! output just prior to the menu prompt.

Warning! If you make any changes to your assignment,
make sure you record the changes (svn commit) and create a new .diff file
before resubmitting!

Submitting Your Assignment

Now submit the changeset as your assignment.

% cd ~
% give cs3231 asst0 asst0.diff

You're now done.

Even though the generated patch should represent all the changes
you have made to the supplied code, occasionally students do something
"ingenious". So always keep your Subversion repository so that we may
recover your assignment should something go wrong.