git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@649 35acf78f-673a-0410-8e92-d51de3d6d3f4

22 files changed, 613 insertions, 403 deletions

diff --git a/docs/ch.txt b/docs/ch.txt
index 70aeda6a4..0ae4eb61b 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -66,15 +66,17 @@
  * The possible groups are: @a Sys, @a Sch, @a VT, @a Thd, @a Sem, @a Mtx,

  * @a Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg,

  * @a Heap, @a Pool.

+ *

+ * @section api_suffixes API Names Suffixes

  * The suffix is not present for normal APIs but can be one of

  * the following:

- * - <b>"I"</b>, I-Class APIs are invokable only from the I-Locked or S-Locked

- *   states. See @ref system_states.

- * - <b>"S"</b>, S-Class APIs are invokable only from the S-Locked state. See

+ * - <b>None</b>, APIs without any suffix can be invoked only from the user

+ *   code in the <b>Normal</b> state unless differently specified. See

  *   @ref system_states.

- *

- * The APIs without suffix can be invoked only from the user code in the Normal

- * state unless differently specified.<br>

+ * - <b>"I"</b>, I-Class APIs are invokable only from the <b>I-Locked</b> or

+ *   <b>S-Locked</b> states. See @ref system_states.

+ * - <b>"S"</b>, S-Class APIs are invokable only from the <b>S-Locked</b>

+ *   state. See @ref system_states.

  * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout().

  *

  * @section interrupt_classes Interrupt Classes

@@ -558,11 +560,42 @@
 /** @} */

 

 /**

+ * @defgroup utilities_library Utilities Library

+ * @{

+ * @brief Utilities Library.

+ * @details This is a collection of useful library code that is not part of

+ * the base kernel services.

+ * <h2>Notes</h2>

+ * The library code does not follow the same naming convention of the

+ * system APIs in order to make very clear that it is not "core" code.<br>

+ * The main difference is that library code is not formally  tested in the

+ * test suite but through usage in the various demo application.

+ */

+/** @} */

+

+/**

  * @defgroup CPlusPlusLibrary C++ Wrapper

  * @{

  * C++ wrapper module. This module allows to use the ChibiOS/RT functionalities

  * from C++ as classes and objects rather the traditional "C" APIs.

+ *

+ * @ingroup utilities_library

  * @file ch.hpp C++ wrapper classes and definitions.

  * @file ch.cpp C++ wrapper code.

  */

 /** @} */

+

+/**

+ * @defgroup event_timer Events Generator Timer

+ * @{

+ * @brief Event Generator Timer.

+ * @details This timer generates an event at regular intervals. The

+ * listening threads can use the event to perform time related activities.

+ * Multiple threads can listen to the same timer.

+ *

+ * @ingroup utilities_library

+ * @file evtimer.c Events Generator Timer code.

+ * @file evtimer.h Events Generator Timer structures and macros.

+ */

+/** @} */

+

diff --git a/src/chcond.c b/src/chcond.c
index 7d90c3ffb..09979a64e 100644
--- a/src/chcond.c
+++ b/src/chcond.c
@@ -31,8 +31,12 @@
 #if defined(CH_USE_CONDVARS) && defined(CH_USE_MUTEXES)

 

 /**

- * Initializes s @p CondVar structure.

+ * @brief Initializes s @p CondVar structure.

+ *

  * @param 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.

  */

 void chCondInit(CondVar *cp) {

 

@@ -40,7 +44,7 @@ void chCondInit(CondVar *cp) {
 }

 

 /**

- * Signals one thread that is waiting on the condition variable.

+ * @brief Signals one thread that is waiting on the condition variable.

  *

  * @param cp pointer to the @p CondVar structure

  */

@@ -55,11 +59,9 @@ void chCondSignal(CondVar *cp) {
 }

 

 /**

- * Signals one thread that is waiting on the condition variable.

+ * @brief Signals one thread that is waiting on the condition variable.

  *

  * @param cp pointer to the @p CondVar structure

- * @note This function must be called within a @p chSysLock() / @p chSysUnlock()

- *       block.

  */

 void chCondSignalI(CondVar *cp) {

 

@@ -68,7 +70,7 @@ void chCondSignalI(CondVar *cp) {
 }

 

 /**

- * Signals all threads that are waiting on the condition variable.

+ * @brief Signals all threads that are waiting on the condition variable.

  *

  * @param cp pointer to the @p CondVar structure

  */

@@ -83,10 +85,9 @@ void chCondBroadcast(CondVar *cp) {
 }

 

 /**

- * Signals all threads that are waiting on the condition variable.

+ * @brief Signals all threads that are waiting on the condition variable.

  *

  * @param cp pointer to the @p CondVar structure

- * @note This function must be called within a @p chSysLock() / @p chSysUnlock()

  */

 void chCondBroadcastI(CondVar *cp) {

 

@@ -98,17 +99,16 @@ void chCondBroadcastI(CondVar *cp) {
 }

 

 /**

- * Waits on the condition variable releasing the mutex lock.

- *

- * Releases the mutex, waits on the condition variable, and finally acquires

- * the mutex again. This is done atomically.

- *

- * The thread MUST already have locked the mutex when calling chCondWait().

+ * @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.

  *

  * @param 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().

  */

 msg_t chCondWait(CondVar *cp) {

   msg_t msg;

@@ -122,18 +122,16 @@ msg_t chCondWait(CondVar *cp) {
 }

 

 /**

- * Waits on the condition variable releasing the mutex lock.

- *

- * Releases the mutex, waits on the condition variable, and finally acquires

- * the mutex again. This is done atomically.

- *

- * The thread MUST already have locked the mutex when calling chCondWait().

+ * @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.

  *

  * @param 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 This function must be called within a @p chSysLock() / @p chSysUnlock()

+ * @note  The thread MUST already have locked the mutex when calling

+ *        @p chCondWaitS().

  */

 msg_t chCondWaitS(CondVar *cp) {

   Mutex *mp;

@@ -152,12 +150,9 @@ msg_t chCondWaitS(CondVar *cp) {
 

 #ifdef CH_USE_CONDVARS_TIMEOUT

 /**

- * Waits on the condition variable releasing the mutex lock.

- *

- * Releases the mutex, waits on the condition variable, and finally acquires

- * the mutex again. This is done atomically.

- *

- * The thread MUST already have locked the mutex when calling chCondWait().

+ * @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.

  *

  * @param cp pointer to the @p CondVar structure

  * @param time the number of ticks before the operation fails

@@ -166,6 +161,8 @@ msg_t chCondWaitS(CondVar *cp) {
  * @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().

  */

 msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {

   msg_t msg;

@@ -179,12 +176,9 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
 }

 

 /**

- * Waits on the condition variable releasing the mutex lock.

- *

- * Releases the mutex, waits on the condition variable, and finally acquires

- * the mutex again. This is done atomically.

- *

- * The thread MUST already have locked the mutex when calling chCondWait().

+ * @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.

  *

  * @param cp pointer to the @p CondVar structure

  * @param time the number of ticks before the operation fails

@@ -193,7 +187,8 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
  * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().

  * @retval RDY_TIMEOUT if the condvar was not signaled within the specified

  *         timeout.

- * @note This function must be called within a @p chSysLock() / @p chSysUnlock()

+ * @note  The thread MUST already have locked the mutex when calling

+ *        @p chCondWaitTimeoutS().

  */

 msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {

   Mutex *mp;

diff --git a/src/chdebug.c b/src/chdebug.c
index 56edd2a0d..60bbf49ef 100644
--- a/src/chdebug.c
+++ b/src/chdebug.c
@@ -24,7 +24,7 @@
 char *panicmsg;

 

 /**

- * Debug subsystem initialization.

+ * @brief Debug subsystem initialization.

  */

 void chDbgInit(void) {

 

@@ -35,7 +35,9 @@ void chDbgInit(void) {
 }

 

 /**

- * Prints a panic message on the console/debugger and then halts the system.

+ * @brief Prints a panic message on the console/debugger and then halts the

+ * system.

+ *

  * @param msg the pointer to the message string

  */

 void chDbgPanic(char *msg) {

@@ -48,12 +50,13 @@ void chDbgPanic(char *msg) {
 

 #ifdef CH_USE_TRACE

 /**

- * Public trace buffer.

+ * @brief Public trace buffer.

  */

 TraceBuffer dbgtb;

 

 /**

- * Inserts in the circular debug trace buffer a context switch record.

+ * @brief Inserts in the circular debug trace buffer a context switch record.

+ *

  * @param otp the thread being switched out

  * @param ntp the thread to be resumed

  */

diff --git a/src/chevents.c b/src/chevents.c
index cddc2215a..dc096767e 100644
--- a/src/chevents.c
+++ b/src/chevents.c
@@ -25,7 +25,8 @@
 

 #ifdef CH_USE_EVENTS

 /**

- * Registers an Event Listener on an Event Source.

+ * @brief Registers an Event Listener on an Event Source.

+ *

  * @param esp pointer to the  @p EventSource structure

  * @param elp pointer to the @p EventListener structure

  * @param emask the mask of event flags to be pended to the thread when the

@@ -45,7 +46,8 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t emask)
 }

 

 /**

- * Unregisters an Event Listener from its Event Source.

+ * @brief Unregisters an Event Listener from its Event Source.

+ *

  * @param esp pointer to the  @p EventSource structure

  * @param elp pointer to the @p EventListener structure

  * @note If the event listener is not registered on the specified event source

@@ -71,7 +73,8 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) {
 }

 

 /**

- * Clears the pending events specified in the mask.

+ * @brief Clears the pending events specified in the mask.

+ *

  * @param mask the events to be cleared

  * @return The pending events that were cleared.

  */

@@ -88,8 +91,9 @@ eventmask_t chEvtClear(eventmask_t mask) {
 }

 

 /**

- * Makes an events mask pending in the current thread, this is \b much faster than

- * using @p chEvtBroadcast().

+ * @brief Makes an events mask pending in the current thread, this is \b much

+ * faster than using @p chEvtBroadcast().

+ *

  * @param mask the events to be pended

  * @return The current pending events mask.

  */

@@ -104,7 +108,9 @@ eventmask_t chEvtPend(eventmask_t mask) {
 }

 

 /**

- * Signals all the Event Listeners registered on the specified Event Source.

+ * @brief Signals all the Event Listeners registered on the specified Event

+ * Source.

+ *

  * @param esp pointer to the @p EventSource structure

  */

 void chEvtBroadcast(EventSource *esp) {

@@ -118,9 +124,10 @@ void chEvtBroadcast(EventSource *esp) {
 }

 

 /**

- * Signals all the Event Listeners registered on the specified Event Source.

+ * @brief Signals all the Event Listeners registered on the specified Event

+ * Source.

+ *

  * @param esp pointer to the @p EventSource structure

- * @note This function does not reschedule.

  */

 void chEvtBroadcastI(EventSource *esp) {

   EventListener *elp;

@@ -141,7 +148,8 @@ void chEvtBroadcastI(EventSource *esp) {
 }

 

 /**

- * Invokes the event handlers associated with a mask.

+ * @brief Invokes the event handlers associated with a mask.

+ *

  * @param mask mask of the events to be dispatched

  * @param handlers an array of @p evhandler_t. The array must be

  *                 have indexes from zero up the higher registered event

@@ -163,8 +171,9 @@ void chEvtDispatch(const evhandler_t handlers[], eventmask_t mask) {
 #if defined(CH_OPTIMIZE_SPEED) || !defined(CH_USE_EVENTS_TIMEOUT) || \

     defined(__DOXIGEN__)

 /**

- * A pending event among those specified in @p ewmask is selected, cleared and

- * its mask returned.

+ * @brief A pending event among those specified in @p ewmask is selected,

+ * cleared and its mask returned.

+ *

  * @param 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.

@@ -192,9 +201,10 @@ eventmask_t chEvtWaitOne(eventmask_t ewmask) {
 }

 

 /**

- * Waits for any of the specified events.

- * The function waits for any event among those specified in @p ewmask to

- * become pending then the events are cleared and returned.

+ * @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.

+ *

  * @param 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.

@@ -216,9 +226,10 @@ eventmask_t chEvtWaitAny(eventmask_t ewmask) {
 }

 

 /**

- * Waits for all the specified event flags then clears them.

- * The function waits for all the events specified in @p ewmask to become

- * pending then the events are cleared and returned.

+ * @brief Waits for all the specified event flags then clears them.

+ * @details The function waits for all the events specified in @p ewmask to

+ * become pending then the events are cleared and returned.

+ *

  * @param ewmask mask of the event ids that the function should wait for

  * @return The mask of the served and cleared events.

  */

@@ -239,9 +250,10 @@ eventmask_t chEvtWaitAll(eventmask_t ewmask) {
 

 #ifdef CH_USE_EVENTS_TIMEOUT

 /**

- * Waits for a single event.

- * A pending event among those specified in @p ewmask is selected, cleared and

- * its mask returned.

+ * @brief Waits for a single event.

+ * @details A pending event among those specified in @p ewmask is selected,

+ * cleared and its mask returned.

+ *

  * @param ewmask mask of the events that the function should wait for,

  *               @p ALL_EVENTS enables all the events

  * @param time the number of ticks before the operation timouts

@@ -272,9 +284,10 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t ewmask, systime_t time) {
 }

 

 /**

- * Waits for any of the specified events.

- * The function waits for any event among those specified in @p ewmask to

- * become pending then the events are cleared and returned.

+ * @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.

+ *

  * @param ewmask mask of the events that the function should wait for,

  *               @p ALL_EVENTS enables all the events

  * @param time the number of ticks before the operation timouts

@@ -299,9 +312,10 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t ewmask, systime_t time) {
 }

 

 /**

- * Waits for all the specified event flags then clears them.

- * The function waits for all the events specified in @p ewmask to become

- * pending then the events are cleared and returned.

+ * @brief Waits for all the specified event flags then clears them.

+ * @details The function waits for all the events specified in @p ewmask to

+ * become pending then the events are cleared and returned.

+ *

  * @param ewmask mask of the event ids that the function should wait for

  * @param time the number of ticks before the operation timouts

  * @return The mask of the served and cleared events.

diff --git a/src/chheap.c b/src/chheap.c
index 98bff9c43..8ba55f9ad 100644
--- a/src/chheap.c
+++ b/src/chheap.c
@@ -63,7 +63,8 @@ static struct {
 } heap;

 

 /**

- * Initializes the allocator subsystem.

+ * @brief Initializes the allocator subsystem.

+ *

  * @note It is internally invoked, this function should not normally be

  *       invoked from the user code.

  */

@@ -92,9 +93,11 @@ void chHeapInit(void) {
 }

 

 /**

- * Allocates a block of memory from the heap by using the first-fit algorithm.

- * The allocated block is guaranteed to be properly aligned for a pointer data

- * type.

+ * @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.

+ *

  * @param 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.

@@ -142,7 +145,8 @@ void *chHeapAlloc(size_t size) {
                                    (p)->h_size)

 

 /**

- * Frees a previously allocated memory block.

+ * @brief Frees a previously allocated memory block.

+ *

  * @param p the memory block pointer

  */

 void chHeapFree(void *p) {

@@ -184,7 +188,8 @@ void chHeapFree(void *p) {
 }

 

 /**

- * Determines the heap status.

+ * @brief Reports the heap status.

+ *

  * @param sizep pointer to a variable that will receive the total fragmented

  *              free space

  * @return The number of fragments in the heap.

diff --git a/src/chlists.c b/src/chlists.c
index 397529bbe..ece7e7dd9 100644
--- a/src/chlists.c
+++ b/src/chlists.c
@@ -25,13 +25,13 @@
 

 #if !defined(CH_OPTIMIZE_SPEED) || defined(__DOXIGEN__)

 /**

- * Inserts a thread into a priority ordered queue.

+ * @brief Inserts a thread into a priority ordered queue.

  *

  * @param tp the pointer to the thread to be inserted in the list

  * @param tqp the pointer to the threads list header

  * @note The insertion is done by scanning the list from the highest priority

  *       toward the lowest.

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 void prio_insert(Thread *tp, ThreadsQueue *tqp) {

 

@@ -48,11 +48,11 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
 }

 

 /**

- * Inserts a Thread into a queue.

+ * @brief Inserts a Thread into a queue.

  *

  * @param tp the pointer to the thread to be inserted in the list

  * @param tqp the pointer to the threads list header

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 void queue_insert(Thread *tp, ThreadsQueue *tqp) {

 

@@ -61,11 +61,11 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
 }

 

 /**

- * Removes the first-out Thread from a queue and returns it.

+ * @brief Removes the first-out Thread from a queue and returns it.

  *

  * @param tqp the pointer to the threads list header

  * @return The removed thread pointer.

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 Thread *fifo_remove(ThreadsQueue *tqp) {

   Thread *tp = tqp->p_next;

@@ -75,11 +75,11 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
 }

 

 /**

- * Removes the last-out Thread from a queue and returns it.

+ * @brief Removes the last-out Thread from a queue and returns it.

  *

  * @param tqp the pointer to the threads list header

  * @return The removed thread pointer.

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 Thread *lifo_remove(ThreadsQueue *tqp) {

   Thread *tp = tqp->p_next;

@@ -89,11 +89,11 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
 }

 

 /**

- * Removes a Thread from a FIFO list and returns it.

+ * @brief Removes a Thread from a FIFO list and returns it.

  *

  * @param tp the pointer to the thread to be removed from the list

  * @return The removed thread pointer.

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 Thread *dequeue(Thread *tp) {

 

@@ -103,11 +103,11 @@ Thread *dequeue(Thread *tp) {
 }

 

 /**

- * Pushes a Thread on top of a stack list.

+ * @brief Pushes a Thread on top of a stack list.

  *

  * @param tp the pointer to the thread to be inserted in the list

  * @param tlp the pointer to the threads list header

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 void list_insert(Thread *tp, ThreadsList *tlp) {

 

@@ -116,12 +116,12 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
 }

 

 /**

- * Pops a Thread from the top of a stack list and returns it.

+ * @brief Pops a Thread from the top of a stack list and returns it.

  *

  * @param tlp the pointer to the threads list header

  * @return The removed thread pointer.

  * @note The list must be non-empty before calling this function.

- * @note This function is \b not an API.

+ * @note This function is @b not an API.

  */

 Thread *list_remove(ThreadsList *tlp) {

 

diff --git a/src/chmempools.c b/src/chmempools.c
index fac9db851..caaa60c44 100644
--- a/src/chmempools.c
+++ b/src/chmempools.c
@@ -27,7 +27,8 @@
 #ifdef CH_USE_MEMPOOLS

 

 /**

- * Initializes an empty memory pool.

+ * @brief Initializes an empty memory pool.

+ *

  * @param mp pointer to a @p MemoryPool structure

  * @param size the size of the objects contained in this memory pool

  */

@@ -41,7 +42,8 @@ void chPoolInit(MemoryPool *mp, size_t size) {
 }

 

 /**

- * Allocates an object from a memory pool.

+ * @brief Allocates an object from a memory pool.

+ *

  * @param mp pointer to a @p MemoryPool structure

  * @return The pointer to the allocated object.

  * @retval NULL if pool is empty.

@@ -58,7 +60,8 @@ void *chPoolAllocI(MemoryPool *mp) {
 }

 

 /**

- * Allocates an object from a memory pool.

+ * @brief Allocates an object from a memory pool.

+ *

  * @param mp pointer to a @p MemoryPool structure

  * @return The pointer to the allocated object.

  * @retval NULL if pool is empty.

@@ -73,7 +76,8 @@ void *chPoolAlloc(MemoryPool *mp) {
 }

 

 /**

- * Releases (or adds) an object into (to) a memory pool.

+ * @brief Releases (or adds) an object into (to) a memory pool.

+ *

  * @param mp pointer to a @p MemoryPool structure

  * @param 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

@@ -90,7 +94,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
 }

 

 /**

- * Releases (or adds) an object into (to) a memory pool.

+ * @brief Releases (or adds) an object into (to) a memory pool.

+ *

  * @param mp pointer to a @p MemoryPool structure

  * @param 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

diff --git a/src/chmsg.c b/src/chmsg.c
index f53e84030..6f253067c 100644
--- a/src/chmsg.c
+++ b/src/chmsg.c
@@ -25,8 +25,9 @@
 

 #ifdef CH_USE_MESSAGES

 /**

- * Sends a message to the specified thread. The client is stopped until the

- * server executes a @p chMsgRelease() after receiving the message.

+ * @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 tp the pointer to the thread

  * @param msg the message, it can be a pointer to a complex structure

@@ -54,9 +55,10 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
 

 #ifdef CH_USE_MESSAGES_EVENT

 /**

- * Sends a message to the specified thread and atomically triggers an event.

- * The client is stopped until the server executes a @p chMsgRelease()

- * after receiving the message.

+ * @brief Sends a message to the specified thread and atomically triggers

+ * an event.

+ * @details The sender is stopped until the receiver executes a

+ * @p chMsgRelease() after receiving the message.

  *

  * @param tp the pointer to the thread

  * @param msg the message, it can be a pointer to a complex structure

@@ -88,7 +90,7 @@ msg_t chMsgSendWithEvent(Thread *tp, msg_t msg, EventSource *esp) {
 #endif

 

 /**

- * Suspends the thread and waits for an incoming message.

+ * @brief Suspends the thread and waits for an incoming message.

  *

  * @return The pointer to the message structure. Note, it is always the

  *         message associated to the thread on the top of the messages queue.

@@ -110,7 +112,7 @@ msg_t chMsgWait(void) {
 }

 

 /**

- * Returns the next message in the queue.

+ * @brief Returns the next message in the queue.

  *

  * @return The pointer to the message structure. Note, it is always the

  *         message associated to the thread on the top of the messages queue.

@@ -132,7 +134,7 @@ msg_t chMsgGet(void) {
 }

 

 /**

- * Releases the thread waiting on top of the messages queue.

+ * @brief Releases the thread waiting on top of the messages queue.

  *

  * @param msg the message returned to the message sender

  * @note You can call this function only if there is a message already in the

diff --git a/src/chmtx.c b/src/chmtx.c
index 8288cfe89..47d1d7969 100644
--- a/src/chmtx.c
+++ b/src/chmtx.c
@@ -27,8 +27,12 @@
 #ifdef CH_USE_MUTEXES
 
 /**
- * Initializes s @p Mutex structure.
+ * @brief Initializes s @p Mutex structure.
+ *
  * @param 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.
  */
 void chMtxInit(Mutex *mp) {
 
@@ -37,7 +41,8 @@ void chMtxInit(Mutex *mp) {
 }
 
 /**
- * Locks the specified mutex.
+ * @brief Locks the specified mutex.
+ *
  * @param mp pointer to the @p Mutex structure
  */
 void chMtxLock(Mutex *mp) {
@@ -50,7 +55,7 @@ void chMtxLock(Mutex *mp) {
 }
 
 /**
- * Locks the specified mutex.
+ * @brief Locks the specified mutex.
  *
  * @param mp pointer to the @p Mutex structure
  * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
@@ -110,9 +115,11 @@ void chMtxLockS(Mutex *mp) {
 }
 
 /**
- * Tries to lock a mutex. This function does not have any overhead related to
+ * @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 mp pointer to the @p Mutex structure
  * @retval TRUE if the mutex was successfully acquired
  * @retval FALSE if the lock attempt failed.
@@ -129,7 +136,8 @@ bool_t chMtxTryLock(Mutex *mp) {
 }
 
 /**
- * Tries to lock a mutex. This function does not have any overhead related to
+ * @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 mp pointer to the @p Mutex structure
@@ -149,7 +157,8 @@ bool_t chMtxTryLockS(Mutex *mp) {
 }
 
 /**
- * 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.
  */
 Mutex *chMtxUnlock(void) {
@@ -194,7 +203,8 @@ Mutex *chMtxUnlock(void) {
 }
 
 /**
- * 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.
  * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
  *       block.
@@ -234,10 +244,11 @@ Mutex *chMtxUnlockS(void) {
 }
 
 /**
- * Unlocks all the mutexes owned by the invoking thread, this 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 inheritance mechanism.
+ * @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 inheritance mechanism
+ * too.
  */
 void chMtxUnlockAll(void) {
 
diff --git a/src/chqueues.c b/src/chqueues.c
index f7cc10f42..ed0806c6d 100644
--- a/src/chqueues.c
+++ b/src/chqueues.c
@@ -27,8 +27,10 @@
 #ifdef CH_USE_QUEUES

 

 /**

- * Initializes an input queue. A Semaphore is internally initialized

- * and works as a counter of the bytes contained in the queue.

+ * @brief Initializes an input queue.

+ * @details A Semaphore is internally initialized and works as a counter of

+ * the bytes contained in the queue.

+ *

  * @param qp pointer to a @p Queue structure

  * @param buffer pointer to a memory area allocated as queue buffer

  * @param size size of the queue buffer

@@ -44,8 +46,9 @@ void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
 }

 

 /**

- * Resets an input queue. All the data is lost and the waiting threads

- * resumed.

+ * @brief Resets an input queue.

+ * @details All the data is lost and the waiting threads resumed.

+ *

  * @param qp pointer to a @p Queue structure

  */

 void chIQReset(Queue *qp) {

@@ -59,7 +62,8 @@ void chIQReset(Queue *qp) {
 }

 

 /**

- * Inserts a byte into an input queue.

+ * @brief Inserts a byte into an input queue.

+ *

  * @param qp pointer to a @p Queue structure

  * @param b the byte value to be written

  * @retval Q_OK if the operation is successful.

@@ -81,8 +85,10 @@ msg_t chIQPutI(Queue *qp, uint8_t b) {
 }

 

 /**

- * Gets a byte from the input queue, if the queue is empty then the

- * calling thread is suspended until a byte arrives in the queue.

+ * @brief Gets a byte from the input queue.

+ * @details If the queue is empty then the calling thread is suspended until

+ * a byte arrives in the queue.

+ *

  * @param qp pointer to a @p Queue structure

  * @return A byte value from the queue.

  * @retval Q_RESET if the queue was reset.

@@ -110,9 +116,10 @@ msg_t chIQGet(Queue *qp) {
 

 #if defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT)

 /**

- * Gets a byte from the input queue, if the queue is empty then the

- * calling thread is suspended until a byte arrives in the queue or the

- * specified time expires.

+ * @brief Gets a byte from the input queue.

+ * @details If the queue is empty then the calling thread is suspended until

+ * a byte arrives in the queue or the specified time expires.

+ *

  * @param qp pointer to a @p Queue structure

  * @param time the number of ticks before the operation timouts

  * @return A byte value from the queue.

@@ -145,8 +152,10 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) {
 #endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */

 

 /**

- * Reads some data from the input queue into the specified buffer. The function

- * is non-blocking and can return zero if the queue is empty.

+ * @brief Reads some data from the input queue into the specified buffer.

+ * @details The function is non-blocking and can return zero if the queue is

+ * empty.

+ *

  * @param qp pointer to a @p Queue structure

  * @param buffer the data buffer

  * @param n the maximum amount of data to be read

@@ -187,8 +196,10 @@ size_t chIQRead(Queue *qp, uint8_t *buffer, size_t n) {
 }

 

 /**

- * Initializes an output queue. A Semaphore is internally initialized

- * and works as a counter of the free bytes in the queue.

+ * @brief Initializes an output queue.

+ * @details A Semaphore is internally initialized and works as a counter of the

+ * free bytes in the queue.

+ *

  * @param qp pointer to a @p Queue structure

  * @param buffer pointer to a memory area allocated as queue buffer

  * @param size size of the queue buffer

@@ -204,8 +215,9 @@ void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
 }

 

 /**

- * Resets an Output Queue. All the data is lost and the waiting threads

- * resumed.

+ * @brief Resets an Output Queue.

+ * @details All the data is lost and the waiting threads resumed.

+ *

  * @param qp pointer to a @p Queue structure

  */

 void chOQReset(Queue *qp) {

@@ -219,8 +231,10 @@ void chOQReset(Queue *qp) {
 }

 

 /**

- * Inserts a byte in the output queue, if the queue is full then the thread

- * is suspended until the queue has free space available.

+ * @brief Inserts a byte in the output queue.

+ * @details If the queue is full then the thread is suspended until the queue

+ * has free space available.

+ *

  * @param qp pointer to a @p Queue structure

  * @param b the byte value to be written

  */

@@ -240,7 +254,8 @@ void chOQPut(Queue *qp, uint8_t b) {
 }

 

 /**

- * Gets a byte from an output queue.

+ * @brief Gets a byte from an output queue.

+ *

  * @param qp pointer to a @p Queue structure

  * @return The byte value from the queue.

  * @retval Q_EMPTY if the queue is empty.

@@ -262,8 +277,10 @@ msg_t chOQGetI(Queue *qp) {
 }

 

 /**

- * Writes some data from the specified buffer into the queue. The function

- * is non-blocking and can return zero if the queue is full.

+ * @brief Writes some data from the specified buffer into the queue.

+ * @details The function is non-blocking and can return zero if the queue is

+ * full.

+ *

  * @param qp pointer to a @p Queue structure

  * @param buffer the data buffer

  * @param n the maximum amount of data to be written

@@ -306,7 +323,8 @@ size_t chOQWrite(Queue *qp, uint8_t *buffer, size_t n) {
 

 #ifdef CH_USE_QUEUES_HALFDUPLEX

  /**

- * Initializes an half duplex queue.

+ * @brief Initializes an half duplex queue.

+ *

  * @param qp pointer to the @p HalfDuplexQueue structure

  * @param buffer pointer to a memory area allocated as buffer for the queue

  * @param size the size of the queue buffer

@@ -327,8 +345,10 @@ void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
 }

 

 /**

- * Reads a byte from the receive queue, if the queue is empty or is in

- * transmission mode then the invoking thread is suspended.

+ * @brief Reads a byte from the receive queue.

+ * @details If the queue is empty or is in transmission mode then the invoking

+ * thread is suspended.

+ *

  * @param qp pointer to a @p HalfDuplexQueue structure

  * @return The byte value.

  * @retval Q_RESET if the queue was reset.

@@ -360,8 +380,10 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) {
 

 #if defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT)

 /**

- * Reads a byte from the receive queue, if the queue is empty or is in

- * transmission mode then the invoking thread is suspended.

+ * @brief Reads a byte from the receive queue.

+ * @details If the queue is empty or is in transmission mode then the invoking

+ * thread is suspended.

+ *

  * @param qp pointer to a @p HalfDuplexQueue structure

  * @param time the number of ticks before the operation timouts

  * @return The byte value.

@@ -397,9 +419,10 @@ msg_t chHDQGetReceiveTimeout(HalfDuplexQueue *qp, systime_t time) {
 #endif /* defined(CH_USE_QUEUES_TIMEOUT) && defined(CH_USE_SEMAPHORES_TIMEOUT) */

 

 /**

- * Writes a byte into the transmit queue. If the buffer contains unread

- * input data then the the buffer is cleared and the queue goes in

- * transmission mode.

+ * @brief Writes a byte into the transmit queue.

+ * @details If the buffer contains unread input data then the the buffer is

+ * cleared and the queue goes in transmission mode.

+ *

  * @param qp pointer to a @p HalfDuplexQueue structure

  * @param b the byte value to be written

  */

@@ -430,7 +453,8 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
 }

 

 /**

- * Gets a byte from the transmit queue.

+ * @brief Gets a byte from the transmit queue.

+ *

  * @param qp pointer to a @p HalfDuplexQueue structure

  * @return The byte value.

  * @retval Q_EMPTY if the transmit queue is empty (not in transmission mode).

@@ -451,8 +475,9 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) {
 }

 

 /**

- * Writes a byte into the receive queue. If the queue is in transmission mode

- * then the byte is lost.

+ * @brief Writes a byte into the receive queue.

+ * @details If the queue is in transmission mode then the byte is lost.

+ *

  * @param qp pointer to a @p HalfDuplexQueue structure

  * @param b the byte value to be written

  * @retval Q_OK if the operation is successful.

diff --git a/src/chschd.c b/src/chschd.c
index 91a9ea0b0..913cac83d 100644
--- a/src/chschd.c
+++ b/src/chschd.c
@@ -29,7 +29,7 @@ ReadyList rlist;
 /** @endcond */
 
 /**
- * Scheduler initialization.
+ * @brief Scheduler initialization.
  * @note Internally invoked by the @p chSysInit().
  */
 void chSchInit(void) {
@@ -42,7 +42,7 @@ void chSchInit(void) {
 }
 
 /**
- * Inserts a thread in the Ready List.
+ * @brief Inserts a thread in the Ready List.
  *
  * @param tp the Thread to be made ready
  * @return The Thread pointer.
@@ -70,9 +70,10 @@ Thread *chSchReadyI(Thread *tp) {
 }
 
 /**
- * Puts the current thread to sleep into the specified state, the next highest
- * priority thread becomes running. The threads states are described into
- * @p threads.h
+ * @brief Puts the current thread to sleep into the specified state.
+ * @details The next highest priority thread becomes running. The threads
+ * states are described into @p threads.h.
+ *
  * @param newstate the new thread state
  * @note The function must be called in the system mutex zone.
  * @note The function is not meant to be used in the user code directly.
@@ -104,11 +105,9 @@ static void wakeup(void *p) {
 }
 
 /**
- * Puts the current thread to sleep.
- *
- * Puts the current thread to sleep into the specified state. The next highest
- * priority thread becomes running. The thread put to sleep is awakened after
- * the specified time has elapsed.
+ * @brief Puts the current thread to sleep into the specified state.
+ * @details The next highest priority thread becomes running. The thread put
+ * to sleep is awakened after the specified time has elapsed.
  *
  * @param newstate the new thread state
  * @param time the number of ticks before the operation timeouts. the value
@@ -134,10 +133,10 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
 }
 
 /**
- * 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.
  *
- * The thread is inserted into the ready list or immediately made running
- * depending on its relative priority compared to the current thread.
  * @param ntp the Thread to be made ready
  * @param msg message to the awakened thread
  * @note The function must be called in the system mutex zone.
@@ -170,7 +169,7 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
 }
 
 /**
- * Switch to the first thread on the runnable queue.
+ * @brief Switches to the first thread on the runnable queue.
  *
  * @note It is intended to be called if @p chSchRescRequiredI() evaluates to @p TRUE.
  */
@@ -190,10 +189,9 @@ void chSchDoRescheduleI(void) {
 }
 
 /**
- * Reschedule only if a higher priority thread is runnable.
- *
- * If a thread with a higher priority than the current thread is in the
- * ready list then make the higher priority thread running.
+ * @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.
  *
  * @note The function must be called in the system mutex zone.
  */
@@ -205,7 +203,7 @@ void chSchRescheduleS(void) {
 }
 
 /**
- * Evaluates if rescheduling is required.
+ * @brief Evaluates if a reschedulation is required.
  *
  * @retval TRUE if there is a thread that should go in running state.
  * @retval FALSE if a reschedulation is not required.
diff --git a/src/chsem.c b/src/chsem.c
index 094a30d4e..3af4854f5 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -26,10 +26,13 @@
 

 #ifdef CH_USE_SEMAPHORES

 /**

- * Initializes a semaphore with the specified counter value.

+ * @brief Initializes a semaphore with the specified counter value.

+ *

  * @param sp pointer to a @p Semaphore structure

  * @param n initial value of the semaphore counter. Must be non-negative.

- * @note Can be called with interrupts disabled or enabled.

+ * @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.

  */

 void chSemInit(Semaphore *sp, cnt_t n) {

 

@@ -39,7 +42,8 @@ void chSemInit(Semaphore *sp, cnt_t n) {
 }

 

 /**

- * Performs a reset operation on the semaphore.

+ * @brief Performs a reset operation on the semaphore.

+ *

  * @param sp pointer to a @p Semaphore structure

  * @param 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

@@ -57,7 +61,8 @@ void chSemReset(Semaphore *sp, cnt_t n) {
 }

 

 /**

- * Performs a reset operation on the semaphore.

+ * @brief Performs a reset operation on the semaphore.

+ *

  * @param sp pointer to a @p Semaphore structure

  * @param 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

@@ -76,7 +81,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
 }

 

 /**

- * Performs a wait operation on a semaphore.

+ * @brief Performs a wait operation on a semaphore.

+ *

  * @param 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().

@@ -93,7 +99,8 @@ msg_t chSemWait(Semaphore *sp) {
 }

 

 /**

- * Performs a wait operation on a semaphore.

+ * @brief Performs a wait operation on a semaphore.

+ *

  * @param 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().

@@ -113,7 +120,8 @@ msg_t chSemWaitS(Semaphore *sp) {
 

 #ifdef CH_USE_SEMAPHORES_TIMEOUT

 /**

- * Performs a wait operation on a semaphore with timeout specification.

+ * @brief Performs a wait operation on a semaphore with timeout specification.

+ *

  * @param sp pointer to a @p Semaphore structure

  * @param time the number of ticks before the operation fails

  * @retval RDY_OK if the semaphore was signaled or not taken.

@@ -135,7 +143,8 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
 }

 

 /**

- * Performs a wait operation on a semaphore with timeout specification.

+ * @brief Performs a wait operation on a semaphore with timeout specification.

+ *

  * @param sp pointer to a @p Semaphore structure

  * @param time the number of ticks before the operation fails

  * @retval RDY_OK if the semaphore was signaled or not taken.

@@ -157,7 +166,8 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
 #endif /* CH_USE_SEMAPHORES_TIMEOUT */

 

 /**

- * Performs a signal operation on a semaphore.

+ * @brief Performs a signal operation on a semaphore.

+ *

  * @param 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.

@@ -173,7 +183,8 @@ void chSemSignal(Semaphore *sp) {
 }

 

 /**

- * Performs a signal operation on a semaphore.

+ * @brief Performs a signal operation on a semaphore.

+ *

  * @param 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.

@@ -192,7 +203,8 @@ void chSemSignalI(Semaphore *sp) {
 

 #ifdef CH_USE_SEMSW

 /**

- * Performs atomic signal and wait operations on two semaphores.

+ * @brief Performs atomic signal and wait operations on two semaphores.

+ *

  * @param sps pointer to a @p Semaphore structure to be signaled

  * @param spw pointer to a @p Semaphore structure to be wait on

  * @retval RDY_OK if the semaphore was signaled or not taken.

diff --git a/src/chserial.c b/src/chserial.c
index c41bc2c4a..91a4834ab 100644
--- a/src/chserial.c
+++ b/src/chserial.c
@@ -26,9 +26,10 @@
 

 #ifdef CH_USE_SERIAL_FULLDUPLEX

 /**

- * Initializes a generic full duplex driver. The HW dependent part of the

- * initialization has to be performed outside, usually in the hardware

- * initialization code.

+ * @brief Initializes a generic full duplex driver.

+ * @details The HW dependent part of the initialization has to be performed

+ * outside, usually in the hardware initialization code.

+ *

  * @param sd pointer to a @p FullDuplexDriver structure

  * @param ib pointer to a memory area allocated for the Input Queue buffer

  * @param isize size of the Input Queue buffer

@@ -52,8 +53,9 @@ void chFDDInit(FullDuplexDriver *sd,
 }

 

 /**

- * This function must be called from the input interrupt service routine in

- * order to enqueue incoming data and generate the related events.

+ * @brief Handles incoming data.

+ * @details This function must be called from the input interrupt service

+ * routine in order to enqueue incoming data and generate the related events.

  * @param sd pointer to a @p FullDuplexDriver structure

  * @param b the byte to be written in the driver's Input Queue

  */

@@ -66,8 +68,9 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
 }

 

 /**

- * Must be called from the output interrupt service routine in order to get

- * the next byte to be transmitted.

+ * @brief Handles outgoing data.

+ * @details Must be called from the output interrupt service routine in order

+ * to get the next byte to be transmitted.

  *

  * @param sd pointer to a @p FullDuplexDriver structure

  * @return The byte value read from the driver's output queue.

@@ -83,8 +86,10 @@ msg_t chFDDRequestDataI(FullDuplexDriver *sd) {
 }

 

 /**

- * Must be called from the I/O interrupt service routine in order to

+ * @brief Handles communication events/errors.

+ * @details Must be called from the I/O interrupt service routine in order to

  * notify I/O conditions as errors, signals change etc.

+ *

  * @param sd pointer to a @p FullDuplexDriver structure

  * @param mask condition flags to be added to the mask

  */

@@ -95,7 +100,8 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
 }

 

 /**

- * This function returns and clears the errors mask associated to the driver.

+ * @brief Returns and clears the errors mask associated to the driver.

+ *

  * @param sd pointer to a @p FullDuplexDriver structure

  * @return The condition flags modified since last time this function was

  *         invoked.

@@ -111,9 +117,10 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {
 

 #ifdef CH_USE_SERIAL_HALFDUPLEX

 /**

- * Initializes a generic half duplex driver. The HW dependent part of the

- * initialization has to be performed outside, usually in the hardware

- * initialization code.

+ * @brief Initializes a generic half duplex driver.

+ * @details The HW dependent part of the initialization has to be performed

+ * outside, usually in the hardware initialization code.

+ *

  * @param sd pointer to a @p HalfDuplexDriver structure

  * @param b pointer to a memory area allocated for the queue buffer

  * @param size the buffer size

@@ -133,8 +140,9 @@ void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
 }

 

 /**

- * This function must be called from the input interrupt service routine in

- * order to enqueue incoming data and generate the related events.

+ * @brief Handles incoming data.

+ * @details This function must be called from the input interrupt service

+ * routine in order to enqueue incoming data and generate the related events.

  * @param sd pointer to a @p FullDuplexDriver structure

  * @param b the byte to be written in the driver's input queue

  */

@@ -147,8 +155,9 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
 }

 

 /**

- * Must be called from the output interrupt service routine in order to get

- * the next byte to be transmitted.

+ * @brief Handles outgoing data.

+ * @brief Must be called from the output interrupt service routine in order

+ * to get the next byte to be transmitted.

  *

  * @param sd pointer to a @p HalfDuplexDriver structure

  * @return The byte value read from the driver's output queue.

@@ -164,8 +173,10 @@ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {
 }

 

 /**

- * Must be called from the I/O interrupt service routine in order to

+ * @brief Handles communication events/errors.

+ * @details Must be called from the I/O interrupt service routine in order to

  * notify I/O conditions as errors, signals change etc.

+ *

  * @param sd pointer to a @p HalfDuplexDriver structure

  * @param mask condition flags to be added to the mask

  */

@@ -176,7 +187,8 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
 }

 

 /**

- * This function returns and clears the errors mask associated to the driver.

+ * @brief Returns and clears the errors mask associated to the driver.

+ *

  * @param sd pointer to a @p HalfDuplexDriver structure

  * @return The condition flags modified since last time this function was

  *         invoked.

diff --git a/src/chsys.c b/src/chsys.c
index 71eb59d98..1629796dd 100644
--- a/src/chsys.c
+++ b/src/chsys.c
@@ -27,10 +27,12 @@
 static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
 
 /**
- * This function implements the idle thread infinite loop. The function should
- * put the processor in the lowest power mode capable to serve interrupts.
+ * @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 that this
  * thread is executed only if there are no other ready threads in the system.
+ *
  * @param p the thread parameter, unused in this scenario
  * @note Implementation should declare this function as a weak symbol in order
  *       to allow applications to re-implement it.
@@ -43,8 +45,10 @@ static void idle_thread(void *p) {
 }
 
 /**
- * ChibiOS/RT initialization. After executing this function the current
- * instructions stream becomes the main thread.
+ * @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.
@@ -77,10 +81,10 @@ void chSysInit(void) {
 }
 
 /**
- * Handles time ticks for round robin preemption and timer increments.
- * 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.
+ * @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.
  */
diff --git a/src/chthreads.c b/src/chthreads.c
index dfa413641..355687423 100644
--- a/src/chthreads.c
+++ b/src/chthreads.c
@@ -64,9 +64,10 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) {
 #endif
 
 /**
- * Initializes a new thread.
- * The new thread is initialized but not inserted in the ready list, the
- * initial state is @p PRSUSPENDED.
+ * @brief Initializes a new thread.
+ * @details The new thread is initialized but not inserted in the ready list,
+ * the initial state is @p PRSUSPENDED.
+ *
  * @param prio the priority level for the new thread. Usually the threads are
  *             created with priority @p NORMALPRIO, priorities
  *             can range from @p LOWPRIO to @p HIGHPRIO.
@@ -78,7 +79,9 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) {
  *         thread into the working space area.
  * @note A thread can terminate by calling @p chThdExit() or by simply
  *       returning from its main function.
- * @note This function can be invoked from within an interrupt handler.
+ * @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.
  */
 Thread *chThdInit(void *workspace, size_t wsize,
                   tprio_t prio, tfunc_t pf, void *arg) {
@@ -96,7 +99,8 @@ Thread *chThdInit(void *workspace, size_t wsize,
 }
 
 /**
- * Creates a new thread into a static memory area.
+ * @brief Creates a new thread into a static memory area.
+ *
  * @param workspace pointer to a working area dedicated to the thread stack
  * @param wsize size of the working area.
  * @param prio the priority level for the new thread. Usually the threads are
@@ -117,7 +121,8 @@ Thread *chThdCreateStatic(void *workspace, size_t wsize,
 
 #if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_HEAP)
 /**
- * Creates a new thread allocating the memory from the heap.
+ * @brief Creates a new thread allocating the memory from the heap.
+ *
  * @param wsize size of the working area to be allocated
  * @param prio the priority level for the new thread. Usually the threads are
  *             created with priority @p NORMALPRIO, priorities
@@ -149,7 +154,9 @@ Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio,
 
 #if defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS)
 /**
- * Creates a new thread allocating the memory from the specified Memory Pool.
+ * @brief Creates a new thread allocating the memory from the specified Memory
+ * Pool.
+ *
  * @param mp the memory pool
  * @param prio the priority level for the new thread. Usually the threads are
  *             created with priority @p NORMALPRIO, priorities
@@ -182,7 +189,7 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
 #endif /* defined(CH_USE_DYNAMIC) && defined(CH_USE_WAITEXIT) && defined(CH_USE_MEMPOOLS) */
 
 /**
- * Changes the running thread priority, reschedules if necessary.
+ * @brief Changes the running thread priority then reschedules if necessary.
  *
  * @param newprio the new priority of the running thread
  */
@@ -208,13 +215,15 @@ void chThdSetPriority(tprio_t newprio) {
 }
 
 /**
- * Suspends the invoking thread.
+ * @brief Suspends the invoking thread.
  *
  * @param tpp pointer to a @p Thread pointer, the @p Thread pointer is set
  *            to point to the suspended process before it enters the
- *            @p PRSUSPENDED state, it is set to @p NULL after it is resumed.
- *            This allows to implement a "test and resume" on the variable
- *            into interrupt handlers.
+ *            @p PRSUSPENDED state. The variable pointed by this parameter
+ *            must be set to @p NULL on entry.
+ * @note The resume operation is meant to be executed into an interrupt or timer
+ *       handler. The handler is also responsible to clear the variable pointed
+ *       by @p tpp after invoking @p chThdResumeI().
  */
 void chThdSuspend(Thread **tpp) {
 
@@ -222,14 +231,16 @@ void chThdSuspend(Thread **tpp) {
   chDbgAssert(*tpp == NULL, "chthreads.c, chThdSuspend()");
   *tpp = currp;
   chSchGoSleepS(PRSUSPENDED);
-  *tpp = NULL;
   chSysUnlock();
 }
 
 /**
- * Resumes a suspended thread.
+ * @brief Resumes a suspended thread.
+ *
  * @param tp the pointer to the thread
  * @return The pointer to the thread.
+ * @note This call is supposed to resume threads created with @p chThdInit().
+ *       It should not be used on threads suspended using @p chThdSuspend().
  */
 Thread *chThdResume(Thread *tp) {
 
@@ -241,7 +252,8 @@ Thread *chThdResume(Thread *tp) {
 }
 
 /**
- * Requests a thread termination.
+ * @brief Requests a thread termination.
+ *
  * @param tp the pointer to the thread
  * @note The thread is not termitated but a termination request is added to
  *       its @p p_flags field. The thread can read this status by
@@ -255,7 +267,8 @@ void chThdTerminate(Thread *tp) {
 }
 
 /**
- * Suspends the invoking thread for the specified time.
+ * @brief Suspends the invoking thread for the specified time.
+ *
  * @param time the delay in system ticks
  */
 void chThdSleep(systime_t time) {
@@ -266,8 +279,9 @@ void chThdSleep(systime_t time) {
 }
 
 /**
- * Suspends the invoking thread until the system time arrives to the specified
- * value.
+ * @brief Suspends the invoking thread until the system time arrives to the
+ * specified value.
+ *
  * @param time the absolute system time
  */
 void chThdSleepUntil(systime_t time) {
@@ -279,7 +293,7 @@ void chThdSleepUntil(systime_t time) {
 }
 
 /**
- * Terminates the current thread by specifying an exit status code.
+ * @brief Terminates the current thread by specifying an exit status code.
  *
  * @param msg the thread exit code. The code can be retrieved by using
  *            @p chThdWait().
@@ -299,19 +313,18 @@ void chThdExit(msg_t msg) {
 
 #ifdef CH_USE_WAITEXIT
 /**
- * Blocks the execution of the invoking thread until the specified thread
- * terminates then the exit code is returned.
- * The memory used by the exited thread is handled in different ways depending
- * on the API that spawned the thread:
- * <ul>
- * <li>If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit()
- *     then nothing happens and the thread working area is not released or
- *     modified in any way. This is the default, totally static, behavior.</li>
- * <li>If the thread was spawned by @p chThdCreateFromHeap() then the working
- *     area is returned to the system heap.</li>
- * <li>If the thread was spawned by @p chThdCreateFromMemoryPool() then the
- *     working area is returned to the owning memory pool.</li>
- * </ul>
+ * @brief Blocks the execution of the invoking thread until the specified
+ * thread terminates then the exit code is returned.
+ * @details The memory used by the exited thread is handled in different ways
+ * depending on the API that spawned the thread:
+ * - If the thread was spawned by @p chThdCreateStatic() or by @p chThdInit()
+ *   then nothing happens and the thread working area is not released or
+ *   modified in any way. This is the default, totally static, behavior.
+ * - If the thread was spawned by @p chThdCreateFromHeap() then the working
+ *   area is returned to the system heap.
+ * - If the thread was spawned by @p chThdCreateFromMemoryPool() then the
+ *   working area is returned to the owning memory pool.
+ *
  * @param tp the thread pointer
  * @return The exit code from the terminated thread
  * @note After invoking @p chThdWait() the thread pointer becomes invalid and
diff --git a/src/chvt.c b/src/chvt.c
index 0071b1733..7f63437ad 100644
--- a/src/chvt.c
+++ b/src/chvt.c
@@ -27,7 +27,8 @@
 VTList vtlist;

 

 /**

- * Virtual Timers initialization.

+ * @brief Virtual Timers initialization.

+ *

  * @note Internal use only.

  */

 void chVTInit(void) {

@@ -38,15 +39,16 @@ void chVTInit(void) {
 }

 

 /**

- * Enables a virtual timer.

+ * @brief Enables a virtual timer.

+ *

  * @param vtp the @p VirtualTimer structure pointer

  * @param time the number of time ticks, the value zero is not allowed

  * @param vtfunc the timer callback function. After invoking the callback

  *               the timer is disabled and the structure can be disposed or

  *               reused.

  * @param par a parameter that will be passed to the callback function

- * @note Must be called with the interrupts disabled.

- * @note The associated function is invoked by an interrupt handler.

+ * @note The associated function is invoked by an interrupt handler within

+ *       the I-Locked state, see @ref system_states.

  */

 void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {

   VirtualTimer *p;

@@ -69,9 +71,9 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
 }

 

 /**

- * Disables a Virtual Timer.

+ * @brief Disables a Virtual Timer.

+ *

  * @param vtp the @p VirtualTimer structure pointer

- * @note It must be called with the interrupts disabled.

  * @note The timer MUST be active when this function is invoked.

  */

 void chVTResetI(VirtualTimer *vtp) {

@@ -84,7 +86,8 @@ void chVTResetI(VirtualTimer *vtp) {
 }

 

 /**

- * 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.

+ *

  * @param start the start of the time window (inclusive)

  * @param end the end of the time window (non inclusive)

  */

diff --git a/src/include/sys.h b/src/include/sys.h
index 0e08452d9..368d108aa 100644
--- a/src/include/sys.h
+++ b/src/include/sys.h
@@ -26,22 +26,24 @@
 #define _SYS_H_

 

 /**

- * Prints a message on the system console (if any).

+ * @brief Prints a message on the system console (if any).

  * @param msg the message to be printed on the system console

  */

 #define chSysPuts(msg) port_puts(msg)

 

 /**

- * Halts the system. This function is invoked by the operating system when an

+ * @brief Halts the system.

+ * @details This function is invoked by the operating system when an

  * unrecoverable error is detected (as example because a programming error in

  * the application code that triggers an assertion while in debug mode).

  */

 #define chSysHalt() port_halt()

 

 /**

- * Performs a context switch.

- * This is the most critical code in any port, this function is responsible

- * for the context switch between 2 threads.

+ * @brief Performs a context switch.

+ * @details This is the most critical code in any port, this function

+ * is responsible for the context switch between 2 threads.

+ *

  * @param otp the thread to be switched out

  * @param ntp the thread to be switched in

  * @note The implementation of this code affects <b>directly</b> the context

@@ -50,9 +52,10 @@
 #define chSysSwitchI(otp, ntp) port_switch(otp, ntp)

 

 /**

- * Raises the system interrupt priority mask to the maximum level.

- * All the maskable interrupt sources are disabled regardless their hardware

- * priority.

+ * @brief Raises the system interrupt priority mask to the maximum level.

+ * @details All the maskable interrupt sources are disabled regardless their

+ * hardware priority.

+ *

  * @note The implementation is architecture dependent, it may just disable the

  *       interrupts or be exactly equivalent to @p chSysDisable().

  * @note Do not invoke this API from within a kernel lock.

@@ -60,9 +63,10 @@
 #define chSysDisable() port_disable()

 

 /**

- * Raises the system interrupt priority mask to system level.

- * The interrupt sources that should not be able to preempt the kernel are

- * disabled, interrupt sources with higher priority are still enabled.

+ * @brief Raises the system interrupt priority mask to system level.

+ * @details The interrupt sources that should not be able to preempt the kernel

+ * are disabled, interrupt sources with higher priority are still enabled.

+ *

  * @note The implementation is architecture dependent, it may just disable the

  *       interrupts.

  * @note Do not invoke this API from within a kernel lock.

@@ -72,8 +76,9 @@
 #define chSysSuspend() port_suspend()

 

 /**

- * Lowers the system interrupt priority mask to user level.

- * All the interrupt sources are enabled.

+ * @brief Lowers the system interrupt priority mask to user level.

+ * @details All the interrupt sources are enabled.

+ *

  * @note The implementation is architecture dependent, it may just enable the

  *       interrupts.

  * @note Do not invoke this API from within a kernel lock.

@@ -83,7 +88,8 @@
 #define chSysEnable() port_enable()

 

 /**

- * Enters the kernel lock mode.

+ * @brief Enters the kernel lock mode.

+ *

  * @note The use of kernel lock mode is not recommended in the user code, it is

  *       a better idea to use the semaphores or mutexes instead.

  * @see CH_USE_NESTED_LOCKS

@@ -100,7 +106,8 @@
 #endif /* !defined(CH_USE_NESTED_LOCKS) */

 

 /**

- * Leaves the kernel lock mode.

+ * @brief Leaves the kernel lock mode.

+ *

  * @note The use of kernel lock mode is not recommended in the user code, it is

  *       a better idea to use the semaphores or mutexes instead.

  * @see CH_USE_NESTED_LOCKS

@@ -117,7 +124,8 @@
 #endif /* !defined(CH_USE_NESTED_LOCKS) */

 

 /**

- * Enters the kernel lock mode from within an interrupt handler.

+ * @brief Enters the kernel lock mode from within an interrupt handler.

+ *

  * @note This API may do nothing on some architectures, it is required because

  *       on ports that support preemptable interrupt handlers it is required to

  *       raise the interrupt mask to the same level of the system mutual

@@ -129,7 +137,8 @@
 #define chSysLockI() port_lock_from_isr()

 

 /**

- * Leaves the kernel lock mode from within an interrupt handler.

+ * @brief Leaves the kernel lock mode from within an interrupt handler.

+ *

  * @note This API may do nothing on some architectures, it is required because

  *       on ports that support preemptable interrupt handlers it is required to

  *       raise the interrupt mask to the same level of the system mutual

@@ -141,14 +150,16 @@
 #define chSysUnlockI() port_unlock_from_isr()

 

 /**

- * IRQ handler enter code.

+ * @brief IRQ handler enter code.

+ *

  * @note Usually IRQ handlers functions are also declared naked.

  * @note On some architectures this macro can be empty.

  */

 #define CH_IRQ_PROLOGUE() PORT_IRQ_PROLOGUE()

 

 /**

- * IRQ handler exit code.

+ * @brief IRQ handler exit code.

+ *

  * @note Usually IRQ handlers function are also declared naked.

  * @note This macro usually performs the final reschedulation by using

  *       @p chSchRescRequiredI() and @p chSchDoRescheduleI().

@@ -156,7 +167,8 @@
 #define CH_IRQ_EPILOGUE() PORT_IRQ_EPILOGUE()

 

 /**

- * Standard IRQ handler declaration.
+ * @brief Standard IRQ handler declaration.

+ *
  * @note @p id can be a function name or a vector number depending on the

  *       port implementation.

  */

diff --git a/src/lib/ch.hpp b/src/lib/ch.hpp
index 2d34a0563..4a052ed39 100644
--- a/src/lib/ch.hpp
+++ b/src/lib/ch.hpp
@@ -30,50 +30,55 @@
 namespace chibios_rt {

 

   /**

-   * Class encapsulating the base system functionalities.

+   * @brief Class encapsulating the base system functionalities.

    */

   class System {

   public:

     /**

-     * ChibiOS/RT initialization.

-     * The system is initialized, the idle thread is spawned and the current

-     * instruction flow becomes the main thread with priority @p NORMALPRIO.

+     * @brief ChibiOS/RT initialization.

+     * @details The system is initialized, the idle thread is spawned and the

+     * current instruction flow becomes the main thread with priority

+     * @p NORMALPRIO.

      */

     static void Init(void);

 

     /**

-     * Disables interrupts.

+     * @brief Kernel lock.

+     *

      * @note On some ports it is faster to invoke chSysLock() directly because

      *       inlining.

      */

     static void Lock(void);

 

     /**

-     * Enables interrupts.

+     * @brief Kernel unlock.

+     *

      * @note On some ports it is faster to invoke chSysUnlock() directly

      *       because inlining.

      */

     static void Unlock(void);

 

     /**

-     * Returns the system time as system ticks.

+     * @brief Returns the system time as system ticks.

+     *

      * @note the system tick time interval is implementation dependent.

      */

     static systime_t GetTime(void);

   };

 

   /**

-   * Timer class.

+   * @brief Timer class.

    */

   class Timer {

   public:

     /**

-     * Embedded @p VirtualTimer structure.
+     * @brief Embedded @p VirtualTimer structure.
      */

     struct ::VirtualTimer timer;

 

     /**

-     * Starts the timer.

+     * @brief Starts the timer.

+     *

      * @param time the time in system ticks

      * @param vtfunc the timer callback function

      * @param par the parameter for the callback function

@@ -83,14 +88,16 @@ namespace chibios_rt {
     void Set(systime_t time, vtfunc_t vtfunc, void *par);

 

     /**

-     * Resets the timer.

+     * @brief Resets the timer.

+     *

      * @note It must be called with the interrupts disabled.

      * @note The timer MUST be active when this function is invoked.

      */

     void Reset();

 

     /**

-     * Returns the timer status.

+     * @brief Returns the timer status.

+     *

      * @retval TRUE The timer is armed.

      * @retval FALSE The timer already fired its callback.

      */

@@ -98,19 +105,21 @@ namespace chibios_rt {
   };

 

   /**

-   * Base class for a ChibiOS/RT thread, the thread body is the virtual

-   * function @p Main().

+   * @brief Base class for a ChibiOS/RT thread.

+   * @details The thread body is the virtual function @p Main().

    */

   class BaseThread {

   public:

     /**

-     * Pointer to the system thread.
+     * @brief Pointer to the system thread.
      */

     ::Thread *thread_ref;

 

     /**

-     * Thread constructor.

-     * The thread object is initialized and a system thread is started.

+     * @brief Thread constructor.

+     * @details The thread object is initialized and a system thread is

+     * started.

+     *

      * @param workspace pointer to the workspace area

      * @param wsize size of the workspace area

      * @param prio thread priority

@@ -118,53 +127,60 @@ namespace chibios_rt {
     BaseThread(void *workspace, size_t wsize, tprio_t prio);

 

     /**

-     * Thread exit.

+     * @brief Thread exit.

+     *

      * @param msg the exit message

      */

     static void Exit(msg_t msg);

 

 #ifdef CH_USE_WAITEXIT

     /**

-     * Synchronization on Thread exit.

+     * @brief Synchronization on Thread exit.

+     *

      * @return the exit message from the thread

      */

     msg_t Wait(void);

 #endif /* CH_USE_WAITEXIT */

 

     /**

-     * Resumes the thread.

-     * The thread encapsulated into the object is resumed.

+     * @brief Resumes the thread.

+     * @details The thread encapsulated into the object is resumed.

      */

     void Resume(void);

 

     /**

-     * Change thread priority.

+     * @brief Changes the thread priority.

+     *

      * @param newprio the new priority level

      */

     static void SetPriority(tprio_t newprio);

 

     /**

-     * Requests thread termination.

-     * A termination flag is pended on the thread, it is thread responsibility

-     * to detect it and exit.

+     * @brief Requests thread termination.

+     * @details A termination flag is pended on the thread, it is thread

+     * responsibility to detect it and exit.

      */

     void Terminate(void);

 

     /**

-     * Suspends the thread execution for the specified number of system ticks.

+     * @brief Suspends the thread execution for the specified number of

+     * system ticks.

+     *

      * @param n the number of system ticks

      */

     static void Sleep(systime_t n);

 

     /**

-     * Suspends the thread execution until the specified time arrives.

+     * @brief Suspends the thread execution until the specified time arrives.

+     *

      * @param time the system time

      */

     static void SleepUntil(systime_t time);

 

 #ifdef CH_USE_MESSAGES

     /**

-     * Sends a message to the thread and returns the answer.

+     * @brief Sends a message to the thread and returns the answer.

+     *

      * @param tp the target thread

      * @param msg the sent message

      * @return The returned message.

@@ -172,33 +188,38 @@ namespace chibios_rt {
     static msg_t SendMessage(::Thread *tp, msg_t msg);

 

     /**

-     * Sends a message to the thread and returns the answer.

+     * @brief Sends a message to the thread and returns the answer.

+     *

      * @param msg the sent message

      * @return The returned message.

      */

     msg_t SendMessage(msg_t msg);

 

     /**

-     * Waits for a message and returns it.

+     * @brief Waits for a message and returns it.

+     *

      * @return The incoming message.

      */

     static msg_t WaitMessage(void);

 

     /**

-     * Returns an enqueued message or @p NULL.

+     * @brief Returns an enqueued message or @p NULL.

+     *

      * @return The incoming message.

      * @retval NULL No incoming message.

      */

     static msg_t GetMessage(void);

 

     /**

-     * Releases the next message in queue with a reply.

+     * @brief Releases the next message in queue with a reply.

+     *

      * @param msg the answer message

      */

     static void ReleaseMessage(msg_t msg);

 

     /**

-     * Returns true if there is at least one message in queue.

+     * @brief Returns true if there is at least one message in queue.

+     *

      * @retval TRUE A message is waiting in queue.

      * @retval FALSE A message is not waiting in queue.

      */

@@ -206,15 +227,18 @@ namespace chibios_rt {
 #endif /* CH_USE_MESSAGES */

 

     /**

-     * Thread body function.

+     * @brief Thread body function.

+     *

      * @return The exit message.

      */

     virtual msg_t Main(void);

   };

 

   /**

-   * Enhanced threads template class. This class introduces thread names

-   * and static working area allocation.

+   * @brief Enhanced threads template class.

+   * @details This class introduces thread names and static working area

+   * allocation.

+   *

    * @param N the working area size for the thread class

    */

   template <int N>

@@ -224,13 +248,14 @@ namespace chibios_rt {
 

   public:

     /**

-     * The thread name.
+     * @brief The thread name.
      */

     const char *name;

 

     /**

-     * Full constructor. It allows to set a priority level for the new thread

-     * and specify the special option flags.

+     * @brief Full constructor.

+     * @details This constructor allows to set a priority level for the new

+     * thread.

      * @param tname the name to be assigned to the thread

      * @param prio the priority to be assigned to the thread

      */

@@ -241,9 +266,10 @@ namespace chibios_rt {
     }

 

     /**

-     * Simplified constructor, it allows to create a thread by simply

-     * specifying a name. In is assumed @p NORMALPRIO as initial priority

-     * and no special option flags.

+     * @brief Simplified constructor.

+     * @details This constructor allows to create a thread by simply

+     * specifying a name. In is assumed @p NORMALPRIO as initial priority.

+     *

      * @param tname the name to be assigned to the thread

      */

     EnhancedThread(const char *tname) :

@@ -255,30 +281,33 @@ namespace chibios_rt {
 

 #ifdef CH_USE_SEMAPHORES

   /**

-   * Class encapsulating a @p Semaphore.

+   * @brief Class encapsulating a @p Semaphore.

    */

   class Semaphore {

   public:

     /**

-     * Embedded @p Semaphore structure.

+     * @brief Embedded @p Semaphore structure.

      */

     struct ::Semaphore sem;

 

     /**

-     * Semaphore constructor.

-     * The embedded @p ::Semaphore structure is initialized.

+     * @brief Semaphore constructor.

+     * @details The embedded @p ::Semaphore structure is initialized.

+     *

      * @param n the semaphore counter value, must be greater or equal to zero

      */

     Semaphore(cnt_t n);

 

     /**

-     * Resets a semaphore.

-    * @param n the new semaphore counter value, must be greater or equal to zero

+     * @brief Resets a semaphore.

+     *

+     * @param n the new semaphore counter value, must be greater or equal to zero

      */

     void Reset(cnt_t n);

 

     /**

-     * Wait operation on the semaphore.

+     * @brief Wait operation on the semaphore.

+     *

      * @retval RDY_OK if the semaphore was signaled or not taken.

      * @retval RDY_RESET if the semaphore was reset.

      */

@@ -286,7 +315,8 @@ namespace chibios_rt {
 

 #ifdef CH_USE_SEMAPHORES_TIMEOUT

     /**

-     * Wait operation on the semaphore with timeout.

+     * @brief Wait operation on the semaphore with timeout.

+     *

      * @param time the number of ticks before the operation fails

      * @retval RDY_OK if the semaphore was signaled or not taken.

      * @retval RDY_RESET if the semaphore was reset.

@@ -297,14 +327,16 @@ namespace chibios_rt {
 #endif /* CH_USE_SEMAPHORES_TIMEOUT */

 

     /**

-     * Signal operation on the semaphore.

-     * The semaphore is signaled, the next thread in queue, if any, is awakened.

+     * @brief Signal operation on the semaphore.

+     * @details The semaphore is signaled, the next thread in queue, if any,

+     * is awakened.

      */

     void Signal(void);

 

 #ifdef CH_USE_SEMSW

     /**

-     * Atomic signal and wait operations.

+     * @brief Atomic signal and wait operations.

+     *

      * @param ssem pointer to a @p Semaphore to be signaled

      * @param wsem pointer to a @p Semaphore to be wait on

      * @retval RDY_OK if the semaphore was signaled or not taken.

@@ -317,82 +349,85 @@ namespace chibios_rt {
 

 #ifdef CH_USE_MUTEXES

   /**

-   * Class encapsulating a @p Mutex.

+   * @brief Class encapsulating a @p Mutex.

    */

   class Mutex {

   public:

     /**

-     * Embedded @p Mutex structure.

+     * @brief Embedded @p Mutex structure.

      */

     struct ::Mutex mutex;

 

     /**

-     * Mutex constructor.

-     * The embedded @p ::Mutex structure is initialized.

+     * @brief Mutex constructor.

+     * @details The embedded @p ::Mutex structure is initialized.

      */

     Mutex(void);

 

     /**

-     * Tries a lock operation on the mutex.

+     * @brief Tries a lock operation on the mutex.

      * @retval TRUE if the mutex was successfully acquired

      * @retval FALSE if the lock attempt failed.

      */

     bool TryLock(void);

 

     /**

-     * Locks the mutex.

-     * Performs a lock operation on the mutex, if the mutex is already locked

-     * then the thread enters the mutex priority queue and waits.

+     * @brief Locks the mutex.

+     * @details Performs a lock operation on the mutex, if the mutex is

+     * already locked then the thread enters the mutex priority queue and

+     * waits.

      */

     void Lock(void);

 

     /**

-     * Unlocks the mutex.

-     * Performs an unlock operation on the mutex, the next waiting thread, if

-     * any, is resumed and locks the mutex.

+     * @brief Unlocks the mutex.

+     * @details Performs an unlock operation on the mutex, the next waiting

+     * thread, if any, is resumed and locks the mutex.

      */

     static void Unlock(void);

 

     /**

-     * Unlocks all the mutexes owned by the invoking thread.

-     * This operation 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 inheritance mechanism.

+     * @brief Unlocks all the mutexes owned by the invoking thread.

+     * @details This operation 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 inheritance

+     * mechanism.

      */

     static void UnlockAll(void);

   };

 

 #ifdef CH_USE_CONDVARS

   /**

-   * Class encapsulating a @p CondVar.

+   * @brief Class encapsulating a @p CondVar.

    */

   class CondVar {

   public:

     /**

-     * Embedded @p CondVar structure.

+     * @brief Embedded @p CondVar structure.

      */

     struct ::CondVar condvar;

 

     /**

-     * CondVar constructor.

-     * The embedded @p ::CondVar structure is initialized.

+     * @brief CondVar constructor.

+     * @details The embedded @p ::CondVar structure is initialized.

      */

     CondVar(void);

 

     /**

-     * Signals the CondVar.

-     * The next thread waiting on the @p CondVar, if any, is awakened.
+     * @brief Signals the CondVar.

+     * @details The next thread waiting on the @p CondVar, if any, is awakened.
      */

     void Signal(void);

 

     /**

-     * Broadcasts the CondVar.
-     * All the threads waiting on the @p CondVar, if any, are awakened.

+     * @brief Broadcasts the CondVar.
+     * @details All the threads waiting on the @p CondVar, if any, are awakened.

      */

     void Broadcast(void);

 

     /**

-     * Waits on the CondVar while releasing the controlling mutex.
+     * @brief Waits on the CondVar while releasing the controlling mutex.

+     *
      * @return The wakep mode.

      * @retval RDY_OK if the condvar was signaled using chCondSignal().

      * @retval RDY_RESET if the condvar was signaled using chCondBroadcast().

@@ -401,7 +436,8 @@ namespace chibios_rt {
 

 #ifdef CH_USE_CONDVARS_TIMEOUT

     /**

-     * Waits on the CondVar while releasing the controlling mutex.

+     * @brief Waits on the CondVar while releasing the controlling mutex.

+     *

      * @param time the number of ticks before the operation fails

      * @return The wakep mode.

      * @retval RDY_OK if the condvar was signaled using chCondSignal().

@@ -417,30 +453,32 @@ namespace chibios_rt {
 

 #ifdef CH_USE_EVENTS

   /**

-   * Class encapsulating an @p EventSource.

+   * @brief Class encapsulating an @p EventSource.

    */

   class Event {

   public:

     /**

-     * Embedded @p EventSource structure.

+     * @brief Embedded @p EventSource structure.

      */

     struct ::EventSource event;

 

     /**

-     * Event constructor.

-     * The embedded @p ::EventSource structure is initialized.

+     * @brief Event constructor.

+     * @details The embedded @p ::EventSource structure is initialized.

      */

     Event(void);

 

     /**

-     * Registers a listener on the event source.

+     * @brief Registers a listener on the event source.

+     *

      * @param elp pointer to the @p EventListener structure

      * @param eid numeric identifier assigned to the Event Listener

      */

     void Register(EventListener *elp, eventid_t eid);

 

     /**

-     * Registers an Event Listener on an Event Source.

+     * @brief Registers an Event Listener on an Event Source.

+     *

      * @param elp pointer to the @p EventListener structure

      * @param emask the mask of event flags to be pended to the thread when the

      *              event source is broadcasted

@@ -449,35 +487,40 @@ namespace chibios_rt {
     void RegisterMask(EventListener *elp, eventmask_t emask);

 

     /**

-     * Unregisters a listener.

-     * The specified listeners is no more signaled by the event source.

+     * @brief Unregisters a listener.

+     * @details The specified listeners is no more signaled by the event

+     * source.

+     *

      * @param elp the listener to be unregistered

      */

     void Unregister(EventListener *elp);

 

     /**

-     * Broadcasts an event.

-     * All the listeners registered on the event source are signaled.

+     * @brief Broadcasts an event.

+     * @details All the listeners registered on the event source are signaled.

      */

     void Broadcast(void);

 

     /**

-     * Clears specified events from the pending events mask.

+     * @brief Clears specified events from the pending events mask.

+     *

      * @param mask the events to be cleared

      * @return The pending events that were cleared.

      */

     static eventmask_t Clear(eventmask_t mask);

 

     /**

-     * Makes an events mask pending in the current thread, this is \b much

-     * faster than using @p Broadcast().

+     * @brief Makes an events mask pending in the current thread.

+     * @details This functon is @b much faster than using @p Broadcast().

+     *

      * @param mask the events to be pended

      * @return The current pending events mask.

      */

     static eventmask_t Pend(eventmask_t mask);

 

     /**

-     * Invokes the event handlers associated with a mask.

+     * @brief Invokes the event handlers associated with a mask.

+     *

      * @param mask mask of the events to be dispatched

      * @param handlers an array of @p evhandler_t. The array must be

      *                 have indexes from zero up the higher registered event

@@ -486,8 +529,10 @@ namespace chibios_rt {
     static void Dispatch(const evhandler_t handlers[], eventmask_t mask);

 

     /**

-     * A pending event among those specified in @p ewmask is selected, cleared and

-     * its mask returned.

+     * @brief Waits for a single event.

+     * @details A pending event among those specified in @p ewmask is selected,

+     * cleared and its mask returned.

+     *

      * @param 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.

@@ -500,9 +545,10 @@ namespace chibios_rt {
     static eventmask_t WaitOne(eventmask_t ewmask);

 

     /**

-     * Waits for any of the specified events.

-     * The function waits for any event among those specified in @p ewmask to

-     * become pending then the events are cleared and returned.

+     * @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.

+     *

      * @param 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.

@@ -510,9 +556,10 @@ namespace chibios_rt {
     static eventmask_t WaitAny(eventmask_t ewmask);

 

     /**

-     * Waits for all the specified event flags then clears them.

-     * The function waits for all the events specified in @p ewmask to become

-     * pending then the events are cleared and returned.

+     * @brief Waits for all the specified event flags then clears them.

+     * @details The function waits for all the events specified in @p ewmask

+     * to become pending then the events are cleared and returned.

+     *

      * @param ewmask mask of the event ids that the function should wait for

      * @return The mask of the served and cleared events.

      */

@@ -520,9 +567,9 @@ namespace chibios_rt {
 

 #ifdef CH_USE_EVENTS_TIMEOUT

     /**

-     * Waits for a single event.

-     * A pending event among those specified in @p ewmask is selected, cleared

-     * and its mask returned.

+     * @brief Waits for a single event.

+     * @details A pending event among those specified in @p ewmask is selected,

+     * cleared and its mask returned.

      * @param ewmask mask of the events that the function should wait for,

      *               @p ALL_EVENTS enables all the events

      * @param time the number of ticks before the operation timouts

@@ -537,9 +584,10 @@ namespace chibios_rt {
     static eventmask_t WaitOneTimeout(eventmask_t ewmask, systime_t time);

 

     /**

-     * Waits for any of the specified events.

-     * The function waits for any event among those specified in @p ewmask to

-     * become pending then the events are cleared and returned.

+     * @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.

+     *

      * @param ewmask mask of the events that the function should wait for,

      *               @p ALL_EVENTS enables all the events

      * @param time the number of ticks before the operation timouts

@@ -549,9 +597,10 @@ namespace chibios_rt {
     static eventmask_t WaitAnyTimeout(eventmask_t ewmask, systime_t time);

 

     /**

-     * Waits for all the specified event flags then clears them.

-     * The function waits for all the events specified in @p ewmask to become

-     * pending then the events are cleared and returned.

+     * @brief Waits for all the specified event flags then clears them.

+     * @details The function waits for all the events specified in @p ewmask

+     * to become pending then the events are cleared and returned.

+     *

      * @param ewmask mask of the event ids that the function should wait for

      * @param time the number of ticks before the operation timouts

      * @return The mask of the served and cleared events.

diff --git a/src/lib/evtimer.c b/src/lib/evtimer.c
index 786a25c7f..691484336 100644
--- a/src/lib/evtimer.c
+++ b/src/lib/evtimer.c
@@ -18,11 +18,8 @@
 */

 

 /**

- * @file evtimer.c

+ * @addtogroup event_timer

  * @{

- * Event Timer, this timer generates an event at regular intervals. The

- * listening threads can use the event to perform time related activities.

- * Multiple threads can listen to the same timer.

  */

 

 #include <ch.h>

@@ -37,8 +34,9 @@ static void tmrcb(void *p) {
 }

 

 /**

- * Starts the timer, if the timer was already running then the function has

- * no effect.

+ * @brief Starts the timer

+ * @details If the timer was already running then the function has no effect.

+ *

  * @param etp pointer to an initialized @p EvTimer structure.

  */

 void evtStart(EvTimer *etp) {

@@ -52,8 +50,9 @@ void evtStart(EvTimer *etp) {
 }

 

 /**

- * Stops the timer, if the timer was already stopped then the function has

- * no effect.

+ * @brief Stops the timer.

+ * @details If the timer was already stopped then the function has no effect.

+ *

  * @param etp pointer to an initialized @p EvTimer structure.

  */

 void evtStop(EvTimer *etp) {

diff --git a/src/lib/evtimer.h b/src/lib/evtimer.h
index d0ff5f7c7..5a148e4db 100644
--- a/src/lib/evtimer.h
+++ b/src/lib/evtimer.h
@@ -18,10 +18,8 @@
 */

 

 /**

- * @file evtimer.h

+ * @addtogroup event_timer

  * @{

- * Event Timer definitions.

- * @see evtimer.c

  */

 

 #ifndef _EVTIMER_H_

@@ -46,7 +44,8 @@ extern "C" {
 #endif

 

 /**

- * Initializes an @p EvTimer structure.

+ * @brief Initializes an @p EvTimer structure.

+ *

  * @param etp the EvTimer structure to be initialized

  * @param time the interval in system ticks

  */

diff --git a/src/templates/chcore.c b/src/templates/chcore.c
index e9f1868af..838cffe60 100644
--- a/src/templates/chcore.c
+++ b/src/templates/chcore.c
@@ -32,72 +32,79 @@
  */

 

 /**

- * Port-related initialization code.

+ * @brief Port-related initialization code.

+ *

  * @note This function is usually empty.
  */

 void port_init(void){

 }

 

 /**

- * Kernel-unlock action. Usually this function just disables interrupts but

- * may perform more actions.
+ * @brief Kernel-unlock action.

+ * @details Usually this function just disables interrupts but may perform more

+ * actions.
  */

 void port_lock(void) {

 }

 

 /**

- * Kernel-unlock action. Usually this function just disables interrupts but

- * may perform more actions.

+ * @brief Kernel-unlock action.

+ * @details Usually this function just disables interrupts but may perform more

+ * actions.

  */

 void port_unlock(void) {

 }

 

 /**

- * Kernel-lock action from an interrupt handler. This function is invoked

- * before invoking I-class APIs from interrupt handlers. The implementation

- * is architecture dependent, in its simplest form it is void.

+ * @brief Kernel-lock action from an interrupt handler.

+ * @details This function is invoked before invoking I-class APIs from

+ * interrupt handlers. The implementation is architecture dependent, in its

+ * simplest form it is void.

  */

 void port_lock_from_isr(void) {

 }

 

 /**

- * Kernel-unlock action from an interrupt handler. This function is invoked

- * after invoking I-class APIs from interrupt handlers. The implementation

- * is architecture dependent, in its simplest form it is void.

+ * @brief Kernel-unlock action from an interrupt handler.

+ * @details This function is invoked after invoking I-class APIs from interrupt

+ * handlers. The implementation is architecture dependent, in its simplest form

+ * it is void.

  */

 void port_unlock_from_isr(void) {

 }

 

 /**

- * Disables all the interrupt sources.

+ * @brief Disables all the interrupt sources.

+ *

  * @note Of course non maskable interrupt sources are not included.
  */

 void port_disable() {

 }

 

 /**

- * Disables the interrupt sources that are not supposed to preempt the kernel.
+ * @brief Disables the interrupt sources that are not supposed to preempt the kernel.
  */

 void port_suspend(void) {

 }

 

 /**

- * Enables all the interrupt sources.
+ * @brief Enables all the interrupt sources.
  */

 void port_enable(void) {

 }

 

 /**

- * Enters an architecture-dependent halt mode. The function is meant to return

- * when an interrupt becomes pending. The simplest implementation is an empty

- * function but this will not take advantage of architecture-specific power

- * saving modes.
+ * @brief Enters an architecture-dependent halt mode.

+ * @details The function is meant to return when an interrupt becomes pending.

+ * The simplest implementation is an empty function but this will not take

+ * advantage of architecture-specific power saving modes.
  */

 void port_wait_for_interrupt(void) {

 }

 

 /**

- * Halts the system. This function is invoked by the operating system when an

+ * @brief Halts the system.

+ * @details This function is invoked by the operating system when an

  * unrecoverable error is detected (as example because a programming error in

  * the application code that triggers an assertion while in debug mode).
  */

@@ -109,7 +116,8 @@ void port_halt(void) {
 }

 

 /**

- * Performs a context switch between two threads.

+ * @brief Performs a context switch between two threads.

+ *

  * @param otp the thread to be switched out

  * @param ntp the thread to be switched in

  */

@@ -117,7 +125,8 @@ void port_switch(Thread *otp, Thread *ntp) {
 }

 

 /**

- * Prints a message on the system console.

+ * @brief Prints a message on the system console.

+ *

  * @param msg pointer to the message

  */

 void port_puts(char *msg) {

diff --git a/src/templates/chtypes.h b/src/templates/chtypes.h
index 547b0fb7e..821517574 100644
--- a/src/templates/chtypes.h
+++ b/src/templates/chtypes.h
@@ -63,9 +63,16 @@ typedef uint32_t        systime_t;
 /** Counter, recommended fastest signed.*/

 typedef int32_t         cnt_t;

 

+/** Inline function modifier. */

 #define INLINE      inline

+

+/** Packed structure modifier (within). */

 #define PACK_STRUCT_STRUCT __attribute__((packed))

+

+/** Packed structure modifier (before). */

 #define PACK_STRUCT_BEGIN

+

+/** Packed structure modifier (after). */

 #define PACK_STRUCT_END

 

 #endif /* _CHTYPES_H_ */