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

22 files changed, 213 insertions, 117 deletions

diff --git a/docs/Doxyfile b/docs/Doxyfile
index b9baae9ad..98fe036c1 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -9,7 +9,7 @@ PROJECT_NUMBER         = "0.7.2 beta"
 OUTPUT_DIRECTORY       = .
 CREATE_SUBDIRS         = NO
 OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = NO
+BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
 ABBREVIATE_BRIEF       = "The $name class" \
                          "The $name widget" \
diff --git a/docs/ch.txt b/docs/ch.txt
index 05d38e33c..de2db1c6f 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -329,6 +329,16 @@
 /** @} */

 

 /**

+ * @defgroup ThreadLists Thread Lists and Queues

+ * @{

+ * ChibiOS/RT thread lists and queues utilities.

+ * @ingroup Kernel

+ * @file chlists.c Lists and queues code.

+ * @file lists.h Lists and queues macros and structures.

+ */

+/** @} */

+

+/**

  * @defgroup Threads Threads

  * @{

  * Threads creation and termination APIs.

diff --git a/docs/readme.txt b/docs/readme.txt
new file mode 100644
index 000000000..730d20072
--- /dev/null
+++ b/docs/readme.txt
@@ -0,0 +1,35 @@
+*** Documentation access ***

+

+Open ./docs/index.html to open the start page or ./docs/html/index.html in

+order to access directly the doxigen documentation.

+

+*** Documentation rebuild procedure ***

+

+The following software must be installed:

+- Doxigen 1.5.7.1 or later.

+- Graphviz 2.21 or later. The ./bin directory must be specified in the path in

+  order to make Graphviz accessible by doxigen.

+

+Build procedure:

+- Run Doxiwizard.

+- Load ./docs/Doxifile from Doxiwizard.

+- Start.

+

+*** Doxygen usage rules ***

+- The JavaDoc style is recommended (@ instad of \, /** instead of /*!).

+- Params descriptions must not begin with a capital letter and must not be

+  terminated with a dot unless it is composed of multiple paragraphs.

+- Retvals descriptions must not begin with a capital letter but must be

+  terminated by a dot.

+- Normal paragraphs, return rescriptions and notes must start with a capital

+  letter and must be terminated with a dot.

+- Multiple return values should be listed using the @retval command.

+- AUTOBRIEF is enabled but deprecated, gradually convert to the use of explicit

+  @brief command.

+

+Examples:

+@note This is a note.

+@retval RDY_OK is a possible return value.

+@return The pointer to the created thread is returned.

+@param n the number of bytes to be written

+@param n the number of bytes to be written. This value can be zero.

diff --git a/readme.txt b/readme.txt
index 8daa3d017..4395ba1f3 100644
--- a/readme.txt
+++ b/readme.txt
@@ -94,6 +94,7 @@ Win32-MinGW            - ChibiOS/RT simulator and demo into a WIN32 process,
 - Modified the STM32 demo makefile to use the latest YAGARTO toolchain as

   default (arm-elf-gcc).

 - Documentation improvements, added collaboration diagrams and call graphs.

+  Added a documentation-related readme under ./docs.

 

 *** 0.7.1 ***

 - NEW: New chThdInit() and chThdCreateStatic() APIs now replace the old

diff --git a/src/chdebug.c b/src/chdebug.c
index 14b57669d..a826776fe 100644
--- a/src/chdebug.c
+++ b/src/chdebug.c
@@ -36,6 +36,7 @@ void chDbgInit(void) {
 

 /**

  * 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) {

 

diff --git a/src/chdelta.c b/src/chdelta.c
index 41f4490d0..62f3b35cc 100644
--- a/src/chdelta.c
+++ b/src/chdelta.c
@@ -28,7 +28,8 @@
 DeltaList dlist;

 

 /**

- * Virtual Timers initialization. Internal use only.

+ * Virtual Timers initialization.

+ * @note Internal use only.

  */

 void chVTInit(void) {

 

diff --git a/src/chevents.c b/src/chevents.c
index 87ba7ca95..25d9d5d39 100644
--- a/src/chevents.c
+++ b/src/chevents.c
@@ -129,7 +129,7 @@ void chEvtBroadcastI(EventSource *esp) {
  *                 have indexes from zero up the higher registered event

  *                 identifier. The array can be \p NULL or contain \p NULL

  *                 elements (no callbacks specified).

- * @return the event identifier

+ * @return The event identifier.

  * @note Only a single event is served in the function, the one with the

  *       lowest event id. The function is meant to be invoked into a loop so

  *       that all events are received and served.<br>

@@ -153,7 +153,8 @@ eventid_t chEvtWait(eventmask_t ewmask,
  *                 identifier. The array can be NULL or contain NULL elements

  *                 (no callback specified).

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

- * @return the event identifier or \p RDY_TIMEOUT if the specified time expired

+ * @return The event identifier.

+ * @retval RDY_TIMEOUT if the specified timeout expired.

  * @note Only a single event is served in the function, the one with the

  *       lowest event id. The function is meant to be invoked into a loop so

  *       that all events are received and served.<br>

diff --git a/src/chheap.c b/src/chheap.c
index 7a2f0ccac..08ead3411 100644
--- a/src/chheap.c
+++ b/src/chheap.c
@@ -98,8 +98,8 @@ void chHeapInit(void) {
  * @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.

- * @return a pointer to the allocated block or \p NULL if the block cannot be

- *         allocated.

+ * @return A pointer to the allocated block.

+ * @retval NULL if the block cannot be allocated.

  */

 void *chHeapAlloc(size_t size) {

   struct header *qp, *hp, *fp;

@@ -187,7 +187,7 @@ void chHeapFree(void *p) {
  * Determines 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

+ * @return The number of fragments in the heap.

  * @note This function is meant to be used in the test suite, it should not be

  *       really useful for the application code.

  * @note This function is not implemented when the \p CH_USE_MALLOC_HEAP

diff --git a/src/chinit.c b/src/chinit.c
index 9162d84f1..5d46808d8 100644
--- a/src/chinit.c
+++ b/src/chinit.c
@@ -62,11 +62,9 @@ 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.
- *
  * @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/chlists.c b/src/chlists.c
index 3f5f3e8ee..3df824397 100644
--- a/src/chlists.c
+++ b/src/chlists.c
@@ -18,19 +18,20 @@
 */

 

 /**

- * @addtogroup Threads

+ * @addtogroup ThreadLists

  * @{

  */

 #include <ch.h>

 

 #ifndef CH_OPTIMIZE_SPEED

-/*

+/**

  * 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 The insertion is done by scanning the list from the highest priority

+ *       toward the lowest.

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

  */

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

 

@@ -46,11 +47,12 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
   tp->p_prev->p_next = cp->p_prev = tp;

 }

 

-/*

+/**

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

  */

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

 

@@ -58,11 +60,12 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
   tp->p_prev->p_next = tqp->p_prev = tp;

 }

 

-/*

+/**

  * 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

+ * @return The removed thread pointer.

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

  */

 Thread *fifo_remove(ThreadsQueue *tqp) {

   Thread *tp = tqp->p_next;

@@ -71,11 +74,12 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
   return tp;

 }

 

-/*

+/**

  * 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

+ * @return The removed thread pointer.

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

  */

 Thread *lifo_remove(ThreadsQueue *tqp) {

   Thread *tp = tqp->p_next;

@@ -84,11 +88,12 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
   return tp;

 }

 

-/*

+/**

  * 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

+ * @return The removed thread pointer.

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

  */

 Thread *dequeue(Thread *tp) {

 

@@ -97,11 +102,12 @@ Thread *dequeue(Thread *tp) {
   return tp;

 }

 

-/*

+/**

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

  */

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

 

@@ -109,12 +115,13 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
   tlp->p_next = tp;

 }

 

-/*

+/**

  * 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

+ * @return The removed thread pointer.

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

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

  */

 Thread *list_remove(ThreadsList *tlp) {

 

diff --git a/src/chmempools.c b/src/chmempools.c
index 52914b7c6..ae97648a4 100644
--- a/src/chmempools.c
+++ b/src/chmempools.c
@@ -43,7 +43,8 @@ void chPoolInit(MemoryPool *mp, size_t size) {
 /**

  * Allocates an object from a memory pool.

  * @param mp pointer to a \p MemoryPool structure

- * @return the pointer to the allocated object or \p NULL if pool is empty

+ * @return The pointer to the allocated object.

+ * @retval NULL if pool is empty.

  */

 void *chPoolAlloc(MemoryPool *mp) {

   void *objp;

diff --git a/src/chmsg.c b/src/chmsg.c
index 5a1ce4b15..51a126c0f 100644
--- a/src/chmsg.c
+++ b/src/chmsg.c
@@ -30,7 +30,7 @@
  *

  * @param tp the pointer to the thread

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

- * @return the return message from \p chMsgRelease()

+ * @return The return message from \p chMsgRelease().

  */

 msg_t chMsgSend(Thread *tp, msg_t msg) {

 

@@ -61,8 +61,7 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
  * @param tp the pointer to the thread

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

  * @param esp the event source to pulse while sending the message

- * @return the return message from \p chMsgRelease()

- * @return the message return status from \p chMsgRelease()

+ * @return The return message from \p chMsgRelease().

  * @note This function assumes that the receiving thread is not sleeping into

  *       a \p chMsgWait(). The use case is that the server thread is waiting

  *       for both messages AND events while waiting into \p chEvtWait().

@@ -91,7 +90,7 @@ msg_t chMsgSendWithEvent(Thread *tp, msg_t msg, EventSource *esp) {
 /**

  * Suspends the thread and waits for an incoming message.

  *

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

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

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

  * @note You can assume that the data contained in the message is stable until

  *       you invoke \p chMsgRelease() because the sending thread is

@@ -113,7 +112,7 @@ msg_t chMsgWait(void) {
 /**

  * Returns the next message in the queue.

  *

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

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

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

  *         If the queue is empty then \p NULL is returned.

  * @note You can assume that the data pointed by the message is stable until

diff --git a/src/chmtx.c b/src/chmtx.c
index f5dbaca43..ea3ccccda 100644
--- a/src/chmtx.c
+++ b/src/chmtx.c
@@ -114,7 +114,8 @@ void chMtxLockS(Mutex *mp) {
  * 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
- * @return \p TRUE if the mutex was successfully acquired else \p FALSE
+ * @retval TRUE if the mutex was successfully acquired
+ * @retval FALSE if the lock attempt failed.
  */
 bool_t chMtxTryLock(Mutex *mp) {
   bool_t b;
@@ -132,7 +133,8 @@ bool_t chMtxTryLock(Mutex *mp) {
  * 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
- * @return \p TRUE if the mutex was successfully acquired else \p FALSE
+ * @retval TRUE if the mutex was successfully acquired
+ * @retval FALSE if the lock attempt failed.
  * @note This function must be called within a \p chSysLock() / \p chSysUnlock()
  *       block.
  */
@@ -148,6 +150,7 @@ bool_t chMtxTryLockS(Mutex *mp) {
 
 /**
  * Unlocks the next owned mutex in reverse lock order.
+ * @return The pointer to the unlocked mutex.
  */
 Mutex *chMtxUnlock(void) {
   Mutex *ump, *mp;
@@ -192,6 +195,7 @@ Mutex *chMtxUnlock(void) {
 
 /**
  * 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.
  * @note This function does not reschedule internally.
diff --git a/src/chqueues.c b/src/chqueues.c
index ec456c5f1..ed9eb840c 100644
--- a/src/chqueues.c
+++ b/src/chqueues.c
@@ -62,8 +62,8 @@ void chIQReset(Queue *qp) {
  * Inserts a byte into an input queue.

  * @param qp pointer to a \p Queue structure

  * @param b the byte value to be written

- * @return \p Q_OK if the operation is successful or \p Q_FULL if the queue is

- *         full.

+ * @retval Q_OK if the operation is successful.

+ * @retval Q_FULL if the queue is full.

  * @note This function is the lower side endpoint of the Input Queue.

  * @note This function must be called with interrupts disabled or from an

  *       interrupt handler.

@@ -84,7 +84,8 @@ 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.

  * @param qp pointer to a \p Queue structure

- * @return a byte from the queue or \p Q_RESET if the queue was reset

+ * @return A byte value from the queue.

+ * @retval Q_RESET if the queue was reset.

  */

 msg_t chIQGet(Queue *qp) {

   uint8_t b;

@@ -114,8 +115,9 @@ msg_t chIQGet(Queue *qp) {
  * specified time expires.

  * @param qp pointer to a \p Queue structure

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

- * @return a byte from the queue, \p Q_TIMEOUT if the specified time expired

- *         or \p Q_RESET if the queue was reset

+ * @return A byte value from the queue.

+ * @retval Q_TIMEOUT if the specified time expired.

+ * @retval Q_RESET if the queue was reset.

  * @note The function is available only if the \p CH_USE_QUEUES_TIMEOUT

  *       option is enabled in \p chconf.h.

  */

@@ -148,7 +150,7 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) {
  * @param qp pointer to a \p Queue structure

  * @param buffer the data buffer

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

- * @return the number of bytes read

+ * @return The number of bytes read.

  * @note This function is the upper side endpoint of the input queue.

  * @note The function is not atomic, if you need atomicity it is suggested

  *       to use a semaphore for mutual exclusion.

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

  * Gets a byte from an output queue.

  * @param qp pointer to a \p Queue structure

- * @return the byte value or \p Q_EMPTY if the queue is empty

+ * @return The byte value from the queue.

+ * @retval Q_EMPTY if the queue is empty.

  * @note This function is the lower side endpoint of the output queue.

  * @note This function must be called with interrupts disabled or from an

  *       interrupt handler.

@@ -264,6 +267,7 @@ msg_t chOQGetI(Queue *qp) {
  * @param qp pointer to a \p Queue structure

  * @param buffer the data buffer

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

+ * @return The number of written bytes.

  * @note This function is the upper side endpoint of the output queue.

  * @note The function is not atomic, if you need atomicity it is suggested

  *       to use a semaphore for mutual exclusion.

@@ -326,7 +330,8 @@ 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.

  * @param qp pointer to a \p HalfDuplexQueue structure

- * @return the byte value or \p Q_RESET if the queue was reset

+ * @return The byte value.

+ * @retval Q_RESET if the queue was reset.

  */

 msg_t chHDQGetReceive(HalfDuplexQueue *qp) {

   uint8_t b;

@@ -359,7 +364,8 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) {
  * 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 or \p Q_TIMEOUT if a timeout occurs

+ * @return The byte value.

+ * @retval Q_TIMEOUT if a timeout occurs.

  * @note The function is available only if the \p CH_USE_QUEUES_TIMEOUT

  *       option is enabled in \p chconf.h.

  */

@@ -426,8 +432,8 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
 /**

  * Gets a byte from the transmit queue.

  * @param qp pointer to a \p HalfDuplexQueue structure

- * @return the byte value or \p Q_EMPTY if the transmit queue is empty (not in

- *         transmission mode)

+ * @return The byte value.

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

  * @note This function must be called with interrupts disabled or from an

  *       interrupt handler.

  */

@@ -449,8 +455,8 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) {
  * then the byte is lost.

  * @param qp pointer to a \p HalfDuplexQueue structure

  * @param b the byte value to be written

- * @return \p Q_OK if the operation is successful or \p Q_FULL if the driver

- *         is in transmit mode or the receive queue is full.

+ * @retval Q_OK if the operation is successful.

+ * @retval Q_FULL if the driver is in transmit mode or the receive queue is full.

  * @note This function must be called with interrupts disabled or from an

  *       interrupt handler.

  */

diff --git a/src/chschd.c b/src/chschd.c
index 8b606cd1b..c9e4608ca 100644
--- a/src/chschd.c
+++ b/src/chschd.c
@@ -48,7 +48,7 @@ void chSchInit(void) {
  * Inserts a thread in the Ready List.
  *
  * @param tp the Thread to be made ready
- * @return the Thread pointer
+ * @return The Thread pointer.
  * @note The function must be called in the system mutex zone.
  * @note The function does not reschedule, the \p chSchRescheduleS() should
  *       be called soon after.
@@ -108,15 +108,16 @@ static void wakeup(void *p) {
 }
 
 /**
- * Put the current thread to sleep.
+ * 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.
  *
  * @param newstate the new thread state
- * @param time the number of ticks before the operation timouts
- * @return the wakeup message, it is \p RDY_TIMEOUT if a timeout occurs
+ * @param time the number of ticks before the operation timeouts
+ * @return The wakeup message.
+ * @retval RDY_TIMEOUT if a timeout occurs.
  * @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.
  */
@@ -134,9 +135,8 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
 /**
  * Wakes up a thread.
  *
- * Wakes up a thread. 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.
@@ -171,7 +171,7 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
 /**
  * Switch to the first thread on the runnable queue.
  *
- * Intended to be called if \p chSchRescRequired() evaluates to \p TRUE.
+ * @note It is intended to be called if \p chSchRescRequired() evaluates to \p TRUE.
  */
 void chSchDoRescheduleI(void) {
 
@@ -206,8 +206,8 @@ void chSchRescheduleS(void) {
 /**
  * Evaluates if rescheduling is required.
  *
- * @return \p TRUE if there is a thread that should go in running state
- *         immediately else \p FALSE.
+ * @retval TRUE if there is a thread that should go in running state.
+ * @retval FALSE if a reschedulation is not required.
  */
 bool_t chSchRescRequiredI(void) {
   tprio_t p1 = firstprio(&rlist.r_queue);
diff --git a/src/chsem.c b/src/chsem.c
index b5c197b6b..011737642 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -41,7 +41,7 @@ void chSemInit(Semaphore *sp, cnt_t n) {
 /**

  * Performs a reset operation on the semaphore.

  * @param sp pointer to a \p Semaphore structure

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

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

  *       instead than a signal because the \p chSemWait() will return

  *       \p RDY_RESET instead of \p RDY_OK.

@@ -59,7 +59,7 @@ void chSemReset(Semaphore *sp, cnt_t n) {
 /**

  * Performs a reset operation on the semaphore.

  * @param sp pointer to a \p Semaphore structure

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

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

  *       instead than a signal because the \p chSemWait() will return

  *       \p RDY_RESET instead of \p RDY_OK.

@@ -78,7 +78,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
 /**

  * Performs a wait operation on a semaphore.

  * @param sp pointer to a \p Semaphore structure

- * @return the function can return \p RDY_OK or \p RDY_RESET.

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

+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().

  */

 msg_t chSemWait(Semaphore *sp) {

   msg_t msg;

@@ -94,7 +95,8 @@ msg_t chSemWait(Semaphore *sp) {
 /**

  * Performs a wait operation on a semaphore.

  * @param sp pointer to a \p Semaphore structure

- * @return the function can return \p RDY_OK or \p RDY_RESET.

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

+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().

  * @note This function must be called with interrupts disabled.

  * @note This function cannot be called by an interrupt handler.

  */

@@ -114,7 +116,12 @@ msg_t chSemWaitS(Semaphore *sp) {
  * 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

- * @return the function can return \p RDY_OK, \p RDY_TIMEOUT or \p RDY_RESET.

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

+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().

+ * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified

+ *         timeout.

+ * @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT

+ *       option is enabled in \p chconf.h.

  */

 msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {

   msg_t msg;

@@ -131,9 +138,10 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
  * 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

- * @return the function can return \p RDY_OK, \p RDY_TIMEOUT or \p RDY_RESET.

- * @note This function must be called with interrupts disabled.

- * @note This function cannot be called by an interrupt handler.

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

+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().

+ * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified

+ *         timeout.

  * @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT

  *       option is enabled in \p chconf.h.

  */

@@ -167,7 +175,6 @@ void chSemSignal(Semaphore *sp) {
 /**

  * Performs a signal operation on a semaphore.

  * @param sp pointer to a \p Semaphore structure

- * @note This function must be called with interrupts disabled.

  * @note The function is available only if the \p CH_USE_SEMAPHORES

  *       option is enabled in \p chconf.h.

  * @note This function does not reschedule.

@@ -188,7 +195,8 @@ void chSemSignalI(Semaphore *sp) {
  * 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

- * @return the function can return \p RDY_OK or \p RDY_RESET.

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

+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().

  * @note The function is available only if the \p CH_USE_SEMSW

  *       option is enabled in \p chconf.h.

  */

diff --git a/src/chserial.c b/src/chserial.c
index f185c91fc..4ab65e140 100644
--- a/src/chserial.c
+++ b/src/chserial.c
@@ -70,9 +70,9 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
  * the next byte to be transmitted.

  *

  * @param sd pointer to a \p FullDuplexDriver structure

- * @return the byte read from the driver's Output Queue or \p Q_EMPTY if the

- *         queue is empty (the lower driver usually disables the interrupt

- *         source when this happens).

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

+ * @retval Q_EMPTY if the queue is empty (the lower driver usually disables

+ *         the interrupt source when this happens).

  */

 msg_t chFDDRequestDataI(FullDuplexDriver *sd) {

 

@@ -97,8 +97,8 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
 /**

  * This function 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

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

+ *         invoked.

  */

 dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {

   dflags_t mask;

@@ -136,7 +136,7 @@ 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.

  * @param sd pointer to a \p FullDuplexDriver structure

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

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

  */

 void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {

 

@@ -151,9 +151,9 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
  * the next byte to be transmitted.

  *

  * @param sd pointer to a \p HalfDuplexDriver structure

- * @return the byte read from the driver's Output Queue or \p Q_EMPTY if the

- *         queue is empty (the lower driver usually disables the interrupt

- *         source when this happens).

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

+ * @retval Q_EMPTY if the queue is empty (the lower driver usually disables

+ *         the interrupt source when this happens).

  */

 msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {

 

@@ -178,8 +178,8 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
 /**

  * This function 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

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

+ *         invoked.

  */

 dflags_t chHDDGetAndClearFlags(HalfDuplexDriver *sd) {

   dflags_t mask;

diff --git a/src/chthreads.c b/src/chthreads.c
index 755cda99e..58df0a5c1 100644
--- a/src/chthreads.c
+++ b/src/chthreads.c
@@ -74,7 +74,7 @@ static void memfill(uint8_t *p, uint32_t n, uint8_t v) {
  * @param wsize size of the working area.
  * @param pf the thread function
  * @param arg an argument passed to the thread function. It can be \p NULL.
- * @return the pointer to the \p Thread structure allocated for the
+ * @return The pointer to the \p Thread structure allocated for the
  *         thread into the working space area.
  * @note A thread can terminate by calling \p chThdExit() or by simply
  *       returning from its main function.
@@ -104,7 +104,7 @@ Thread *chThdInit(void *workspace, size_t wsize,
  *             can range from \p LOWPRIO to \p HIGHPRIO.
  * @param pf the thread function
  * @param arg an argument passed to the thread function. It can be \p NULL.
- * @return the pointer to the \p Thread structure allocated for the
+ * @return The pointer to the \p Thread structure allocated for the
  *         thread into the working space area.
  * @note A thread can terminate by calling \p chThdExit() or by simply
  *       returning from its main function.
@@ -124,9 +124,9 @@ Thread *chThdCreateStatic(void *workspace, size_t wsize,
  *             can range from \p LOWPRIO to \p HIGHPRIO.
  * @param pf the thread function
  * @param arg an argument passed to the thread function. It can be \p NULL.
- * @return the pointer to the \p Thread structure allocated for the
- *         thread into the working space area or \p NULL if the memory cannot
- *         be allocated.
+ * @return The pointer to the \p Thread structure allocated for the
+ *         thread into the working space area.
+ * @retval NULL if the memory cannot be allocated.
  * @note A thread can terminate by calling \p chThdExit() or by simply
  *       returning from its main function.
  * @note The memory allocated for the thread is not released when the thread
@@ -156,9 +156,10 @@ Thread *chThdCreateFromHeap(size_t wsize, tprio_t prio,
  *             can range from \p LOWPRIO to \p HIGHPRIO.
  * @param pf the thread function
  * @param arg an argument passed to the thread function. It can be \p NULL.
- * @return the pointer to the \p Thread structure allocated for the
+ * @return The pointer to the \p Thread structure allocated for the
  *         thread into the working space area or \p NULL if the memory cannot
  *         be allocated.
+ * @retval NULL if the memory pool is empty.
  * @note A thread can terminate by calling \p chThdExit() or by simply
  *       returning from its main function.
  * @note The memory allocated for the thread is not released when the thread
@@ -197,7 +198,7 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
  * @param wsize size of the working area.
  * @param pf the thread function
  * @param arg an argument passed to the thread function. It can be \p NULL.
- * @return the pointer to the \p Thread structure allocated for the
+ * @return The pointer to the \p Thread structure allocated for the
  *         thread into the working space area.
  * @note A thread can terminate by calling \p chThdExit() or by simply
  *       returning from its main function.
@@ -261,7 +262,7 @@ void chThdSuspend(Thread **tpp) {
 /**
  * Resumes a suspended thread.
  * @param tp the pointer to the thread
- * @return the pointer to the thread
+ * @return The pointer to the thread.
  */
 Thread *chThdResume(Thread *tp) {
 
@@ -324,7 +325,7 @@ void chThdExit(msg_t msg) {
  *     working area is returned to the owning memory pool.</li>
  * </ul>
  * @param tp the thread pointer
- * @return the exit code from the terminated thread
+ * @return The exit code from the terminated thread
  * @note After invoking \p chThdWait() the thread pointer becomes invalid and
  *       must not be used as parameter for further system calls.
  * @note The function is available only if the \p CH_USE_WAITEXIT
diff --git a/src/include/lists.h b/src/include/lists.h
index 5c3c98093..2f4324b71 100644
--- a/src/include/lists.h
+++ b/src/include/lists.h
@@ -18,7 +18,7 @@
 */

 

 /**

- * @addtogroup Threads

+ * @addtogroup ThreadLists

  * @{

  */

 

diff --git a/src/templates/chcore.c b/src/templates/chcore.c
index 2aaa0b06a..95427c161 100644
--- a/src/templates/chcore.c
+++ b/src/templates/chcore.c
@@ -55,6 +55,30 @@ void chSysHalt(void) {
 }

 

 /**

+ * Enters the ChibiOS/RT system mutual exclusion zone. The implementation is

+ * architecture dependent, on single core systems usually this function usually

+ * just disables the interrupts.

+ * @note The code in the system mutual exclusion zone must be as light and

+ *       fast as possible, the system performance is affected by this.

+ * @note The use of system mutual exclusion zones are not recommended in

+ *       the user code, it is a better idea to use the Semaphores instead.

+ */

+void chSysLock(void) {

+}

+

+/**

+ * Leaves the ChibiOS/RT system mutual exclusion zone. The implementation is

+ * architecture dependent, on single core systems usually this function usually

+ * just enables the interrupts.

+ * @note The code in the system mutual exclusion zone must be as light and

+ *       fast as possible, the system performance is affected by this.

+ * @note The use of system mutual exclusion zones are not recommended in

+ *       the user code, it is a better idea to use the Semaphores instead.

+ */

+void chSysUnlock(void) {

+}

+

+/**

  * Context switch.

  */

 void chSysSwitchI(Thread *otp, Thread *ntp) {}

diff --git a/src/templates/chcore.h b/src/templates/chcore.h
index c84a237f8..1be2d7145 100644
--- a/src/templates/chcore.h
+++ b/src/templates/chcore.h
@@ -84,28 +84,6 @@ typedef struct {
 #define WorkingArea(s, n) uint8_t s[UserStackSize(n)];

 

 /**

- * Enters the ChibiOS/RT system mutual exclusion zone, the implementation is

- * architecture dependent, on single core systems usually this function

- * just disables the interrupts.

- * @note The code in the system mutual exclusion zone must be as light and

- *       fast as possible, the system performance is affected by this.

- * @note The use of system mutual exclusion zones are not recommended in

- *       the user code, it is a better idea to use the Semaphores instead.

- */

-#define chSysLock()

-

-/**

- * Leaves the ChibiOS/RT system mutual exclusion zone, the implementation is

- * architecture dependent, on single core systems usually this function

- * just enables the interrupts.

- * @note The code in the system mutual exclusion zone must be as light and

- *       fast as possible, the system performance is affected by this.

- * @note The use of system mutual exclusion zones are not recommended in

- *       the user code, it is a better idea to use the Semaphores instead.

- */

-#define chSysUnlock()

-

-/**

  * Enables the interrupts, it is only invoked once into \p chSysInit().

  */

 #define chSysEnable()

@@ -130,6 +108,8 @@ extern "C" {
 #endif

   void _IdleThread(void *p);

   void chSysHalt(void);

+  void chSysLock(void);

+  void chSysUnlock(void);

   void chSysSwitchI(Thread *otp, Thread *ntp);

   void chSysPuts(char *msg);

 #ifdef __cplusplus

diff --git a/src/templates/chtypes.h b/src/templates/chtypes.h
index 6c51687ad..92b5dc443 100644
--- a/src/templates/chtypes.h
+++ b/src/templates/chtypes.h
@@ -33,16 +33,35 @@
 #include <stdint.h>

 #endif

 

-typedef int32_t         bool_t;     /* Signed boolean. */

-typedef uint8_t         tmode_t;    /* Thread mode flags, uint8_t is ok. */

-typedef uint8_t         tstate_t;   /* Thread state, uint8_t is ok. */

-typedef uint16_t        tid_t;      /* Thread id. */

-typedef uint32_t        tprio_t;    /* Priority, use the fastest unsigned type. */

-typedef int32_t         msg_t;      /* Message, use signed pointer equivalent.*/

-typedef int32_t         eventid_t;  /* Event Id, use fastest signed.*/

-typedef uint32_t        eventmask_t;/* Event Mask, recommended fastest unsigned.*/

-typedef uint32_t        systime_t;  /* System Time, recommended fastest unsigned.*/

-typedef int32_t         cnt_t;      /* Counter, recommended fastest signed.*/

+/** Signed boolean. */

+typedef int32_t         bool_t;

+

+/** Thread mode flags, uint8_t is ok. */

+typedef uint8_t         tmode_t;

+

+/** Thread state, uint8_t is ok. */

+typedef uint8_t         tstate_t;

+

+/** Thread id. */

+typedef uint16_t        tid_t;

+

+/** Priority, use the fastest unsigned type. */

+typedef uint32_t        tprio_t;

+

+/** Message, use signed pointer equivalent.*/

+typedef int32_t         msg_t;

+

+/** Event Id, use fastest signed.*/

+typedef int32_t         eventid_t;

+

+/** Event Mask, recommended fastest unsigned.*/

+typedef uint32_t        eventmask_t;

+

+/** System Time, recommended fastest unsigned.*/

+typedef uint32_t        systime_t;

+

+/** Counter, recommended fastest signed.*/

+typedef int32_t         cnt_t;

 

 #define INLINE      inline

 #define PACK_STRUCT_STRUCT __attribute__((packed))