Reformatted doxygen tags into the kernel sources to make them more readable.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1567 35acf78f-673a-0410-8e92-d51de3d6d3f4
author: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4> 2010-02-06 10:55:53 +0000
committer: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4> 2010-02-06 10:55:53 +0000
commit: f17db1931e95f5ebb42f557b6eead2bf1320db5a (patch)
tree: 0676532b6f3231f6c7343b3f644cdc5282433090 /os/kernel/src
parent: 6f7c30adff593e365515898082436f893f2ccb00 (diff)
download: ChibiOS-f17db1931e95f5ebb42f557b6eead2bf1320db5a.tar.gz
ChibiOS-f17db1931e95f5ebb42f557b6eead2bf1320db5a.tar.bz2
ChibiOS-f17db1931e95f5ebb42f557b6eead2bf1320db5a.zip
17 files changed, 787 insertions, 805 deletions
diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c
index 9e1a70cc4..21f3a22e2 100644
--- a/os/kernel/src/chcond.c
+++ b/os/kernel/src/chcond.c
@@ -22,8 +22,9 @@
  */
 
 /**
- * @file chcond.c
- * @brief Condition Variables code.
+ * @file    chcond.c
+ * @brief   Condition Variables code.
+ *
  * @addtogroup condvars Condition Variables
  * @{
  */
@@ -33,12 +34,12 @@
 #if CH_USE_CONDVARS && CH_USE_MUTEXES
 
 /**
- * @brief Initializes s @p CondVar structure.
+ * @brief   Initializes s @p CondVar structure.
+ * @note    This function can be invoked from within an interrupt handler even
+ *          if it is not an I-Class API because it does not touch any critical
+ *          kernel data structure.
  *
- * @param[out] cp pointer to a @p CondVar structure
- * @note This function can be invoked from within an interrupt handler even if
- *       it is not an I-Class API because it does not touch any critical kernel
- *       data structure.
+ * @param[out] cp       pointer to a @p CondVar structure
  */
 void chCondInit(CondVar *cp) {
 
@@ -48,37 +49,37 @@ void chCondInit(CondVar *cp) {
 }
 
 /**
- * @brief Signals one thread that is waiting on the condition variable.
+ * @brief   Signals one thread that is waiting on the condition variable.
  *
- * @param[in] cp pointer to the @p CondVar structure
+ * @param[in] cp        pointer to the @p CondVar structure
  */
 void chCondSignal(CondVar *cp) {
 
   chDbgCheck(cp != NULL, "chCondSignal");
 
   chSysLock();
-  if (notempty(&cp->c_queue))                           /* any thread ? */
+  if (notempty(&cp->c_queue))
     chSchWakeupS(fifo_remove(&cp->c_queue), RDY_OK);
   chSysUnlock();
 }
 
 /**
- * @brief Signals one thread that is waiting on the condition variable.
+ * @brief   Signals one thread that is waiting on the condition variable.
  *
- * @param[in] cp pointer to the @p CondVar structure
+ * @param[in] cp        pointer to the @p CondVar structure
  */
 void chCondSignalI(CondVar *cp) {
 
   chDbgCheck(cp != NULL, "chCondSignalI");
 
-  if (notempty(&cp->c_queue))                           /* any thread ? */
+  if (notempty(&cp->c_queue))
     chSchReadyI(fifo_remove(&cp->c_queue))->p_u.rdymsg = RDY_OK;
 }
 
 /**
- * @brief Signals all threads that are waiting on the condition variable.
+ * @brief   Signals all threads that are waiting on the condition variable.
  *
- * @param[in] cp pointer to the @p CondVar structure
+ * @param[in] cp        pointer to the @p CondVar structure
  */
 void chCondBroadcast(CondVar *cp) {
 
@@ -89,32 +90,32 @@ void chCondBroadcast(CondVar *cp) {
 }
 
 /**
- * @brief Signals all threads that are waiting on the condition variable.
+ * @brief   Signals all threads that are waiting on the condition variable.
  *
- * @param[in] cp pointer to the @p CondVar structure
+ * @param[in] cp        pointer to the @p CondVar structure
  */
 void chCondBroadcastI(CondVar *cp) {
 
   chDbgCheck(cp != NULL, "chCondBroadcastI");
 
   /* Empties the condition variable queue and inserts all the Threads into the
-   * ready list in FIFO order. The wakeup message is set to @p RDY_RESET in
-   * order to make a chCondBroadcast() detectable from a chCondSignal().*/
+     ready list in FIFO order. The wakeup message is set to @p RDY_RESET in
+     order to make a chCondBroadcast() detectable from a chCondSignal().*/
   while (cp->c_queue.p_next != (void *)&cp->c_queue)
     chSchReadyI(fifo_remove(&cp->c_queue))->p_u.rdymsg = RDY_RESET;
 }
 
 /**
- * @brief Waits on the condition variable releasing the mutex lock.
+ * @brief   Waits on the condition variable releasing the mutex lock.
  * @details Releases the mutex, waits on the condition variable, and finally
  *          acquires the mutex again. This is done atomically.
+ * @note    The thread MUST already have locked the mutex when calling
+ *          @p chCondWait().
  *
- * @param[in] cp pointer to the @p CondVar structure
- * @return The wakep mode.
- * @retval RDY_OK if the condvar was signaled using chCondSignal().
- * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
- * @note  The thread MUST already have locked the mutex when calling
- *        @p chCondWait().
+ * @param[in] cp        pointer to the @p CondVar structure
+ * @return              The wakep mode.
+ * @retval RDY_OK       if the condvar was signaled using @p chCondSignal().
+ * @retval RDY_RESET    if the condvar was signaled using @p chCondBroadcast().
  */
 msg_t chCondWait(CondVar *cp) {
   msg_t msg;
@@ -126,16 +127,16 @@ msg_t chCondWait(CondVar *cp) {
 }
 
 /**
- * @brief Waits on the condition variable releasing the mutex lock.
+ * @brief   Waits on the condition variable releasing the mutex lock.
  * @details Releases the mutex, waits on the condition variable, and finally
  *          acquires the mutex again. This is done atomically.
+ * @note    The thread MUST already have locked the mutex when calling
+ *          @p chCondWaitS().
  *
- * @param[in] cp pointer to the @p CondVar structure
- * @return The wakep mode.
- * @retval RDY_OK if the condvar was signaled using chCondSignal().
- * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
- * @note  The thread MUST already have locked the mutex when calling
- *        @p chCondWaitS().
+ * @param[in] cp        pointer to the @p CondVar structure
+ * @return              The wakep mode.
+ * @retval RDY_OK       if the condvar was signaled using @p chCondSignal().
+ * @retval RDY_RESET    if the condvar was signaled using @p chCondBroadcast().
  */
 msg_t chCondWaitS(CondVar *cp) {
   Thread *ctp = currp;
@@ -158,23 +159,23 @@ msg_t chCondWaitS(CondVar *cp) {
 
 #if CH_USE_CONDVARS_TIMEOUT
 /**
- * @brief Waits on the condition variable releasing the mutex lock.
+ * @brief   Waits on the condition variable releasing the mutex lock.
  * @details Releases the mutex, waits on the condition variable, and finally
  *          acquires the mutex again. This is done atomically.
+ * @note    The thread MUST already have locked the mutex when calling
+ *          @p chCondWaitTimeout().
  *
- * @param[in] cp pointer to the @p CondVar structure
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the special value @p TIME_INFINITE is allowed.
- *                 It is not possible to specify zero @p TIME_IMMEDIATE
- *                 as timeout specification because it would make no sense
- *                 in this function.
- * @return The wakep mode.
- * @retval RDY_OK if the condvar was signaled using chCondSignal().
- * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
- * @retval RDY_TIMEOUT if the condvar was not signaled within the specified
- *         timeout.
- * @note  The thread MUST already have locked the mutex when calling
- *        @p chCondWaitTimeout().
+ * @param[in] cp        pointer to the @p CondVar structure
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the special value @p TIME_INFINITE is allowed.
+ *                      It is not possible to specify zero @p TIME_IMMEDIATE
+ *                      as timeout specification because it would make no sense
+ *                      in this function.
+ * @return              The wakep mode.
+ * @retval RDY_OK       if the condvar was signaled using @p chCondSignal().
+ * @retval RDY_RESET    if the condvar was signaled using @p chCondBroadcast().
+ * @retval RDY_TIMEOUT  if the condvar was not signaled @p within the specified
+ *                      timeout.
  */
 msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
   msg_t msg;
@@ -186,23 +187,23 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
 }
 
 /**
- * @brief Waits on the condition variable releasing the mutex lock.
+ * @brief   Waits on the condition variable releasing the mutex lock.
  * @details Releases the mutex, waits on the condition variable, and finally
  *          acquires the mutex again. This is done atomically.
+ * @note    The thread MUST already have locked the mutex when calling
+ *          @p chCondWaitTimeoutS().
  *
- * @param[in] cp pointer to the @p CondVar structure
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the special value @p TIME_INFINITE is allowed.
- *                 It is not possible to specify zero @p TIME_IMMEDIATE
- *                 as timeout specification because it would make no sense
- *                 in this function.
- * @return The wakep mode.
- * @retval RDY_OK if the condvar was signaled using chCondSignal().
- * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().
- * @retval RDY_TIMEOUT if the condvar was not signaled within the specified
- *         timeout.
- * @note  The thread MUST already have locked the mutex when calling
- *        @p chCondWaitTimeoutS().
+ * @param[in] cp        pointer to the @p CondVar structure
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the special value @p TIME_INFINITE is allowed.
+ *                      It is not possible to specify zero @p TIME_IMMEDIATE
+ *                      as timeout specification because it would make no sense
+ *                      in this function.
+ * @return              The wakep mode.
+ * @retval RDY_OK       if the condvar was signaled using @p chCondSignal().
+ * @retval RDY_RESET    if the condvar was signaled using @p chCondBroadcast().
+ * @retval RDY_TIMEOUT  if the condvar was not signaled within the specified
+ *                      timeout.
  */
 msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
   Thread *ctp = currp;
diff --git a/os/kernel/src/chdebug.c b/os/kernel/src/chdebug.c
index 4868090b5..8a5b58744 100644
--- a/os/kernel/src/chdebug.c
+++ b/os/kernel/src/chdebug.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chdebug.c
- * @brief ChibiOS/RT Debug code.
+ * @file    chdebug.c
+ * @brief   ChibiOS/RT Debug code.
+ *
  * @addtogroup debug
  * @{
  */
@@ -28,12 +29,12 @@
 
 #if CH_DBG_ENABLE_TRACE
 /**
- * @brief Public trace buffer.
+ * @brief   Public trace buffer.
  */
 TraceBuffer trace_buffer;
 
 /**
- * @brief Trace circular buffer subsystem initialization.
+ * @brief   Trace circular buffer subsystem initialization.
  */
 void trace_init(void) {
 
@@ -42,10 +43,10 @@ void trace_init(void) {
 }
 
 /**
- * @brief Inserts in the circular debug trace buffer a context switch record.
+ * @brief   Inserts in the circular debug trace buffer a context switch record.
  *
- * @param[in] otp the thread being switched out
- * @param[in] ntp the thread to be switched in
+ * @param[in] otp       the thread being switched out
+ * @param[in] ntp       the thread to be switched in
  */
 void chDbgTrace(Thread *otp, Thread *ntp) {
 
@@ -60,7 +61,7 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
 
 #if CH_DBG_ENABLE_ASSERTS || CH_DBG_ENABLE_CHECKS || CH_DBG_ENABLE_STACK_CHECK
 /**
- * @brief Pointer to the panic message.
+ * @brief   Pointer to the panic message.
  * @details This pointer is meant to be accessed through the debugger, it is
  *          written once and then the system is halted. This variable can be
  *          set to @p NULL if the halt is caused by a stack overflow.
@@ -68,9 +69,9 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
 char *panic_msg;
 
 /**
- * @brief Prints a panic message on the console and then halts the system.
+ * @brief   Prints a panic message on the console and then halts the system.
  *
- * @param[in] msg the pointer to the panic message string
+ * @param[in] msg       the pointer to the panic message string
  */
 void chDbgPanic(char *msg) {
 
diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c
index 9da61adaf..310f04212 100644
--- a/os/kernel/src/chevents.c
+++ b/os/kernel/src/chevents.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chevents.c
- * @brief Events code.
+ * @file    chevents.c
+ * @brief   Events code.
+ *
  * @addtogroup events
  * @{
  */
@@ -27,15 +28,15 @@
 
 #if CH_USE_EVENTS
 /**
- * @brief Registers an Event Listener on an Event Source.
+ * @brief   Registers an Event Listener on an Event Source.
+ * @note    Multiple Event Listeners can specify the same bits to be pended.
  *
- * @param[in] esp pointer to the  @p EventSource structure
- * @param[in] elp pointer to the @p EventListener structure
- * @param[in] emask the mask of event flags to be pended to the thread when the
- *                  event source is broadcasted
- * @note Multiple Event Listeners can specify the same bits to be pended.
+ * @param[in] esp       pointer to the  @p EventSource structure
+ * @param[in] elp       pointer to the @p EventListener structure
+ * @param[in] mask      the mask of event flags to be pended to the thread when
+ *                      the event source is broadcasted
  */
-void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask) {
+void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {
 
   chDbgCheck((esp != NULL) && (elp != NULL), "chEvtRegisterMask");
 
@@ -43,20 +44,20 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask)
   elp->el_next = esp->es_next;
   esp->es_next = elp;
   elp->el_listener = currp;
-  elp->el_mask = emask;
+  elp->el_mask = mask;
   chSysUnlock();
 }
 
 /**
- * @brief Unregisters an Event Listener from its Event Source.
+ * @brief   Unregisters an Event Listener from its Event Source.
+ * @note    If the event listener is not registered on the specified event
+ *          source then the function does nothing.
+ * @note    For optimal performance it is better to perform the unregister
+ *          operations in inverse order of the register operations (elements
+ *          are found on top of the list).
  *
- * @param[in] esp pointer to the  @p EventSource structure
- * @param[in] elp pointer to the @p EventListener structure
- * @note If the event listener is not registered on the specified event source
- *       then the function does nothing.
- * @note For optimal performance it is better to perform the unregister
- *       operations in inverse order of the register operations (elements are
- *       found on top of the list).
+ * @param[in] esp       pointer to the  @p EventSource structure
+ * @param[in] elp       pointer to the @p EventListener structure
  */
 void chEvtUnregister(EventSource *esp, EventListener *elp) {
   EventListener *p;
@@ -76,10 +77,10 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) {
 }
 
 /**
- * @brief Clears the pending events specified in the mask.
+ * @brief   Clears the pending events specified in the mask.
  *
- * @param[in] mask the events to be cleared
- * @return The pending events that were cleared.
+ * @param[in] mask      the events to be cleared
+ * @return              The pending events that were cleared.
  */
 eventmask_t chEvtClear(eventmask_t mask) {
   eventmask_t m;
@@ -94,11 +95,11 @@ eventmask_t chEvtClear(eventmask_t mask) {
 }
 
 /**
- * @brief Pends a set of event flags on the current thread, this is @b much
- *        faster than using @p chEvtBroadcast() or @p chEvtSignal().
+ * @brief   Pends a set of event flags on the current thread, this is @b much
+ *          faster than using @p chEvtBroadcast() or @p chEvtSignal().
  *
- * @param[in] mask the events to be pended
- * @return The current pending events mask.
+ * @param[in] mask      the events to be pended
+ * @return              The current pending events mask.
  */
 eventmask_t chEvtPend(eventmask_t mask) {
 
@@ -111,10 +112,10 @@ eventmask_t chEvtPend(eventmask_t mask) {
 }
 
 /**
- * @brief Pends a set of event flags on the specified @p Thread.
+ * @brief   Pends a set of event flags on the specified @p Thread.
  *
- * @param[in] tp the thread to be signaled
- * @param[in] mask the event flags set to be pended
+ * @param[in] tp        the thread to be signaled
+ * @param[in] mask      the event flags set to be pended
  */
 void chEvtSignal(Thread *tp, eventmask_t mask) {
 
@@ -126,10 +127,10 @@ void chEvtSignal(Thread *tp, eventmask_t mask) {
 }
 
 /**
- * @brief Pends a set of event flags on the specified @p Thread.
+ * @brief   Pends a set of event flags on the specified @p Thread.
  *
- * @param[in] tp the thread to be signaled
- * @param[in] mask the event flags set to be pended
+ * @param[in] tp        the thread to be signaled
+ * @param[in] mask      the event flags set to be pended
  */
 void chEvtSignalI(Thread *tp, eventmask_t mask) {
 
@@ -145,10 +146,10 @@ void chEvtSignalI(Thread *tp, eventmask_t mask) {
 }
 
 /**
- * @brief Signals all the Event Listeners registered on the specified Event
- *        Source.
+ * @brief   Signals all the Event Listeners registered on the specified Event
+ *          Source.
  *
- * @param[in] esp pointer to the @p EventSource structure
+ * @param[in] esp       pointer to the @p EventSource structure
  */
 void chEvtBroadcast(EventSource *esp) {
 
@@ -159,10 +160,10 @@ void chEvtBroadcast(EventSource *esp) {
 }
 
 /**
- * @brief Signals all the Event Listeners registered on the specified Event
- *        Source.
+ * @brief   Signals all the Event Listeners registered on the specified Event
+ *          Source.
  *
- * @param[in] esp pointer to the @p EventSource structure
+ * @param[in] esp       pointer to the @p EventSource structure
  */
 void chEvtBroadcastI(EventSource *esp) {
   EventListener *elp;
@@ -177,11 +178,11 @@ void chEvtBroadcastI(EventSource *esp) {
 }
 
 /**
- * @brief Invokes the event handlers associated to an event flags mask.
+ * @brief   Invokes the event handlers associated to an event flags mask.
  *
- * @param[in] mask mask of the events to be dispatched
- * @param[in] handlers an array of @p evhandler_t. The array must have size
- *                     equal to the number of bits in eventmask_t.
+ * @param[in] mask      mask of the events to be dispatched
+ * @param[in] handlers  an array of @p evhandler_t. The array must have size
+ *                      equal to the number of bits in eventmask_t.
  */
 void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) {
   eventid_t eid;
@@ -203,29 +204,29 @@ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) {
 
 #if CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT || defined(__DOXYGEN__)
 /**
- * @brief Waits for exactly one of the specified events.
+ * @brief   Waits for exactly one of the specified events.
  * @details The function waits for one event among those specified in
- *          @p ewmask to become pending then the event is cleared and returned.
+ *          @p mask to become pending then the event is cleared and returned.
+ * @note    One and only one event is served in the function, the one with the
+ *          lowest event id. The function is meant to be invoked into a loop in
+ *          order to serve all the pending events.<br>
+ *          This means that Event Listeners with a lower event identifier have
+ *          an higher priority.
  *
- * @param[in] ewmask mask of the events that the function should wait for,
- *                   @p ALL_EVENTS enables all the events
- * @return The mask of the lowest id served and cleared event.
- * @note One and only one event is served in the function, the one with the
- *       lowest event id. The function is meant to be invoked into a loop in
- *       order to serve all the pending events.<br>
- *       This means that Event Listeners with a lower event identifier have
- *       an higher priority.
+ * @param[in] mask      mask of the events that the function should wait for,
+ *                      @p ALL_EVENTS enables all the events
+ * @return              The mask of the lowest id served and cleared event.
  */
-eventmask_t chEvtWaitOne(eventmask_t ewmask) {
+eventmask_t chEvtWaitOne(eventmask_t mask) {
   Thread *ctp = currp;
   eventmask_t m;
 
   chSysLock();
 
-  if ((m = (ctp->p_epending & ewmask)) == 0) {
-    ctp->p_u.ewmask = ewmask;
+  if ((m = (ctp->p_epending & mask)) == 0) {
+    ctp->p_u.ewmask = mask;
     chSchGoSleepS(THD_STATE_WTOREVT);
-    m = ctp->p_epending & ewmask;
+    m = ctp->p_epending & mask;
   }
   m &= -m;
   ctp->p_epending &= ~m;
@@ -235,24 +236,24 @@ eventmask_t chEvtWaitOne(eventmask_t ewmask) {
 }
 
 /**
- * @brief Waits for any of the specified events.
+ * @brief   Waits for any of the specified events.
  * @details The function waits for any event among those specified in
- *          @p ewmask to become pending then the events are cleared and returned.
+ *          @p mask to become pending then the events are cleared and returned.
  *
- * @param[in] ewmask mask of the events that the function should wait for,
- *                   @p ALL_EVENTS enables all the events
- * @return The mask of the served and cleared events.
+ * @param[in] mask      mask of the events that the function should wait for,
+ *                      @p ALL_EVENTS enables all the events
+ * @return              The mask of the served and cleared events.
  */
-eventmask_t chEvtWaitAny(eventmask_t ewmask) {
+eventmask_t chEvtWaitAny(eventmask_t mask) {
   Thread *ctp = currp;
   eventmask_t m;
 
   chSysLock();
 
-  if ((m = (ctp->p_epending & ewmask)) == 0) {
-    ctp->p_u.ewmask = ewmask;
+  if ((m = (ctp->p_epending & mask)) == 0) {
+    ctp->p_u.ewmask = mask;
     chSchGoSleepS(THD_STATE_WTOREVT);
-    m = ctp->p_epending & ewmask;
+    m = ctp->p_epending & mask;
   }
   ctp->p_epending &= ~m;
 
@@ -261,63 +262,63 @@ eventmask_t chEvtWaitAny(eventmask_t ewmask) {
 }
 
 /**
- * @brief Waits for all the specified events.
- * @details The function waits for all the events specified in @p ewmask to
+ * @brief   Waits for all the specified events.
+ * @details The function waits for all the events specified in @p mask to
  *          become pending then the events are cleared and returned.
  *
- * @param[in] ewmask mask of the event ids that the function should wait for
- * @return The mask of the served and cleared events.
+ * @param[in] mask      mask of the event ids that the function should wait for
+ * @return              The mask of the served and cleared events.
  */
-eventmask_t chEvtWaitAll(eventmask_t ewmask) {
+eventmask_t chEvtWaitAll(eventmask_t mask) {
   Thread *ctp = currp;
 
   chSysLock();
 
-  if ((ctp->p_epending & ewmask) != ewmask) {
-    ctp->p_u.ewmask = ewmask;
+  if ((ctp->p_epending & mask) != mask) {
+    ctp->p_u.ewmask = mask;
     chSchGoSleepS(THD_STATE_WTANDEVT);
   }
-  ctp->p_epending &= ~ewmask;
+  ctp->p_epending &= ~mask;
 
   chSysUnlock();
-  return ewmask;
+  return mask;
 }
 #endif /* CH_OPTIMIZE_SPEED || !CH_USE_EVENTS_TIMEOUT */
 
 #if CH_USE_EVENTS_TIMEOUT
 /**
- * @brief Waits for exactly one of the specified events.
+ * @brief   Waits for exactly one of the specified events.
  * @details The function waits for one event among those specified in
- *          @p ewmask to become pending then the event is cleared and returned.
+ *          @p mask to become pending then the event is cleared and returned.
+ * @note    One and only one event is served in the function, the one with the
+ *          lowest event id. The function is meant to be invoked into a loop in
+ *          order to serve all the pending events.<br>
+ *          This means that Event Listeners with a lower event identifier have
+ *          an higher priority.
  *
- * @param[in] ewmask mask of the events that the function should wait for,
- *                   @p ALL_EVENTS enables all the events
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The mask of the lowest id served and cleared event.
- * @retval 0 if the specified timeout expired.
- * @note One and only one event is served in the function, the one with the
- *       lowest event id. The function is meant to be invoked into a loop in
- *       order to serve all the pending events.<br>
- *       This means that Event Listeners with a lower event identifier have
- *       an higher priority.
+ * @param[in] mask      mask of the events that the function should wait for,
+ *                      @p ALL_EVENTS enables all the events
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The mask of the lowest id served and cleared event.
+ * @retval 0            if the specified timeout expired.
  */
-eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
+eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {
   Thread *ctp = currp;
   eventmask_t m;
 
   chSysLock();
 
-  if ((m = (ctp->p_epending & ewmask)) == 0) {
+  if ((m = (ctp->p_epending & mask)) == 0) {
     if (TIME_IMMEDIATE == time)
       return (eventmask_t)0;
-    ctp->p_u.ewmask = ewmask;
+    ctp->p_u.ewmask = mask;
     if (chSchGoSleepTimeoutS(THD_STATE_WTOREVT, time) < RDY_OK)
       return (eventmask_t)0;
-    m = ctp->p_epending & ewmask;
+    m = ctp->p_epending & mask;
   }
   m &= -m;
   ctp->p_epending &= ~m;
@@ -327,34 +328,34 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
 }
 
 /**
- * @brief Waits for any of the specified events.
+ * @brief   Waits for any of the specified events.
  * @details The function waits for any event among those specified in
- *          @p ewmask to become pending then the events are cleared and
+ *          @p mask to become pending then the events are cleared and
  *          returned.
  *
- * @param[in] ewmask mask of the events that the function should wait for,
- *                   @p ALL_EVENTS enables all the events
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The mask of the served and cleared events.
- * @retval 0 if the specified timeout expired.
+ * @param[in] mask      mask of the events that the function should wait for,
+ *                      @p ALL_EVENTS enables all the events
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The mask of the served and cleared events.
+ * @retval 0            if the specified timeout expired.
  */
-eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
+eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {
   Thread *ctp = currp;
   eventmask_t m;
 
   chSysLock();
 
-  if ((m = (ctp->p_epending & ewmask)) == 0) {
+  if ((m = (ctp->p_epending & mask)) == 0) {
     if (TIME_IMMEDIATE == time)
       return (eventmask_t)0;
-    ctp->p_u.ewmask = ewmask;
+    ctp->p_u.ewmask = mask;
     if (chSchGoSleepTimeoutS(THD_STATE_WTOREVT, time) < RDY_OK)
       return (eventmask_t)0;
-    m = ctp->p_epending & ewmask;
+    m = ctp->p_epending & mask;
   }
   ctp->p_epending &= ~m;
 
@@ -363,35 +364,35 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
 }
 
 /**
- * @brief Waits for all the specified events.
- * @details The function waits for all the events specified in @p ewmask to
+ * @brief   Waits for all the specified events.
+ * @details The function waits for all the events specified in @p mask to
  *          become pending then the events are cleared and returned.
  *
- * @param[in] ewmask mask of the event ids that the function should wait for
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The mask of the served and cleared events.
- * @retval 0 if the specified timeout expired.
+ * @param[in] mask      mask of the event ids that the function should wait for
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The mask of the served and cleared events.
+ * @retval 0            if the specified timeout expired.
  */
-eventmask_t chEvtWaitAllTimeout(eventmask_t ewmask, systime_t time) {
+eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time) {
   Thread *ctp = currp;
 
   chSysLock();
 
-  if ((ctp->p_epending & ewmask) != ewmask) {
+  if ((ctp->p_epending & mask) != mask) {
     if (TIME_IMMEDIATE == time)
       return (eventmask_t)0;
-    ctp->p_u.ewmask = ewmask;
+    ctp->p_u.ewmask = mask;
     if (chSchGoSleepTimeoutS(THD_STATE_WTANDEVT, time) < RDY_OK)
       return (eventmask_t)0;
   }
-  ctp->p_epending &= ~ewmask;
+  ctp->p_epending &= ~mask;
 
   chSysUnlock();
-  return ewmask;
+  return mask;
 }
 #endif /* CH_USE_EVENTS_TIMEOUT */
 
diff --git a/os/kernel/src/chheap.c b/os/kernel/src/chheap.c
index e434fd2ab..45431d5f4 100644
--- a/os/kernel/src/chheap.c
+++ b/os/kernel/src/chheap.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chheap.c
- * @brief Heaps code.
+ * @file    chheap.c
+ * @brief   Heaps code.
+ *
  * @addtogroup heaps
  * @{
  */
@@ -42,14 +43,13 @@
 #if !CH_USE_MALLOC_HEAP
 
 /**
- * @brief Default heap descriptor.
+ * @brief   Default heap descriptor.
  */
 static MemoryHeap default_heap;
 
 /**
- * @brief Initializes the default heap.
- *
- * @note Internal use only.
+ * @brief   Initializes the default heap.
+ * @note    Internal use only.
  */
 void heap_init(void) {
   default_heap.h_provider = chCoreAlloc;
@@ -63,14 +63,13 @@ void heap_init(void) {
 }
 
 /**
- * @brief Initializes a memory heap from a static memory area.
- *
- * @param[out] heapp pointer to a memory heap descriptor to be initialized
- * @param[in] buf heap buffer base
- * @param[in] size heap size
+ * @brief   Initializes a memory heap from a static memory area.
+ * @note    Both the heap buffer base and the heap size must be aligned to
+ *          the @p align_t type size.
  *
- * @note Both the heap buffer base and the heap size must be aligned to
- *       the @p align_t type size.
+ * @param[out] heapp    pointer to the memory heap descriptor to be initialized
+ * @param[in] buf       heap buffer base
+ * @param[in] size      heap size
  */
 void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
   struct heap_header *hp;
@@ -90,18 +89,18 @@ void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
 }
 
 /**
- * @brief Allocates a block of memory from the heap by using the first-fit
- *        algorithm.
+ * @brief   Allocates a block of memory from the heap by using the first-fit
+ *          algorithm.
  * @details The allocated block is guaranteed to be properly aligned for a
  *          pointer data type (@p align_t).
  *
- * @param[in] heapp pointer to a heap descriptor or @p NULL in order to access
- *                  the default heap.
- * @param[in] size the size of the block to be allocated. Note that the
- *                 allocated block may be a bit bigger than the requested
- *                 size for alignment and fragmentation reasons.
- * @return A pointer to the allocated block.
- * @retval NULL if the block cannot be allocated.
+ * @param[in] heapp     pointer to a heap descriptor or @p NULL in order to
+ *                      access the default heap.
+ * @param[in] size      the size of the block to be allocated. Note that the
+ *                      allocated block may be a bit bigger than the requested
+ *                      size for alignment and fragmentation reasons.
+ * @return              A pointer to the allocated block.
+ * @retval NULL         if the block cannot be allocated.
  */
 void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
   struct heap_header *qp, *hp, *fp;
@@ -117,17 +116,13 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
     hp = qp->h_u.next;
     if (hp->h_size >= size) {
       if (hp->h_size < size + sizeof(struct heap_header)) {
-        /*
-         * Gets the whole block even if it is slightly bigger than the
-         * requested size because the fragment would be too small to be
-         * useful.
-         */
+        /* Gets the whole block even if it is slightly bigger than the
+           requested size because the fragment would be too small to be
+           useful.*/
         qp->h_u.next = hp->h_u.next;
       }
       else {
-        /*
-         * Block bigger enough, must split it.
-         */
+        /* Block bigger enough, must split it.*/
         fp = (void *)((uint8_t *)(hp) + sizeof(struct heap_header) + size);
         fp->h_u.next = hp->h_u.next;
         fp->h_size = hp->h_size - sizeof(struct heap_header) - size;
@@ -144,9 +139,8 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
 
   H_UNLOCK(heapp);
 
-  /*
-   * More memory is required, tries to get it from the associated provider.
-   */
+  /* More memory is required, tries to get it from the associated provider
+     else fails.*/
   if (heapp->h_provider) {
     hp = heapp->h_provider(size + sizeof(struct heap_header));
     if (hp != NULL) {
@@ -164,9 +158,9 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
                                         (p)->h_size)
 
 /**
- * @brief Frees a previously allocated memory block.
+ * @brief   Frees a previously allocated memory block.
  *
- * @param[in] p the memory block pointer
+ * @param[in] p         pointer to the memory block to be freed
  */
 void chHeapFree(void *p) {
   struct heap_header *qp, *hp;
@@ -186,25 +180,17 @@ void chHeapFree(void *p) {
 
     if (((qp == &heapp->h_free) || (hp > qp)) &&
         ((qp->h_u.next == NULL) || (hp < qp->h_u.next))) {
-      /*
-       * Insertion after qp.
-       */
+      /* Insertion after qp.*/
       hp->h_u.next = qp->h_u.next;
       qp->h_u.next = hp;
-      /*
-       * Verifies if the newly inserted block should be merged.
-       */
+      /* Verifies if the newly inserted block should be merged.*/
       if (LIMIT(hp) == hp->h_u.next) {
-        /*
-         * Merge with the next block.
-         */
+        /* Merge with the next block.*/
         hp->h_size += hp->h_u.next->h_size + sizeof(struct heap_header);
         hp->h_u.next = hp->h_u.next->h_u.next;
       }
       if ((LIMIT(qp) == hp)) {
-        /*
-         * Merge with the previous block.
-         */
+        /* Merge with the previous block.*/
         qp->h_size += hp->h_size + sizeof(struct heap_header);
         qp->h_u.next = hp->h_u.next;
       }
@@ -218,17 +204,17 @@ void chHeapFree(void *p) {
 }
 
 /**
- * @brief Reports the heap status.
+ * @brief   Reports the heap status.
+ * @note    This function is meant to be used in the test suite, it should
+ *          not be really useful for the application code.
+ * @note    This function is not implemented when the @p CH_USE_MALLOC_HEAP
+ *          configuration option is used (it always returns zero).
  *
- * @param[in] heapp pointer to a heap descriptor or @p NULL in order to access
- *                  the default heap.
- * @param[in] sizep pointer to a variable that will receive the total
- *                  fragmented free space
- * @return The number of fragments in the heap.
- * @note This function is meant to be used in the test suite, it should not be
- *       really useful for the application code.
- * @note This function is not implemented when the @p CH_USE_MALLOC_HEAP
- *       configuration option is used (it always returns zero).
+ * @param[in] heapp     pointer to a heap descriptor or @p NULL in order to
+ *                      access the default heap.
+ * @param[in] sizep     pointer to a variable that will receive the total
+ *                      fragmented free space
+ * @return              The number of fragments in the heap.
  */
 size_t chHeapStatus(MemoryHeap *heapp, size_t *sizep) {
   struct heap_header *qp;
diff --git a/os/kernel/src/chlists.c b/os/kernel/src/chlists.c
index 53f91649a..2aeb55ecb 100644
--- a/os/kernel/src/chlists.c
+++ b/os/kernel/src/chlists.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chlists.c
- * @brief Thread queues/lists code.
+ * @file    chlists.c
+ * @brief   Thread queues/lists code.
+ *
  * @addtogroup internals
  * @{
  */
@@ -27,35 +28,35 @@
 
 #if !CH_OPTIMIZE_SPEED || defined(__DOXYGEN__)
 /**
- * @brief Inserts a thread into a priority ordered queue.
- * @note The insertion is done by scanning the list from the highest priority
- *       toward the lowest.
- * @note This function is @b not an API.
+ * @brief   Inserts a thread into a priority ordered queue.
+ * @note    The insertion is done by scanning the list from the highest priority
+ *          toward the lowest.
+ * @note    This function is @b not an API.
  *
- * @param[in] tp the pointer to the thread to be inserted in the list
- * @param[in] tqp the pointer to the threads list header
+ * @param[in] tp        the pointer to the thread to be inserted in the list
+ * @param[in] tqp       the pointer to the threads list header
  */
 void prio_insert(Thread *tp, ThreadsQueue *tqp) {
 
-  /* cp iterates over the queue */
+  /* cp iterates over the queue.*/
   Thread *cp = (Thread *)tqp;
   do {
-    /* iterate to next thread in queue */
+    /* Iterate to next thread in queue.*/
     cp = cp->p_next;
-    /* not end of queue? and cp has equal or higher priority than tp? */
+    /* Not end of queue? and cp has equal or higher priority than tp?.*/
   } while ((cp != (Thread *)tqp) && (cp->p_prio >= tp->p_prio));
-  /* insert before cp, point tp to next and prev in queue */
+  /* Insert before cp, point tp to next and prev in queue.*/
   tp->p_prev = (tp->p_next = cp)->p_prev;
-  /* make prev point to tp, and cp point back to tp */
+  /* Make prev point to tp, and cp point back to tp.*/
   tp->p_prev->p_next = cp->p_prev = tp;
 }
 
 /**
- * @brief Inserts a Thread into a queue.
- * @note This function is @b not an API.
+ * @brief   Inserts a Thread into a queue.
+ * @note    This function is @b not an API.
  *
- * @param[in] tp the pointer to the thread to be inserted in the list
- * @param[in] tqp the pointer to the threads list header
+ * @param[in] tp        the pointer to the thread to be inserted in the list
+ * @param[in] tqp       the pointer to the threads list header
  */
 void queue_insert(Thread *tp, ThreadsQueue *tqp) {
 
@@ -64,13 +65,13 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
 }
 
 /**
- * @brief Removes the first-out Thread from a queue and returns it.
- * @note If the queue is priority ordered then this function returns the
- *       thread with the highest priority.
- * @note This function is @b not an API.
+ * @brief   Removes the first-out Thread from a queue and returns it.
+ * @note    If the queue is priority ordered then this function returns the
+ *          thread with the highest priority.
+ * @note    This function is @b not an API.
  *
- * @param[in] tqp the pointer to the threads list header
- * @return The removed thread pointer.
+ * @param[in] tqp       the pointer to the threads list header
+ * @return              The removed thread pointer.
  */
 Thread *fifo_remove(ThreadsQueue *tqp) {
   Thread *tp = tqp->p_next;
@@ -80,13 +81,13 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
 }
 
 /**
- * @brief Removes the last-out Thread from a queue and returns it.
- * @note If the queue is priority ordered then this function returns the
- *       thread with the lowest priority.
- * @note This function is @b not an API.
+ * @brief   Removes the last-out Thread from a queue and returns it.
+ * @note    If the queue is priority ordered then this function returns the
+ *          thread with the lowest priority.
+ * @note    This function is @b not an API.
  *
- * @param[in] tqp the pointer to the threads list header
- * @return The removed thread pointer.
+ * @param[in] tqp   the pointer to the threads list header
+ * @return          The removed thread pointer.
  */
 Thread *lifo_remove(ThreadsQueue *tqp) {
   Thread *tp = tqp->p_prev;
@@ -96,13 +97,13 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
 }
 
 /**
- * @brief Removes a Thread from a queue and returns it.
+ * @brief   Removes a Thread from a queue and returns it.
  * @details The thread is removed from the queue regardless of its relative
  *          position and regardless the used insertion method.
- * @note This function is @b not an API.
+ * @note    This function is @b not an API.
  *
- * @param[in] tp the pointer to the thread to be removed from the queue
- * @return The removed thread pointer.
+ * @param[in] tp        the pointer to the thread to be removed from the queue
+ * @return              The removed thread pointer.
  */
 Thread *dequeue(Thread *tp) {
 
@@ -112,11 +113,11 @@ Thread *dequeue(Thread *tp) {
 }
 
 /**
- * @brief Pushes a Thread on top of a stack list.
- * @note This function is @b not an API.
+ * @brief   Pushes a Thread on top of a stack list.
+ * @note    This function is @b not an API.
  *
- * @param[in] tp the pointer to the thread to be inserted in the list
- * @param[in] tlp the pointer to the threads list header
+ * @param[in] tp    the pointer to the thread to be inserted in the list
+ * @param[in] tlp   the pointer to the threads list header
  */
 void list_insert(Thread *tp, ThreadsList *tlp) {
 
@@ -125,12 +126,12 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
 }
 
 /**
- * @brief Pops a Thread from the top of a stack list and returns it.
- * @note The list must be non-empty before calling this function.
- * @note This function is @b not an API.
+ * @brief   Pops a Thread from the top of a stack list and returns it.
+ * @note    The list must be non-empty before calling this function.
+ * @note    This function is @b not an API.
  *
- * @param[in] tlp the pointer to the threads list header
- * @return The removed thread pointer.
+ * @param[in] tlp       the pointer to the threads list header
+ * @return              The removed thread pointer.
  */
 Thread *list_remove(ThreadsList *tlp) {
 
diff --git a/os/kernel/src/chmboxes.c b/os/kernel/src/chmboxes.c
index 3bcf687fc..aee514f84 100644
--- a/os/kernel/src/chmboxes.c
+++ b/os/kernel/src/chmboxes.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chmboxes.c
- * @brief Mailboxes code.
+ * @file    chmboxes.c
+ * @brief   Mailboxes code.
+ *
  * @addtogroup mailboxes
  * @{
  */
@@ -28,11 +29,11 @@
 
 #if CH_USE_MAILBOXES
 /**
- * @brief Initializes a Mailbox object.
+ * @brief   Initializes a Mailbox object.
  *
- * @param[out] mbp the pointer to the Mailbox structure to be initialized
- * @param[in] buf the circular messages buffer
- * @param[in] n the buffer size as number of @p msg_t
+ * @param[out] mbp      the pointer to the Mailbox structure to be initialized
+ * @param[in] buf       the circular messages buffer
+ * @param[in] n         the buffer size as number of @p msg_t
  */
 void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
 
@@ -45,11 +46,11 @@ void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
 }
 
 /**
- * @brief Resets a Mailbox object.
+ * @brief   Resets a Mailbox object.
  * @details All the waiting threads are resumed with status @p RDY_RESET and
  *          the queued messages are lost.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
+ * @param[in] mbp       the pointer to an initialized Mailbox object
  */
 void chMBReset(Mailbox *mbp) {
 
@@ -64,21 +65,21 @@ void chMBReset(Mailbox *mbp) {
 }
 
 /**
- * @brief Posts a message into a mailbox.
+ * @brief   Posts a message into a mailbox.
  * @details The invoking thread waits until a empty slot in the mailbox becomes
  *          available or the specified time runs out.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
- * @param[in] msg the message to be posted on the mailbox
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The operation status.
- * @retval RDY_OK if the message was correctly posted.
- * @retval RDY_RESET if the mailbox was reset while waiting.
- * @retval RDY_TIMEOUT if the operation timed out.
+ * @param[in] mbp       the pointer to an initialized Mailbox object
+ * @param[in] msg       the message to be posted on the mailbox
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status.
+ * @retval RDY_OK       if the message was correctly posted.
+ * @retval RDY_RESET    if the mailbox was reset while waiting.
+ * @retval RDY_TIMEOUT  if the operation timed out.
  */
 msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
   msg_t rdymsg;
@@ -90,21 +91,21 @@ msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
 }
 
 /**
- * @brief Posts a message into a mailbox.
+ * @brief   Posts a message into a mailbox.
  * @details The invoking thread waits until a empty slot in the mailbox becomes
  *          available or the specified time runs out.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
- * @param[in] msg the message to be posted on the mailbox
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The operation status.
- * @retval RDY_OK if the message was correctly posted.
- * @retval RDY_RESET if the mailbox was reset while waiting.
- * @retval RDY_TIMEOUT if the operation timed out.
+ * @param[in] mbp       the pointer to an initialized Mailbox object
+ * @param[in] msg       the message to be posted on the mailbox
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status.
+ * @retval RDY_OK       if the message was correctly posted.
+ * @retval RDY_RESET    if the mailbox was reset while waiting.
+ * @retval RDY_TIMEOUT  if the operation timed out.
  */
 msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
   msg_t rdymsg;
@@ -123,21 +124,21 @@ msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
 }
 
 /**
- * @brief Posts an high priority message into a mailbox.
+ * @brief   Posts an high priority message into a mailbox.
  * @details The invoking thread waits until a empty slot in the mailbox becomes
  *          available or the specified time runs out.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
- * @param[in] msg the message to be posted on the mailbox
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The operation status.
- * @retval RDY_OK if the message was correctly posted.
- * @retval RDY_RESET if the mailbox was reset while waiting.
- * @retval RDY_TIMEOUT if the operation timed out.
+ * @param[in] mbp       the pointer to an initialized Mailbox object
+ * @param[in] msg       the message to be posted on the mailbox
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status.
+ * @retval RDY_OK       if the message was correctly posted.
+ * @retval RDY_RESET    if the mailbox was reset while waiting.
+ * @retval RDY_TIMEOUT  if the operation timed out.
  */
 msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
   msg_t rdymsg;
@@ -149,21 +150,21 @@ msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
 }
 
 /**
- * @brief Posts an high priority message into a mailbox.
+ * @brief   Posts an high priority message into a mailbox.
  * @details The invoking thread waits until a empty slot in the mailbox becomes
  *          available or the specified time runs out.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
- * @param[in] msg the message to be posted on the mailbox
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The operation status.
- * @retval RDY_OK if the message was correctly posted.
- * @retval RDY_RESET if the mailbox was reset while waiting.
- * @retval RDY_TIMEOUT if the operation timed out.
+ * @param[in] mbp       the pointer to an initialized Mailbox object
+ * @param[in] msg       the message to be posted on the mailbox
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status.
+ * @retval RDY_OK       if the message was correctly posted.
+ * @retval RDY_RESET    if the mailbox was reset while waiting.
+ * @retval RDY_TIMEOUT  if the operation timed out.
  */
 msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
   msg_t rdymsg;
@@ -182,21 +183,21 @@ msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
 }
 
 /**
- * @brief Retrieves a message from a mailbox.
+ * @brief   Retrieves a message from a mailbox.
  * @details The invoking thread waits until a message is posted in the mailbox
  *          or the specified time runs out.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
- * @param[out] msgp pointer to a message variable for the received message
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The operation status.
- * @retval RDY_OK if a message was correctly fetched.
- * @retval RDY_RESET if the mailbox was reset while waiting.
- * @retval RDY_TIMEOUT if the operation timed out.
+ * @param[in] mbp       the pointer to an initialized Mailbox object
+ * @param[out] msgp     pointer to a message variable for the received message
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status.
+ * @retval RDY_OK       if a message was correctly fetched.
+ * @retval RDY_RESET    if the mailbox was reset while waiting.
+ * @retval RDY_TIMEOUT  if the operation timed out.
  */
 msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
   msg_t rdymsg;
@@ -208,21 +209,21 @@ msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
 }
 
 /**
- * @brief Retrieves a message from a mailbox.
+ * @brief   Retrieves a message from a mailbox.
  * @details The invoking thread waits until a message is posted in the mailbox
  *          or the specified time runs out.
  *
- * @param[in] mbp the pointer to an initialized Mailbox object
- * @param[out] msgp pointer to a message variable for the received message
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @return The operation status.
- * @retval RDY_OK if a message was correctly fetched.
- * @retval RDY_RESET if the mailbox was reset while waiting.
- * @retval RDY_TIMEOUT if the operation timed out.
+ * @param[in] mbp       the pointer to an initialized Mailbox object
+ * @param[out] msgp     pointer to a message variable for the received message
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status.
+ * @retval RDY_OK       if a message was correctly fetched.
+ * @retval RDY_RESET    if the mailbox was reset while waiting.
+ * @retval RDY_TIMEOUT  if the operation timed out.
  */
 msg_t chMBFetchS(Mailbox *mbp, msg_t *msgp, systime_t time) {
   msg_t rdymsg;
diff --git a/os/kernel/src/chmemcore.c b/os/kernel/src/chmemcore.c
index 6cf42788b..8269deb48 100644
--- a/os/kernel/src/chmemcore.c
+++ b/os/kernel/src/chmemcore.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chmemcore.c
- * @brief Core memory manager code.
+ * @file    chmemcore.c
+ * @brief   Core memory manager code.
+ *
  * @addtogroup memcore
  * @{
  */
@@ -55,9 +56,9 @@ void core_init(void) {
  *          <code>sizeof(align_t)</code>.
  *
  *
- * @param[in] size  the size of the block to be allocated
- * @return  A pointer to the allocated memory block.
- * @retval  NULL allocation failed, core memory exhausted.
+ * @param[in] size      the size of the block to be allocated
+ * @return              A pointer to the allocated memory block.
+ * @retval NULL         allocation failed, core memory exhausted.
  */
 void *chCoreAlloc(size_t size) {
   void *p;
@@ -74,9 +75,9 @@ void *chCoreAlloc(size_t size) {
  *          type @p align_t so it is not possible to allocate less than
  *          <code>sizeof(align_t)</code>.
  *
- * @param[in] size  the size of the block to be allocated.
- * @return  A pointer to the allocated memory block.
- * @retval  NULL allocation failed, core memory exhausted.
+ * @param[in] size      the size of the block to be allocated.
+ * @return              A pointer to the allocated memory block.
+ * @retval NULL         allocation failed, core memory exhausted.
  */
 void *chCoreAllocI(size_t size) {
   void *p;
@@ -92,7 +93,7 @@ void *chCoreAllocI(size_t size) {
 /**
  * @brief   Core memory left.
  *
- * @return  The size, in bytes, of the free core memory.
+ * @return              The size, in bytes, of the free core memory.
  */
 size_t chCoreFree(void) {
 
diff --git a/os/kernel/src/chmempools.c b/os/kernel/src/chmempools.c
index 02bbcee45..1e827c128 100644
--- a/os/kernel/src/chmempools.c
+++ b/os/kernel/src/chmempools.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chmempools.c
- * @brief Memory Pools code.
+ * @file    chmempools.c
+ * @brief   Memory Pools code.
+ *
  * @addtogroup pools
  * @{
  */
@@ -28,16 +29,17 @@
 
 #if CH_USE_MEMPOOLS
 /**
- * @brief Initializes an empty memory pool.
- *
- * @param[out] mp pointer to a @p MemoryPool structure
- * @param[in] size the size of the objects contained in this memory pool,
- *                 the minimum accepted size is the size of a pointer to void.
- * @param[in] provider memory provider function for the memory pool or
- *                     @p NULL if the pool is not allowed to grow automatically
+ * @brief   Initializes an empty memory pool.
+ * @note    The size is internally aligned to be a multiple of the @p align_t
+ *          type size.
  *
- * @note The size is internally aligned to be a multiple of the @p align_t
- *       type size.
+ * @param[out] mp       pointer to a @p MemoryPool structure
+ * @param[in] size      the size of the objects contained in this memory pool,
+ *                      the minimum accepted size is the size of a pointer to
+ *                      void.
+ * @param[in] provider  memory provider function for the memory pool or
+ *                      @p NULL if the pool is not allowed to grow
+ *                      automatically
  */
 void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
 
@@ -49,11 +51,11 @@ void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
 }
 
 /**
- * @brief Allocates an object from a memory pool.
+ * @brief   Allocates an object from a memory pool.
  *
- * @param[in] mp pointer to a @p MemoryPool structure
- * @return The pointer to the allocated object.
- * @retval NULL if pool is empty.
+ * @param[in] mp        pointer to a @p MemoryPool structure
+ * @return              The pointer to the allocated object.
+ * @retval NULL         if pool is empty.
  */
 void *chPoolAllocI(MemoryPool *mp) {
   void *objp;
@@ -70,11 +72,11 @@ void *chPoolAllocI(MemoryPool *mp) {
 }
 
 /**
- * @brief Allocates an object from a memory pool.
+ * @brief   Allocates an object from a memory pool.
  *
- * @param[in] mp pointer to a @p MemoryPool structure
- * @return The pointer to the allocated object.
- * @retval NULL if pool is empty.
+ * @param[in] mp        pointer to a @p MemoryPool structure
+ * @return              The pointer to the allocated object.
+ * @retval NULL         if pool is empty.
  */
 void *chPoolAlloc(MemoryPool *mp) {
   void *objp;
@@ -86,15 +88,14 @@ void *chPoolAlloc(MemoryPool *mp) {
 }
 
 /**
- * @brief Releases (or adds) an object into (to) a memory pool.
- *
- * @param[in] mp pointer to a @p MemoryPool structure
- * @param[in] objp the pointer to the object to be released or added
+ * @brief   Releases (or adds) an object into (to) a memory pool.
+ * @note    The object is assumed to be of the right size for the specified
+ *          memory pool.
+ * @note    The object is assumed to be memory aligned to the size of @p align_t
+ *          type.
  *
- * @note The object is assumed to be of the right size for the specified
- *       memory pool.
- * @note The object is assumed to be memory aligned to the size of @p align_t
- *       type.
+ * @param[in] mp        pointer to a @p MemoryPool structure
+ * @param[in] objp      the pointer to the object to be released or added
  */
 void chPoolFreeI(MemoryPool *mp, void *objp) {
   struct pool_header *php = objp;
@@ -107,12 +108,12 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
 }
 
 /**
- * @brief Releases (or adds) an object into (to) a memory pool.
+ * @brief   Releases (or adds) an object into (to) a memory pool.
+ * @note    The object is assumed to be of the right size for the specified
+ *          memory pool.
  *
- * @param[in] mp pointer to a @p MemoryPool structure
- * @param[in] objp the pointer to the object to be released or added
- * @note the object is assumed to be of the right size for the specified
- *       memory pool.
+ * @param[in] mp        pointer to a @p MemoryPool structure
+ * @param[in] objp      the pointer to the object to be released or added
  */
 void chPoolFree(MemoryPool *mp, void *objp) {
 
diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c
index 6c0c6a81a..9b6afd950 100644
--- a/os/kernel/src/chmsg.c
+++ b/os/kernel/src/chmsg.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chmsg.c
- * @brief Messages code.
+ * @file    chmsg.c
+ * @brief   Messages code.
+ *
  * @addtogroup messages
  * @{
  */
@@ -35,13 +36,13 @@
 #endif
 
 /**
- * @brief Sends a message to the specified thread.
+ * @brief   Sends a message to the specified thread.
  * @details The sender is stopped until the receiver executes a
  *          @p chMsgRelease()after receiving the message.
  *
- * @param[in] tp the pointer to the thread
- * @param[in] msg the message
- * @return The return message from @p chMsgRelease().
+ * @param[in] tp        the pointer to the thread
+ * @param[in] msg       the message
+ * @return              The answer message from @p chMsgRelease().
  */
 msg_t chMsgSend(Thread *tp, msg_t msg) {
   Thread *ctp = currp;
@@ -61,13 +62,14 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
 }
 
 /**
- * @brief Suspends the thread and waits for an incoming message.
+ * @brief   Suspends the thread and waits for an incoming message.
+ * @note    You can assume that the data contained in the message is stable
+ *          until you invoke @p chMsgRelease() because the sending thread is
+ *          suspended until then.
  *
- * @return The pointer to the message structure. Note, it is always the
- *         message associated to the thread on the top of the messages queue.
- * @note You can assume that the data contained in the message is stable until
- *       you invoke @p chMsgRelease() because the sending thread is
- *       suspended until then.
+ * @return              The pointer to the message structure. Note, it is
+ *                      always the message associated to the thread on the
+ *                      top of the messages queue.
  */
 msg_t chMsgWait(void) {
   msg_t msg;
@@ -81,15 +83,17 @@ msg_t chMsgWait(void) {
 }
 
 /**
- * @brief Returns the next message in the queue.
+ * @brief   Returns the next message in the queue.
+ * @note    You can assume that the data pointed by the message is stable until
+ *          you invoke @p chMsgRelease() because the sending thread is
+ *          suspended until then. Always remember that the message data is not
+ *          copied between the sender and the receiver, just a pointer is
+ *          passed.
  *
- * @return The pointer to the message structure. Note, it is always the
- *         message associated to the thread on the top of the messages queue.
- *         If the queue is empty then @p NULL is returned.
- * @note You can assume that the data pointed by the message is stable until
- *       you invoke @p chMsgRelease() because the sending thread is
- *       suspended until then. Always remember that the message data is not
- *       copied between the sender and the receiver, just a pointer is passed.
+ * @return              The pointer to the message structure. Note, it is
+ *                      always the message associated to the thread on the
+ *                      top of the messages queue.
+ * @retval NULL         if the queue is empty.
  */
 msg_t chMsgGet(void) {
   msg_t msg;
@@ -101,15 +105,15 @@ msg_t chMsgGet(void) {
 }
 
 /**
- * @brief Releases the thread waiting on top of the messages queue.
+ * @brief   Releases the thread waiting on top of the messages queue.
+ * @note    You can call this function only if there is a message already in
+ *          the queue else the result will be unpredictable (a crash most likely).
+ *          Exiting from the @p chMsgWait() ensures you have at least one
+ *          message in the queue so it is not a big deal.<br>
+ *          The condition is only tested in debug mode in order to make this
+ *          code as fast as possible.
  *
- * @param[in] msg the message returned to the message sender
- * @note You can call this function only if there is a message already in the
- *       queue else the result will be unpredictable (a crash most likely).
- *       Exiting from the @p chMsgWait() ensures you have at least one
- *       message in the queue so it is not a big deal.<br>
- *       The condition is only tested in debug mode in order to make this code
- *       as fast as possible.
+ * @param[in] msg       the message returned to the message sender
  */
 void chMsgRelease(msg_t msg) {
 
diff --git a/os/kernel/src/chmtx.c b/os/kernel/src/chmtx.c
index 9d66022c2..d5335c0aa 100644
--- a/os/kernel/src/chmtx.c
+++ b/os/kernel/src/chmtx.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chmtx.c
- * @brief Mutexes code.
+ * @file    chmtx.c
+ * @brief   Mutexes code.
+ *
  * @addtogroup mutexes
  * @{
  */
@@ -29,12 +30,9 @@
 #if CH_USE_MUTEXES
 
 /**
- * @brief Initializes s @p Mutex structure.
+ * @brief   Initializes s @p Mutex structure.
  *
- * @param[out] mp pointer to a @p Mutex structure
- * @note This function can be invoked from within an interrupt handler even if
- *       it is not an I-Class API because it does not touch any critical kernel
- *       data structure.
+ * @param[out] mp       pointer to a @p Mutex structure
  */
 void chMtxInit(Mutex *mp) {
 
@@ -45,9 +43,9 @@ void chMtxInit(Mutex *mp) {
 }
 
 /**
- * @brief Locks the specified mutex.
+ * @brief   Locks the specified mutex.
  *
- * @param[in] mp pointer to the @p Mutex structure
+ * @param[in] mp        pointer to the @p Mutex structure
  */
 void chMtxLock(Mutex *mp) {
 
@@ -59,11 +57,9 @@ void chMtxLock(Mutex *mp) {
 }
 
 /**
- * @brief Locks the specified mutex.
+ * @brief   Locks the specified mutex.
  *
- * @param[in] mp pointer to the @p Mutex structure
- * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
- *       block.
+ * @param[in] mp        pointer to the @p Mutex structure
  */
 void chMtxLockS(Mutex *mp) {
   Thread *ctp = currp;
@@ -121,14 +117,14 @@ void chMtxLockS(Mutex *mp) {
 }
 
 /**
- * @brief Tries to lock a mutex.
+ * @brief   Tries to lock a mutex.
  * @details This function does not have any overhead related to
  *          the priority inheritance mechanism because it does not try to
  *          enter a sleep state on the mutex.
  *
- * @param[in] mp pointer to the @p Mutex structure
- * @retval TRUE if the mutex was successfully acquired
- * @retval FALSE if the lock attempt failed.
+ * @param[in] mp        pointer to the @p Mutex structure
+ * @retval TRUE         if the mutex was successfully acquired
+ * @retval FALSE        if the lock attempt failed.
  */
 bool_t chMtxTryLock(Mutex *mp) {
   bool_t b;
@@ -142,15 +138,14 @@ bool_t chMtxTryLock(Mutex *mp) {
 }
 
 /**
- * @brief Tries to lock a mutex.
+ * @brief   Tries to lock a mutex.
  * @details This function does not have any overhead related to
  *          the priority inheritance mechanism because it does not try to
  *          enter a sleep state on the mutex.
- * @param[in] mp pointer to the @p Mutex structure
- * @retval TRUE if the mutex was successfully acquired
- * @retval FALSE if the lock attempt failed.
- * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
- *       block.
+ *
+ * @param[in] mp        pointer to the @p Mutex structure
+ * @retval TRUE         if the mutex was successfully acquired
+ * @retval FALSE        if the lock attempt failed.
  */
 bool_t chMtxTryLockS(Mutex *mp) {
 
@@ -165,9 +160,9 @@ bool_t chMtxTryLockS(Mutex *mp) {
 }
 
 /**
- * @brief Unlocks the next owned mutex in reverse lock order.
+ * @brief   Unlocks the next owned mutex in reverse lock order.
  *
- * @return The pointer to the unlocked mutex.
+ * @return              The pointer to the unlocked mutex.
  */
 Mutex *chMtxUnlock(void) {
   Thread *ctp = currp;
@@ -210,12 +205,10 @@ Mutex *chMtxUnlock(void) {
 }
 
 /**
- * @brief Unlocks the next owned mutex in reverse lock order.
+ * @brief   Unlocks the next owned mutex in reverse lock order.
+ * @note    This function does not reschedule internally.
  *
- * @return The pointer to the unlocked mutex.
- * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
- *       block.
- * @note This function does not reschedule internally.
+ * @return              The pointer to the unlocked mutex.
  */
 Mutex *chMtxUnlockS(void) {
   Thread *ctp = currp;
@@ -254,7 +247,7 @@ Mutex *chMtxUnlockS(void) {
 }
 
 /**
- * @brief Unlocks all the mutexes owned by the invoking thread.
+ * @brief   Unlocks all the mutexes owned by the invoking thread.
  * @details This function is <b>MUCH MORE</b> efficient than releasing the
  *          mutexes one by one and not just because the call overhead,
  *          this function does not have any overhead related to the priority
diff --git a/os/kernel/src/chqueues.c b/os/kernel/src/chqueues.c
index 6a951f223..50f1f2401 100644
--- a/os/kernel/src/chqueues.c
+++ b/os/kernel/src/chqueues.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chqueues.c
- * @brief I/O Queues code.
+ * @file    chqueues.c
+ * @brief   I/O Queues code.
+ *
  * @addtogroup io_queues
  * @{
  */
@@ -29,18 +30,17 @@
 #if CH_USE_QUEUES
 
 /**
- * @brief Initializes an input queue.
+ * @brief   Initializes an input queue.
  * @details A Semaphore is internally initialized and works as a counter of
  *          the bytes contained in the queue.
+ * @note    The callback is invoked from within the S-Locked system state,
+ *          see @ref system_states.
  *
- * @param[out] iqp pointer to an @p InputQueue structure
- * @param[in] bp pointer to a memory area allocated as queue buffer
- * @param[in] size size of the queue buffer
- * @param[in] infy pointer to a callback function that is invoked when
- *                 data is read from the queue. The value can be @p NULL.
- *
- * @note The callback is invoked from within the S-Locked system state,
- *       see @ref system_states.
+ * @param[out] iqp      pointer to an @p InputQueue structure
+ * @param[in] bp        pointer to a memory area allocated as queue buffer
+ * @param[in] size      size of the queue buffer
+ * @param[in] infy      pointer to a callback function that is invoked when
+ *                      data is read from the queue. The value can be @p NULL.
  */
 void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
 
@@ -51,13 +51,13 @@ void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
 }
 
 /**
- * @brief Resets an input queue.
+ * @brief   Resets an input queue.
  * @details All the data in the input queue is erased and lost, any waiting
  *          thread is resumed with status @p Q_RESET.
- * @note A reset operation can be used by a low level driver in order to obtain
- *       immediate attention from the high level layers.
+ * @note    A reset operation can be used by a low level driver in order to
+ *          obtain immediate attention from the high level layers.
  *
- * @param[in] iqp pointer to an @p InputQueue structure
+ * @param[in] iqp       pointer to an @p InputQueue structure
  */
 void chIQResetI(InputQueue *iqp) {
 
@@ -66,14 +66,15 @@ void chIQResetI(InputQueue *iqp) {
 }
 
 /**
- * @brief Input queue write.
+ * @brief   Input queue write.
  * @details A byte value is written into the low end of an input queue.
  *
- * @param[in] iqp pointer to an @p InputQueue structure
- * @param[in] b the byte value to be written in the queue
- * @return The operation status, it can be one of:
- * @retval Q_OK if the operation has been completed with success.
- * @retval Q_FULL if the queue is full and the operation cannot be completed.
+ * @param[in] iqp       pointer to an @p InputQueue structure
+ * @param[in] b         the byte value to be written in the queue
+ * @return              The operation status, it can be one of:
+ * @retval Q_OK         if the operation has been completed with success.
+ * @retval Q_FULL       if the queue is full and the operation cannot be
+ *                      completed.
  */
 msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
 
@@ -88,20 +89,20 @@ msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
 }
 
 /**
- * @brief Input queue read with timeout.
+ * @brief   Input queue read with timeout.
  * @details This function reads a byte value from an input queue. If the queue
  *          is empty then the calling thread is suspended until a byte arrives
  *          in the queue or a timeout occurs.
  *
- * @param[in] iqp pointer to an @p InputQueue structure
- * @param[in] time the number of ticks before the operation timeouts,
- *             the following special values are allowed:
- *             - @a TIME_IMMEDIATE immediate timeout.
- *             - @a TIME_INFINITE no timeout.
- *             .
- * @return A byte value from the queue or:
- * @retval Q_TIMEOUT if the specified time expired.
- * @retval Q_RESET if the queue was reset.
+ * @param[in] iqp       pointer to an @p InputQueue structure
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              A byte value from the queue or:
+ * @retval Q_TIMEOUT    if the specified time expired.
+ * @retval Q_RESET      if the queue was reset.
  */
 msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
   uint8_t b;
@@ -124,25 +125,25 @@ msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
 }
 
 /**
- * @brief Input queue read with timeout.
+ * @brief   Input queue read with timeout.
  * @details The function reads data from an input queue into a buffer. The
  *          operation completes when the specified amount of data has been
  *          transferred or after the specified timeout or if the queue has
  *          been reset.
- * @note The function is not atomic, if you need atomicity it is suggested
- *       to use a semaphore or a mutex for mutual exclusion.
- * @note The queue callback is invoked before entering a sleep state and at
- *       the end of the transfer.
+ * @note    The function is not atomic, if you need atomicity it is suggested
+ *          to use a semaphore or a mutex for mutual exclusion.
+ * @note    The queue callback is invoked before entering a sleep state and at
+ *          the end of the transfer.
  *
- * @param[in] iqp pointer to an @p InputQueue structure
- * @param[out] bp pointer to the data buffer
- * @param[in] n the maximum amount of data to be transferred
- * @param[in] time the number of ticks before the operation timeouts,
- *             the following special values are allowed:
- *             - @a TIME_IMMEDIATE immediate timeout.
- *             - @a TIME_INFINITE no timeout.
- *             .
- * @return The number of bytes effectively transferred.
+ * @param[in] iqp       pointer to an @p InputQueue structure
+ * @param[out] bp       pointer to the data buffer
+ * @param[in] n         the maximum amount of data to be transferred
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The number of bytes effectively transferred.
  */
 size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
                        size_t n, systime_t time) {
@@ -180,18 +181,17 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
 }
 
 /**
- * @brief Initializes an output queue.
+ * @brief   Initializes an output queue.
  * @details A Semaphore is internally initialized and works as a counter of
  *          the free bytes in the queue.
+ * @note    The callback is invoked from within the S-Locked system state,
+ *          see @ref system_states.
  *
- * @param[out] oqp pointer to an @p OutputQueue structure
- * @param[in] bp pointer to a memory area allocated as queue buffer
- * @param[in] size size of the queue buffer
- * @param[in] onfy pointer to a callback function that is invoked when
- *                 data is written to the queue. The value can be @p NULL.
- *
- * @note The callback is invoked from within the S-Locked system state,
- *       see @ref system_states.
+ * @param[out] oqp      pointer to an @p OutputQueue structure
+ * @param[in] bp        pointer to a memory area allocated as queue buffer
+ * @param[in] size      size of the queue buffer
+ * @param[in] onfy      pointer to a callback function that is invoked when
+ *                      data is written to the queue. The value can be @p NULL.
  */
 void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
 
@@ -202,14 +202,13 @@ void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
 }
 
 /**
- * @brief Resets an output queue.
+ * @brief   Resets an output queue.
  * @details All the data in the output queue is erased and lost, any waiting
  *          thread is resumed with status @p Q_RESET.
+ * @note    A reset operation can be used by a low level driver in order to
+ *          obtain immediate attention from the high level layers.
  *
- * @param[in] oqp pointer to an @p OutputQueue structure
- *
- * @note A reset operation can be used by a low level driver in order to obtain
- *       immediate attention from the high level layers.
+ * @param[in] oqp       pointer to an @p OutputQueue structure
  */
 void chOQResetI(OutputQueue *oqp) {
 
@@ -218,22 +217,22 @@ void chOQResetI(OutputQueue *oqp) {
 }
 
 /**
- * @brief Output queue write with timeout.
+ * @brief   Output queue write with timeout.
  * @details This function writes a byte value to an output queue. If the queue
  *          is full then the calling thread is suspended until there is space
  *          in the queue or a timeout occurs.
  *
- * @param[in] oqp pointer to an @p OutputQueue structure
- * @param[in] b the byte value to be written in the queue
- * @param[in] time the number of ticks before the operation timeouts,
- *             the following special values are allowed:
- *             - @a TIME_IMMEDIATE immediate timeout.
- *             - @a TIME_INFINITE no timeout.
- *             .
- * @return The operation status:
- * @retval Q_OK if the operation succeeded.
- * @retval Q_TIMEOUT if the specified time expired.
- * @retval Q_RESET if the queue was reset.
+ * @param[in] oqp       pointer to an @p OutputQueue structure
+ * @param[in] b         the byte value to be written in the queue
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The operation status:
+ * @retval Q_OK         if the operation succeeded.
+ * @retval Q_TIMEOUT    if the specified time expired.
+ * @retval Q_RESET      if the queue was reset.
  */
 msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
   msg_t msg;
@@ -255,12 +254,12 @@ msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
 }
 
 /**
- * @brief Output queue read.
+ * @brief   Output queue read.
  * @details A byte value is read from the low end of an output queue.
  *
- * @param[in] oqp pointer to an @p OutputQueue structure
- * @return The byte value from the queue or:
- * @retval Q_EMPTY if the queue is empty.
+ * @param[in] oqp       pointer to an @p OutputQueue structure
+ * @return              The byte value from the queue or:
+ * @retval Q_EMPTY      if the queue is empty.
  */
 msg_t chOQGetI(OutputQueue *oqp) {
   uint8_t b;
@@ -276,25 +275,25 @@ msg_t chOQGetI(OutputQueue *oqp) {
 }
 
 /**
- * @brief Output queue write with timeout.
+ * @brief   Output queue write with timeout.
  * @details The function writes data from a buffer to an output queue. The
  *          operation completes when the specified amount of data has been
  *          transferred or after the specified timeout or if the queue has
  *          been reset.
- * @note The function is not atomic, if you need atomicity it is suggested
- *       to use a semaphore or a mutex for mutual exclusion.
- * @note The queue callback is invoked before entering a sleep state and at
- *       the end of the transfer.
+ * @note    The function is not atomic, if you need atomicity it is suggested
+ *          to use a semaphore or a mutex for mutual exclusion.
+ * @note    The queue callback is invoked before entering a sleep state and at
+ *          the end of the transfer.
  *
- * @param[in] oqp pointer to an @p OutputQueue structure
- * @param[out] bp pointer to the data buffer
- * @param[in] n the maximum amount of data to be transferred
- * @param[in] time the number of ticks before the operation timeouts,
- *             the following special values are allowed:
- *             - @a TIME_IMMEDIATE immediate timeout.
- *             - @a TIME_INFINITE no timeout.
- *             .
- * @return The number of bytes effectively transferred.
+ * @param[in] oqp       pointer to an @p OutputQueue structure
+ * @param[out] bp       pointer to the data buffer
+ * @param[in] n         the maximum amount of data to be transferred
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @return              The number of bytes effectively transferred.
  */
 size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp,
                         size_t n, systime_t time) {
diff --git a/os/kernel/src/chregistry.c b/os/kernel/src/chregistry.c
index b02d5f1fb..05573acbf 100644
--- a/os/kernel/src/chregistry.c
+++ b/os/kernel/src/chregistry.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chregistry.c
- * @brief Threads registry code.
+ * @file    chregistry.c
+ * @brief   Threads registry code.
+ *
  * @addtogroup registry
  * @{
  */
@@ -36,7 +37,7 @@
  * @note    This function cannot return @p NULL because there is always at
  *          least one thread in the system.
  *
- * @return  A reference to the first thread.
+ * @return              A reference to the first thread.
  */
 Thread *chRegFirstThread(void) {
   Thread *tp;
@@ -52,9 +53,9 @@ Thread *chRegFirstThread(void) {
  * @details The reference counter of the specified thread is decremented and
  *          the reference counter of the returned thread is incremented.
  *
- * @param[in] tp    pointer to the thread
- * @return  A reference to the next thread.
- * @retval  NULL if there is no next thread.
+ * @param[in] tp        pointer to the thread
+ * @return              A reference to the next thread.
+ * @retval NULL         if there is no next thread.
  */
 Thread *chRegNextThread(Thread *tp) {
 
diff --git a/os/kernel/src/chschd.c b/os/kernel/src/chschd.c
index 5b4d18133..5bd016226 100644
--- a/os/kernel/src/chschd.c
+++ b/os/kernel/src/chschd.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chschd.c
- * @brief Scheduler code.
+ * @file    chschd.c
+ * @brief   Scheduler code.
+ *
  * @addtogroup scheduler
  * @{
  */
@@ -27,14 +28,13 @@
 #include "ch.h"
 
 /**
- * @brief Ready list header.
+ * @brief   Ready list header.
  */
 ReadyList rlist;
 
 /**
- * @brief Scheduler initialization.
- *
- * @note Internally invoked by the @p chSysInit().
+ * @brief   Scheduler initialization.
+ * @note    Internally invoked by the @p chSysInit(), not an API.
  */
 void scheduler_init(void) {
 
@@ -49,12 +49,12 @@ void scheduler_init(void) {
 }
 
 /**
- * @brief Inserts a thread in the Ready List.
+ * @brief   Inserts a thread in the Ready List.
+ * @note    The function does not reschedule, the @p chSchRescheduleS() should
+ *          be called soon after.
  *
- * @param[in] tp the Thread to be made ready
- * @return The Thread pointer.
- * @note The function does not reschedule, the @p chSchRescheduleS() should
- *       be called soon after.
+ * @param[in] tp        the Thread to be made ready
+ * @return              The Thread pointer.
  */
 #if CH_OPTIMIZE_SPEED
 /* NOTE: it is inlined in this module only.*/
@@ -76,11 +76,11 @@ Thread *chSchReadyI(Thread *tp) {
 }
 
 /**
- * @brief Puts the current thread to sleep into the specified state.
+ * @brief   Puts the current thread to sleep into the specified state.
  * @details The thread goes into a sleeping state. The @ref thread_states are
  *          described into @p threads.h.
  *
- * @param[in] newstate the new thread state
+ * @param[in] newstate  the new thread state
  */
 void chSchGoSleepS(tstate_t newstate) {
   Thread *otp;
@@ -121,24 +121,24 @@ static void wakeup(void *p) {
 }
 
 /**
- * @brief Puts the current thread to sleep into the specified state with
- *        timeout specification.
+ * @brief   Puts the current thread to sleep into the specified state with
+ *          timeout specification.
  * @details The thread goes into a sleeping state, if it is not awakened
  *          explicitly within the specified timeout then it is forcibly
  *          awakened with a @p RDY_TIMEOUT low level message. The @ref
  *          thread_states are described into @p threads.h.
  *
- * @param[in] newstate the new thread state
- * @param[in] time the number of ticks before the operation timeouts, the
- *                 special values are handled as follow:
- *                 - @a TIME_INFINITE the thread enters an infinite sleep
- *                   state, this is equivalent to invoking @p chSchGoSleepS()
- *                   but, of course, less efficient.
- *                 - @a TIME_IMMEDIATE this value is accepted but interpreted
- *                   as a normal time specification not as an immediate timeout
- *                   specification.
- *                 .
- * @return The wakeup message.
+ * @param[in] newstate  the new thread state
+ * @param[in] time      the number of ticks before the operation timeouts, the
+ *                      special values are handled as follow:
+ *                      - @a TIME_INFINITE the thread enters an infinite sleep
+ *                        state, this is equivalent to invoking
+ *                        @p chSchGoSleepS() but, of course, less efficient.
+ *                      - @a TIME_IMMEDIATE this value is accepted but
+ *                        interpreted as a normal time specification not as an
+ *                        immediate timeout specification.
+ *                      .
+ * @return              The wakeup message.
  * @retval RDY_TIMEOUT if a timeout occurs.
  */
 msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
@@ -157,24 +157,25 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
 }
 
 /**
- * @brief Wakes up a thread.
+ * @brief   Wakes up a thread.
  * @details The thread is inserted into the ready list or immediately made
  *          running depending on its relative priority compared to the current
  *          thread.
+ * @note    It is equivalent to a @p chSchReadyI() followed by a
+ *          @p chSchRescheduleS() but much more efficient.
+ * @note    The function assumes that the current thread has the highest
+ *          priority.
  *
- * @param[in] ntp the Thread to be made ready
- * @param[in] msg message to the awakened thread
- * @note It is equivalent to a @p chSchReadyI() followed by a
- *       @p chSchRescheduleS() but much more efficient.
- * @note The function assumes that the current thread has the highest priority
+ * @param[in] ntp       the Thread to be made ready
+ * @param[in] msg       message to the awakened thread
  */
 void chSchWakeupS(Thread *ntp, msg_t msg) {
 
   ntp->p_u.rdymsg = msg;
   /* If the waken thread has a not-greater priority than the current
-   * one then it is just inserted in the ready list else it made
-   * running immediately and the invoking thread goes in the ready
-   * list instead.*/
+     one then it is just inserted in the ready list else it made
+     running immediately and the invoking thread goes in the ready
+     list instead.*/
   if (ntp->p_prio <= currp->p_prio)
     chSchReadyI(ntp);
   else {
@@ -190,10 +191,9 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
 }
 
 /**
- * @brief Switches to the first thread on the runnable queue.
- *
- * @note It is intended to be called if @p chSchRescRequiredI() evaluates to
- *       @p TRUE.
+ * @brief   Switches to the first thread on the runnable queue.
+ * @note    It is intended to be called if @p chSchRescRequiredI() evaluates
+ *          to @p TRUE.
  */
 void chSchDoRescheduleI(void) {
 
@@ -209,7 +209,7 @@ void chSchDoRescheduleI(void) {
 }
 
 /**
- * @brief Performs a reschedulation if a higher priority thread is runnable.
+ * @brief   Performs a reschedulation if a higher priority thread is runnable.
  * @details If a thread with a higher priority than the current thread is in
  *          the ready list then make the higher priority thread running.
  */
@@ -220,34 +220,33 @@ void chSchRescheduleS(void) {
 }
 
 /**
- * @brief Evaluates if a reschedulation is required.
+ * @brief   Evaluates if a reschedulation is required.
  * @details The decision is taken by comparing the relative priorities and
  *          depending on the state of the round robin timeout counter.
+ * @note    This function is meant to be used in the timer interrupt handler
+ *          where @p chVTDoTickI() is invoked.
  *
- * @retval TRUE if there is a thread that should go in running state.
- * @retval FALSE if a reschedulation is not required.
- *
- * @note This function is meant to be used in the timer interrupt handler
- *       where @p chVTDoTickI() is invoked.
+ * @retval TRUE         if there is a thread that should go in running state.
+ * @retval FALSE        if a reschedulation is not required.
  */
 bool_t chSchIsRescRequiredExI(void) {
   tprio_t p1 = firstprio(&rlist.r_queue);
   tprio_t p2 = currp->p_prio;
 #if CH_TIME_QUANTUM > 0
   /* If the running thread has not reached its time quantum, reschedule only
-   * if the first thread on the ready queue has a higher priority.
-   * Otherwise, if the running thread has used up its time quantum, reschedule
-   * if the first thread on the ready queue has equal or higher priority.*/
+     if the first thread on the ready queue has a higher priority.
+     Otherwise, if the running thread has used up its time quantum, reschedule
+     if the first thread on the ready queue has equal or higher priority.*/
   return rlist.r_preempt ? p1 > p2 : p1 >= p2;
 #else
-  /* If the round robin feature is not enabled then performs a simpler
-   * comparison.*/
+  /* If the round robin preemption feature is not enabled then performs a
+     simpler comparison.*/
   return p1 > p2;
 #endif
 }
 
 /**
- * @brief Yields the time slot.
+ * @brief   Yields the time slot.
  * @details Yields the CPU control to the next thread in the ready list with
  *          equal priority, if any.
  */
@@ -257,11 +256,9 @@ void chSchDoYieldS(void) {
     Thread *cp = (Thread *)&rlist.r_queue;
     Thread *otp = currp;
 
-    /*
-     * Note, the following insertion code works because we know that on the
-     * ready list there is at least one thread with priority equal or higher
-     * than the current one.
-     */
+    /* Note, the following insertion code works because we know that on the
+       ready list there is at least one thread with priority equal or higher
+       than the current one.*/
     otp->p_state = THD_STATE_READY;
     do {
       cp = cp->p_prev;
diff --git a/os/kernel/src/chsem.c b/os/kernel/src/chsem.c
index c78d52f74..b4ff0d9bc 100644
--- a/os/kernel/src/chsem.c
+++ b/os/kernel/src/chsem.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chsem.c
- * @brief Semaphores code.
+ * @file    chsem.c
+ * @brief   Semaphores code.
+ *
  * @addtogroup semaphores
  * @{
  */
@@ -35,13 +36,11 @@
 #endif
 
 /**
- * @brief Initializes a semaphore with the specified counter value.
+ * @brief   Initializes a semaphore with the specified counter value.
  *
- * @param[out] sp pointer to a @p Semaphore structure
- * @param[in] n initial value of the semaphore counter. Must be non-negative.
- * @note This function can be invoked from within an interrupt handler even if
- *       it is not an I-Class API because it does not touch any critical kernel
- *       data structure.
+ * @param[out] sp       pointer to a @p Semaphore structure
+ * @param[in] n         initial value of the semaphore counter. Must be
+ *                      non-negative.
  */
 void chSemInit(Semaphore *sp, cnt_t n) {
 
@@ -52,13 +51,14 @@ void chSemInit(Semaphore *sp, cnt_t n) {
 }
 
 /**
- * @brief Performs a reset operation on the semaphore.
+ * @brief   Performs a reset operation on the semaphore.
+ * @note    The released threads can recognize they were waked up by a reset
+ *          rather than a signal because the @p chSemWait() will return
+ *          @p RDY_RESET instead of @p RDY_OK.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @param[in] n the new value of the semaphore counter. The value must be non-negative.
- * @note The released threads can recognize they were waked up by a reset
- *       instead than a signal because the @p chSemWait() will return
- *       @p RDY_RESET instead of @p RDY_OK.
+ * @param[in] sp        pointer to a @p Semaphore structure
+ * @param[in] n         the new value of the semaphore counter. The value must
+ *                      be non-negative.
  */
 void chSemReset(Semaphore *sp, cnt_t n) {
 
@@ -69,14 +69,15 @@ void chSemReset(Semaphore *sp, cnt_t n) {
 }
 
 /**
- * @brief Performs a reset operation on the semaphore.
+ * @brief   Performs a reset operation on the semaphore.
+ * @note    The released threads can recognize they were waked up by a reset
+ *          rather than a signal because the @p chSemWait() will return
+ *          @p RDY_RESET instead of @p RDY_OK.
+ * @note    This function does not reschedule.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @param[in] n the new value of the semaphore counter. The value must be non-negative.
- * @note The released threads can recognize they were waked up by a reset
- *       instead than a signal because the @p chSemWait() will return
- *       @p RDY_RESET instead of @p RDY_OK.
- * @note This function does not reschedule.
+ * @param[in] sp        pointer to a @p Semaphore structure
+ * @param[in] n         the new value of the semaphore counter. The value must
+ *                      be non-negative.
  */
 void chSemResetI(Semaphore *sp, cnt_t n) {
   cnt_t cnt;
@@ -90,11 +91,11 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
 }
 
 /**
- * @brief Performs a wait operation on a semaphore.
+ * @brief   Performs a wait operation on a semaphore.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset using @p chSemReset().
+ * @param[in] sp        pointer to a @p Semaphore structure
+ * @retval RDY_OK       if the semaphore was signaled or not taken.
+ * @retval RDY_RESET    if the semaphore was reset using @p chSemReset().
  */
 msg_t chSemWait(Semaphore *sp) {
   msg_t msg;
@@ -106,13 +107,11 @@ msg_t chSemWait(Semaphore *sp) {
 }
 
 /**
- * @brief Performs a wait operation on a semaphore.
+ * @brief   Performs a wait operation on a semaphore.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset using @p chSemReset().
- * @note This function must be called with interrupts disabled.
- * @note This function cannot be called by an interrupt handler.
+ * @param[in] sp        pointer to a @p Semaphore structure
+ * @retval RDY_OK       if the semaphore was signaled or not taken.
+ * @retval RDY_RESET    if the semaphore was reset using @p chSemReset().
  */
 msg_t chSemWaitS(Semaphore *sp) {
 
@@ -128,18 +127,18 @@ msg_t chSemWaitS(Semaphore *sp) {
 }
 
 /**
- * @brief Performs a wait operation on a semaphore with timeout specification.
+ * @brief   Performs a wait operation on a semaphore with timeout specification.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @param[in] time the number of ticks before the operation timeouts,
- *             the following special values are allowed:
- *             - @a TIME_IMMEDIATE immediate timeout.
- *             - @a TIME_INFINITE no timeout.
- *             .
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset using @p chSemReset().
- * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the
- *         specified timeout.
+ * @param[in] sp        pointer to a @p Semaphore structure
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @retval RDY_OK       if the semaphore was signaled or not taken.
+ * @retval RDY_RESET    if the semaphore was reset using @p chSemReset().
+ * @retval RDY_TIMEOUT  if the semaphore was not signaled or reset within the
+ *                      specified timeout.
  */
 msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
   msg_t msg;
@@ -151,18 +150,18 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
 }
 
 /**
- * @brief Performs a wait operation on a semaphore with timeout specification.
+ * @brief   Performs a wait operation on a semaphore with timeout specification.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @param[in] time the number of ticks before the operation timeouts,
- *                 the following special values are allowed:
- *                 - @a TIME_IMMEDIATE immediate timeout.
- *                 - @a TIME_INFINITE no timeout.
- *                 .
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset using @p chSemReset().
- * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified
- *         timeout.
+ * @param[in] sp        pointer to a @p Semaphore structure
+ * @param[in] time      the number of ticks before the operation timeouts,
+ *                      the following special values are allowed:
+ *                      - @a TIME_IMMEDIATE immediate timeout.
+ *                      - @a TIME_INFINITE no timeout.
+ *                      .
+ * @retval RDY_OK       if the semaphore was signaled or not taken.
+ * @retval RDY_RESET    if the semaphore was reset using @p chSemReset().
+ * @retval RDY_TIMEOUT  if the semaphore was not signaled or reset within the
+ *                      specified timeout.
  */
 msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
 
@@ -181,11 +180,9 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
 }
 
 /**
- * @brief Performs a signal operation on a semaphore.
+ * @brief   Performs a signal operation on a semaphore.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @note The function is available only if the @p CH_USE_SEMAPHORES
- *       option is enabled in @p chconf.h.
+ * @param[in] sp        pointer to a @p Semaphore structure
  */
 void chSemSignal(Semaphore *sp) {
 
@@ -198,19 +195,17 @@ void chSemSignal(Semaphore *sp) {
 }
 
 /**
- * @brief Performs a signal operation on a semaphore.
+ * @brief   Performs a signal operation on a semaphore.
+ * @note    This function does not reschedule.
  *
- * @param[in] sp pointer to a @p Semaphore structure
- * @note The function is available only if the @p CH_USE_SEMAPHORES
- *       option is enabled in @p chconf.h.
- * @note This function does not reschedule.
+ * @param[in] sp    pointer to a @p Semaphore structure
  */
 void chSemSignalI(Semaphore *sp) {
 
   chDbgCheck(sp != NULL, "chSemSignalI");
 
   if (sp->s_cnt++ < 0) {
-    /* NOTE: It is done this way in order to allow a tail call on
+    /* note, it is done this way in order to allow a tail call on
              chSchReadyI().*/
     Thread *tp = fifo_remove(&sp->s_queue);
     tp->p_u.rdymsg = RDY_OK;
@@ -220,14 +215,14 @@ void chSemSignalI(Semaphore *sp) {
 
 #if CH_USE_SEMSW
 /**
- * @brief Performs atomic signal and wait operations on two semaphores.
+ * @brief   Performs atomic signal and wait operations on two semaphores.
+ * @note    The function is available only if the @p CH_USE_SEMSW
+ *          option is enabled in @p chconf.h.
  *
- * @param[in] sps pointer to a @p Semaphore structure to be signaled
- * @param[in] spw pointer to a @p Semaphore structure to be wait on
- * @retval RDY_OK if the semaphore was signaled or not taken.
- * @retval RDY_RESET if the semaphore was reset using @p chSemReset().
- * @note The function is available only if the @p CH_USE_SEMSW
- *       option is enabled in @p chconf.h.
+ * @param[in] sps       pointer to a @p Semaphore structure to be signaled
+ * @param[in] spw       pointer to a @p Semaphore structure to be wait on
+ * @retval RDY_OK       if the semaphore was signaled or not taken.
+ * @retval RDY_RESET    if the semaphore was reset using @p chSemReset().
  */
 msg_t chSemSignalWait(Semaphore *sps, Semaphore *spw) {
   msg_t msg;
diff --git a/os/kernel/src/chsys.c b/os/kernel/src/chsys.c
index 2863f253c..8c252609d 100644
--- a/os/kernel/src/chsys.c
+++ b/os/kernel/src/chsys.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chsys.c
- * @brief System related code.
+ * @file    chsys.c
+ * @brief   System related code.
+ *
  * @addtogroup system
  * @{
  */
@@ -29,7 +30,7 @@
 static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
 
 /**
- * @brief This function implements the idle thread infinite loop.
+ * @brief   This function implements the idle thread infinite loop.
  * @details The function puts the processor in the lowest power mode capable
  *          to serve interrupts.<br>
  *          The priority is internally set to the minimum system value so
@@ -48,13 +49,12 @@ static void idle_thread(void *p) {
 }
 
 /**
- * @brief ChibiOS/RT initialization.
+ * @brief   ChibiOS/RT initialization.
  * @details After executing this function the current instructions stream
  *          becomes the main thread.
- *
- * @note Interrupts should be still disabled when @p chSysInit() is invoked
- *       and are internally enabled.
- * @note The main thread is created with priority @p NORMALPRIO.
+ * @note    Interrupts should be still disabled when @p chSysInit() is invoked
+ *          and are internally enabled.
+ * @note    The main thread is created with priority @p NORMALPRIO.
  */
 void chSysInit(void) {
   static Thread mainthread;
@@ -72,29 +72,26 @@ void chSysInit(void) {
   trace_init();
 #endif
 
-  /*
-   * Now this instructions flow becomes the main thread.
-   */
+  /* Now this instructions flow becomes the main thread.*/
   (currp = init_thread(&mainthread, NORMALPRIO))->p_state = THD_STATE_CURRENT;
   chSysEnable();
 
-  /*
-   * This thread has the lowest priority in the system, its role is just to
-   * serve interrupts in its context while keeping the lowest energy saving
-   * mode compatible with the system status.
-   */
+  /* This thread has the lowest priority in the system, its role is just to
+     serve interrupts in its context while keeping the lowest energy saving
+     mode compatible with the system status.*/
   chThdCreateStatic(idle_thread_wa, sizeof(idle_thread_wa), IDLEPRIO,
                     (tfunc_t)idle_thread, NULL);
 }
 
 /**
- * @brief Handles time ticks for round robin preemption and timer increments.
+ * @brief   Handles time ticks for round robin preemption and timer increments.
  * @details Decrements the remaining time quantum of the running thread
  *          and preempts it when the quantum is used up. Increments system
  *          time and manages the timers.
  *
- * @note The frequency of the timer determines the system tick granularity and,
- *       together with the @p CH_TIME_QUANTUM macro, the round robin interval.
+ * @note    The frequency of the timer determines the system tick granularity
+ *          and, together with the @p CH_TIME_QUANTUM macro, the round robin
+ *          interval.
  */
 void chSysTimerHandlerI(void) {
 
diff --git a/os/kernel/src/chthreads.c b/os/kernel/src/chthreads.c
index e28efa43c..f96cea942 100644
--- a/os/kernel/src/chthreads.c
+++ b/os/kernel/src/chthreads.c
@@ -18,8 +18,9 @@
 */
 
 /**
- * @file chthreads.c
- * @brief Threads code.
+ * @file    chthreads.c
+ * @brief   Threads code.
+ *
  * @addtogroup threads
  * @{
  */
@@ -29,10 +30,9 @@
 /**
  * @brief   Initializes a thread structure.
  *
- * @param[in] tp    pointer to the thread
- * @param[in] prio  the priority level for the new thread
- *
- * @return  The same thread pointer passed as parameter.
+ * @param[in] tp        pointer to the thread
+ * @param[in] prio      the priority level for the new thread
+ * @return              The same thread pointer passed as parameter.
  */
 Thread *init_thread(Thread *tp, tprio_t prio) {
 
@@ -86,14 +86,14 @@ static void memfill(uint8_t *startp, uint8_t *endp, uint8_t v) {
  *          even if it is not an I-Class API because it does not touch
  *          any critical kernel data structure.
  *
- * @param[out] wsp  pointer to a working area dedicated to the thread stack
- * @param[in] size  size of the working area
- * @param[in] prio  the priority level for the new thread
- * @param[in] pf    the thread function
- * @param[in] arg   an argument passed to the thread function. It can be
- *                  @p NULL.
- * @return  The pointer to the @p Thread structure allocated for the
- *          thread into the working space area.
+ * @param[out] wsp      pointer to a working area dedicated to the thread stack
+ * @param[in] size      size of the working area
+ * @param[in] prio      the priority level for the new thread
+ * @param[in] pf        the thread function
+ * @param[in] arg       an argument passed to the thread function. It can be
+ *                      @p NULL.
+ * @return              The pointer to the @p Thread structure allocated for
+ *                      the thread into the working space area.
  */
 Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {
   /* Thread structure is layed out in the lower part of the thread workspace */
@@ -116,14 +116,14 @@ Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {
  * @note    A thread can terminate by calling @p chThdExit() or by simply
  *          returning from its main function.
  *
- * @param[out] wsp  pointer to a working area dedicated to the thread stack
- * @param[in] size  size of the working area
- * @param[in] prio  the priority level for the new thread
- * @param[in] pf    the thread function
- * @param[in] arg   an argument passed to the thread function. It can be
- *                  @p NULL.
- * @return  The pointer to the @p Thread structure allocated for the
- *          thread into the working space area.
+ * @param[out] wsp      pointer to a working area dedicated to the thread stack
+ * @param[in] size      size of the working area
+ * @param[in] prio      the priority level for the new thread
+ * @param[in] pf        the thread function
+ * @param[in] arg       an argument passed to the thread function. It can be
+ *                      @p NULL.
+ * @return              The pointer to the @p Thread structure allocated for
+ *                      the thread into the working space area.
  */
 Thread *chThdCreateStatic(void *wsp, size_t size,
                           tprio_t prio, tfunc_t pf, void *arg) {
@@ -142,16 +142,16 @@ Thread *chThdCreateStatic(void *wsp, size_t size,
  *          @p CH_USE_HEAP and @p CH_USE_WAITEXIT options are enabled
  *          in @p chconf.h.
  *
- * @param[in] heapp heap from which allocate the memory or @p NULL for the
- *                  default heap
- * @param[in] size  size of the working area to be allocated
- * @param[in] prio  the priority level for the new thread
- * @param[in] pf    the thread function
- * @param[in] arg   an argument passed to the thread function. It can be
- *                  @p NULL.
- * @return  The pointer to the @p Thread structure allocated for the
- *          thread into the working space area.
- * @retval  NULL if the memory cannot be allocated.
+ * @param[in] heapp     heap from which allocate the memory or @p NULL for the
+ *                      default heap
+ * @param[in] size      size of the working area to be allocated
+ * @param[in] prio      the priority level for the new thread
+ * @param[in] pf        the thread function
+ * @param[in] arg       an argument passed to the thread function. It can be
+ *                      @p NULL.
+ * @return              The pointer to the @p Thread structure allocated for
+ *                      the thread into the working space area.
+ * @retval NULL         if the memory cannot be allocated.
  */
 Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
                             tprio_t prio, tfunc_t pf, void *arg) {
@@ -179,15 +179,14 @@ Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
  *          @p CH_USE_MEMPOOLS and @p CH_USE_WAITEXIT options are enabled
  *          in @p chconf.h.
  *
- * @param[in] mp    pointer to the memory pool object
- * @param[in] prio  the priority level for the new thread
- * @param[in] pf    the thread function
- * @param[in] arg   an argument passed to the thread function. It can be
- *                  @p NULL.
- * @return  The pointer to the @p Thread structure allocated for the
- *          thread into the working space area or @p NULL if the memory cannot
- *          be allocated.
- * @retval  NULL if the memory pool is empty.
+ * @param[in] mp        pointer to the memory pool object
+ * @param[in] prio      the priority level for the new thread
+ * @param[in] pf        the thread function
+ * @param[in] arg       an argument passed to the thread function. It can be
+ *                      @p NULL.
+ * @return              The pointer to the @p Thread structure allocated for
+ *                      the thread into the working space area.
+ * @retval  NULL        if the memory pool is empty.
  */
 Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
                                   tfunc_t pf, void *arg) {
@@ -213,8 +212,8 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
  *          current priority that could be higher than the real priority
  *          because the priority inheritance mechanism.
  *
- * @param[in] newprio the new priority level of the running thread
- * @return  The old priority level.
+ * @param[in] newprio   the new priority level of the running thread
+ * @return              The old priority level.
  */
 tprio_t chThdSetPriority(tprio_t newprio) {
   tprio_t oldprio;
@@ -241,8 +240,8 @@ tprio_t chThdSetPriority(tprio_t newprio) {
  * @brief   Resumes a suspended thread.
  * @note    Use this function to resume threads created with @p chThdInit().
  *
- * @param[in] tp    pointer to the thread
- * @return  The pointer to the thread.
+ * @param[in] tp        pointer to the thread
+ * @return              The pointer to the thread.
  */
 Thread *chThdResume(Thread *tp) {
 
@@ -261,7 +260,7 @@ Thread *chThdResume(Thread *tp) {
  *          its @p p_flags field. The thread can read this status by
  *          invoking @p chThdShouldTerminate() and then terminate cleanly.
  *
- * @param[in] tp    pointer to the thread
+ * @param[in] tp        pointer to the thread
  */
 void chThdTerminate(Thread *tp) {
 
@@ -273,14 +272,14 @@ void chThdTerminate(Thread *tp) {
 /**
  * @brief   Suspends the invoking thread for the specified time.
  *
- * @param[in] time  the delay in system ticks, the special values are handled
- *                  as follow:
- *                  - @a TIME_INFINITE the thread enters an infinite sleep
- *                    state.
- *                  - @a TIME_IMMEDIATE this value is accepted but interpreted
- *                    as a normal time specification not as an immediate
- *                    timeout specification.
- *                  .
+ * @param[in] time      the delay in system ticks, the special values are
+ *                      handled as follow:
+ *                      - @a TIME_INFINITE the thread enters an infinite sleep
+ *                        state.
+ *                      - @a TIME_IMMEDIATE this value is accepted but
+ *                        interpreted as a normal time specification not as an
+ *                        immediate timeout specification.
+ *                      .
  */
 void chThdSleep(systime_t time) {
 
@@ -295,7 +294,7 @@ void chThdSleep(systime_t time) {
  * @brief   Suspends the invoking thread until the system time arrives to the
  *          specified value.
  *
- * @param[in] time  absolute system time
+ * @param[in] time      absolute system time
  */
 void chThdSleepUntil(systime_t time) {
 
@@ -320,9 +319,8 @@ void chThdYield(void) {
 /**
  * @brief   Terminates the current thread by specifying an exit status code.
  *
- * @param[in] msg   thread exit code. The code can be retrieved by using
- *                  @p chThdWait().
- * @return  The same thread pointer passed as parameter.
+ * @param[in] msg       thread exit code. The code can be retrieved by using
+ *                      @p chThdWait().
  */
 void chThdExit(msg_t msg) {
   Thread *tp = currp;
@@ -344,9 +342,9 @@ void chThdExit(msg_t msg) {
 /**
  * @brief   Adds a reference to a thread object.
  *
- * @param[in] tp    pointer to the thread
- * @return  The same thread pointer passed as parameter representing the
- *          new reference.
+ * @param[in] tp        pointer to the thread
+ * @return              The same thread pointer passed as parameter
+ *                      representing the new reference.
  */
 Thread *chThdAddRef(Thread *tp) {
 
@@ -364,7 +362,7 @@ Thread *chThdAddRef(Thread *tp) {
  *          returned to the proper allocator.
  * @note    Static threads are not affected.
  *
- * @param[in] tp    pointer to the thread
+ * @param[in] tp        pointer to the thread
  */
 void chThdRelease(Thread *tp) {
   trefs_t refs;
@@ -419,8 +417,8 @@ void chThdRelease(Thread *tp) {
  * @note    If @p CH_USE_DYNAMIC is not specified this function just waits for
  *          the thread termination, no memory allocators are involved.
  *
- * @param[in] tp    pointer to the thread
- * @return  The exit code from the terminated thread
+ * @param[in] tp        pointer to the thread
+ * @return              The exit code from the terminated thread.
  */
 msg_t chThdWait(Thread *tp) {
   msg_t msg;
diff --git a/os/kernel/src/chvt.c b/os/kernel/src/chvt.c
index 5acde49aa..9558a1cb7 100644
--- a/os/kernel/src/chvt.c
+++ b/os/kernel/src/chvt.c
@@ -18,20 +18,23 @@
 */
 
 /**
- * @file chvt.c
- * @brief Time and Virtual Timers related code.
+ * @file    chvt.c
+ * @brief   Time and Virtual Timers related code.
+ *
  * @addtogroup time
  * @{
  */
 
 #include "ch.h"
 
+/**
+ * @brief   Virtual timers delta list header.
+ */
 VTList vtlist;
 
 /**
- * @brief Virtual Timers initialization.
- *
- * @note Internal use only.
+ * @brief   Virtual Timers initialization.
+ * @note    Internal use only.
  */
 void vt_init(void) {
 
@@ -41,19 +44,20 @@ void vt_init(void) {
 }
 
 /**
- * @brief Enables a virtual timer.
+ * @brief   Enables a virtual timer.
+ * @note    The associated function is invoked by an interrupt handler within
+ *          the I-Locked state, see @ref system_states.
  *
- * @param[out] vtp the @p VirtualTimer structure pointer
- * @param[in] time the number of time ticks, the value @p TIME_INFINITE is not
- *                 allowed. The value @p TIME_IMMEDIATE is allowed but
- *                 interpreted as a normal time specification not as an
- *                 immediate timeout specification.
- * @param[in] vtfunc the timer callback function. After invoking the callback
- *                   the timer is disabled and the structure can be disposed or
- *                   reused.
- * @param[in] par a parameter that will be passed to the callback function
- * @note The associated function is invoked by an interrupt handler within
- *       the I-Locked state, see @ref system_states.
+ * @param[out] vtp      the @p VirtualTimer structure pointer
+ * @param[in] time      the number of time ticks, the value @p TIME_INFINITE
+ *                      is notallowed. The value @p TIME_IMMEDIATE is allowed
+ *                      but interpreted as a normal time specification not as
+ *                      an immediate timeout specification.
+ * @param[in] vtfunc    the timer callback function. After invoking the
+ *                      callback the timer is disabled and the structure can
+ *                      be disposed or reused.
+ * @param[in] par       a parameter that will be passed to the callback
+ *                      function
  */
 void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
   VirtualTimer *p;
@@ -77,10 +81,10 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
 }
 
 /**
- * @brief Disables a Virtual Timer.
+ * @brief   Disables a Virtual Timer.
+ * @note    The timer MUST be active when this function is invoked.
  *
- * @param[in] vtp the @p VirtualTimer structure pointer
- * @note The timer MUST be active when this function is invoked.
+ * @param[in] vtp       the @p VirtualTimer structure pointer
  */
 void chVTResetI(VirtualTimer *vtp) {
 
@@ -97,14 +101,15 @@ void chVTResetI(VirtualTimer *vtp) {
 }
 
 /**
- * @brief Checks if the current system time is within the specified time window.
+ * @brief   Checks if the current system time is within the specified time
+ *          window.
+ * @note    When start==end then the function returns always true because the
+ *          whole time range is specified.
  *
- * @param[in] start the start of the time window (inclusive)
- * @param[in] end the end of the time window (non inclusive)
- * @retval TRUE current time within the specified time window.
- * @retval FALSE current time not within the specified time window.
- * @note When start==end then the function returns always true because the
- *       whole time range is specified.
+ * @param[in] start     the start of the time window (inclusive)
+ * @param[in] end       the end of the time window (non inclusive)
+ * @retval TRUE         current time within the specified time window.
+ * @retval FALSE        current time not within the specified time window.
  */
 bool_t chTimeIsWithin(systime_t start, systime_t end) {
author	gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>	2010-02-06 10:55:53 +0000
committer	gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>	2010-02-06 10:55:53 +0000
commit	f17db1931e95f5ebb42f557b6eead2bf1320db5a (patch)
tree	0676532b6f3231f6c7343b3f644cdc5282433090 /os/kernel/src
parent	6f7c30adff593e365515898082436f893f2ccb00 (diff)
download	ChibiOS-f17db1931e95f5ebb42f557b6eead2bf1320db5a.tar.gz ChibiOS-f17db1931e95f5ebb42f557b6eead2bf1320db5a.tar.bz2 ChibiOS-f17db1931e95f5ebb42f557b6eead2bf1320db5a.zip