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

42 files changed, 519 insertions, 104 deletions

diff --git a/docs/Doxyfile b/docs/Doxyfile
index bcf262453..ee6752f5d 100644
--- a/docs/Doxyfile
+++ b/docs/Doxyfile
@@ -189,7 +189,27 @@ TAB_SIZE               = 2
 # will result in a user-defined paragraph with heading "Side Effects:". 
 # You can put \n's in the value part of an alias to insert newlines.
 
-ALIASES                = 
+ALIASES                = "iclass=@par Function Class:\n This is an          \
+                          <b>I-Class</b> API, this function can be          \
+                          invoked from within a system lock zone by both    \
+                          threads and interrupt handlers."                  \
+                         "sclass=@par Function Class:\n This is an          \
+                          <b>S-Class</b> API, this function can be          \
+                          invoked from within a system lock zone by threads \
+                          only."                                            \
+                         "api=@par Function Class:\n Normal API, this       \
+                          function can be invoked by regular system threads \
+                          but not from within a lock zone."                 \
+                         "notapi=@par Function Class:\n Not an API, this    \
+                          function is for internal use only."               \
+                         "isr=@par Function Class:\n Interrupt handler,     \
+                          this function should not be directly invoked."    \
+                         "init=@par Function Class:\n Initializer, this     \
+                          function just initializes an object and can be    \
+                          invoked before the kernel is initialized."        \
+                         "special=@par Function Class:\n Special function,  \
+                          this function has special requirements see the    \
+                          notes."
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C 
 # sources only. Doxygen will then generate output that is more tailored for C. 
diff --git a/os/hal/platforms/LPC11xx/serial_lld.c b/os/hal/platforms/LPC11xx/serial_lld.c
index 2cff76cd6..881087bc6 100644
--- a/os/hal/platforms/LPC11xx/serial_lld.c
+++ b/os/hal/platforms/LPC11xx/serial_lld.c
@@ -137,7 +137,7 @@ static void serve_interrupt(SerialDriver *sdp) {
     case IIR_SRC_TIMEOUT:

     case IIR_SRC_RX:

       chSysLockFromIsr();

-      if (chIQIsEmpty(&sdp->iqueue))

+      if (chIQIsEmptyI(&sdp->iqueue))

         chEvtBroadcastI(&sdp->ievent);

       chSysUnlockFromIsr();

       while (u->LSR & LSR_RBR_FULL) {

diff --git a/os/hal/platforms/LPC13xx/serial_lld.c b/os/hal/platforms/LPC13xx/serial_lld.c
index 53fd7e11e..2c5b7f47e 100644
--- a/os/hal/platforms/LPC13xx/serial_lld.c
+++ b/os/hal/platforms/LPC13xx/serial_lld.c
@@ -137,7 +137,7 @@ static void serve_interrupt(SerialDriver *sdp) {
     case IIR_SRC_TIMEOUT:

     case IIR_SRC_RX:

       chSysLockFromIsr();

-      if (chIQIsEmpty(&sdp->iqueue))

+      if (chIQIsEmptyI(&sdp->iqueue))

         chEvtBroadcastI(&sdp->ievent);

       chSysUnlockFromIsr();

       while (u->LSR & LSR_RBR_FULL) {

diff --git a/os/hal/platforms/LPC214x/serial_lld.c b/os/hal/platforms/LPC214x/serial_lld.c
index 21c39f674..87699aeb1 100644
--- a/os/hal/platforms/LPC214x/serial_lld.c
+++ b/os/hal/platforms/LPC214x/serial_lld.c
@@ -144,7 +144,7 @@ static void serve_interrupt(SerialDriver *sdp) {
     case IIR_SRC_TIMEOUT:

     case IIR_SRC_RX:

       chSysLockFromIsr();

-      if (chIQIsEmpty(&sdp->iqueue))

+      if (chIQIsEmptyI(&sdp->iqueue))

         chEvtBroadcastI(&sdp->ievent);

       chSysUnlockFromIsr();

       while (u->UART_LSR & LSR_RBR_FULL) {

diff --git a/os/hal/src/serial.c b/os/hal/src/serial.c
index 94418e46c..48518e66c 100644
--- a/os/hal/src/serial.c
+++ b/os/hal/src/serial.c
@@ -61,12 +61,12 @@ static size_t reads(void *ip, uint8_t *bp, size_t n) {
 

 static bool_t putwouldblock(void *ip) {

 

-  return chOQIsFull(&((SerialDriver *)ip)->oqueue);

+  return chOQIsFullI(&((SerialDriver *)ip)->oqueue);

 }

 

 static bool_t getwouldblock(void *ip) {

 

-  return chIQIsEmpty(&((SerialDriver *)ip)->iqueue);

+  return chIQIsEmptyI(&((SerialDriver *)ip)->iqueue);

 }

 

 static msg_t putt(void *ip, uint8_t b, systime_t timeout) {

@@ -192,7 +192,7 @@ void sdIncomingDataI(SerialDriver *sdp, uint8_t b) {
 

   chDbgCheck(sdp != NULL, "sdIncomingDataI");

 

-  if (chIQIsEmpty(&sdp->iqueue))

+  if (chIQIsEmptyI(&sdp->iqueue))

     chEvtBroadcastI(&sdp->ievent);

   if (chIQPutI(&sdp->iqueue, b) < Q_OK)

     sdAddFlagsI(sdp, SD_OVERRUN_ERROR);

diff --git a/os/kernel/include/chbsem.h b/os/kernel/include/chbsem.h
index 04d4579da..238ee2607 100644
--- a/os/kernel/include/chbsem.h
+++ b/os/kernel/include/chbsem.h
@@ -91,6 +91,8 @@ typedef struct  {
  *                      - @a FALSE, the initial state is not taken.

  *                      - @a TRUE, the initial state is taken.

  *                      .

+ *

+ * @init

  */

 #define chBSemInit(bsp, taken) chSemInit(&bsp->bs_sem, taken ? 0 : 1)

 

@@ -98,9 +100,13 @@ typedef struct  {
  * @brief   Wait operation on the binary semaphore.

  *

  * @param[in] bsp       pointer to a @p BinarySemaphore structure
- * @retval RDY_OK       if the binary semaphore had been successfully taken.

+ * @return              A message specifying how the invoking thread has been

+ *                      released from the semaphore.

+ * @retval RDY_OK       if the binary semaphore has been successfully taken.

  * @retval RDY_RESET    if the binary semaphore has been reset using

  *                      @p bsemReset().

+ *

+ * @api

  */

 #define chBSemWait(bsp) chSemWait(&bsp->bs_sem)

 

@@ -108,9 +114,13 @@ typedef struct  {
  * @brief   Wait operation on the binary semaphore.

  *

  * @param[in] bsp       pointer to a @p BinarySemaphore structure

- * @retval RDY_OK       if the binary semaphore had been successfully taken.

+ * @return              A message specifying how the invoking thread has been

+ *                      released from the semaphore.

+ * @retval RDY_OK       if the binary semaphore has been successfully taken.

  * @retval RDY_RESET    if the binary semaphore has been reset using

  *                      @p bsemReset().

+ *

+ * @sclass

  */

 #define chBSemWaitS(bsp) chSemWaitS(&bsp->bs_sem)

 

@@ -123,11 +133,15 @@ typedef struct  {
  *                      - @a TIME_IMMEDIATE immediate timeout.

  *                      - @a TIME_INFINITE no timeout.

  *                      .

- * @retval RDY_OK       if the binary semaphore had been successfully taken.

+ * @return              A message specifying how the invoking thread has been

+ *                      released from the semaphore.

+ * @retval RDY_OK       if the binary semaphore has been successfully taken.

  * @retval RDY_RESET    if the binary semaphore has been reset using

  *                      @p bsemReset().

- * @retval RDY_TIMEOUT  if the binary semaphore was not signaled or reset

+ * @retval RDY_TIMEOUT  if the binary semaphore has not been signaled or reset

  *                      within the specified timeout.

+ *

+ * @api

  */

 #define chBSemWaitTimeout(bsp, time) chSemWaitTimeout(&bsp->bs_sem, time)

 

@@ -140,11 +154,15 @@ typedef struct  {
  *                      - @a TIME_IMMEDIATE immediate timeout.

  *                      - @a TIME_INFINITE no timeout.

  *                      .

- * @retval RDY_OK       if the binary semaphore had been successfully taken.

+ * @return              A message specifying how the invoking thread has been

+ *                      released from the semaphore.

+ * @retval RDY_OK       if the binary semaphore has been successfully taken.

  * @retval RDY_RESET    if the binary semaphore has been reset using

  *                      @p bsemReset().

- * @retval RDY_TIMEOUT  if the binary semaphore was not signaled or reset

+ * @retval RDY_TIMEOUT  if the binary semaphore has not been signaled or reset

  *                      within the specified timeout.

+ *

+ * @sclass

  */

 #define chBSemWaitTimeoutS(bsp, time) chSemWaitTimeoutS(&bsp->bs_sem, time)

 

@@ -159,6 +177,8 @@ typedef struct  {
  *                      - @a FALSE, the new state is not taken.

  *                      - @a TRUE, the new state is taken.

  *                      .

+ *

+ * @api

  */

 #define chBSemReset(bsp, taken) chSemReset(&bsp->bs_sem, taken ? 0 : 1)

 

@@ -174,6 +194,8 @@ typedef struct  {
  *                      - @a FALSE, the new state is not taken.

  *                      - @a TRUE, the new state is taken.

  *                      .

+ *

+ * @iclass

  */

 #define chBSemResetI(bsp, taken) chSemResetI(&bsp->bs_sem, taken ? 0 : 1)

 

@@ -181,6 +203,8 @@ typedef struct  {
  * @brief   Performs a signal operation on a binary semaphore.

  *

  * @param[in] bsp       pointer to a @p BinarySemaphore structure

+ *

+ * @api

  */

 #define chBSemSignal(bsp) {                                                 \

   chSysLock();                                                              \

@@ -194,6 +218,8 @@ typedef struct  {
  * @note    This function does not reschedule.

  *

  * @param[in] bsp       pointer to a @p BinarySemaphore structure

+ *

+ * @iclass

  */

 #define chBSemSignalI(bsp) {                                                \

   if (bsp->bs_sem.s_cnt < 1)                                                \

@@ -207,6 +233,8 @@ typedef struct  {
  * @return              The binary semaphore current state.

  * @retval FALSE        if the binary semaphore is not taken.

  * @retval TRUE         if the binary semaphore is taken.

+ *

+ * @iclass

  */

 #define chBSemGetStateI(bsp) ((bsp)->bs_sem.s_cnt > 0 ? 0 : 1)

 

diff --git a/os/kernel/include/chdebug.h b/os/kernel/include/chdebug.h
index e6d6f231c..e29b095e8 100644
--- a/os/kernel/include/chdebug.h
+++ b/os/kernel/include/chdebug.h
@@ -91,6 +91,8 @@ typedef struct {
  *

  * @param[in] c         the condition to be verified to be true

  * @param[in] func      the undecorated function name

+ *

+ * @api

  */

 #define chDbgCheck(c, func) {                                           \

   if (!(c))                                                             \

@@ -117,6 +119,8 @@ typedef struct {
  * @param[in] c         the condition to be verified to be true

  * @param[in] m         the text message

  * @param[in] r         a remark string

+ *

+ * @api

  */

 #define chDbgAssert(c, m, r) {                                          \

   if (!(c))                                                             \

diff --git a/os/kernel/include/chevents.h b/os/kernel/include/chevents.h
index cf7939d57..6a1cd6106 100644
--- a/os/kernel/include/chevents.h
+++ b/os/kernel/include/chevents.h
@@ -90,6 +90,8 @@ typedef struct EventSource {
  *                      function.

  *                      The value must range between zero and the size, in bit,

  *                      of the @p eventid_t type minus one.

+ *

+ * @api

  */

 #define chEvtRegister(esp, elp, eid) \

   chEvtRegisterMask(esp, elp, EVENT_MASK(eid))

@@ -100,17 +102,20 @@ typedef struct EventSource {
  *          because it just prepares a @p EventSource structure.

  *

  * @param[in] esp       pointer to the @p EventSource structure

+ *

+ * @init

  */

 #define chEvtInit(esp) \

   ((esp)->es_next = (EventListener *)(void *)(esp))

 

 /**

  * @brief   Verifies if there is at least one @p EventListener registered.

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

  *

  * @param[in] esp       pointer to the @p EventSource structure

+ *

+ * @iclass

  */

-#define chEvtIsListening(esp) \

+#define chEvtIsListeningI(esp) \

   ((void *)(esp) != (void *)(esp)->es_next)

 

 /**

diff --git a/os/kernel/include/chfiles.h b/os/kernel/include/chfiles.h
index 3053419d9..dbe5e0567 100644
--- a/os/kernel/include/chfiles.h
+++ b/os/kernel/include/chfiles.h
@@ -96,6 +96,8 @@ typedef struct {
  * @details The function closes a file stream.

  *

  * @param[in] ip        pointer to a @p BaseFileStream or derived class

+ *

+ * @api

  */

 #define chFileStreamClose(ip) ((ip)->vmt->close(ip))

 

@@ -103,6 +105,8 @@ typedef struct {
  * @brief   Returns an implementation dependent error code.

  *

  * @param[in] ip        pointer to a @p BaseFileStream or derived class

+ *

+ * @api

  */

 #define chFileStreamGetError ((ip)->vmt->geterror(ip))

 

@@ -110,6 +114,8 @@ typedef struct {
  * @brief   Returns the current file size.

  *

  * @param[in] ip        pointer to a @p BaseFileStream or derived class

+ *

+ * @api

  */

 #define chFileStreamGetSize ((ip)->vmt->getposition(ip))

 

@@ -117,6 +123,8 @@ typedef struct {
  * @brief   Returns the current file pointer position.

  *

  * @param[in] ip        pointer to a @p BaseFileStream or derived class

+ *

+ * @api

  */

 #define chFileStreamGetPosition ((ip)->vmt->getposition(ip))

 

@@ -125,6 +133,8 @@ typedef struct {
  *

  * @param[in] ip        pointer to a @p BaseFileStream or derived class

  * @param[in] offset    new absolute position

+ *

+ * @api

  */

 #define chFileStreamSeek ((ip)->vmt->lseek(ip, offset))

 

diff --git a/os/kernel/include/chioch.h b/os/kernel/include/chioch.h
index 40103d0a5..3fff4b626 100644
--- a/os/kernel/include/chioch.h
+++ b/os/kernel/include/chioch.h
@@ -91,11 +91,13 @@ typedef struct {
  *          block.

  *

  * @param[in] ip        pointer to a @p BaseChannel or derived class

- * @return              The output queue status:

+ * @return              The output queue status.

  * @retval FALSE        if the output queue has space and would not block a

  *                      write operation.

  * @retval TRUE         if the output queue is full and would block a write

  *                      operation.

+ *

+ * @api

  */

 #define chIOPutWouldBlock(ip) ((ip)->vmt->putwouldblock(ip))

 

@@ -105,11 +107,13 @@ typedef struct {
  *          block.

  *

  * @param[in] ip        pointer to a @p BaseChannel or derived class

- * @return              The input queue status:

+ * @return              The input queue status.

  * @retval FALSE        if the input queue contains data and would not block a

  *                      read operation.

  * @retval TRUE         if the input queue is empty and would block a read

  *                      operation.

+ *

+ * @api

  */

 #define chIOGetWouldBlock(ip) ((ip)->vmt->getwouldblock(ip))

 

@@ -120,9 +124,11 @@ typedef struct {
  *

  * @param[in] ip        pointer to a @p BaseChannel or derived class

  * @param[in] b         the byte value to be written to the channel

- * @return              The operation status:

+ * @return              The operation status.

  * @retval Q_OK         if the operation succeeded.

  * @retval Q_RESET      if the channel associated queue (if any) was reset.

+ *

+ * @api

  */

 #define chIOPut(ip, b) ((ip)->vmt->put(ip, b, TIME_INFINITE))

 

@@ -138,10 +144,12 @@ typedef struct {
  *                      - @a TIME_IMMEDIATE immediate timeout.

  *                      - @a TIME_INFINITE no timeout.

  *                      .

- * @return              The operation status:

+ * @return              The operation status.

  * @retval Q_OK         if the operation succeeded.

  * @retval Q_TIMEOUT    if the specified time expired.

  * @retval Q_RESET      if the channel associated queue (if any) was reset.

+ *

+ * @api

  */

 #define chIOPutTimeout(ip, b, time) ((ip)->vmt->put(ip, b, time))

 

@@ -151,8 +159,11 @@ typedef struct {
  *          is not available then the calling thread is suspended.

  *

  * @param[in] ip        pointer to a @p BaseChannel or derived class

- * @return              A byte value from the queue or:

- * @retval Q_RESET      if the channel associated queue (if any) was reset.

+ * @return              A byte value from the queue.

+ * @retval Q_RESET      if the channel associated queue (if any) has been

+ *                      reset.

+ *

+ * @api

  */

 #define chIOGet(ip) ((ip)->vmt->get(ip, TIME_INFINITE))

 

@@ -167,9 +178,12 @@ typedef struct {
  *                      - @a TIME_IMMEDIATE immediate timeout.

  *                      - @a TIME_INFINITE no timeout.

  *                      .

- * @return              A byte value from the queue or:

+ * @return              A byte value from the queue.

  * @retval Q_TIMEOUT    if the specified time expired.

- * @retval Q_RESET      if the channel associated queue (if any) was reset.

+ * @retval Q_RESET      if the channel associated queue (if any) has been

+ *                      reset.

+ *

+ * @api

  */

 #define chIOGetTimeout(ip, time) ((ip)->vmt->get(ip, time))

 

@@ -187,6 +201,8 @@ typedef struct {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The number of bytes transferred.

+ *

+ * @api

  */

 #define chIOWriteTimeout(ip, bp, n, time)                                   \

   ((ip)->vmt->writet(ip, bp, n, time))

@@ -205,6 +221,8 @@ typedef struct {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The number of bytes transferred.

+ *

+ * @api

  */

 #define chIOReadTimeout(ip, bp, n, time)                                    \

   ((ip)->vmt->readt(ip, bp, n, time))

@@ -255,6 +273,8 @@ typedef struct {
  * @param[in] ip        pointer to a @p BaseAsynchronousChannel or derived

  *                      class

  * @return              A pointer to an @p EventSource object.

+ *

+ * @api

  */

 #define chIOGetWriteEventSource(ip) (&((ip)->vmt->oevent))

 

@@ -267,6 +287,8 @@ typedef struct {
  * @param[in] ip        pointer to a @p BaseAsynchronousChannel or derived

  *                      class

  * @return              A pointer to an @p EventSource object.

+ *

+ * @api

  */

 #define chIOGetReadEventSource(ip) (&((ip)->vmt->ievent))

 

diff --git a/os/kernel/include/chlists.h b/os/kernel/include/chlists.h
index d3eef5417..a93ccedb4 100644
--- a/os/kernel/include/chlists.h
+++ b/os/kernel/include/chlists.h
@@ -35,23 +35,31 @@ typedef struct Thread Thread;
 

 /**

  * @brief   Threads queue initialization.

+ *

+ * @notapi

  */

 #define queue_init(tqp) ((tqp)->p_next = (tqp)->p_prev = (Thread *)(tqp));

 

 /**

  * @brief   Threads list initialization.

+ *

+ * @notapi

  */

 #define list_init(tlp) ((tlp)->p_next = (Thread *)(tlp))

 

 /**

  * @brief   Evaluates to @p TRUE if the specified threads queue or list is

  * empty.

+ *

+ * @notapi

  */

 #define isempty(p)      ((p)->p_next == (Thread *)(p))

 

 /**

  * @brief   Evaluates to @p TRUE if the specified threads queue or list is

  *          not empty.

+ *

+ * @notapi

  */

 #define notempty(p)     ((p)->p_next != (Thread *)(p))

 

diff --git a/os/kernel/include/chmboxes.h b/os/kernel/include/chmboxes.h
index 4447b02d1..ed4bec8ff 100644
--- a/os/kernel/include/chmboxes.h
+++ b/os/kernel/include/chmboxes.h
@@ -72,8 +72,10 @@ extern "C" {
  * @brief   Returns the mailbox buffer size.

  *

  * @param[in] mbp       the pointer to an initialized Mailbox object

+ *

+ * @iclass

  */

-#define chMBSize(mbp)                                                   \

+#define chMBSizeI(mbp)                                                      \

         ((mbp)->mb_top - (mbp)->mb_buffer)

 

 /**

@@ -85,8 +87,10 @@ extern "C" {
  *

  * @param[in] mbp       the pointer to an initialized Mailbox object

  * @return              The number of empty message slots.

+ *

+ * @iclass

  */

-#define chMBGetEmpty(mbp) chSemGetCounterI(&(mbp)->mb_emptysem)

+#define chMBGetEmptyI(mbp) chSemGetCounterI(&(mbp)->mb_emptysem)

 

 /**

  * @brief   Returns the number of messages into the mailbox.

@@ -97,8 +101,10 @@ extern "C" {
  *

  * @param[in] mbp       the pointer to an initialized Mailbox object

  * @return              The number of queued messages.

+ *

+ * @iclass

  */

-#define chMBGetFull(mbp) chSemGetCounterI(&(mbp)->mb_fullsem)

+#define chMBGetFullI(mbp) chSemGetCounterI(&(mbp)->mb_fullsem)

 

 /**

  * @brief   Returns the next message in the queue without removing it.

@@ -106,8 +112,10 @@ extern "C" {
  *          or it would return garbage. The correct way to use this macro is

  *          to use @p chMBGetFull() and then use this macro, all within a

  *          lock state.

+ *

+ * @iclass

  */

-#define chMBPeek(mbp) (*(mbp)->mb_rdptr)

+#define chMBPeekI(mbp) (*(mbp)->mb_rdptr)

 

 /**

  * @brief   Data part of a static mailbox initializer.

diff --git a/os/kernel/include/chmsg.h b/os/kernel/include/chmsg.h
index 16f6d1ef4..438da021f 100644
--- a/os/kernel/include/chmsg.h
+++ b/os/kernel/include/chmsg.h
@@ -32,12 +32,16 @@
 

 /**

  * @brief   Evaluates to TRUE if the thread has pending messages.

+ *

+ * @iclass

  */

 #define chMsgIsPendingI(tp) \

         ((tp)->p_msgqueue.p_next != (Thread *)&(tp)->p_msgqueue)

 

 /**

  * @brief   Returns the first message in the queue.

+ *

+ * @iclass

  */

 #define chMsgGetI(tp) \

         ((tp)->p_msgqueue.p_next->p_msg)

diff --git a/os/kernel/include/chmtx.h b/os/kernel/include/chmtx.h
index c551f47bf..cb0e78001 100644
--- a/os/kernel/include/chmtx.h
+++ b/os/kernel/include/chmtx.h
@@ -78,6 +78,8 @@ extern "C" {
 /**

  * @brief   Returns @p TRUE if the mutex queue contains at least a waiting

  *          thread.

+ *

+ * @sclass

  */

 #define chMtxQueueNotEmptyS(mp) notempty(&(mp)->m_queue)

 

diff --git a/os/kernel/include/chqueues.h b/os/kernel/include/chqueues.h
index c18da0fc7..92007ae0f 100644
--- a/os/kernel/include/chqueues.h
+++ b/os/kernel/include/chqueues.h
@@ -72,8 +72,10 @@ typedef struct {
 

 /**

  * @brief   Returns the queue's buffer size.

+ *

+ * @iclass

  */

-#define chQSize(q) ((q)->q_top - (q)->q_buffer)

+#define chQSizeI(q) ((q)->q_top - (q)->q_buffer)

 

 /**

  * @brief   Queue space.

@@ -81,8 +83,10 @@ typedef struct {
  *          space if used on an Output Queue.

  * @note    The returned value can be less than zero when there are waiting

  *          threads on the internal semaphore.

+ *

+ * @iclass

  */

-#define chQSpace(q) chSemGetCounterI(&(q)->q_sem)

+#define chQSpaceI(q) chSemGetCounterI(&(q)->q_sem)

 

 /**

  * @extends GenericQueue

@@ -97,11 +101,19 @@ typedef struct {
  */

 typedef GenericQueue InputQueue;

 

-/** @brief Evaluates to @p TRUE if the specified Input Queue is empty.*/

-#define chIQIsEmpty(q) ((bool_t)(chQSpace(q) <= 0))

+/**

+ * @brief   Evaluates to @p TRUE if the specified Input Queue is empty.

+ *

+ * @iclass

+ */

+#define chIQIsEmptyI(q) ((bool_t)(chQSpaceI(q) <= 0))

 

-/** @brief Evaluates to @p TRUE if the specified Input Queue is full.*/

-#define chIQIsFull(q) ((bool_t)(chQSpace(q) >= chQSize(q)))

+/**

+ * @brief   Evaluates to @p TRUE if the specified Input Queue is full.

+ *

+ * @iclass

+ */

+#define chIQIsFullI(q) ((bool_t)(chQSpaceI(q) >= chQSizeI(q)))

 

 /**

  * @brief   Input queue read.

@@ -110,8 +122,10 @@ typedef GenericQueue InputQueue;
  *          in the queue.

  *

  * @param[in] iqp       pointer to an @p InputQueue structure

- * @return              A byte value from the queue or:

+ * @return              A byte value from the queue.

  * @retval Q_RESET      if the queue was reset.

+ *

+ * @api

  */

 #define chIQGet(iqp) chIQGetTimeout(iqp, TIME_INFINITE)

 

@@ -162,13 +176,17 @@ typedef GenericQueue OutputQueue;
 

 /**

  * @brief   Evaluates to @p TRUE if the specified Output Queue is empty.

+ *

+ * @iclass

  */

-#define chOQIsEmpty(q) ((bool_t)(chQSpace(q) >= chQSize(q)))

+#define chOQIsEmptyI(q) ((bool_t)(chQSpaceI(q) >= chQSizeI(q)))

 

 /**

  * @brief   Evaluates to @p TRUE if the specified Output Queue is full.

+ *

+ * @iclass

  */

-#define chOQIsFull(q) ((bool_t)(chQSpace(q) <= 0))

+#define chOQIsFullI(q) ((bool_t)(chQSpaceI(q) <= 0))

 

 /**

  * @brief   Output queue write.

@@ -178,9 +196,11 @@ typedef GenericQueue OutputQueue;
  *

  * @param[in] oqp       pointer to an @p OutputQueue structure

  * @param[in] b         the byte value to be written in the queue

- * @return              The operation status:

+ * @return              The operation status.

  * @retval Q_OK         if the operation succeeded.

  * @retval Q_RESET      if the queue was reset.

+ *

+ * @api

  */

 #define chOQPut(oqp, b) chOQPutTimeout(oqp, b, TIME_INFINITE)

 

diff --git a/os/kernel/include/chschd.h b/os/kernel/include/chschd.h
index e5c6d7e55..a9283c290 100644
--- a/os/kernel/include/chschd.h
+++ b/os/kernel/include/chschd.h
@@ -58,6 +58,8 @@
 

 /**

  * @brief   Returns the priority of the first thread on the given ready list.

+ *

+ * @notapi

  */

 #define firstprio(rlp)  ((rlp)->p_next->p_prio)

 

@@ -111,6 +113,8 @@ register Thread *currp asm(CH_CURRP_REGISTER_CACHE);
  * @brief   Current thread pointer change macro.

  * @note    This macro is not meant to be used in the application code but

  *          only from within the kernel.

+ *

+ * @notapi

  */

 #if !defined(PORT_OPTIMIZED_SETCURRP) || defined(__DOXYGEN__)

 #define setcurrp(tp) (currp = (tp))

@@ -152,6 +156,8 @@ extern "C" {
  * @brief   Determines if the current thread must reschedule.

  * @details This function returns @p TRUE if there is a ready thread with

  *          higher priority.

+ *

+ * @iclass

  */

 #if !defined(PORT_OPTIMIZED_ISRESCHREQUIREDI) || defined(__DOXYGEN__)

 #define chSchIsRescRequiredI() (firstprio(&rlist.r_queue) > currp->p_prio)

@@ -161,6 +167,8 @@ extern "C" {
  * @brief   Determines if yielding is possible.

  * @details This function returns @p TRUE if there is a ready thread with

  *          equal or higher priority.

+ *

+ * @sclass

  */

 #if !defined(PORT_OPTIMIZED_CANYIELDS) || defined(__DOXYGEN__)

 #define chSchCanYieldS() (firstprio(&rlist.r_queue) >= currp->p_prio)

@@ -170,6 +178,8 @@ extern "C" {
  * @brief   Yields the time slot.

  * @details Yields the CPU control to the next thread in the ready list with

  *          equal or higher priority, if any.

+ *

+ * @sclass

  */

 #if !defined(PORT_OPTIMIZED_DOYIELDS) || defined(__DOXYGEN__)

 #define chSchDoYieldS() {                                                   \

diff --git a/os/kernel/include/chsem.h b/os/kernel/include/chsem.h
index cf0897675..17c6a03e3 100644
--- a/os/kernel/include/chsem.h
+++ b/os/kernel/include/chsem.h
@@ -83,17 +83,24 @@ extern "C" {
 /**

  * @brief   Decreases the semaphore counter.

  * @details This macro can be used when the counter is known to be positive.

+ *

+ * @iclass

  */

 #define chSemFastWaitI(sp)      ((sp)->s_cnt--)

 

 /**

  * @brief   Increases the semaphore counter.

- * @details This macro can be used when the counter is known to be not negative.

+ * @details This macro can be used when the counter is known to be not

+ *          negative.

+ *

+ * @iclass

  */

 #define chSemFastSignalI(sp)    ((sp)->s_cnt++)

 

 /**

  * @brief   Returns the semaphore counter current value.

+ *

+ * @iclass

  */

 #define chSemGetCounterI(sp)    ((sp)->s_cnt)

 

diff --git a/os/kernel/include/chstreams.h b/os/kernel/include/chstreams.h
index 436697a9a..039f0dbd6 100644
--- a/os/kernel/include/chstreams.h
+++ b/os/kernel/include/chstreams.h
@@ -83,6 +83,8 @@ typedef struct {
  *                      be less than the specified number of bytes if the

  *                      stream reaches a physical end of file and cannot be

  *                      extended.

+ *

+ * @api

  */

 #define chSequentialStreamWrite(ip, bp, n) ((ip)->vmt->write(ip, bp, n))

 

@@ -96,6 +98,8 @@ typedef struct {
  * @return              The number of bytes transferred. The return value can

  *                      be less than the specified number of bytes if the

  *                      stream reaches the end of the available data.

+ *

+ * @api

  */

 #define chSequentialStreamRead(ip, bp, n) ((ip)->vmt->read(ip, bp, n))

 

diff --git a/os/kernel/include/chsys.h b/os/kernel/include/chsys.h
index 22396f41f..2a30ceabf 100644
--- a/os/kernel/include/chsys.h
+++ b/os/kernel/include/chsys.h
@@ -35,6 +35,8 @@
  *          object.

  *

  * @return              Pointer to the idle thread,
+ *

+ * @api

  */

 #define chSysGetIdleThread() ((Thread *)_idle_thread_wa)

 

@@ -44,6 +46,9 @@
  *          unrecoverable error is detected, as example because a programming

  *          error in the application code that triggers an assertion while

  *          in debug mode.

+ * @note    Can be invoked from any system state.

+ *

+ * @special

  */

 #if !defined(SYSTEM_HALT_HOOK) || defined(__DOXYGEN__)

 #define chSysHalt() port_halt()

@@ -56,9 +61,12 @@
 

 /**

  * @brief   Performs a context switch.

+ * @note    This function should nevel be used from user code directly.

  *

  * @param[in] ntp       the thread to be switched in

  * @param[in] otp       the thread to be switched out

+ *

+ * @special

  */

 #define chSysSwitchI(ntp, otp) port_switch(ntp, otp)

 

@@ -66,9 +74,9 @@
  * @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.

+ *

+ * @special

  */

 #define chSysDisable() port_disable()

 

@@ -77,22 +85,22 @@
  * @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.

  * @note    This API is no replacement for @p chSysLock(), the @p chSysLock()

  *          could do more than just disable the interrupts.

+ *

+ * @special

  */

 #define chSysSuspend() port_suspend()

 

 /**

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

  * @note    This API is no replacement for @p chSysUnlock(), the

  *          @p chSysUnlock() could do more than just enable the interrupts.

+ *

+ * @special

  */

 #define chSysEnable() port_enable()

 

@@ -101,6 +109,8 @@
  * @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

+ *

+ * @special

  */

 #if CH_USE_NESTED_LOCKS || defined(__DOXYGEN__)

 #if CH_OPTIMIZE_SPEED || defined(__DOXYGEN__)

@@ -118,6 +128,8 @@
  * @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

+ *

+ * @special

  */

 #if CH_USE_NESTED_LOCKS || defined(__DOXYGEN__)

 #if CH_OPTIMIZE_SPEED || defined(__DOXYGEN__)

@@ -139,6 +151,8 @@
  *          It is good practice to invoke this API before invoking any I-class

  *          syscall from an interrupt handler.

  * @note    This API must be invoked exclusively from interrupt handlers.

+ *

+ * @special

  */

 #define chSysLockFromIsr() port_lock_from_isr()

 

@@ -151,7 +165,9 @@
  *          the system mutual exclusion zone.<br>

  *          It is good practice to invoke this API after invoking any I-class

  *          syscall from an interrupt handler.

- * @note This API must be invoked exclusively from interrupt handlers.

+ * @note    This API must be invoked exclusively from interrupt handlers.

+ *

+ * @special

  */

 #define chSysUnlockFromIsr() port_unlock_from_isr()

 

diff --git a/os/kernel/include/chthreads.h b/os/kernel/include/chthreads.h
index 9748166b9..97e03840b 100644
--- a/os/kernel/include/chthreads.h
+++ b/os/kernel/include/chthreads.h
@@ -244,11 +244,15 @@ extern "C" {
 

 /**

  * @brief   Returns a pointer to the current @p Thread.

+ *

+ * @api

  */

 #define chThdSelf() currp

 

 /**

  * @brief   Returns the current thread priority.

+ *

+ * @api

  */

 #define chThdGetPriority() (currp->p_prio)

 

@@ -258,11 +262,15 @@ extern "C" {
  *          @p CH_DBG_THREADS_PROFILING configuration option is enabled.

  *

  * @param[in] tp        the pointer to the thread

+ *

+ * @api

  */

 #define chThdGetTicks(tp) ((tp)->p_time)

 

 /**

  * @brief   Returns the pointer to the @p Thread local storage area, if any.

+ *

+ * @api

  */

 #define chThdLS() (void *)(currp + 1)

 

@@ -272,6 +280,8 @@ extern "C" {
  * @param[in] tp        the pointer to the thread

  * @retval TRUE         thread terminated.

  * @retval FALSE        thread not terminated.

+ *

+ * @api

  */

 #define chThdTerminated(tp) ((tp)->p_state == THD_STATE_FINAL)

 

@@ -280,6 +290,8 @@ extern "C" {
  *

  * @retval TRUE         termination request pended.

  * @retval FALSE        termination request not pended.

+ *

+ * @api

  */

 #define chThdShouldTerminate() (currp->p_flags & THD_TERMINATE)

 

@@ -287,6 +299,8 @@ extern "C" {
  * @brief   Resumes a thread created with @p chThdInit().

  *

  * @param[in] tp        the pointer to the thread

+ *

+ * @iclass

  */

 #define chThdResumeI(tp) chSchReadyI(tp)

 

@@ -301,6 +315,8 @@ extern "C" {
  *                        interpreted as a normal time specification not as

  *                        an immediate timeout specification.

  *                      .

+ *

+ * @sclass

  */

 #define chThdSleepS(time) chSchGoSleepTimeoutS(THD_STATE_SLEEPING, time)

 

@@ -311,6 +327,8 @@ extern "C" {
  * @note    The maximum specified value is implementation dependent.

  *

  * @param[in] sec       the time in seconds

+ *

+ * @api

  */

 #define chThdSleepSeconds(sec) chThdSleep(S2ST(sec))

 

@@ -322,6 +340,8 @@ extern "C" {
  * @note    The maximum specified value is implementation dependent.

  *

  * @param[in] msec      the time in milliseconds

+ *

+ * @api

  */

 #define chThdSleepMilliseconds(msec) chThdSleep(MS2ST(msec))

 

@@ -333,6 +353,8 @@ extern "C" {
  * @note    The maximum specified value is implementation dependent.

  *

  * @param[in] usec      the time in microseconds

+ *

+ * @api

  */

 #define chThdSleepMicroseconds(usec) chThdSleep(US2ST(usec))

 

diff --git a/os/kernel/include/chvt.h b/os/kernel/include/chvt.h
index 8b065b208..8a44bf703 100644
--- a/os/kernel/include/chvt.h
+++ b/os/kernel/include/chvt.h
@@ -94,6 +94,8 @@ extern VTList vtlist;
 

 /**

  * @brief   Virtual timers ticker.

+ *

+ * @iclass

  */

 #define chVTDoTickI() {                                                 \

   vtlist.vt_systime++;                                                  \

@@ -127,6 +129,8 @@ extern "C" {
 

 /**

  * @brief   Returns TRUE if the speciified timer is armed.

+ *

+ * @iclass

  */

 #define chVTIsArmedI(vtp) ((vtp)->vt_func != NULL)

 

@@ -138,6 +142,8 @@ extern "C" {
  * @note    This function is designed to work with the @p chThdSleepUntil().

  *

  * @return              The system time in ticks.r

+ *

+ * @api

  */

 #define chTimeNow() (vtlist.vt_systime)

 

diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c
index 71729139f..0ad9d459d 100644
--- a/os/kernel/src/chcond.c
+++ b/os/kernel/src/chcond.c
@@ -43,10 +43,10 @@
 

 /**

  * @brief   Initializes s @p CondVar structure.

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p CondVar structure.

  *

  * @param[out] cp       pointer to a @p CondVar structure

+ *

+ * @init

  */

 void chCondInit(CondVar *cp) {

 

@@ -59,6 +59,8 @@ void chCondInit(CondVar *cp) {
  * @brief   Signals one thread that is waiting on the condition variable.

  *

  * @param[in] cp        pointer to the @p CondVar structure

+ *

+ * @api

  */

 void chCondSignal(CondVar *cp) {

 

@@ -78,6 +80,8 @@ void chCondSignal(CondVar *cp) {
  *          reschedule must not be performed in ISRs.

  *

  * @param[in] cp        pointer to the @p CondVar structure

+ *

+ * @iclass

  */

 void chCondSignalI(CondVar *cp) {

 

@@ -91,6 +95,8 @@ void chCondSignalI(CondVar *cp) {
  * @brief   Signals all threads that are waiting on the condition variable.

  *

  * @param[in] cp        pointer to the @p CondVar structure

+ *

+ * @api

  */

 void chCondBroadcast(CondVar *cp) {

 

@@ -108,6 +114,8 @@ void chCondBroadcast(CondVar *cp) {
  *          reschedule must not be performed in ISRs.

  *

  * @param[in] cp        pointer to the @p CondVar structure

+ *

+ * @iclass

  */

 void chCondBroadcastI(CondVar *cp) {

 

@@ -134,6 +142,8 @@ void chCondBroadcastI(CondVar *cp) {
  *                      @p chCondSignal().

  * @retval RDY_RESET    if the condvar has been signaled using

  *                      @p chCondBroadcast().

+ *

+ * @api

  */

 msg_t chCondWait(CondVar *cp) {

   msg_t msg;

@@ -158,6 +168,8 @@ msg_t chCondWait(CondVar *cp) {
  *                      @p chCondSignal().

  * @retval RDY_RESET    if the condvar has been signaled using

  *                      @p chCondBroadcast().

+ *

+ * @sclass

  */

 msg_t chCondWaitS(CondVar *cp) {

   Thread *ctp = currp;

@@ -204,6 +216,8 @@ msg_t chCondWaitS(CondVar *cp) {
  *                      @p chCondBroadcast().

  * @retval RDY_TIMEOUT  if the condvar has not been signaled within the

  *                      specified timeout.

+ *

+ * @api

  */

 msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {

   msg_t msg;

@@ -239,6 +253,8 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
  *                      @p chCondBroadcast().

  * @retval RDY_TIMEOUT  if the condvar has not been signaled within the

  *                      specified timeout.

+ *

+ * @sclass

  */

 msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {

   Mutex *mp;

diff --git a/os/kernel/src/chdebug.c b/os/kernel/src/chdebug.c
index dcf42c2b3..80323e183 100644
--- a/os/kernel/src/chdebug.c
+++ b/os/kernel/src/chdebug.c
@@ -55,6 +55,8 @@ void trace_init(void) {
  * @brief   Inserts in the circular debug trace buffer a context switch record.

  *

  * @param[in] otp       the thread being switched out

+ *

+ * @notapi

  */

 void chDbgTrace(Thread *otp) {

 

diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c
index aac3a22af..a66a7fa28 100644
--- a/os/kernel/src/chevents.c
+++ b/os/kernel/src/chevents.c
@@ -68,6 +68,8 @@
  * @param[in] elp       pointer to the @p EventListener structure

  * @param[in] mask      the mask of event flags to be ORed to the thread when

  *                      the event source is broadcasted

+ *

+ * @api

  */

 void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {

 

@@ -91,6 +93,8 @@ void chEvtRegisterMask(EventSource *esp, EventListener *elp, eventmask_t mask) {
  *

  * @param[in] esp       pointer to the  @p EventSource structure

  * @param[in] elp       pointer to the @p EventListener structure

+ *

+ * @api

  */

 void chEvtUnregister(EventSource *esp, EventListener *elp) {

   EventListener *p;

@@ -114,6 +118,8 @@ void chEvtUnregister(EventSource *esp, EventListener *elp) {
  *

  * @param[in] mask      the events to be cleared

  * @return              The pending events that were cleared.

+ *

+ * @api

  */

 eventmask_t chEvtClearFlags(eventmask_t mask) {

   eventmask_t m;

@@ -133,6 +139,8 @@ eventmask_t chEvtClearFlags(eventmask_t mask) {
  *

  * @param[in] mask      the event flags to be ORed

  * @return              The current pending events mask.

+ *

+ * @api

  */

 eventmask_t chEvtAddFlags(eventmask_t mask) {

 

@@ -149,6 +157,8 @@ eventmask_t chEvtAddFlags(eventmask_t mask) {
  *

  * @param[in] tp        the thread to be signaled

  * @param[in] mask      the event flags set to be ORed

+ *

+ * @api

  */

 void chEvtSignal(Thread *tp, eventmask_t mask) {

 

@@ -169,6 +179,8 @@ void chEvtSignal(Thread *tp, eventmask_t mask) {
  *

  * @param[in] tp        the thread to be signaled

  * @param[in] mask      the event flags set to be ORed

+ *

+ * @iclass

  */

 void chEvtSignalI(Thread *tp, eventmask_t mask) {

 

@@ -188,6 +200,8 @@ void chEvtSignalI(Thread *tp, eventmask_t mask) {
  *          Source.

  *

  * @param[in] esp       pointer to the @p EventSource structure

+ *

+ * @api

  */

 void chEvtBroadcast(EventSource *esp) {

 

@@ -206,6 +220,8 @@ void chEvtBroadcast(EventSource *esp) {
  *          reschedule must not be performed in ISRs.

  *

  * @param[in] esp       pointer to the @p EventSource structure

+ *

+ * @iclass

  */

 void chEvtBroadcastI(EventSource *esp) {

   EventListener *elp;

@@ -225,6 +241,8 @@ void chEvtBroadcastI(EventSource *esp) {
  * @param[in] mask      mask of the event flags to be dispatched

  * @param[in] handlers  an array of @p evhandler_t. The array must have size

  *                      equal to the number of bits in eventmask_t.

+ *

+ * @api

  */

 void chEvtDispatch(const evhandler_t *handlers, eventmask_t mask) {

   eventid_t eid;

@@ -258,6 +276,8 @@ void chEvtDispatch(const evhandler_t *handlers, eventmask_t mask) {
  * @param[in] mask      mask of the event flags that the function should wait

  *                      for, @p ALL_EVENTS enables all the events

  * @return              The mask of the lowest id served and cleared event.

+ *

+ * @api

  */

 eventmask_t chEvtWaitOne(eventmask_t mask) {

   Thread *ctp = currp;

@@ -285,6 +305,8 @@ eventmask_t chEvtWaitOne(eventmask_t mask) {
  * @param[in] mask      mask of the event flags that the function should wait

  *                      for, @p ALL_EVENTS enables all the events

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

+ *

+ * @api

  */

 eventmask_t chEvtWaitAny(eventmask_t mask) {

   Thread *ctp = currp;

@@ -311,6 +333,8 @@ eventmask_t chEvtWaitAny(eventmask_t mask) {
  * @param[in] mask      mask of the event flags that the function should wait

  *                      for, @p ALL_EVENTS requires all the events

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

+ *

+ * @api

  */

 eventmask_t chEvtWaitAll(eventmask_t mask) {

   Thread *ctp = currp;

@@ -348,6 +372,8 @@ eventmask_t chEvtWaitAll(eventmask_t mask) {
  *                      .

  * @return              The mask of the lowest id served and cleared event.

  * @retval 0            if the operation has timed out.

+ *

+ * @api

  */

 eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {

   Thread *ctp = currp;

@@ -385,6 +411,8 @@ eventmask_t chEvtWaitOneTimeout(eventmask_t mask, systime_t time) {
  *                      .

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

  * @retval 0            if the operation has timed out.

+ *

+ * @api

  */

 eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {

   Thread *ctp = currp;

@@ -420,6 +448,8 @@ eventmask_t chEvtWaitAnyTimeout(eventmask_t mask, systime_t time) {
  *                      .

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

  * @retval 0            if the operation has timed out.

+ *

+ * @api

  */

 eventmask_t chEvtWaitAllTimeout(eventmask_t mask, systime_t time) {

   Thread *ctp = currp;

diff --git a/os/kernel/src/chheap.c b/os/kernel/src/chheap.c
index fc92e3c18..13db7cf6b 100644
--- a/os/kernel/src/chheap.c
+++ b/os/kernel/src/chheap.c
@@ -61,7 +61,8 @@ static MemoryHeap default_heap;
 

 /**

  * @brief   Initializes the default heap.

- * @note    Internal use only.

+ *

+ * @notapi

  */

 void heap_init(void) {

   default_heap.h_provider = chCoreAlloc;

@@ -82,6 +83,8 @@ void heap_init(void) {
  * @param[out] heapp    pointer to the memory heap descriptor to be initialized

  * @param[in] buf       heap buffer base

  * @param[in] size      heap size

+ *

+ * @init

  */

 void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {

   union heap_header *hp;

@@ -113,6 +116,8 @@ void chHeapInit(MemoryHeap *heapp, void *buf, size_t size) {
  *                      size for alignment and fragmentation reasons.

  * @return              A pointer to the allocated block.

  * @retval NULL         if the block cannot be allocated.

+ *

+ * @api

  */

 void *chHeapAlloc(MemoryHeap *heapp, size_t size) {

   union heap_header *qp, *hp, *fp;

@@ -173,6 +178,8 @@ void *chHeapAlloc(MemoryHeap *heapp, size_t size) {
  * @brief   Frees a previously allocated memory block.

  *

  * @param[in] p         pointer to the memory block to be freed

+ *

+ * @api

  */

 void chHeapFree(void *p) {

   union heap_header *qp, *hp;

@@ -227,6 +234,8 @@ void chHeapFree(void *p) {
  * @param[in] sizep     pointer to a variable that will receive the total

  *                      fragmented free space

  * @return              The number of fragments in the heap.

+ *

+ * @api

  */

 size_t chHeapStatus(MemoryHeap *heapp, size_t *sizep) {

   union heap_header *qp;

diff --git a/os/kernel/src/chlists.c b/os/kernel/src/chlists.c
index 83bdf8b35..878f1360c 100644
--- a/os/kernel/src/chlists.c
+++ b/os/kernel/src/chlists.c
@@ -23,7 +23,7 @@
  *

  * @addtogroup internals

  * @details All the functions present in this module, while public, are not

- *          an OS API and should not be directly used in the user applications

+ *          OS APIs and should not be directly used in the user applications

  *          code.

  * @{

  */

@@ -32,12 +32,13 @@
 #if !CH_OPTIMIZE_SPEED || defined(__DOXYGEN__)

 /**

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

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

- *          toward the lowest.

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

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

+ *          priority toward the lowest.

  *

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

  * @param[in] tqp       the pointer to the threads list header

+ *

+ * @notapi

  */

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

 

@@ -56,10 +57,11 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
 

 /**

  * @brief   Inserts a Thread into a queue.

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

  *

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

  * @param[in] tqp       the pointer to the threads list header

+ *

+ * @notapi

  */

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

 

@@ -72,10 +74,11 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
  * @brief   Removes the first-out Thread from a queue and returns it.

  * @note    If the queue is priority ordered then this function returns the

  *          thread with the highest priority.

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

  *

  * @param[in] tqp       the pointer to the threads list header

  * @return              The removed thread pointer.

+ *

+ * @notapi

  */

 Thread *fifo_remove(ThreadsQueue *tqp) {

   Thread *tp = tqp->p_next;

@@ -88,10 +91,11 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
  * @brief   Removes the last-out Thread from a queue and returns it.

  * @note    If the queue is priority ordered then this function returns the

  *          thread with the lowest priority.

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

  *

  * @param[in] tqp   the pointer to the threads list header

  * @return          The removed thread pointer.

+ *

+ * @notapi

  */

 Thread *lifo_remove(ThreadsQueue *tqp) {

   Thread *tp = tqp->p_prev;

@@ -104,10 +108,11 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
  * @brief   Removes a Thread from a queue and returns it.

  * @details The thread is removed from the queue regardless of its relative

  *          position and regardless the used insertion method.

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

  *

  * @param[in] tp        the pointer to the thread to be removed from the queue

  * @return              The removed thread pointer.

+ *

+ * @notapi

  */

 Thread *dequeue(Thread *tp) {

 

@@ -118,10 +123,11 @@ Thread *dequeue(Thread *tp) {
 

 /**

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

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

  *

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

  * @param[in] tlp   the pointer to the threads list header

+ *

+ * @notapi

  */

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

 

@@ -131,11 +137,12 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
 

 /**

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

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

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

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

  *

  * @param[in] tlp       the pointer to the threads list header

  * @return              The removed thread pointer.

+ *

+ * @notapi

  */

 Thread *list_remove(ThreadsList *tlp) {

 

diff --git a/os/kernel/src/chmboxes.c b/os/kernel/src/chmboxes.c
index 279778e48..b2cef2470 100644
--- a/os/kernel/src/chmboxes.c
+++ b/os/kernel/src/chmboxes.c
@@ -54,12 +54,12 @@
 #if CH_USE_MAILBOXES || defined(__DOXYGEN__)

 /**

  * @brief   Initializes a Mailbox object.

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p Mailbox structure.

  *

  * @param[out] mbp      the pointer to the Mailbox structure to be initialized

  * @param[in] buf       the circular messages buffer

  * @param[in] n         the buffer size as number of @p msg_t

+ *

+ * @init

  */

 void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {

 

@@ -77,6 +77,8 @@ void chMBInit(Mailbox *mbp, msg_t *buf, cnt_t n) {
  *          the queued messages are lost.

  *

  * @param[in] mbp       the pointer to an initialized Mailbox object

+ *

+ * @api

  */

 void chMBReset(Mailbox *mbp) {

 

@@ -106,6 +108,8 @@ void chMBReset(Mailbox *mbp) {
  * @retval RDY_OK       if a message has been correctly posted.

  * @retval RDY_RESET    if the mailbox has been reset while waiting.

  * @retval RDY_TIMEOUT  if the operation has timed out.

+ *

+ * @api

  */

 msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -132,6 +136,8 @@ msg_t chMBPost(Mailbox *mbp, msg_t msg, systime_t time) {
  * @retval RDY_OK       if a message has been correctly posted.

  * @retval RDY_RESET    if the mailbox has been reset while waiting.

  * @retval RDY_TIMEOUT  if the operation has timed out.

+ *

+ * @sclass

  */

 msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -165,6 +171,8 @@ msg_t chMBPostS(Mailbox *mbp, msg_t msg, systime_t time) {
  * @retval RDY_OK       if a message has been correctly posted.

  * @retval RDY_RESET    if the mailbox has been reset while waiting.

  * @retval RDY_TIMEOUT  if the operation has timed out.

+ *

+ * @api

  */

 msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -191,6 +199,8 @@ msg_t chMBPostAhead(Mailbox *mbp, msg_t msg, systime_t time) {
  * @retval RDY_OK       if a message has been correctly posted.

  * @retval RDY_RESET    if the mailbox has been reset while waiting.

  * @retval RDY_TIMEOUT  if the operation has timed out.

+ *

+ * @sclass

  */

 msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {

   msg_t rdymsg;

@@ -224,6 +234,8 @@ msg_t chMBPostAheadS(Mailbox *mbp, msg_t msg, systime_t time) {
  * @retval RDY_OK       if a message has been correctly fetched.

  * @retval RDY_RESET    if the mailbox has been reset while waiting.

  * @retval RDY_TIMEOUT  if the operation has timed out.

+ *

+ * @api

  */

 msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {

   msg_t rdymsg;

@@ -250,6 +262,8 @@ msg_t chMBFetch(Mailbox *mbp, msg_t *msgp, systime_t time) {
  * @retval RDY_OK       if a message has been correctly fetched.

  * @retval RDY_RESET    if the mailbox has been reset while waiting.

  * @retval RDY_TIMEOUT  if the operation has timed out.

+ *

+ * @sclass

  */

 msg_t chMBFetchS(Mailbox *mbp, msg_t *msgp, systime_t time) {

   msg_t rdymsg;

diff --git a/os/kernel/src/chmemcore.c b/os/kernel/src/chmemcore.c
index 04edb7dae..69d3014a5 100644
--- a/os/kernel/src/chmemcore.c
+++ b/os/kernel/src/chmemcore.c
@@ -50,7 +50,8 @@ static uint8_t *endmem;
 

 /**

  * @brief   Low level memory manager initialization.

- * @note    Internal use only.

+ *

+ * @notapi

  */

 void core_init(void) {

 #if CH_MEMCORE_SIZE == 0

@@ -76,6 +77,8 @@ void core_init(void) {
  * @param[in] size      the size of the block to be allocated

  * @return              A pointer to the allocated memory block.

  * @retval NULL         allocation failed, core memory exhausted.

+ *

+ * @api

  */

 void *chCoreAlloc(size_t size) {

   void *p;

@@ -95,6 +98,8 @@ void *chCoreAlloc(size_t size) {
  * @param[in] size      the size of the block to be allocated.

  * @return              A pointer to the allocated memory block.

  * @retval NULL         allocation failed, core memory exhausted.

+ *

+ * @iclass

  */

 void *chCoreAllocI(size_t size) {

   void *p;

@@ -111,6 +116,8 @@ void *chCoreAllocI(size_t size) {
  * @brief   Core memory status.

  *

  * @return              The size, in bytes, of the free core memory.

+ *

+ * @api

  */

 size_t chCoreStatus(void) {

 

diff --git a/os/kernel/src/chmempools.c b/os/kernel/src/chmempools.c
index e1817aa60..092944b59 100644
--- a/os/kernel/src/chmempools.c
+++ b/os/kernel/src/chmempools.c
@@ -37,8 +37,6 @@
 #if CH_USE_MEMPOOLS || defined(__DOXYGEN__)

 /**

  * @brief   Initializes an empty memory pool.

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p MemoryPool structure.

  * @note    The size is internally aligned to be a multiple of the

  *          @p stkalign_t type size.

  *

@@ -49,6 +47,8 @@
  * @param[in] provider  memory provider function for the memory pool or

  *                      @p NULL if the pool is not allowed to grow

  *                      automatically

+ *

+ * @init

  */

 void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {

 

@@ -65,6 +65,8 @@ void chPoolInit(MemoryPool *mp, size_t size, memgetfunc_t provider) {
  * @param[in] mp        pointer to a @p MemoryPool structure

  * @return              The pointer to the allocated object.

  * @retval NULL         if pool is empty.

+ *

+ * @iclass

  */

 void *chPoolAllocI(MemoryPool *mp) {

   void *objp;

@@ -86,6 +88,8 @@ void *chPoolAllocI(MemoryPool *mp) {
  * @param[in] mp        pointer to a @p MemoryPool structure

  * @return              The pointer to the allocated object.

  * @retval NULL         if pool is empty.

+ *

+ * @api

  */

 void *chPoolAlloc(MemoryPool *mp) {

   void *objp;

@@ -105,6 +109,8 @@ void *chPoolAlloc(MemoryPool *mp) {
  *

  * @param[in] mp        pointer to a @p MemoryPool structure

  * @param[in] objp      the pointer to the object to be released or added

+ *

+ * @iclass

  */

 void chPoolFreeI(MemoryPool *mp, void *objp) {

   struct pool_header *php = objp;

@@ -125,6 +131,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
  *

  * @param[in] mp        pointer to a @p MemoryPool structure

  * @param[in] objp      the pointer to the object to be released or added

+ *

+ * @api

  */

 void chPoolFree(MemoryPool *mp, void *objp) {

 

diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c
index 09acf7b42..c3b4848b0 100644
--- a/os/kernel/src/chmsg.c
+++ b/os/kernel/src/chmsg.c
@@ -61,6 +61,8 @@
  * @param[in] tp        the pointer to the thread

  * @param[in] msg       the message

  * @return              The answer message from @p chMsgRelease().

+ *

+ * @api

  */

 msg_t chMsgSend(Thread *tp, msg_t msg) {

   Thread *ctp = currp;

@@ -88,6 +90,8 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
  *          because the sending thread is suspended until then.

  *

  * @return              The message.

+ *

+ * @api

  */

 msg_t chMsgWait(void) {

   msg_t msg;

@@ -114,6 +118,8 @@ msg_t chMsgWait(void) {
  *

  * @return              The message.

  * @retval 0            if the queue is empty.

+ *

+ * @api

  */

 msg_t chMsgGet(void) {

   msg_t msg;

@@ -130,6 +136,8 @@ msg_t chMsgGet(void) {
  *          using @p chMsgWait() or @p chMsgGet().

  *

  * @param[in] msg       the message returned to the message sender

+ *

+ * @api

  */

 void chMsgRelease(msg_t msg) {

 

diff --git a/os/kernel/src/chmtx.c b/os/kernel/src/chmtx.c
index 9698d3cd8..b84c4d57e 100644
--- a/os/kernel/src/chmtx.c
+++ b/os/kernel/src/chmtx.c
@@ -70,10 +70,10 @@
 

 /**

  * @brief   Initializes s @p Mutex structure.

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p Mutex structure.

  *

  * @param[out] mp       pointer to a @p Mutex structure

+ *

+ * @init

  */

 void chMtxInit(Mutex *mp) {

 

@@ -89,6 +89,8 @@ void chMtxInit(Mutex *mp) {
  *          mutexes.

  *

  * @param[in] mp        pointer to the @p Mutex structure

+ *

+ * @api

  */

 void chMtxLock(Mutex *mp) {

 

@@ -105,6 +107,8 @@ void chMtxLock(Mutex *mp) {
  *          mutexes.

  *

  * @param[in] mp        pointer to the @p Mutex structure

+ *

+ * @sclass

  */

 void chMtxLockS(Mutex *mp) {

   Thread *ctp = currp;

@@ -184,6 +188,8 @@ void chMtxLockS(Mutex *mp) {
  * @return              The operation status.

  * @retval TRUE         if the mutex has been successfully acquired

  * @retval FALSE        if the lock attempt failed.

+ *

+ * @api

  */

 bool_t chMtxTryLock(Mutex *mp) {

   bool_t b;

@@ -210,6 +216,8 @@ bool_t chMtxTryLock(Mutex *mp) {
  * @return              The operation status.

  * @retval TRUE         if the mutex has been successfully acquired

  * @retval FALSE        if the lock attempt failed.

+ *

+ * @sclass

  */

 bool_t chMtxTryLockS(Mutex *mp) {

 

@@ -230,6 +238,8 @@ bool_t chMtxTryLockS(Mutex *mp) {
  *          owned mutexes.

  *

  * @return              A pointer to the unlocked mutex.

+ *

+ * @api

  */

 Mutex *chMtxUnlock(void) {

   Thread *ctp = currp;

@@ -288,6 +298,8 @@ Mutex *chMtxUnlock(void) {
  *          function must be performed before unlocking the kernel.

  *

  * @return              A pointer to the unlocked mutex.

+ *

+ * @sclass

  */

 Mutex *chMtxUnlockS(void) {

   Thread *ctp = currp;

@@ -342,6 +354,8 @@ Mutex *chMtxUnlockS(void) {
  *          mutexes one by one and not just because the call overhead,

  *          this function does not have any overhead related to the priority

  *          inheritance mechanism.

+ *

+ * @api

  */

 void chMtxUnlockAll(void) {

   Thread *ctp = currp;

diff --git a/os/kernel/src/chqueues.c b/os/kernel/src/chqueues.c
index 485984fdf..b02fa6a64 100644
--- a/os/kernel/src/chqueues.c
+++ b/os/kernel/src/chqueues.c
@@ -50,8 +50,6 @@
  * @brief   Initializes an input queue.

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

  *          the bytes contained in the queue.

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p InputQueue structure.

  * @note    The callback is invoked from within the S-Locked system state,

  *          see @ref system_states.

  *

@@ -60,6 +58,8 @@
  * @param[in] size      size of the queue buffer

  * @param[in] infy      pointer to a callback function that is invoked when

  *                      data is read from the queue. The value can be @p NULL.

+ *

+ * @init

  */

 void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {

 

@@ -77,6 +77,8 @@ void chIQInit(InputQueue *iqp, uint8_t *bp, size_t size, qnotify_t infy) {
  *          obtain immediate attention from the high level layers.

  *

  * @param[in] iqp       pointer to an @p InputQueue structure

+ *

+ * @iclass

  */

 void chIQResetI(InputQueue *iqp) {

 

@@ -94,10 +96,12 @@ void chIQResetI(InputQueue *iqp) {
  * @retval Q_OK         if the operation has been completed with success.

  * @retval Q_FULL       if the queue is full and the operation cannot be

  *                      completed.

+ *

+ * @iclass

  */

 msg_t chIQPutI(InputQueue *iqp, uint8_t b) {

 

-  if (chIQIsFull(iqp))

+  if (chIQIsFullI(iqp))

     return Q_FULL;

 

   *iqp->q_wrptr++ = b;

@@ -122,6 +126,8 @@ msg_t chIQPutI(InputQueue *iqp, uint8_t b) {
  * @return              A byte value from the queue.

  * @retval Q_TIMEOUT    if the specified time expired.

  * @retval Q_RESET      if the queue was reset.

+ *

+ * @api

  */

 msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {

   uint8_t b;

@@ -165,6 +171,8 @@ msg_t chIQGetTimeout(InputQueue *iqp, systime_t time) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The number of bytes effectively transferred.

+ *

+ * @api

  */

 size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,

                        size_t n, systime_t time) {

@@ -175,7 +183,7 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
 

   chSysLock();

   while (TRUE) {

-    if (chIQIsEmpty(iqp)) {

+    if (chIQIsEmptyI(iqp)) {

       if (nfy)

         nfy();

       if ((chSemWaitTimeoutS(&iqp->q_sem, time) != RDY_OK)) {

@@ -207,8 +215,6 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
  * @brief   Initializes an output queue.

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

  *          the free bytes in the queue.

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p OutputQueue structure.

  * @note    The callback is invoked from within the S-Locked system state,

  *          see @ref system_states.

  *

@@ -217,6 +223,8 @@ size_t chIQReadTimeout(InputQueue *iqp, uint8_t *bp,
  * @param[in] size      size of the queue buffer

  * @param[in] onfy      pointer to a callback function that is invoked when

  *                      data is written to the queue. The value can be @p NULL.

+ *

+ * @init

  */

 void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {

 

@@ -234,6 +242,8 @@ void chOQInit(OutputQueue *oqp, uint8_t *bp, size_t size, qnotify_t onfy) {
  *          obtain immediate attention from the high level layers.

  *

  * @param[in] oqp       pointer to an @p OutputQueue structure

+ *

+ * @iclass

  */

 void chOQResetI(OutputQueue *oqp) {

 

@@ -258,6 +268,8 @@ void chOQResetI(OutputQueue *oqp) {
  * @retval Q_OK         if the operation succeeded.

  * @retval Q_TIMEOUT    if the specified time expired.

  * @retval Q_RESET      if the queue was reset.

+ *

+ * @api

  */

 msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {

   msg_t msg;

@@ -285,11 +297,13 @@ msg_t chOQPutTimeout(OutputQueue *oqp, uint8_t b, systime_t time) {
  * @param[in] oqp       pointer to an @p OutputQueue structure

  * @return              The byte value from the queue.

  * @retval Q_EMPTY      if the queue is empty.

+ *

+ * @iclass

  */

 msg_t chOQGetI(OutputQueue *oqp) {

   uint8_t b;

 

-  if (chOQIsEmpty(oqp))

+  if (chOQIsEmptyI(oqp))

     return Q_EMPTY;

 

   b = *oqp->q_rdptr++;

@@ -320,6 +334,8 @@ msg_t chOQGetI(OutputQueue *oqp) {
  *                      - @a TIME_INFINITE no timeout.

  *                      .

  * @return              The number of bytes effectively transferred.

+ *

+ * @api

  */

 size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp,

                         size_t n, systime_t time) {

@@ -330,7 +346,7 @@ size_t chOQWriteTimeout(OutputQueue *oqp, const uint8_t *bp,
 

   chSysLock();

   while (TRUE) {

-    if (chOQIsFull(oqp)) {

+    if (chOQIsFullI(oqp)) {

       if (nfy)

         nfy();

       if ((chSemWaitTimeoutS(&oqp->q_sem, time) != RDY_OK)) {

diff --git a/os/kernel/src/chregistry.c b/os/kernel/src/chregistry.c
index 216758c85..95893de85 100644
--- a/os/kernel/src/chregistry.c
+++ b/os/kernel/src/chregistry.c
@@ -58,6 +58,8 @@
  *          least one thread in the system.

  *

  * @return              A reference to the most ancient thread.

+ *

+ * @api

  */

 Thread *chRegFirstThread(void) {

   Thread *tp;

@@ -79,6 +81,8 @@ Thread *chRegFirstThread(void) {
  * @param[in] tp        pointer to the thread

  * @return              A reference to the next thread.

  * @retval NULL         if there is no next thread.

+ *

+ * @api

  */

 Thread *chRegNextThread(Thread *tp) {

   Thread *ntp;

diff --git a/os/kernel/src/chschd.c b/os/kernel/src/chschd.c
index 213d999ce..c7db9ad60 100644
--- a/os/kernel/src/chschd.c
+++ b/os/kernel/src/chschd.c
@@ -41,7 +41,8 @@ ReadyList rlist;
 

 /**

  * @brief   Scheduler initialization.

- * @note    Internally invoked by the @p chSysInit(), not an API.

+ *

+ * @notapi

  */

 void scheduler_init(void) {

 

@@ -66,6 +67,8 @@ void scheduler_init(void) {
  *

  * @param[in] tp        the thread to be made ready

  * @return              The thread pointer.

+ *

+ * @iclass

  */

 #if !defined(PORT_OPTIMIZED_READYI) || defined(__DOXYGEN__)

 #if CH_OPTIMIZE_SPEED

@@ -101,6 +104,8 @@ Thread *chSchReadyI(Thread *tp) {
  *          @ref thread_states are defined into @p threads.h.

  *

  * @param[in] newstate  the new thread state

+ *

+ * @sclass

  */

 #if !defined(PORT_OPTIMIZED_GOSLEEPS) || defined(__DOXYGEN__)

 void chSchGoSleepS(tstate_t newstate) {

@@ -163,6 +168,8 @@ static void wakeup(void *p) {
  *                      .

  * @return              The wakeup message.

  * @retval RDY_TIMEOUT if a timeout occurs.

+ *

+ * @sclass

  */

 msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {

 

@@ -194,6 +201,8 @@ msg_t chSchGoSleepTimeoutS(tstate_t newstate, systime_t time) {
  *

  * @param[in] ntp       the Thread to be made ready

  * @param[in] msg       message to the awakened thread

+ *

+ * @sclass

  */

 #if !defined(PORT_OPTIMIZED_WAKEUPS) || defined(__DOXYGEN__)

 void chSchWakeupS(Thread *ntp, msg_t msg) {

@@ -222,6 +231,8 @@ void chSchWakeupS(Thread *ntp, msg_t msg) {
  * @brief   Switches to the first thread on the runnable queue.

  * @note    It is intended to be called if @p chSchRescRequiredI() evaluates

  *          to @p TRUE.

+ *

+ * @iclass

  */

 #if !defined(PORT_OPTIMIZED_DORESCHEDULEI) || defined(__DOXYGEN__)

 void chSchDoRescheduleI(void) {

@@ -244,6 +255,8 @@ void chSchDoRescheduleI(void) {
  * @brief   Performs a reschedule 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.

+ *

+ * @iclass

  */

 #if !defined(PORT_OPTIMIZED_RESCHEDULES) || defined(__DOXYGEN__)

 void chSchRescheduleS(void) {

@@ -262,6 +275,8 @@ void chSchRescheduleS(void) {
  *

  * @retval TRUE         if there is a thread that should go in running state.

  * @retval FALSE        if a reschedule is not required.

+ *

+ * @iclass

  */

 #if !defined(PORT_OPTIMIZED_ISRESCHREQUIREDEXI) || defined(__DOXYGEN__)

 bool_t chSchIsRescRequiredExI(void) {

diff --git a/os/kernel/src/chsem.c b/os/kernel/src/chsem.c
index 750402266..58cd94808 100644
--- a/os/kernel/src/chsem.c
+++ b/os/kernel/src/chsem.c
@@ -68,12 +68,12 @@
 

 /**

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

- * @note    This function can be invoked before the kernel is initialized

- *          because it just prepares a @p Semaphore structure.

  *

  * @param[out] sp       pointer to a @p Semaphore structure

  * @param[in] n         initial value of the semaphore counter. Must be

  *                      non-negative.

+ *

+ * @init

  */

 void chSemInit(Semaphore *sp, cnt_t n) {

 

@@ -95,6 +95,8 @@ void chSemInit(Semaphore *sp, cnt_t n) {
  * @param[in] sp        pointer to a @p Semaphore structure

  * @param[in] n         the new value of the semaphore counter. The value must

  *                      be non-negative.

+ *

+ * @api

  */

 void chSemReset(Semaphore *sp, cnt_t n) {

 

@@ -120,6 +122,8 @@ void chSemReset(Semaphore *sp, cnt_t n) {
  * @param[in] sp        pointer to a @p Semaphore structure

  * @param[in] n         the new value of the semaphore counter. The value must

  *                      be non-negative.

+ *

+ * @iclass

  */

 void chSemResetI(Semaphore *sp, cnt_t n) {

   cnt_t cnt;

@@ -146,6 +150,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
  * @retval RDY_OK       if the thread has not stopped on the semaphore or the

  *                      semaphore has been signaled.

  * @retval RDY_RESET    if the semaphore has been reset using @p chSemReset().

+ *

+ * @api

  */

 msg_t chSemWait(Semaphore *sp) {

   msg_t msg;

@@ -165,6 +171,8 @@ msg_t chSemWait(Semaphore *sp) {
  * @retval RDY_OK       if the thread has not stopped on the semaphore or the

  *                      semaphore has been signaled.

  * @retval RDY_RESET    if the semaphore has been reset using @p chSemReset().

+ *

+ * @sclass

  */

 msg_t chSemWaitS(Semaphore *sp) {

 

@@ -200,6 +208,8 @@ msg_t chSemWaitS(Semaphore *sp) {
  * @retval RDY_RESET    if the semaphore has been reset using @p chSemReset().

  * @retval RDY_TIMEOUT  if the semaphore has not been signaled or reset within

  *                      the specified timeout.

+ *

+ * @api

  */

 msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {

   msg_t msg;

@@ -226,6 +236,8 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
  * @retval RDY_RESET    if the semaphore has been reset using @p chSemReset().

  * @retval RDY_TIMEOUT  if the semaphore has not been signaled or reset within

  *                      the specified timeout.

+ *

+ * @sclass

  */

 msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {

 

@@ -252,6 +264,8 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) {
  * @brief   Performs a signal operation on a semaphore.

  *

  * @param[in] sp        pointer to a @p Semaphore structure

+ *

+ * @api

  */

 void chSemSignal(Semaphore *sp) {

 

@@ -276,6 +290,8 @@ void chSemSignal(Semaphore *sp) {
  *          reschedule must not be performed in ISRs.

  *

  * @param[in] sp    pointer to a @p Semaphore structure

+ *

+ * @iclass

  */

 void chSemSignalI(Semaphore *sp) {

 

@@ -308,6 +324,8 @@ void chSemSignalI(Semaphore *sp) {
  * @retval RDY_OK       if the thread has not stopped on the semaphore or the

  *                      semaphore has been signaled.

  * @retval RDY_RESET    if the semaphore has been reset using @p chSemReset().

+ *

+ * @api

  */

 msg_t chSemSignalWait(Semaphore *sps, Semaphore *spw) {

   msg_t msg;

diff --git a/os/kernel/src/chsys.c b/os/kernel/src/chsys.c
index 809212a7b..a567b73da 100644
--- a/os/kernel/src/chsys.c
+++ b/os/kernel/src/chsys.c
@@ -66,6 +66,10 @@ void _idle_thread(void *p) {
  * @pre     Interrupts must be still disabled when @p chSysInit() is invoked

  *          and are internally enabled.

  * @post    The main thread is created with priority @p NORMALPRIO.

+ * @note    This function has special, architecture-dependent, requirements,

+ *          see the notes into the various port reference manuals.

+ *

+ * @special

  */

 void chSysInit(void) {

   static Thread mainthread;

@@ -100,10 +104,11 @@ void chSysInit(void) {
  * @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.

+ *

+ * @iclass

  */

 void chSysTimerHandlerI(void) {

 

diff --git a/os/kernel/src/chthreads.c b/os/kernel/src/chthreads.c
index 5bcadb96d..c4aa7437c 100644
--- a/os/kernel/src/chthreads.c
+++ b/os/kernel/src/chthreads.c
@@ -64,6 +64,8 @@
  * @param[in] tp        pointer to the thread

  * @param[in] prio      the priority level for the new thread

  * @return              The same thread pointer passed as parameter.

+ *

+ * @notapi

  */

 Thread *init_thread(Thread *tp, tprio_t prio) {

 

@@ -128,6 +130,8 @@ static void memfill(uint8_t *startp, uint8_t *endp, uint8_t v) {
  *                      @p NULL.

  * @return              The pointer to the @p Thread structure allocated for

  *                      the thread into the working space area.

+ *

+ * @api

  */

 Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {

   /* Thread structure is layed out in the lower part of the thread workspace */

@@ -158,6 +162,8 @@ Thread *chThdInit(void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg) {
  *                      @p NULL.

  * @return              The pointer to the @p Thread structure allocated for

  *                      the thread into the working space area.

+ *

+ * @api

  */

 Thread *chThdCreateStatic(void *wsp, size_t size,

                           tprio_t prio, tfunc_t pf, void *arg) {

@@ -185,6 +191,8 @@ Thread *chThdCreateStatic(void *wsp, size_t size,
  * @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.

+ *

+ * @api

  */

 Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,

                             tprio_t prio, tfunc_t pf, void *arg) {

@@ -219,6 +227,8 @@ Thread *chThdCreateFromHeap(MemoryHeap *heapp, size_t size,
  * @return              The pointer to the @p Thread structure allocated for

  *                      the thread into the working space area.

  * @retval  NULL        if the memory pool is empty.

+ *

+ * @api

  */

 Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,

                                   tfunc_t pf, void *arg) {

@@ -246,6 +256,8 @@ Thread *chThdCreateFromMemoryPool(MemoryPool *mp, tprio_t prio,
  *

  * @param[in] newprio   the new priority level of the running thread

  * @return              The old priority level.

+ *

+ * @api

  */

 tprio_t chThdSetPriority(tprio_t newprio) {

   tprio_t oldprio;

@@ -278,6 +290,8 @@ tprio_t chThdSetPriority(tprio_t newprio) {
  *

  * @param[in] tp        pointer to the thread

  * @return              The pointer to the thread.

+ *

+ * @api

  */

 Thread *chThdResume(Thread *tp) {

 

@@ -299,6 +313,8 @@ Thread *chThdResume(Thread *tp) {
  *          condition.

  *

  * @param[in] tp        pointer to the thread

+ *

+ * @api

  */

 void chThdTerminate(Thread *tp) {

 

@@ -318,6 +334,8 @@ void chThdTerminate(Thread *tp) {
  *                        interpreted as a normal time specification not as an

  *                        immediate timeout specification.

  *                      .

+ *

+ * @api

  */

 void chThdSleep(systime_t time) {

 

@@ -333,6 +351,8 @@ void chThdSleep(systime_t time) {
  *          specified value.

  *

  * @param[in] time      absolute system time

+ *

+ * @api

  */

 void chThdSleepUntil(systime_t time) {

 

@@ -346,6 +366,8 @@ void chThdSleepUntil(systime_t time) {
  * @brief   Yields the time slot.

  * @details Yields the CPU control to the next thread in the ready list with

  *          equal priority, if any.

+ *

+ * @api

  */

 void chThdYield(void) {

 

@@ -360,9 +382,13 @@ void chThdYield(void) {
  *          specified exit status code, other threads can retrieve the

  *          exit status code by invoking the function @p chThdWait().

  * @post    Eventual code after this function will never be executed,

- *          this function never returns.

+ *          this function never returns. The compiler has no way to

+ *          know this so do not assume that the compiler would remove

+ *          the dead code.

  *

  * @param[in] msg       thread exit code

+ *

+ * @api

  */

 void chThdExit(msg_t msg) {

   Thread *tp = currp;

@@ -391,6 +417,8 @@ void chThdExit(msg_t msg) {
  * @param[in] tp        pointer to the thread

  * @return              The same thread pointer passed as parameter

  *                      representing the new reference.

+ *

+ * @api

  */

 Thread *chThdAddRef(Thread *tp) {

 

@@ -411,6 +439,8 @@ Thread *chThdAddRef(Thread *tp) {
  * @note    Static threads are not affected.

  *

  * @param[in] tp        pointer to the thread

+ *

+ * @api

  */

 void chThdRelease(Thread *tp) {

   trefs_t refs;

@@ -469,6 +499,8 @@ void chThdRelease(Thread *tp) {
  *

  * @param[in] tp        pointer to the thread

  * @return              The exit code from the terminated thread.

+ *

+ * @api

  */

 msg_t chThdWait(Thread *tp) {

   msg_t msg;

diff --git a/os/kernel/src/chvt.c b/os/kernel/src/chvt.c
index 058433c09..070a9c620 100644
--- a/os/kernel/src/chvt.c
+++ b/os/kernel/src/chvt.c
@@ -36,6 +36,8 @@ VTList vtlist;
 /**

  * @brief   Virtual Timers initialization.

  * @note    Internal use only.

+ *

+ * @notapi

  */

 void vt_init(void) {

 

@@ -58,6 +60,8 @@ void vt_init(void) {
  *                      be disposed or reused.

  * @param[in] par       a parameter that will be passed to the callback

  *                      function

+ *

+ * @iclass

  */

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

   VirtualTimer *p;

@@ -85,6 +89,8 @@ void chVTSetI(VirtualTimer *vtp, systime_t time, vtfunc_t vtfunc, void *par) {
  * @note    The timer MUST be active when this function is invoked.

  *

  * @param[in] vtp       the @p VirtualTimer structure pointer

+ *

+ * @iclass

  */

 void chVTResetI(VirtualTimer *vtp) {

 

@@ -110,6 +116,8 @@ void chVTResetI(VirtualTimer *vtp) {
  * @param[in] end       the end of the time window (non inclusive)

  * @retval TRUE         current time within the specified time window.

  * @retval FALSE        current time not within the specified time window.

+ *

+ * @api

  */

 bool_t chTimeIsWithin(systime_t start, systime_t end) {

 

diff --git a/readme.txt b/readme.txt
index f72c7cf2a..0082dfe65 100644
--- a/readme.txt
+++ b/readme.txt
@@ -111,9 +111,15 @@
 - OPT: Removed an unused field in the VTList structure.

 - OPT: Speed optimizations of the STM32 SPI driver, improved latency.

 - OPT: Speed optimizations of the STM32 ADC driver.

+- CHANGE: The mailboxes macros chMBSize(), chMBGetEmpty(), chMBGetFull(),

+  chMBPeek() have been renamed to chMBSizeI(), chMBGetEmptyI(),

+  chMBGetFullI(), chMBPeekI().

+- CHANGE: The queue APIs chQSize(), chQSpace(), chIQIsEmpty(), chIQIsFull(),

+  chOQIsEmpty(), chOQIsFull() have been renamed to chQSizeI(), chQSpaceI(),

+  chIQIsEmptyI(), chIQIsFullI(), chOQIsEmptyI(), chOQIsFullI().

 - CHANGE: The event APIs chEvtPend() and chEvtClear() have been renamed

   to chEvtAddFlags() and chEvtClearFlags() for consistency and correct

-  English.

+  English. Changed the macro chEvtIsListening() in chEvtIsListeningI().

 - CHANGE: Added a parameter to the UART driver callbacks, the pointer to the

   driver itself.

 - CHANGE: In the UART driver now an error does not automatically brings the

diff --git a/test/testevt.c b/test/testevt.c
index 079257ac5..656a8430d 100644
--- a/test/testevt.c
+++ b/test/testevt.c
@@ -94,11 +94,11 @@ static void evt1_execute(void) {
   chEvtInit(&es1);

   chEvtRegisterMask(&es1, &el1, 1);

   chEvtRegisterMask(&es1, &el2, 2);

-  test_assert(1, chEvtIsListening(&es1), "no listener");

+  test_assert(1, chEvtIsListeningI(&es1), "no listener");

   chEvtUnregister(&es1, &el1);

-  test_assert(2, chEvtIsListening(&es1), "no listener");

+  test_assert(2, chEvtIsListeningI(&es1), "no listener");

   chEvtUnregister(&es1, &el2);

-  test_assert(3, !chEvtIsListening(&es1), "stuck listener");

+  test_assert(3, !chEvtIsListeningI(&es1), "stuck listener");

 

   /*

    * Testing chEvtDispatch().

@@ -220,8 +220,8 @@ static void evt2_execute(void) {
   test_wait_threads();

   chEvtUnregister(&es1, &el1);

   chEvtUnregister(&es2, &el2);

-  test_assert(14, !chEvtIsListening(&es1), "stuck listener");

-  test_assert(15, !chEvtIsListening(&es2), "stuck listener");

+  test_assert(14, !chEvtIsListeningI(&es1), "stuck listener");

+  test_assert(15, !chEvtIsListeningI(&es2), "stuck listener");

 }

 

 ROMCONST struct testcase testevt2 = {

diff --git a/test/testmbox.c b/test/testmbox.c
index 33706b5f5..60fa5cb44 100644
--- a/test/testmbox.c
+++ b/test/testmbox.c
@@ -83,7 +83,7 @@ static void mbox1_execute(void) {
   /*

    * Testing initial space.

    */

-  test_assert(1, chMBGetEmpty(&mb1) == MB_SIZE, "wrong size");

+  test_assert(1, chMBGetEmptyI(&mb1) == MB_SIZE, "wrong size");

 

   /*

    * Testing enqueuing and backward circularity.

@@ -104,8 +104,8 @@ static void mbox1_execute(void) {
   /*

    * Testing final conditions.

    */

-  test_assert(5, chMBGetEmpty(&mb1) == 0, "still empty");

-  test_assert(6, chMBGetFull(&mb1) == MB_SIZE, "not full");

+  test_assert(5, chMBGetEmptyI(&mb1) == 0, "still empty");

+  test_assert(6, chMBGetFullI(&mb1) == MB_SIZE, "not full");

   test_assert(7, mb1.mb_rdptr == mb1.mb_wrptr, "pointers not aligned");

 

   /*

@@ -137,8 +137,8 @@ static void mbox1_execute(void) {
   /*

    * Testing final conditions.

    */

-  test_assert(15, chMBGetEmpty(&mb1) == MB_SIZE, "not empty");

-  test_assert(16, chMBGetFull(&mb1) == 0, "still full");

+  test_assert(15, chMBGetEmptyI(&mb1) == MB_SIZE, "not empty");

+  test_assert(16, chMBGetFullI(&mb1) == 0, "still full");

   test_assert(17, mb1.mb_rdptr == mb1.mb_wrptr, "pointers not aligned");

 

   /*

@@ -149,8 +149,8 @@ static void mbox1_execute(void) {
   /*

    * Re-testing final conditions.

    */

-  test_assert(18, chMBGetEmpty(&mb1) == MB_SIZE, "not empty");

-  test_assert(19, chMBGetFull(&mb1) == 0, "still full");

+  test_assert(18, chMBGetEmptyI(&mb1) == MB_SIZE, "not empty");

+  test_assert(19, chMBGetFullI(&mb1) == 0, "still full");

   test_assert(20, mb1.mb_buffer == mb1.mb_wrptr, "write pointer not aligned to base");

   test_assert(21, mb1.mb_buffer == mb1.mb_rdptr, "read pointer not aligned to base");

 }

diff --git a/test/testqueues.c b/test/testqueues.c
index a9895a29a..27f533142 100644
--- a/test/testqueues.c
+++ b/test/testqueues.c
@@ -86,18 +86,18 @@ static void queues1_execute(void) {
   size_t n;

 

   /* Initial empty state */

-  test_assert(1, chIQIsEmpty(&iq), "not empty");

+  test_assert(1, chIQIsEmptyI(&iq), "not empty");

 

   /* Queue filling */

   for (i = 0; i < TEST_QUEUES_SIZE; i++)

     chIQPutI(&iq, 'A' + i);

-  test_assert(2, chIQIsFull(&iq), "still has space");

+  test_assert(2, chIQIsFullI(&iq), "still has space");

   test_assert(3, chIQPutI(&iq, 0) == Q_FULL, "failed to report Q_FULL");

 

   /* Queue emptying */

   for (i = 0; i < TEST_QUEUES_SIZE; i++)

     test_emit_token(chIQGet(&iq));

-  test_assert(4, chIQIsEmpty(&iq), "still full");

+  test_assert(4, chIQIsEmptyI(&iq), "still full");

   test_assert_sequence(5, "ABCD");

 

   /* Queue filling again */

@@ -107,7 +107,7 @@ static void queues1_execute(void) {
   /* Reading the whole thing */

   n = chIQReadTimeout(&iq, wa[1], TEST_QUEUES_SIZE * 2, TIME_IMMEDIATE);

   test_assert(6, n == TEST_QUEUES_SIZE, "wrong returned size");

-  test_assert(7, chIQIsEmpty(&iq), "still full");

+  test_assert(7, chIQIsEmptyI(&iq), "still full");

 

   /* Queue filling again */

   for (i = 0; i < TEST_QUEUES_SIZE; i++)

@@ -118,12 +118,12 @@ static void queues1_execute(void) {
   test_assert(8, n == TEST_QUEUES_SIZE / 2, "wrong returned size");

   n = chIQReadTimeout(&iq, wa[1], TEST_QUEUES_SIZE / 2, TIME_IMMEDIATE);

   test_assert(9, n == TEST_QUEUES_SIZE / 2, "wrong returned size");

-  test_assert(10, chIQIsEmpty(&iq), "still full");

+  test_assert(10, chIQIsEmptyI(&iq), "still full");

 

   /* Testing reset */

   chIQPutI(&iq, 0);

   chIQResetI(&iq);

-  test_assert(11, chIQIsEmpty(&iq), "still full");

+  test_assert(11, chIQIsEmptyI(&iq), "still full");

 

   /* Timeout */

   test_assert(12, chIQGetTimeout(&iq, 10) == Q_TIMEOUT, "wrong timeout return");

@@ -155,35 +155,35 @@ static void queues2_execute(void) {
   size_t n;

 

   /* Initial empty state */

-  test_assert(1, chOQIsEmpty(&oq), "not empty");

+  test_assert(1, chOQIsEmptyI(&oq), "not empty");

 

   /* Queue filling */

   for (i = 0; i < TEST_QUEUES_SIZE; i++)

     chOQPut(&oq, 'A' + i);

-  test_assert(2, chOQIsFull(&oq), "still has space");

+  test_assert(2, chOQIsFullI(&oq), "still has space");

 

   /* Queue emptying */

   for (i = 0; i < TEST_QUEUES_SIZE; i++)

     test_emit_token(chOQGetI(&oq));

-  test_assert(3, chOQIsEmpty(&oq), "still full");

+  test_assert(3, chOQIsEmptyI(&oq), "still full");

   test_assert_sequence(4, "ABCD");

   test_assert(5, chOQGetI(&oq) == Q_EMPTY, "failed to report Q_EMPTY");

 

   /* Writing the whole thing */

   n = chOQWriteTimeout(&oq, wa[1], TEST_QUEUES_SIZE * 2, TIME_IMMEDIATE);

   test_assert(6, n == TEST_QUEUES_SIZE, "wrong returned size");

-  test_assert(7, chOQIsFull(&oq), "not full");

+  test_assert(7, chOQIsFullI(&oq), "not full");

 

   /* Testing reset */

   chOQResetI(&oq);

-  test_assert(8, chOQIsEmpty(&oq), "still full");

+  test_assert(8, chOQIsEmptyI(&oq), "still full");

 

   /* Partial writes */

   n = chOQWriteTimeout(&oq, wa[1], TEST_QUEUES_SIZE / 2, TIME_IMMEDIATE);

   test_assert(9, n == TEST_QUEUES_SIZE / 2, "wrong returned size");

   n = chOQWriteTimeout(&oq, wa[1], TEST_QUEUES_SIZE / 2, TIME_IMMEDIATE);

   test_assert(10, n == TEST_QUEUES_SIZE / 2, "wrong returned size");

-  test_assert(11, chOQIsFull(&oq), "not full");

+  test_assert(11, chOQIsFullI(&oq), "not full");

 

   /* Timeout */

   test_assert(12, chOQPutTimeout(&oq, 0, 10) == Q_TIMEOUT, "wrong timeout return");