Nachos for Java README



Welcome to Nachos for Java. We believe that working in Java rather than

C++ will greatly simplify the development process by preventing bugs

arising from memory management errors, and improving debugging support.



Getting Nachos:



Download nachos-java.tar.gz from the Projects section of the class

homepage at:



	http://www-inst.EECS.Berkeley.EDU/~cs162/



Unpack it with these commands:



	gunzip -c nachos-java.tar.gz | tar xf -



Additional software:



Nachos requires the Java Devlopment Kit, version 1.5 or later. This is

installed on all instructional machines in:

	/usr/sww/lang/jdk-1.5.0_05

To use this version of the JDK, be sure that

	/usr/sww/lang/jdk-1.5.0_05/bin

is on your PATH. (This should be the case for all class accounts

already.)



If you are working at home, you will need to download the JDK. 

It is available from:

	http://java.sun.com/j2se/1.5/

Please DO NOT DOWNLOAD the JDK into your class account! Use the

preinstalled version instead.



The build process for Nachos relies on GNU make. If you are running on

one of the instructional machines, be sure you run 'gmake', as 'make'

does not support all the features used. If you are running Linux, the

two are equivalent. If you are running Windows, you will need to 

download and install a port. The most popular is the Cygnus toolkit, 

available at:



	http://sources.redhat.com/cygwin/mirrors.html



The Cygnus package includes ports of most common GNU utilities to

Windows. 



For project 2, you will need a MIPS cross compiler, which is a

specially compiled GCC which will run on one architecture (e.g.

Sparc) and produce files for the MIPS processor. These compilers

are already installed on the instructional machines, and are

available in the directory specified by the $ARCHDIR environment

variable.



If you are working at home, you will need to get a cross-compiler

for yourself. Cross-compilers for Linux and Win32 will be available 

from the CS162 Projects web page. Download the cross compiler

distribution and unpack it with the following command:



	gunzip -c mips-x86-linux-xgcc.tar.gz | tar xf -



(Substitute the appropriate file name for mips-x86.linux-xgcc in the

above command.) You need to add the mips-x86.linux-xgcc directory to 

your PATH, and set an environment variable ARCHDIR to point to this 

directory. (Again, this has already been done for you on the

instructional machines.) 



Compiling Nachos:



You should now have a directory called nachos, containing a Makefile,

this README, and a number of subdirectories. 



First, put the 'nachos/bin' directory on your PATH. This directory

contains the script 'nachos', which simply runs the Nachos code.



To compile Nachos, go to the subdirectory for the project you wish 

to compile (I will assume 'proj1/' for Project 1 in my examples), 

and run:



	gmake



This will compile those portions of Nachos which are relevant to the

project, and place the compiled .class files in the proj1/nachos

directory. 



You can now test Nachos from the proj1/ directory with:



	nachos



You should see output resembling the following:



  nachos 5.0j initializing... config interrupt timer elevators user-check grader

  *** thread 0 looped 0 times

  *** thread 1 looped 0 times

  *** thread 0 looped 1 times

  *** thread 1 looped 1 times

  *** thread 0 looped 2 times

  *** thread 1 looped 2 times

  *** thread 0 looped 3 times

  *** thread 1 looped 3 times

  *** thread 0 looped 4 times

  *** thread 1 looped 4 times

  Machine halting!



  Ticks: total 24750, kernel 24750, user 0

  Disk I/O: reads 0, writes 0

  Console I/O: reads 0, writes 0

  Paging: page faults 0, TLB misses 0

  Network I/O: received 0, sent 0



This is the correct output for the "bare bones" Nachos, without any of

the features you will add during the projects.



If you are working on a project which runs user programs (projects 2-4), 

you will also need to compile the MIPS test programs with:



	gmake test



Command Line Arguments:



For a summary of the command line arguments, run:



	nachos -h



The commands are:



        -d <debug flags>

                Enable some debug flags, e.g. -d ti



        -h

                Print this help message.



        -s <seed>

                Specify the seed for the random number generator



        -x <program>

		Specify a program that UserKernel.run() should execute,

		instead of the value of the configuration variable

		Kernel.shellProgram



        -z

                print the copyright message



        -- <grader class>

		Specify an autograder class to use, instead of

		nachos.ag.AutoGrader



        -# <grader arguments>

                Specify the argument string to pass to the autograder.



        -[] <config file>

                Specifiy a config file to use, instead of nachos.conf





Nachos offers the following debug flags:



    c: COFF loader info 

    i: HW interrupt controller info 

    p: processor info 

    m: disassembly 

    M: more disassembly 

    t: thread info 

    a: process info (formerly "address space", hence a) 



To use multiple debug flags, clump them all together. For example, to

monitor coff info and process info, run:



	nachos -d ac



nachos.conf:



When Nachos starts, it reads in nachos.conf from the current

directory.  It contains a bunch of keys and values, in the simple

format "key = value" with one key/value pair per line. To change the

default scheduler, default shell program, to change the amount of

memory the simulator provides, or to reduce network reliability, modify

this file.



Machine.stubFileSystem:

    Specifies whether the machine should provide a stub file system. A

    stub file system just provides direct access to the test directory.

    Since we're not doing the file system project, this should always

    be true.



Machine.processor:

    Specifies whether the machine should provide a MIPS processor. In

    the first project, we only run kernel code, so this is false. In

    the other projects it should be true.



Machine.console:

    Specifies whether the machine should provide a console. Again, the

    first project doesn't need it, but the rest of them do.



Machine.disk:

    Specifies whether the machine should provide a simulated disk. No

    file system project, so this should always be false.



ElevatorBank.allowElevatorGUI:

    Normally true. When we grade, this will be false, to prevent

    malicious students from running a GUI during grading.



NachosSecurityManager.fullySecure:

    Normally false. When we grade, this will be true, to enable

    additional security checks.



Kernel.kernel:

    Specifies what kernel class to dynmically load.  For proj1, this is

    nachos.threads.ThreadedKernel. For proj2, this should be

    nachos.userprog.UserKernel. For proj3, nachos.vm.VMKernel. For

    proj4, nachos.network.NetKernel.



Processor.usingTLB:

    Specifies whether the MIPS processor provides a page table

    interface or a TLB interface. In page table mode (proj2), the

    processor accesses an arbitrarily large kernel data structure to do

    address translation. In TLB mode (proj3 and proj4), the processor

    maintains a small TLB (4 entries).



Processor.numPhysPages:

    The number of pages of physical memory.  Each page is 1K. This is

    normally 64, but we can lower it in proj3 to see whether projects

    thrash or crash.



Documentation:



The JDK provides a command to create a set of HTML pages showing all

classes and methods in program. We will make these pages available on

the webpage, but you can create your own for your home machine by doing

the following (from the nachos/ directory):



	mkdir ../doc

	gmake doc



Troubleshooting:



If you receive an error about "class not found exception", it may be

because you have not set the CLASSPATH environment variable. Add the

following to your .cshrc:



	setenv CLASSPATH .



Credits:



Nachos was originally written by Wayne A. Christopher, Steven J.

Procter, and Thomas E. Anderson. It incorporates the SPIM simulator

written by John Ousterhout. Nachos was rewritten in Java by Daniel

Hettena.



Copyright:



Copyright (c) 1992-2001 The Regents of the University of California.

All rights reserved.



Permission to use, copy, modify, and distribute this software and its

documentation for any purpose, without fee, and without written

agreement is hereby granted, provided that the above copyright notice

and the following two paragraphs appear in all copies of this

software.



IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY

FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES

ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF

THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF

SUCH DAMAGE.



THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,

INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE

PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF

CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,

ENHANCEMENTS, OR MODIFICATIONS.