Assignment 0: Warm Up

Contents

1. Due Dates and Mark Distribution
2. Introduction
3. Getting Started
4. Reading Component
5. Working with the Kernel
6. Your Task
7. Submission

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

Setting up your account

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

% 3231

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:

  % cd /home/cs3231/assigns
  % svn import asst0/src file:///home/$USER/cs3231/repo/asst0/trunk -m "Initial import"
  

• Make an immediate tag of this import. This gives a name to current state of your repository. Later, you will use this tag to generate your assignment submission.

  % svn copy -m "Tag initial import" file:///home/$USER/cs3231/repo/asst0/trunk file:///home/$USER/cs3231/repo/asst0/initial
  

• You've added the assignment 0 source to your repository. In order to make changes, you must now check out a working copy. You'll check out your copy from the trunk.

  % cd ~/cs3231
  % svn checkout file:///home/$USER/cs3231/repo/asst0/trunk asst0-src
  

You should now have an asst0-src directory to work on.

Now that you have an OS/161 source tree, read the code walkthrough.

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.

Building 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

• Download the sample sys161-asst0.conf and install it as ~/cs3231/root/sys161.conf.
• Change to the root directory of your OS.

  % cd ~/cs3231/root
  

• Now run system/161 (the machine simulator) on your kernel.

  % sys161 kernel
  

• Power off the machine by typing q at the menu prompt.

Using GDB

I cannot stress strongly enough to you the need to learn to use GDB. Read the directions and short tutorial on using GDB with OS/161.

Note: the version of GDB used for these assignments is os161-gdb.

Modifying your Kernel

• Begin by downloading hello.c and place it in kern/startup/.
• 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

• 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.

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.

sys161: System/161 release 1.99.04, compiled Mar  6 2010 15:32:32

OS/161 base system version 1.99.05
Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2008, 2009
   President and Fellows of Harvard College.  All rights reserved.

Put-your-group-name-here's system version 0 (ASST0 #3)

320k physical memory available
Device probe...
lamebus0 (system main bus)
emu0 at lamebus0
ltrace0 at lamebus0
ltimer0 at lamebus0
beep0 at ltimer0
rtclock0 at ltimer0
lrandom0 at lamebus0
random0 at lrandom0
lser0 at lamebus0
con0 at lser0

cpu0: MIPS r3000
Hello World!!!
OS/161 kernel [? for menu]: 

% sys161 kernel q

This is generally the way we test your submission, so make sure that you have tested using the above method, even if you have also tested interactively.

% svn diff file:///home/$USER/cs3231/repo/asst0/initial file:///home/$USER/cs3231/repo/asst0/trunk >~/asst0.diff

When you submit your assignment, your submission is tested and you will be informed if your assignment is correct. (Note: This won't be the case for future assignments!) This means that you can check that you have completed this assignment correctly simply by submitting it. For more information on the submission process, look here.

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

% cd ~
% give cs3231 asst0 asst0.diff

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.