Fix documentation for mutex.h

core/include/mutex.h

@@ -19,23 +19,35 @@
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */
 
-#ifndef _MUTEX_H
-#define _MUTEX_H
+#ifndef __MUTEX_H_
+#define __MUTEX_H_
 
 #include "queue.h"
 
 /**
- * @brief Mutex structure. Should never be modified by the user.
+ * @brief Mutex structure. Must never be modified by the user.
  */
 typedef struct mutex_t {
     /* fields are managed by mutex functions, don't touch */
-    unsigned int val;       // @internal
-    queue_node_t queue;     // @internal
+    /**
+     * @internal
+     * @brief   The value of the mutex; 0 if unlocked, 1 if locked. **Must
+     *          never be changed by the user.**
+     */
+    unsigned int val;
+    /**
+     * @internal
+     * @brief   The process waiting queue of the mutex. **Must never be changed
+     *          by the user.**
+     */
+    queue_node_t queue;
 } mutex_t;
 
 /**
- * @brief Initializes a mutex object
- * @param mutex pre-allocated mutex structure.
+ * @brief Initializes a mutex object.
+ *
+ * @param[out] mutex    pre-allocated mutex structure, must not be NULL.
+ *
  * @return  Always returns 1, always succeeds.
  */
 int mutex_init(struct mutex_t *mutex);
@@ -44,7 +56,8 @@ int mutex_init(struct mutex_t *mutex);
 /**
  * @brief Tries to get a mutex, non-blocking.
  *
- * @param mutex Mutex-Object to lock. Has to be initialized first.
+ * @param[in] mutex Mutex object to lock. Has to be initialized first. Must not
+ *                  be NULL.
  *
  * @return 1 if mutex was unlocked, now it is locked.
  * @return 0 if the mutex was locked.
@@ -54,7 +67,8 @@ int mutex_trylock(struct mutex_t *mutex);
 /**
  * @brief Tries to get a mutex, blocking.
  *
- * @param mutex Mutex-Object to lock. Has to be initialized first.
+ * @param[in] mutex Mutex object to lock. Has to be initialized first. Must not
+ *                  be NULL.
  *
  * @return 1 getting the mutex was successful
  * @return <1 there was an error.
@@ -64,28 +78,16 @@ int mutex_lock(struct mutex_t *mutex);
 /**
  * @brief Unlocks the mutex.
  *
- * @param mutex Mutex-Object to unlock.
+ * @param[in] mutex Mutex object to unlock, must not be NULL.
  */
 void mutex_unlock(struct mutex_t *mutex);
 
 /**
  * @brief Unlocks the mutex and sends the current thread to sleep
  *
- * @param mutex Mutex-Object to unlock.
+ * @param[in] mutex Mutex object to unlock, must not be NULL.
  */
 void mutex_unlock_and_sleep(struct mutex_t *mutex);
 
-#define MUTEX_YIELD 1
-#define MUTEX_INISR 2
-
-/**********************
- * internal functions *
- **********************/
-
-void mutex_wake_waiters(struct mutex_t *mutex, int yield);
-void mutex_wait(struct mutex_t *mutex);
-
-/*struct mutex_entry_t * mutex_create_entry(int prio, struct tcb *proc);*/
-
+#endif /* __MUTEX_H_ */
 /** @} */
-#endif /* _MUTEX_H */

core/mutex.c

@@ -33,6 +33,8 @@
 #define ENABLE_DEBUG    (0)
 #include "debug.h"
 
+static void mutex_wait(struct mutex_t *mutex);
+
 int mutex_init(struct mutex_t *mutex)
 {
     mutex->val = 0;
@@ -62,7 +64,7 @@ int mutex_lock(struct mutex_t *mutex)
     return 1;
 }
 
-void mutex_wait(struct mutex_t *mutex)
+static void mutex_wait(struct mutex_t *mutex)
 {
     int irqstate = disableIRQ();
     DEBUG("%s: Mutex in use. %u\n", active_thread->name, mutex->val);
@@ -75,7 +77,7 @@ void mutex_wait(struct mutex_t *mutex)
         return;
     }
 
-    sched_set_status((tcb_t*) active_thread, STATUS_MUTEX_BLOCKED);
+    sched_set_status((tcb_t *) active_thread, STATUS_MUTEX_BLOCKED);
 
     queue_node_t n;
     n.priority = (unsigned int) active_thread->priority;
@@ -101,7 +103,7 @@ void mutex_unlock(struct mutex_t *mutex)
     if (mutex->val != 0) {
         if (mutex->queue.next) {
             queue_node_t *next = queue_remove_head(&(mutex->queue));
-            tcb_t *process = (tcb_t*) next->data;
+            tcb_t *process = (tcb_t *) next->data;
             DEBUG("%s: waking up waiter.\n", process->name);
             sched_set_status(process, STATUS_PENDING);
 
@@ -123,7 +125,7 @@ void mutex_unlock_and_sleep(struct mutex_t *mutex)
     if (mutex->val != 0) {
         if (mutex->queue.next) {
             queue_node_t *next = queue_remove_head(&(mutex->queue));
-            tcb_t *process = (tcb_t*) next->data;
+            tcb_t *process = (tcb_t *) next->data;
             DEBUG("%s: waking up waiter.\n", process->name);
             sched_set_status(process, STATUS_PENDING);
         }
@@ -131,8 +133,9 @@ void mutex_unlock_and_sleep(struct mutex_t *mutex)
             mutex->val = 0;
         }
     }
+
     DEBUG("%s: going to sleep.\n", active_thread->name);
-    sched_set_status((tcb_t*) active_thread, STATUS_SLEEPING);
+    sched_set_status((tcb_t *) active_thread, STATUS_SLEEPING);
     restoreIRQ(irqstate);
     thread_yield();
 }