CS350: Nachos: Installation and Getting Started

Nachos: Installation and Getting Started

The best way to get started with Nachos is to install it in your account, build it, and try it out. This document describes the installation procedure, and gives a brief overview of the structure of the Nachos code.

Setting Up Your Account

The Nachos software is built using the GNU make program. You will need to modify your PATH environment variable so that when you run make, GNU make, and not some other make, will be executed. Your PATH should also include /u/cs350/bin, since there are a number of useful Nachos-related programs there.

Your PATH is normally set by a command in your .cshrc file, in your home directory, each time you log in. (If you are using some shell other than csh, it should have its own startup file, which you can modify.) In the CSCF standard .cshrc file, you can do this by changing the line

setenv PATH `/bin/showpath standard`

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

Note the backquotes that are used in the above commands. They are important, and they must be backquotes and not regular forward quotes. Note also that the gnu argument must come before standard in order for GNU make to become the default.

This change will take effect the next time you log in. If you would like the change to take effect immediately, you need to get your shell to re-load the initialization file you just changed. Assuming you are using csh, you can do that by typing source ~/.cshrc.

Installing Nachos

Create a directory that will contain the nachos installation (ie ~/cs350).

To install Nachos, use the script /u/cs350/bin/install_nachos. This script takes one parameter, which is the name of the directory into which Nachos should be installed. Assuming that your PATH has been set up as described above, you should be able to type

install_nachos cs350

where cs350 is the name of the directory.

Building Nachos

Once Nachos is installed, you should try compiling it. There are actually three separate chunks of code that get installed in your account when you run install_nachos. One is the code for the nachos program itself. This program is written in C++ and implements the machine simulation and the operating system for the simulated machine. The second is a set of test programs. These programs are written in C. They run on the simulated machine, and are used to test its operating system. The third is the coff2noff program for converning a COFF (Common Object File Format) file to a NOFF file (Nachos Object File Format). The first chunk is by far the largest of the three.

These three chunks of code must be built separately. First build the coff2noff program in the directory coff2noff . (All relative pathnames are assumed to be relative to the main Nachos directory, which is cs350_XX/nachos if you installed nachos in cs350_XX.) To build coff2noff, change into the coff2noff directory and type

      make

The test programs live in, and are built in, the directory code/test. (They require the use of coff2noff, so you must compile coff2noff first.) In the directory code/test , you will find a Makefile, which can be used to build the test programs. The Makefile contains instructions on how to do the build.

The source code for the nachos program itself lives in several directories: code/lib, code/machine, code/threads, code/filesys, code/userprog, and code/network. The program is built using the Makefile in one of the "build" directories. You need to choose a build directory depending on the type of machine you are currently logged in to. As of January 2003, all of the CPU servers in the CSCF undergraduate environment are running Solaris, so you should work in the build.solaris directory.

Once you are in the appropriate build directory, read the Makefile carefully, and follow the instructions in it. It explains how to build the nachos program.

Running Nachos

Once you have built nachos, you should be able to run it by simply typing

./nachos

in the build directory. The command line argument -u will give you a list of the available command line options. Using these options, you can control what nachos does when it runs. For starters, you may wish to try the -K and -C flags, which run some simple self-tests. You can also try asking Nachos to run a very simple test program called halt, which is found in the code/test directory. To try this, type

./nachos -d ca -x ../test/halt

The -d ca turns on the address space (a) and system call (c) related debugging output. The halt program simply makes the "Halt" system call, which causes the machine simulator to halt and print out some statistics. Have a look at the halt program. It is in code/test/halt.c.

For more details, you can look in the file code/threads/main.cc. In fact, this is the best place to start reading the Nachos code, since this is where it all begins.

Nachos Directory Structure

The main nachos directory contains three sub-directories:

coff2noff/

The source code and Makefiles for coff2noff, which is a program for converting COFF (Common Object File Format) files to NOFF (Nachos Object File Format) files. Note that noff.h in this directory is a link to the file noff.h in userprog.

c++-example/

The Nachos operating system is written in a subset of C++. This directory contains an excellent primer on C++. This primer is good reading for those who need a refresher, and even for those of you who are experienced C++ programmers. In particular, it explains why some of the "features" of C++ are not used at all in Nachos.

code/

All of the source code for the Nachos operating system, the machine simulation, and the test programs can be found here. This code is organized into several sub-directories:

lib: utilities used by the rest of the Nachos code
machine/: The machine simulation. Except as noted in machine.h, you may not modify the code in this directory.
threads/: Nachos is a multi-threaded program. Thread support is found here. This directory also contains the main() routine of the nachos program, in main.cc.
userprog/: Nachos operating system code to support the creation of address spaces, loading of user (test) programs, and execution of test programs on the simulated machine. The exception handling code is here, in exception.cc.
filesys/: Two different file system implementations are here. The "real" file system uses the simulated workstation's simulated disk to hold files. A "stub" file system translates Nachos file system calls into UNIX file system calls. This is useful initially, so that files can be used (e.g., to hold user programs) before you have had a chance to fix up the "real" file system. By default, the "stub" file system is build into the nachos program and the "real" file system is not. This can be changed by setting a flag in the Nachos makefile.
network/: Nachos operating system support for networking, which implements a simple "post office" facility. Several independent simulated Nachos machines can talk to each other through a simulated network. Unix sockets are used to simulate network connections among the machines.
test/: User test programs to run on the simulated machine. As indicated earlier, these are separate from the source for the Nachos operating system and workstation simulation. This directory contains its own Makefile. The test programs are very simple and are written in C rather than C++.