Fixing commenting (always nice)

diff --git a/Kernel/arch/x86/include/arch.h b/Kernel/arch/x86/include/arch.h
index 67a6290..ede3bf0 100644 (file)
--- a/Kernel/arch/x86/include/arch.h
+++ b/Kernel/arch/x86/include/arch.h
@@ -29,47 +29,67 @@
 
 #define __ASM__        __asm__ __volatile__
 
-#define LONGLOCK_NUM_THREADS   8
-
-// === MACROS ===
+// === Spinlocks ===
+/**
+ * \brief Short Spinlock structure
+ */
 struct sShortSpinlock {
-       volatile int    Lock;
-        int    IF;
+       volatile int    Lock;   //!< Lock value
+        int    IF;     //!< Interrupt state on call to SHORTLOCK
 };
 /**
  * \brief Determine if a short spinlock is locked
+ * \param Lock Lock pointer
  */
 static inline int IS_LOCKED(struct sShortSpinlock *Lock) {
        return !!Lock->Lock;
 }
 /**
  * \brief Acquire a Short Spinlock
- * \note Stops interrupts, so be careful
+ * \param Lock Lock pointer
+ * 
+ * This type of mutex should only be used for very short sections of code,
+ * or in places where a Mutex_* would be overkill, such as appending
+ * an element to linked list (usually two assignement lines in C)
+ * 
+ * \note This type of lock halts interrupts, so ensure that no timing
+ * functions are called while it is held.
  */
 static inline void SHORTLOCK(struct sShortSpinlock *Lock) {
         int    v = 1;
+       
+       // Save interrupt state
        __ASM__ ("pushf;\n\tpop %%eax" : "=a"(Lock->IF));
        Lock->IF &= 0x200;
-       __ASM__ ("cli");        // Stop task switches
+       
+       // Stop interrupts
+       __ASM__ ("cli");
+       
        // Wait for another CPU to release
        while(v)
                __ASM__("xchgl %%eax, (%%edi)":"=a"(v):"a"(1),"D"(&Lock->Lock));
 }
 /**
  * \brief Release a short lock
+ * \param Lock Lock pointer
  */
 static inline void SHORTREL(struct sShortSpinlock *Lock) {
        Lock->Lock = 0;
-       #if 0
+       #if 0   // Which is faster?, meh the test is simpler
        __ASM__ ("pushf;\n\tor %0, (%%esp);\n\tpopf" : : "a"(Lock->IF));
        #else
        if(Lock->IF)    __ASM__ ("sti");
        #endif
 }
+
+// === MACROS ===
 /**
  * \brief Halt the CPU
  */
 #define        HALT()  __asm__ __volatile__ ("hlt")
+/**
+ * \brief Fire a magic breakpoint (bochs)
+ */
 #define        MAGIC_BREAK()   __asm__ __volatile__ ("xchg %bx, %bx")
 
 // === TYPES ===

diff --git a/Kernel/threads.c b/Kernel/threads.c
index 8ec0e9f..99a9add 100644 (file)
--- a/Kernel/threads.c
+++ b/Kernel/threads.c
@@ -840,7 +840,14 @@ void Threads_SegFault(tVAddr Addr)
 }
 
 /**
- * \brief heavy mutex
+ * \brief Acquire a heavy mutex
+ * \param Mutex        Mutex to acquire
+ * 
+ * This type of mutex checks if the mutex is avaliable, and acquires it
+ * if it is. Otherwise, the current thread is added to the mutex's wait
+ * queue and the thread suspends. When the holder of the mutex completes,
+ * the oldest thread (top thread) on the queue is given the lock and
+ * restarted.
  */
 void Mutex_Acquire(tMutex *Mutex)
 {
@@ -884,7 +891,8 @@ void Mutex_Acquire(tMutex *Mutex)
 }
 
 /**
- * \brief Release a held spinlock
+ * \brief Release a held mutex
+ * \param Mutex        Mutex to release
  */
 void Mutex_Release(tMutex *Mutex)
 {
@@ -904,6 +912,10 @@ void Mutex_Release(tMutex *Mutex)
        SHORTREL( &Mutex->Protector );
 }
 
+/**
+ * \brief Is this mutex locked?
+ * \param Mutex        Mutex pointer
+ */
 int Mutex_IsLocked(tMutex *Mutex)
 {
        return Mutex->Owner != NULL;