--------------------------------------------------------------------------
 Yalnix README - Project 3 (Final Release)
--------------------------------------------------------------------------

CMSC 33000 - 3/10/2004

The A Team is :  Austin Robison                   Atul Varma
              :  robison@cs.uchicago.edu          varmaa@cs.uchicago.edu

--------------------------------------------------------------------------
 QUICK NOTES
--------------------------------------------------------------------------

The following things make our kernel phat:

 * We have implemented high-level file I/O syscalls
   (Read/Write/Open/Close/Seek/Dup2).  These currently work with disk
   files, but we haven't implemented file drivers for any other
   devices (e.g. display, pen, pipes, etc).

 * We have implemented the queuing syscalls (CreateQueue/DestroyQueue/
   SleepOnQueue/WaitOnQueue/Dequeue).

 * We have implemented KMalloc/KFree as syscalls, to make kernel
   threads more threadsafe.

 * We have implemented a kprintf() function that takes variable arguments.

 * We have implemented a working bootloader in both C and assembly.

 * We have implemented a kernel break, and our kmalloc can allocate
   memory chunks of sizes > 1 page.

--------------------------------------------------------------------------
 KNOWN BUGS
--------------------------------------------------------------------------

All tests have been found to pass without any problems when executed
through the commandline (test3), yash and ytest.

On the project due date, we had been experiencing some problems with
sema2 but it turned out to be a bug in our Yield() syscall, the fixing
of which hopefully didn't break any other tests...  We can't really
run the whole testing suite again since stonecrusher's overloaded with
everyone using it.

--------------------------------------------------------------------------
 INSTRUCTIONS
--------------------------------------------------------------------------

Type 'make format-minifs' to create and format a ydisk with the minifs 
filesystem or 'make format-ufs' to format a ydisk with the ufs filesystem.

Type 'make' to compile and install the assembly-based bootloader and kernel.

Type 'yboot yalnixdisk' to boot up the ATEAM Yalnix OS.

--------------------------------------------------------------------------
 DIRECTORY LAYOUT / SOURCE TREE
--------------------------------------------------------------------------

This is our source tree:

  boot.s           - Assembly bootloader
  cboot.c          - C bootloader (graduate requirement)
  cboot_asm.s      - Assembly component of C bootloader
  idtable.c        - Generic hashtable data structure, using integer IDs
                     as keys
  init.c           - Sample init process (for testing)
  kernel.c         - The main OS kernel (contains interrupt vector and
                     handlers, kernel main() function)
  kernelcall.s     - Implementation of KMalloc/KFree syscall wrappers
  kmalloc.c        - Implementation of kmalloc/kfree
  kpanic.c         - Kernel PANIC module
  kprint.c         - kprints/kprintd/kprinth and related functions
  kthread.c        - Kernel thread and process management module,
                     including functions to create kthreads/processes
                     and manipulate a process' stack and heap
  list.c           - Generic linked list data structure
  mm.c             - Low-level memory management for physical and
                     virtual memory.  Includes get_free_page,
                     release_page, pmalloc/pfree
  pendriver.c      - Driver for the pen device
  queue.c          - Generic queue data structure
  saveregs.s       - SPARC assembly leaf routine to aid in implementation
                     of functions that take a variable number of
                     arguments (used by kprintf, etc)
  schedule.c       - Process/thread scheduling module, for management
                     of the ready queue and so forth
  sem.c            - Implementation of semaphores
  serialdriver.c   - Implementation of the serial device
  syscall.c        - Implementation of Yalnix system call interface
  
  include/         - Contains include files to all public interfaces
  tests/           - Contains auxiliary testing code for certain modules
  yfs/             - Contains YDISK/YFS/YFILE related code and drivers
  ylibc/           - Contains ylibc, the Yalnix standard C library

--------------------------------------------------------------------------
 PROJECT 1 - GRADUATE REQUIREMENT (CS33000)
--------------------------------------------------------------------------

For graduate credit, we have created a separate target called 'cboot'
for the bootloader written in C.  To use this bootloader, just type
'make cboot', then 'make yalnix'.

--------------------------------------------------------------------------
 OTHER NOTES
--------------------------------------------------------------------------

We have attempted to modularize our code so that no global variables
exist, and as such some modules contain 'accessor' functions.

Note that the ylibc library, following accepted guidelines for
efficient library design, has a single object file for each function;
this makes it so that any program using the library will only have
integrated into its .text segment the code it uses.  And, since it is
rather futile to have a single .h file for each function, the header
for all the ylibc functions is contained in include/ylibc.h.  (The
reason we point this out is because we're aware that this is a
violation of the style guidelines, but we feel that it is justified
for the reasons stated.)