From abe295c77d6755f3a4195a69b27826ccf753619f Mon Sep 17 00:00:00 2001
From: Kelvin Lawson <kelvin@laptop.(none)>
Date: Tue, 19 Jan 2010 00:40:18 +0000
Subject: [PATCH] Add module doxygen description

---
 kernel/atomsem.c | 59 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/kernel/atomsem.c b/kernel/atomsem.c
index 7904138..74206dc 100755
--- a/kernel/atomsem.c
+++ b/kernel/atomsem.c
@@ -27,6 +27,65 @@
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
+
+/** 
+ * \file
+ * Semaphore library.
+ *
+ *
+ * This module implements a counting semaphore library with the following
+ * features:
+ *
+ * \par Flexible blocking APIs
+ * Threads which wish to decrement a semaphore can choose whether to block,
+ * block with timeout, or not block if the semaphore has reached zero.
+ *
+ * \par Interrupt-safe calls
+ * All APIs can be called from interrupt context. Any calls which could
+ * potentially block have optional parameters to prevent blocking if you
+ * wish to call them from interrupt context.
+ *
+ * \par Priority-based queueing
+ * Where multiple threads are blocking on a semaphore, they are woken in
+ * order of the threads' priorities. Where multiple threads of the same
+ * priority are blocking, they are woken in FIFO order.
+ *
+ * \par Count up to 255
+ * Semaphore counts can be initialised and incremented up to a maximum of 255.
+ *
+ * \par Smart semaphore deletion
+ * Where a semaphore is deleted while threads are blocking on it, all blocking
+ * threads are woken and returned an error code to indicate the reason for
+ * being woken.
+ *
+ *
+ * \n <b> Usage instructions: </b> \n
+ *
+ * All semaphore objects must be initialised before use by calling
+ * atomSemCreate(). Once initialised atomSemGet() and atomSemPut() are used to
+ * decrement and increment the semaphore count respectively.
+ *
+ * If a semaphore count reaches zero, further calls to atomSemGet() will block
+ * the calling thread (unless the calling parameters request no blocking). If
+ * a call is made to atomSemPut() while threads are blocking on a zero-count
+ * semaphore, the highest priority thread is woken. Where multiple threads of
+ * the same priority are blocking, they are woken in the order in which the
+ * threads started blocking. 
+ *
+ * Semaphores which are no longer required can be deleted using
+ * atomSemDelete(). This function automatically wakes up any threads which are
+ * waiting on a semaphore which is being deleted.
+ *
+ *
+ * \n <b> Notes: </b> \n
+ *
+ * Note that those considering using a semaphore initialised to 1 for mutual
+ * exclusion purposes may wish to investigate the mutex library available in
+ * Atomthreads.
+ *
+ */
+
+
 #include <stdio.h>
 #include "atom.h"
 #include "atomsem.h"