Merge pull request #962 from authmillenon/issue-953

core: doc: documentation improvement lifo.h lpm.h msg.h mutex.h

core/include/lifo.h

@@ -10,54 +10,57 @@
  * @addtogroup  core_util
  * @{
  *
- * @file        lifo.h
- * @brief       LIFO buffer API, read long description carefully
- * @author      probably Kaspar Schleiser
- *
- * @long        This LIFO implementation very efficiently handles
- *              integer values. The caveat is that it can only handle
- *              values between 0 and its own size -1. Also it can only
- *              handle up to one element of each value. If you insert
- *              a value twice the LIFO will break.
+ * @file    lifo.h
+ * @brief   LIFO buffer API, read long description carefully
+ * @author  Heiko Will <hwill@inf.fu-berlin.de>
+ *
+ * @detail  This LIFO implementation very efficiently handles integer values.
+ *          The caveat is that it **can only handle values between 0 and its own
+ *          size - 1**. Also it can only handle up to one element of each value.
+ *          If you insert a value twice the LIFO will break.
  */
 
-#ifndef __LIFO_H
-#define __LIFO_H
+#ifndef __LIFO_H_
+#define __LIFO_H_
 
 /**
- * @brief:  check if the given lifo is empty
- * @return: true if empty, false otherwise
+ * @brief   Check if the given lifo is empty.
+ *
+ * @param[in] array The lifo array to check.
+ *
+ * @return  1, if empty
+ * @return  0, otherwise.
  */
 int lifo_empty(int *array);
 
 /**
- * @brief:           initialize a lifo array
+ * @brief               Initialize a lifo array.
  *
- * @param array:     an array of int of size n+1
- * @param n:         maximum integer value the lifo is able to store
+ * @param[in,out] array An array of size *n* + 1, may not be NULL.
+ * @param[in] n         Maximum integer value the lifo is able to store.
  */
 void lifo_init(int *array, int n);
 
 /**
- * @brief:          insert an element into the lifo
+ * @brief               Insert an element into the lifo
  *
- * @param array:    an integer array of least i+1 size that does not
- *                  already contain i
- * @param i:        the integer value to store, between 0 and the size
- *                  of the array -1, must not be stored already
+ * @param[in,out] array An integer array of least *i* + 1 size that **does not
+ *                      already contain *i***, may not be NULL.
+ * @param[in] i         The integer value to store, between 0 and the size of
+ *                      the array - 1, must not be stored already.
  *
  */
 void lifo_insert(int *array, int i);
 
 /**
- * @brief:          extract the least recently inserted element from the lifo
+ * @brief           Extract the least recently inserted element from the lifo.
  *
- * @param array:    an integer array
+ * @param[in] array An integer array, may not be NULL.
  *
- * @return:         -1 if the lifo is empty, the least recently
- *                  inserted element otherwise
+ * @return          -1, if the lifo is empty.
+ * @return          the least recently inserted element, otherwise.
  */
 int lifo_get(int *array);
 
+#endif /* __LIFO_H_ */
 /** @} */
-#endif /* __LIFO_H */

core/include/lpm.h

@@ -39,9 +39,19 @@ void lpm_init(void);
  */
 enum lpm_mode lpm_set(enum lpm_mode target);
 
+/**
+ * @brief   Switches the MCU to active power mode LPM_ON
+ */
 void lpm_awake(void);
 
+/**
+ * @brief   Begin to switch MCU to active power mode.
+ */
 void lpm_begin_awake(void);
+
+/**
+ * @brief   Finish to switch MCU to active power mode.
+ */
 void lpm_end_awake(void);
 
 /**
@@ -50,5 +60,5 @@ void lpm_end_awake(void);
  */
 enum lpm_mode lpm_get(void);
 
-#endif /* LPM_H_ */
+#endif /* __LPM_H_ */
 /** @} */

core/include/msg.h

@@ -11,13 +11,14 @@
  * @ingroup     core
  * @brief       Messaging API for inter process communication
  *
- * There are two ways to use the IPC Messaging system of RIOT. The default is synchronous
- * messaging. In this manner, messages are either dropped when the receiver is not waiting and the
- * message was sent non-blocking, or will be delivered immediately when the receiver calls
- * msg_receive(msg_t* m). To use asynchronous messaging any thread can create its own queue by
- * calling msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non full message
- * queue are never dropped and the sending never blocks. Threads with a full message queue behaves
- * like in synchronous mode.
+ * There are two ways to use the IPC Messaging system of RIOT. The default is
+ * synchronous messaging. In this manner, messages are either dropped when the
+ * receiver is not waiting and the message was sent non-blocking, or will be
+ * delivered immediately when the receiver calls msg_receive(msg_t* m). To use
+ * asynchronous messaging any thread can create its own queue by calling
+ * msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non
+ * full message queue are never dropped * and the sending never blocks. Threads
+ * with a full message queue behaves like in synchronous mode.
  *
  * @{
  *
@@ -29,16 +30,12 @@
  * @author      Kévin Roussel <Kevin.Roussel@inria.fr>
  */
 
-#ifndef __MSG_H
-#define __MSG_H
+#ifndef __MSG_H_
+#define __MSG_H_
 
 #include <stdint.h>
 #include <stdbool.h>
 
-#define MESSAGE_SENT 1
-#define MESSAGE_PROCESS_NOT_WAITING 0
-#define MESSAGE_PROCESS_UNKNOWN 2
-
 /**
  * @brief Describes a message object which can be sent between threads.
  *
@@ -48,31 +45,35 @@
  *
  */
 typedef struct msg {
-    uint16_t     sender_pid;    ///< PID of sending thread. Will be filled in by msg_send
-    uint16_t     type;          ///< Type field.
+    uint16_t     sender_pid;    /**< PID of sending thread. Will be filled in
+                                     by msg_send. */
+    uint16_t     type;          /**< Type field. */
     union {
-        char     *ptr;          ///< pointer content field
-        uint32_t value;         ///< value content field
-    } content;
+        char     *ptr;          /**< Pointer content field. */
+        uint32_t value;         /**< Value content field. */
+    } content;                  /**< Content of the message. */
 } msg_t;
 
 
 /**
  * @brief Send a message.
  *
- * This function sends a message to another thread.
- * The msg structure has to be allocated (e.g. on the stack)
- * before calling the function and can be freed afterwards.
- * If called from an interrupt, this function will never block.
- *
- * @param  m Pointer to message structure
- * @param  target_pid PID of target thread
- * @param  block If true and receiver is not receive-blocked, function will block. If not, function
- * returns.
- *
- * @return 1 if sending was successful (message delivered directly or to a queue)
- * @return 0 if receiver is not waiting or has a full message queue and block == false
- * @return -1 on error (invalid PID)
+ * This function sends a message to another thread. The ``msg_t`` structure has
+ * to be allocated (e.g. on the stack) before calling the function and can be
+ * freed afterwards. If called from an interrupt, this function will never
+ * block.
+ *
+ * @param[in] m             Pointer to preallocated ``msg_t`` structure, must
+ *                          not be NULL.
+ * @param[in] target_pid    PID of target thread
+ * @param[in] block         If not 0 and receiver is not receive-blocked,
+ *                          function will block. If not, function returns.
+ *
+ * @return 1, if sending was successful (message delivered directly or to a
+ *         queue)
+ * @return 0, if receiver is not waiting or has a full message queue and
+ *         ``block == 0``
+ * @return -1, on error (invalid PID)
  */
 int msg_send(msg_t *m, unsigned int target_pid, bool block);
 
@@ -95,13 +96,15 @@ int msg_send_to_self(msg_t *m);
 /**
  * @brief Send message from interrupt.
  *
- * Will be automatically chosen instead of msg_send if inISR() == true
+ * Will be automatically chosen instead of ``msg_sennd()`` if called from an
+ * interrupt/ISR.
  *
- * @param  m pointer to message structure
- * @param  target_pid PID of target thread
+ * @param[in] m             Pointer to preallocated ``msg_t`` structure, must
+ *                          not be NULL.
+ * @param[in] target_pid    PID of target thread.
  *
- * @return 1 if sending was successful
- * @return 0 if receiver is not waiting and block == false
+ * @return 1, if sending was successful
+ * @return 0, if receiver is not waiting and ``block == 0``
  */
 int msg_send_int(msg_t *m, unsigned int target_pid);
 
@@ -110,9 +113,11 @@ int msg_send_int(msg_t *m, unsigned int target_pid);
  * @brief Receive a message.
  *
  * This function blocks until a message was received.
- * @param m pointer to preallocated msg
  *
- * @return 1 Function always succeeds or blocks forever.
+ * @param[out] m    Pointer to preallocated ``msg_t`` structure, must not be
+ *                  NULL.
+ *
+ * @return  1, Function always succeeds or blocks forever.
  */
 int msg_receive(msg_t *m);
 
@@ -120,21 +125,30 @@ int msg_receive(msg_t *m);
  * @brief Try to receive a message.
  *
  * This function does not block if no message can be received.
- * @param m pointer to preallocated msg
  *
- * @return 1 if a message was received, -1 otherwise.
+ * @param[out] m    Pointer to preallocated ``msg_t`` structure, must not be
+ *                  NULL.
+ *
+ * @return  1, if a message was received
+ * @return  -1, otherwise.
  */
 int msg_try_receive(msg_t *m);
 
 /**
  * @brief Send a message, block until reply received.
  *
- * This function sends a message to target_pid and then blocks until target has sent a reply.
- * @note CAUTION!Use this function only when receiver is already waiting. If not use simple msg_send()
- * @param m pointer to preallocated msg
- * @param reply pointer to preallocated msg. Reply will be written here.
- * @param target pid the pid of the target process
- * @return 1 if successful
+ * This function sends a message to *target_pid* and then blocks until target
+ * has sent a reply which is then stored in *reply*.
+ *
+ * @note    CAUTION! Use this function only when receiver is already waiting.
+ *          If not use simple msg_send()
+ * @param[in] m             Pointer to preallocated ``msg_t`` structure with
+ *                          the message to send, must not be NULL.
+ * @param[out] reply        Pointer to preallocated msg. Reply will be written
+ *                          here, must not be NULL.
+ * @param[in] target_pid    The PID of the target process
+ *
+ * @return  1, if successful.
  */
 int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid);
 
@@ -143,24 +157,27 @@ int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid);
  *
  * Sender must have sent the message with msg_send_receive().
  *
- * @param m msg to reply to.
- * @param reply message that target will get as reply
+ * @param[in] m         message to reply to, must not be NULL.
+ * @param[out] reply    message that target will get as reply, must not be
+ *                      NULL.
  *
- * @return 1 if successful
- * @return 0 on error
+ * @return 1, if successful
+ * @return 0, on error
  */
 int msg_reply(msg_t *m, msg_t *reply);
 
 /**
  * @brief Initialize the current thread's message queue.
  *
- * @param array Pointer to preallocated array of msg objects
- * @param num Number of msg objects in array. MUST BE POWER OF TWO!
+ * @param[in] array Pointer to preallocated array of ``msg_t`` structures, must
+ *                  not be NULL.
+ * @param[in] num   Number of ``msg_t`` structurs in array.
+ *                  **MUST BE POWER OF TWO!**
  *
- * @return 0 if successful
- * @return -1 on error
+ * @return 0, if successful
+ * @return -1, on error
  */
 int msg_init_queue(msg_t *array, int num);
 
+#endif /* __MSG_H_ */
 /** @} */
-#endif /* __MSG_H */

core/include/mutex.h

@@ -19,24 +19,36 @@
  * @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.
- * @return Always returns 1, always succeeds.
+ * @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();
 }