Cleanup documentation add doxygen and README.

README

@@ -0,0 +1,22 @@
+
+Building COS requires:
+ - SCons 4.0+
+ - Clang 15
+ - Qemu for simulation
+
+To build the source code run:
+# scons
+
+To clean the source tree run:
+# scons -c
+
+Building the documentation requires:
+ - Doxygen
+ - Graphviz
+ - dia
+ - Inkscape or png2pdf
+
+To build the documentation run the following command in the root folder:
+# doxygen docs/Doxyfile
+
+This will place the resulting HTML documentation in docs/html.

sys/kern/process.c

@@ -32,6 +32,15 @@ Slab processSlab;
  * Process
  */
 
+/**
+ * Process_Create --
+ *
+ *	Create a process.
+ *
+ *	@param [in] parent Parent process.
+ *	@param [in] title Process title.
+ *	@return The newly created process.
+ */
 Process *
 Process_Create(Process *parent, const char *title)
 {
@@ -87,6 +96,14 @@ Process_Create(Process *parent, const char *title)
     return proc;
 }
 
+/**
+ * Process_Destroy --
+ *
+ *	Destroy a process.  This should not be called direct, but rather by 
+ *	Process_Release.
+ *
+ *	@param [in] proc Process to destroy.
+ */
 static void
 Process_Destroy(Process *proc)
 {
@@ -109,10 +126,14 @@ Process_Destroy(Process *proc)
     Slab_Free(&processSlab, proc);
 }
 
-/*
+/**
  * Process_Lookup --
  *
  *	Lookup a process by PID and increment its reference count.
+ *	@param [in] pid Process ID to search for.
+ *
+ *	@retval NULL No such process.
+ *	@return Process that corresponds to the pid.
  */
 Process *
 Process_Lookup(uint64_t pid)
@@ -133,10 +154,12 @@ Process_Lookup(uint64_t pid)
     return proc;
 }
 
-/*
+/**
  * Process_Retain --
  *
  *	Increment the reference count for a given process.
+ *
+ *	@param proc Process to retain a reference to.
  */
 void
 Process_Retain(Process *proc)
@@ -145,10 +168,12 @@ Process_Retain(Process *proc)
     __sync_fetch_and_add(&proc->refCount, 1);
 }
 
-/*
+/**
  * Process_Release --
  *
  *	Decrement the reference count for a given process.
+ *
+ *	@param proc Process to release a reference of.
  */
 void
 Process_Release(Process *proc)
@@ -159,12 +184,17 @@ Process_Release(Process *proc)
     }
 }
 
-/*
+/**
  * Process_Wait --
  *
  *	Wait for a process to exit and then cleanup it's references.  If the 
  *	pid == 0, we wait for any process, otherwise we wait for a specific 
  *	process.
+ *
+ *	@param [in] proc Parent process.
+ *	@param [in] pid Optionally specify the pid of the process to wait on.
+ *	@retval ENOENT Process ID doesn't exist.
+ *	@return Exit status of the process that exited or crashed.
  */
 uint64_t
 Process_Wait(Process *proc, uint64_t pid)

sys/kern/sched.c

@@ -19,20 +19,34 @@
 #include <machine/pmap.h>
 
 // Scheduler Queues
+/**
+ * Scheduler lock that protects all queues.
+ */
 Spinlock schedLock;
+/**
+ * All threads currently waiting.
+ */
 ThreadQueue waitQueue;
+/**
+ * All runnable threads.
+ */
 ThreadQueue runnableQueue;
+/**
+ * Current thread executing on a given CPU.
+ */
 Thread *curProc[MAX_CPUS];
 
 /*
  * Scheduler Functions
  */
 
-/*
+/**
  * Sched_Current() --
  *
  *	Get the currently executing thread.  This function retains a reference 
  *	count and you must release the reference by calling Thread_Release.
+ *
+ *	@return Returns the current thread.
  */
 Thread *
 Sched_Current()
@@ -47,11 +61,13 @@ Sched_Current()
     return thr;
 }
 
-/*
+/**
  * Sched_SetRunnable --
  *
  *	Set the thread to the runnable state and move it from the wait queue if 
  *	necessary to the runnable queue.
+ *
+ *	@param [in] thr Thread to be set as runnable.
  */
 void
 Sched_SetRunnable(Thread *thr)
@@ -72,12 +88,13 @@ Sched_SetRunnable(Thread *thr)
     Spinlock_Unlock(&schedLock);
 }
 
-/*
+/**
  * Sched_SetWaiting --
  *
  *	Set the thread to the waiting state and move it to the wait queue.  The 
  *	thread should be currently running.
  *
+ *	@param [in] thr Thread to be set as waiting.
  */
 void
 Sched_SetWaiting(Thread *thr)
@@ -93,13 +110,14 @@ Sched_SetWaiting(Thread *thr)
     Spinlock_Unlock(&schedLock);
 }
 
-/*
+/**
  * Sched_SetZombie --
  *
  *	Set the thread to the zombie state and move it to the parent 
  *	processes's zombie process queue.  The thread should be currently 
  *	running.
  *
+ *	@param [in] thr Thread to be set as zombie.
  */
 void
 Sched_SetZombie(Thread *thr)
@@ -140,13 +158,16 @@ Sched_SetZombie(Thread *thr)
 	Mutex_Unlock(&proc->parent->zombieProcLock);
 }
 
-/*
+/**
  * Sched_Switch --
  *
  *	Switch between threads.  During the creation of kernel threads (and by 
  *	proxy user threads) we may not return through this code path and thus 
  *	the kernel thread initialization function must release the scheduler 
  *	lock.
+ *
+ *	@param [in] oldthr Current thread we are switching from.
+ *	@param [in] newthr Thread to switch to.
  */
 static void
 Sched_Switch(Thread *oldthr, Thread *newthr)
@@ -157,7 +178,7 @@ Sched_Switch(Thread *oldthr, Thread *newthr)
     Thread_SwitchArch(oldthr, newthr);
 }
 
-/*
+/**
  * Sched_Scheduler --
  *
  *	Run our round robin scheduler to find the process and switch to it.

sys/kern/slab.c

@@ -17,6 +17,16 @@
 
 LIST_HEAD(SlabListHead, Slab) slabList = LIST_HEAD_INITIALIZER(slabList);
 
+/**
+ * Slab_Init --
+ *
+ *	Create's a slab for a single type of object in the kernel.
+ *
+ *	@param [in] slab Slab that the object belongs to.
+ *	@param [in] name Developer friendly name for debugging purposes.
+ *	@param [in] objsz Size of the object in bytes.
+ *	@param [in] align Alignment of the object in bytes.
+ */
 void
 Slab_Init(Slab *slab, const char *name, uintptr_t objsz, uintptr_t align)
 {
@@ -40,6 +50,15 @@ Slab_Init(Slab *slab, const char *name, uintptr_t objsz, uintptr_t align)
     LIST_INSERT_HEAD(&slabList, slab, slabList);
 }
 
+/**
+ * SlabExtend --
+ *
+ *	Grow the slab to allocate new objects.
+ *
+ *	@param [in] slab Slab that we want to expand.
+ *	@retval -1 Failed to expand the slab.
+ *	@retval 0 Success.
+ */
 int
 SlabExtend(Slab *slab)
 {
@@ -73,6 +92,15 @@ SlabExtend(Slab *slab)
     return 0;
 }
 
+/**
+ * Slab_Alloc --
+ *
+ *	Free a slab object.
+ *
+ *	@param [in] slab Slab that the object belongs to.
+ *	@retval NULL Could not allocate an object.
+ *	@return Pointer to the allocated object.
+ */
 void *
 Slab_Alloc(Slab *slab)
 {
@@ -95,6 +123,14 @@ Slab_Alloc(Slab *slab)
     return (void *)elem;
 }
 
+/**
+ * Slab_Free --
+ *
+ *	Free a slab object.
+ *
+ *	@param [in] slab Slab that the object belongs to.
+ *	@param [in] region Object to free.
+ */
 void
 Slab_Free(Slab *slab, void *region)
 {