Index: src/synch/spinlock.c
===================================================================
--- src/synch/spinlock.c	(revision 922c7cefbbf5374257e55c367a9baa73034912f9)
+++ src/synch/spinlock.c	(revision 5e04b48df92c9f2fc22584ce028cd113c08ebddf)
@@ -27,14 +27,20 @@
  */
 
-#include <arch.h>
-
+#include <synch/spinlock.h>
 #include <arch/atomic.h>
 #include <arch/barrier.h>
-#include <synch/spinlock.h>
+#include <arch.h>
 #include <preemption.h>
 #include <print.h>
+#include <debug.h>
 
 #ifdef __SMP__
 
+/** Initialize spinlock
+ *
+ * Initialize spinlock.
+ *
+ * @param sl Pointer to spinlock_t structure.
+ */
 void spinlock_initialize(spinlock_t *sl)
 {
@@ -43,4 +49,12 @@
 
 #ifdef DEBUG_SPINLOCK
+/** Lock spinlock
+ *
+ * Lock spinlock.
+ * This version has limitted ability to report 
+ * possible occurence of deadlock.
+ *
+ * @param sl Pointer to spinlock_t structure.
+ */
 void spinlock_lock(spinlock_t *sl)
 {
@@ -55,8 +69,20 @@
 		}
 	}
+
+	/*
+	 * Prevent critical section code from bleeding out this way up.
+	 */
 	CS_ENTER_BARRIER();
 
 }
+
 #else
+
+/** Lock spinlock
+ *
+ * Lock spinlock.
+ *
+ * @param sl Pointer to spinlock_t structure.
+ */
 void spinlock_lock(spinlock_t *sl)
 {
@@ -68,8 +94,22 @@
 	 */
 	spinlock_arch(&sl->val);
+
+	/*
+	 * Prevent critical section code from bleeding out this way up.
+	 */
 	CS_ENTER_BARRIER();
 }
 #endif
 
+/** Lock spinlock conditionally
+ *
+ * Lock spinlock conditionally.
+ * If the spinlock is not available at the moment,
+ * signal failure.
+ *
+ * @param sl Pointer to spinlock_t structure.
+ *
+ * @return Zero on failure, non-zero otherwise.
+ */
 int spinlock_trylock(spinlock_t *sl)
 {
@@ -78,4 +118,8 @@
 	preemption_disable();
 	rc = !test_and_set(&sl->val);
+
+	/*
+	 * Prevent critical section code from bleeding out this way up.
+	 */
 	CS_ENTER_BARRIER();
 
@@ -86,7 +130,19 @@
 }
 
+/** Unlock spinlock
+ *
+ * Unlock spinlock.
+ *
+ * @param sl Pointer to spinlock_t structure.
+ */
 void spinlock_unlock(spinlock_t *sl)
 {
+	ASSERT(sl->val != 0);
+
+	/*
+	 * Prevent critical section code from bleeding out this way down.
+	 */
 	CS_LEAVE_BARRIER();
+	
 	sl->val = 0;
 	preemption_enable();