Initial Spring 2016 commit.

design/assignments.txt

@@ -0,0 +1,120 @@
+The (potential) OS/161 assignments
+----------------------------------
+
+OS/161 is used by a wide variety of courses at a wide variety of
+schools, no two of which have the exact same set of assignments and
+assignment requirements. The code base has been (to the extent
+reasonably possible) structured to allow this and not assume any
+particular structure or (particularly) numbering of assignments.
+
+That said, in various places comments and documentation must (to be
+helpful, at least) refer to particular assignments and things that are
+(typically) done in particular assignments. These are written in
+fairly general terms. This file is provided as an index for those
+terms.
+
+***  Always refer to the course materials provided by your     ***
+***  instructors when trying to figure out what functionality  ***
+***  you are and are not required to implement.                ***
+
+Note that the OS/161 code base you are given may include solutions for
+some parts of the assignments described below, or even some whole
+assignments.
+
+Also note that the text below refers to assorted technical terms and
+OS concepts without much or any explanation; you may not be familiar
+with most of them at first and that's perfectly ok.
+
+
+OS/161 is intended to support six basic assignments, most of which can
+be divided into smaller pieces. These six assignments are:
+
+   - synchronization;
+   - basic system calls;
+   - virtual memory;
+   - basic file system functionality;
+   - file system recovery via journaling;
+   - some additional piece of OS functionality.
+
+
+Synchronization.
+
+This assignment has (potentially) three parts:
+   - Implement (sleep) locks and condition variables.
+   - Implement reader-writer locks.
+   - Solve some synchronization problems of the dining-philosophers
+     variety.
+
+
+Basic system calls. (And processes.)
+
+This assignment has (potentially) up to six parts:
+   - Implement file tables and open-file objects.
+   - Implement the basic system calls for files, normally:
+	- open()
+	- dup2()
+	- read()
+	- write()
+	- lseek()
+	- close()
+	- chdir()
+	- __getcwd()
+   - Implement processes, process IDs, and the basic process system
+     calls, normally:
+	- getpid()
+	- fork()
+	- _exit()
+	- waitpid()
+   - Implement the execv() system call.
+   - Implement a scheduler.
+
+
+Virtual memory.
+
+This assignment entails replacing a provided very simple virtual
+memory system with a real one. This possibly includes providing the
+sbrk() system call. It does not split into parts readily.
+
+
+Basic file system functionality.
+
+This assignment has (potentially) up to five parts:
+   - Add more system calls for file system operations, typically taken
+     from these:
+	- sync()
+	- mkdir()
+	- rmdir()
+	- remove()
+	- link()
+	- rename()
+	- getdirentry()
+	- fstat()
+	- fsync()
+	- ftruncate()
+	- flock()
+     although others may be chosen.
+   - Implement a buffer cache.
+   - Replace a biglock with fine-grained locking in the VFS layer
+     and/or the SFS file system.
+   - Add support for subdirectories to SFS.
+   - Implement cross-directory rename in SFS.
+   - Implement larger files in SFS.
+
+
+File system recovery via journaling.
+
+This assignment has (potentially) five parts:
+   - Implement an on-disk container for a file system journal.
+   - Instrument the buffer cache to support write-ahead journaling.
+   - Design a system of journal records suitable for recovering the
+     file system after a crash.
+   - Add code to SFS to issue these journal records.
+   - Implement code to read the on-disk journal and recover from a
+     crash.
+
+
+Additional projects.
+
+There is a wide variety of things that can be done to build on the
+above assignments. None are listed here, because this file is not
+the place for it.

design/shell.txt

@@ -0,0 +1,55 @@
+                      SHELL DESIGN NOTES
+                      ------------------
+
+   The shell has few bells and whistles. It allows up to 128
+backgrounded jobs (after this point you have to wait for some to exit,
+because the table it uses to track these cannot be resized.)
+
+   The background jobs are tracked in an array of MAXBG pid_t's. If an
+open slot is found, a background job's pid can be stashed there.
+Background jobs can be collected using the "wait" built-in command,
+which removes any pids whose exit status it collects from the
+background jobs table.
+
+   The wait built-in command takes an optional argument, the process
+id to wait for. The shell will attempt to wait for any process, not
+just the ones it actually started as its own background jobs. However,
+since no facility exists for looking up the pids of running processes,
+this ability is not necessarily useful. If no argument is provided,
+wait waits for all outstanding background jobs.
+
+   The shell uses WNOHANG if WNOHANG is defined, in which case
+background jobs are polled after every command, like in Unix shells.
+If WNOHANG is not defined, background jobs are polled only by user
+request. In OS/161 2.0, WNOHANG is always defined in the kernel header
+files, but the implementation is only suggested, not required. To make
+the shell stop trying to use WNOHANG, patch it, or remove WNOHANG from
+kern/wait.h.
+
+   There are two other built-in commands: chdir, which uses the chdir
+system call to change directory, and can also be accessed as just cd,
+and exit, which causes the shell to exit with a specified exit status
+(0 if not supplied).
+
+   Note that all these built-in commands must be built into the shell
+in order to work usefully.
+
+   The shell processes commands by reading lines and then splitting
+them up into words using whitespace characters (space, tab, carriage
+return, and newline) as separators. No punctuation characters are
+interpreted, except for `&'. No variable substitution or argument
+wildcard expansion ("globbing") is performed.
+
+   The `&' character, if present as the last word on a command line,
+is treated as the "background" operator: the command is run as a
+background job, that is, after starting it the shell immediately
+prints another prompt and accepts more commands. Note that the `&'
+must be preceded by whitespace to be recognized. The process id of the
+background job is printed as it starts. Note that shell builtins
+cannot be backgrounded; furthermore, because the OS/161 console does
+not support job control, starting background jobs that perform
+terminal input (or, to a lesser extent, terminal output) may produce
+confusing and/or unwanted results.
+
+   The shell also supports the "sh -c COMMAND" syntax in the hopes
+that it will be useful.

design/usermalloc.txt

@@ -0,0 +1,24 @@
+User-level malloc
+-----------------
+
+   The user-level malloc implementation is defined to be simple, not
+fast or efficient. It uses a very basic first-fit block algorithm.
+
+   There's an 8-byte header which holds the offsets to the previous
+and next blocks, a used/free bit, and some magic numbers (for
+consistency checking) in the remaining available header bits. It also
+allocates in units of 8 bytes to guarantee proper alignment of
+doubles. (It also assumes its own headers are aligned on 8-byte
+boundaries.)
+
+   On malloc(), it searches the entire heap starting at the beginning
+for the first block big enough to hold the allocation. If it doesn't
+find one, it calls sbrk() to get more memory. If it does find one, it
+marks the block in use. It splits the remaining portion of the block
+off as a new free block only if said portion is large enough to hold
+both a header and some data.
+
+   On free(), it marks the block free and then tries to merge it with
+the adjacent blocks (both above and below) if they're free.
+
+   That's about all there is to it.