Installing OS/161 in the student.cs Computing Environment

The following instructions describe how to install OS/161 into your account in the student.cs computing environment.

Step 0: Which Machine to Use?

You should do all of your OS/161 work on one of the Linux servers in the student.cs computing environment. The simplest way to do this is to log in using the generic server name
linux.student.cs.uwaterloo.ca
This will automatically choose a specific Linux machine to log you into.

CSCF maintains a page that provides more information about all of the servers available in the student.cs computing environment, in case you'd like more information. However, all of your work should be done on one of the Linux servers.

Step 1: Setting Up Your Environment

Start by logging in to your account and modifying your PATH environment variable to ensure that various OS/161-related development tools are available. Your PATH is normally set in your shell's startup file each time you log in. There are many different shells available, and each of the shells typically uses a different name for the startup file (or may have multiple startup files). In the student.cs environment, the default shell is either bash or tcsh. If you are using a different shell, you should consult the man page to determine the names of the startup files. You can determine which shell you are currently running using the command echo $SHELL or echo $0. You can change the default shell for your account using the chsh command.

Some scripts for the course use tcsh, so you must set the PATH environment for tcsh even if you are using a different shell. To change the path, look in the .cshrc file in your home directory for a line that looks something like this:

setenv PATH `/bin/showpath standard`

and change it to look like this:

setenv PATH `/bin/showpath /u/cs350/sys161/bin /u/cs350/bin standard`

Users of bash should change a similar line in their .bashrc or .profile file (also in their home directory). On some versions of Linux, the change mush be made in the .bashrc file.
Look for a line like this:

export PATH; PATH=`/bin/showpath standard`

and change it to this

export PATH; PATH=`/bin/showpath /u/cs350/sys161/bin /u/cs350/bin standard`

In another window log in and test to see if your modifications have worked. If you type:
which cs350-gcc
You should see:
/u/cs350/sys161/bin/cs350-gcc

If you do not then your path has not been set up properly.

To ensure that this also works with csh/tcsh, type the following:
csh
which cs350-gcc
Again you should see:
/u/cs350/sys161/bin/cs350-gcc

If you are having problems please consult this documentation: A bit more information about setting up your shell.

Note that you will need to log out and log back in again so that this PATH change will take effect. You can check the current setting of the PATH environment variable using the command

printenv PATH

Step 2: Obtain a Copy of the OS/161 Source Code

Now you are ready to get a copy of OS/161. Starting in your home directory, issue the following commands:

mkdir cs350-os161
cd cs350-os161
tar -xzf /u/cs350/pub/os161_repository/os161.tar.gz

If you are planning to use git, CVS, SVN or some other revision control system to manage the OS/161 source code (which is a good idea), this is the right time to get that set up. Put your copy of the OS/161 code under revision control, then create a working copy under cs350-os161 which you can work with. Proceed to Step 3 using your working copy.

Step 3: Configure OS/161 and Build the OS/161 Kernel

The next step is to configure OS/161 and compile the kernel. From the cs350-os161 directory, do the following:

cd os161-1.99
./configure --ostree=$HOME/cs350-os161/root --toolprefix=cs350-
cd kern/conf
./config ASST0
cd ../compile/ASST0
bmake depend
bmake
bmake install

The string ASST0 in the commands above indicates that you are working on assignment 0. For Assignment X, replace ASST0 with ASSTX in the commands above. The bmake install command will create a directory called $HOME/cs350-os161/root ($HOME refers to your home directory), into which it will place the compiled kernel in a file called kernel-ASST0. It will also create a symbolic link called kernel referring to kernel-ASST0. Check the $HOME/cs350-os161/root directory to make sure that your kernel is in place.

Step 4: Build the OS/161 User-level Programs

Next, build the OS/161 user level utilities and test programs:
cd $HOME/cs350-os161/os161-1.99
bmake
bmake install

Step 5: Try Running OS/161

You should now be able to use the SYS/161 simulator to run the OS/161 kernel that you built and installed. The SYS/161 simulator requires a configuration file in order to run. To obtain one, do this:

cd $HOME/cs350-os161/root
cp /u/cs350/sys161/sys161.conf sys161.conf


If you are running on a home machine or laptop it is best to get a copy from the student.cs machines (e.g., using scp or sftp). For a quick test you can try using a copy of the sys161.conf file like this:
cp $HOME/sys161/sys161.conf .
NOTE: you should remember to get a copy from the student.cs machines in case there are local changes in that copy that you need

Now run your compiled kernel on the simulator. Assuming that you're still in the $HOME/cs350-os161/root directory, do this:

sys161 kernel-ASST0

You should see some output that looks something like this:

sys161: System/161 release 1.99.06, compiled Aug 23 2013 10:23:34

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 #1)

316k 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
lhd0 at lamebus0
lhd1 at lamebus0
lser0 at lamebus0
con0 at lser0

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

The last line is a command prompt from the OS/161 kernel. For now, just enter the command q to shut down the simulation and return to your shell.