Introduction:
	
	NACHOS is an instructional operating system originally developed at
Berkeley to give hands on experience with OS design.  NACHOS was used at
Stanford during fall quarter of the 92/93 school year.  Both the students
and professor wanted more from the NACHOS (actually the students probably
wanted less of it).  NACHOS was redesigned as a senior project last year by
one of the students who used the original version of NACHOS.  
	
Overview:

	It is not possible to give every student in the course a real
machine to learn the techniques of building an operating system.  Therefore
NACHOS includes a machine simulator.  Great effort has been put forth by
many people to make working on the simulator seem like the real thing, but
it's not.  The diagram below shows how relationship between the NACHOS, the
machine simulator, user processes and the peripheral devices.

   __________________________________________________________________
  |    ___________________________                                   |
  |   |                           |                                  |
  |   |  NACHOS Operating System  |         Unix process             |
  |   |___________________________|                                  |
  |             /\                                                   |
  |             ||                                                   |
  |             ||                                                   |
  |             \/                                                   |
  |    __________________________________________________________    |
  |   |                             _______________________      |   |
  |   |                            |                       |     |   |
  |   |  SPARC Machine Simulator   |     User Programs     |     |   |
  |   |                            |_______________________|     |   |
  |   |__________________________________________________________|   |
  |               /\                            /\                   |
  |               ||                            ||                   |
  |               ||                            ||                   |
  |               \/                            \/                   |
  |    ___________________________    ___________________________    | 
  |   |                           |  |                           |   |
  |   |     Console Emulation     |  |      Disk Emulation       |   |
  |   |___________________________|  |___________________________|   | 
  |__________________________________________________________________|


All of NACHOS is contained within a single Unix process which runs on a
workstation.  User programs run completely on the simulated machine as they
would in real life.  The operating system, however runs on the Unix
workstation.  The only parts of the operating system that exists within the
simulator are page tables.  This actually makes life easier for you.  One
of the difficulties of building a real OS is having the OS manage itself.
Most of these problems do not exist with this set up.  Although the
peripheral devices exist with the OS in the Unix process, there is a well
defined interface to them.  Thus interacting with the peripheral devices is
fairly realistic.

	NACHOS can take up a lot of time.  It has been redesigned to take
up less of your time by providing more of the mundane code for you (ie.
lists and hashtables).  However, it will still take a large amount of time,
and you don't want to waste any of it.  Unless you have a lot of spare time
on your hands, you should not try to understand how any of the code in the
machine directory works.  Simply learn the specifications and the interface
to the simulator just as you would if it were a real machine.  

	There is a README file in each of the directories.  These cover
material which is especially relevant to the directory in which the file is
found but which may be relevant to other things as well.  At the beginning
of each README there is an outline of the material in the file.  This
should help you locate relevant material quickly.  If you feel there is
material missing from the README that would benefit students if it were
included, send the TA mail and he/she will consider including the
information.  Below you will find the outlines from the beginning of each
README file.  

	NOTE:  The first assingment is conceptually tricky but does not
take much time.  Do not let this fool you.  After that you might want to
rent out a cubicle at Sweet Hall.  Use the time at the beginning to go
through the specifications, learn the utility classes, etc.

README.threads

I. Flow of Control
  A. Main
    i. NACHOS_main
    ii. main
  B. Initialize
    i. Global Variables
    ii. Initialization Routines
  C. Function Dispatch
  D. Trap Handler
  E. Cleanup

II. Threads and Processes
  A. Difference Between a Thread and a Process
  B. Thread Support in NACHOS
    i. Thread Class
	a. Yield
        b. Sleep
	c. Finish
	d. Fork
	e. addrSpace - Address Space
    ii. Flow of Control with Multiple Threads	
        a. Yield
	b. Sleep
	c. Finish
	d. SWITCH
    iii. Scheduler Class
    iv. Synchronization of Threads

III. Utility Classes
  A. Motivation
    i. List Class
    ii. HashTable Class
  B. Properties of Generic Classes


README.multiprog

I. User Level Process
  A. Executable or Binary File Format
  B. Address Space Structure
    i.   Text
    ii.  Data
    iii. Stack
  C. Running a User Level Process
    i. Initial Stack Configuration
      a. Load Time Support
      b. argc - Argument Count
      c. argv - Argument Vector
      d. Extra Space
    ii. Initial Processor State. 
      a. pc  - Program Counter
      b. npc - Next Program Counter
      c. sp - Stack Pointer
      d. fp - Frame Pointer
      e. ptbr - Page Table Base Register
      f. ptlr - Page Table Length Register
      g. Processor State and Window Invalid Mask Registers
    iii. Saving/Restoring Process State

II. Memory
  A. Page Table Structure
  B. Memory Management
    i. MemoryManager Class
    ii. AddrSpace Class
    iii. PageTable Class

III. System Calls
  A. Argument Passing Convention
  B. System Call Semantics
    i. Console Calls
    ii. File System Calls
    iii. Exec and Wait Calls


README.machine

I. What You Do And Don't Have To Know About The Machine Simulator

II. Machine Emulator Command Groups
  A. Shutdown Routine
  B. Timer Routine
  C. Interrupt Related Routines
  D. Read/Write Main Memory
  E. Processor Commands
    i. Register Windows
  F. Console I/O Routines
  G. Disk I/O Routines