Kernel documentation fixes and improvements.

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

17 files changed, 141 insertions, 24 deletions

diff --git a/os/kernel/include/chbsem.h b/os/kernel/include/chbsem.h
index e0e1ca865..2d8815c3c 100644
--- a/os/kernel/include/chbsem.h
+++ b/os/kernel/include/chbsem.h
@@ -85,6 +85,10 @@ typedef struct  {
   BinarySemaphore name = _BSEMAPHORE_DATA(name, taken)

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Initializes a binary semaphore.

  *

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

@@ -238,6 +242,7 @@ typedef struct  {
  * @iclass

  */

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

+/** @} */

 

 #endif /* CH_USE_SEMAPHORES */

 

diff --git a/os/kernel/include/chdebug.h b/os/kernel/include/chdebug.h
index f3bf6b026..d11eb2eb2 100644
--- a/os/kernel/include/chdebug.h
+++ b/os/kernel/include/chdebug.h
@@ -132,7 +132,10 @@ extern ch_trace_buffer_t dbg_trace_buffer;
 /*===========================================================================*/

 

 #if CH_DBG_ENABLE_CHECKS || defined(__DOXYGEN__)

-

+/**

+ * @name    Macro Functions

+ * @{

+ */

 /**

  * @brief   Function parameter check.

  * @details If the condition check fails then the kernel panics and halts.

@@ -150,6 +153,7 @@ extern ch_trace_buffer_t dbg_trace_buffer;
     chDbgPanic(__QUOTE_THIS(func)"()");                                 \

 }

 #endif /* !defined(chDbgCheck) */

+/** @} */

 #else /* !CH_DBG_ENABLE_CHECKS */

 #define chDbgCheck(c, func) {                                           \

   (void)(c), (void)__QUOTE_THIS(func)"()";                              \

@@ -162,6 +166,10 @@ extern ch_trace_buffer_t dbg_trace_buffer;
 

 #if CH_DBG_ENABLE_ASSERTS || defined(__DOXYGEN__)

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Condition assertion.

  * @details If the condition check fails then the kernel panics with the

  *          specified message and halts.

@@ -184,6 +192,7 @@ extern ch_trace_buffer_t dbg_trace_buffer;
     chDbgPanic(m);                                                      \

 }

 #endif /* !defined(chDbgAssert) */

+/** @} */

 #else /* !CH_DBG_ENABLE_ASSERTS */

 #define chDbgAssert(c, m, r) {(void)(c);}

 #endif /* !CH_DBG_ENABLE_ASSERTS */

diff --git a/os/kernel/include/chevents.h b/os/kernel/include/chevents.h
index f4314aeb2..de89118b4 100644
--- a/os/kernel/include/chevents.h
+++ b/os/kernel/include/chevents.h
@@ -89,6 +89,10 @@ typedef void (*evhandler_t)(eventid_t);
 #define EVENT_MASK(eid) ((eventmask_t)(1 << (eid)))

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

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

  * @note    Multiple Event Listeners can use the same event identifier, the

  *          listener will share the callback function.

@@ -151,6 +155,7 @@ typedef void (*evhandler_t)(eventid_t);
  * @iclass

  */

 #define chEvtBroadcastI(esp) chEvtBroadcastFlagsI(esp, 0)

+/** @} */

 

 #ifdef __cplusplus

 extern "C" {

diff --git a/os/kernel/include/chfiles.h b/os/kernel/include/chfiles.h
index ff3f8274e..69a63965e 100644
--- a/os/kernel/include/chfiles.h
+++ b/os/kernel/include/chfiles.h
@@ -74,6 +74,8 @@ typedef uint32_t fileoffset_t;
   _base_sequential_stream_data

 

 /**

+ * @extends BaseSequentialStreamVMT

+ *

  * @brief   @p BaseFileStream virtual methods table.

  */

 struct BaseFilelStreamVMT {

@@ -93,6 +95,10 @@ typedef struct {
 } BaseFileStream;

 

 /**

+ * @name    Macro Functions (BaseFileStream)

+ * @{

+ */

+/**

  * @brief   Base file Stream close.

  * @details The function closes a file stream.

  *

@@ -138,6 +144,7 @@ typedef struct {
  * @api

  */

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

+/** @} */

 

 #endif /* _CHFILES_H_ */

 

diff --git a/os/kernel/include/chioch.h b/os/kernel/include/chioch.h
index 02757c7e9..3361926e3 100644
--- a/os/kernel/include/chioch.h
+++ b/os/kernel/include/chioch.h
@@ -67,6 +67,8 @@
   _base_sequential_stream_data

 

 /**

+ * @extends BaseSequentialStreamVMT

+ *

  * @brief   @p BaseChannel virtual methods table.

  */

 struct BaseChannelVMT {                                                     \

@@ -87,6 +89,10 @@ typedef struct {
 } BaseChannel;

 

 /**

+ * @name    Macro Functions (BaseChannel)

+ * @{

+ */

+/**

  * @brief   Channel output check.

  * @details This function verifies if a subsequent put/write operation would

  *          block.

@@ -227,9 +233,13 @@ typedef struct {
  */

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

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

+/** @} */

 

-#if CH_USE_EVENTS

-

+#if CH_USE_EVENTS || defined(__DOXYGEN__)

+/**

+ * @name    I/O status flags

+ * @{

+ */

 /** @brief No pending conditions.*/

 #define IO_NO_ERROR             0

 /** @brief Connection happened.*/

@@ -242,6 +252,7 @@ typedef struct {
 #define IO_OUTPUT_EMPTY         8

 /** @brief Transmission end.*/

 #define IO_TRANSMISSION_END     16

+/** @} */

 

 /**

  * @brief   Type of an I/O condition flags mask.

@@ -267,6 +278,8 @@ typedef uint_fast16_t ioflags_t;
   ioflags_t             flags;

 

 /**

+ * @extends BaseChannelVMT

+ *

  * @brief   @p BaseAsynchronousChannel virtual methods table.

  */

 struct BaseAsynchronousChannelVMT {

@@ -287,6 +300,10 @@ typedef struct {
 } BaseAsynchronousChannel;

 

 /**

+ * @name    Macro Functions (BaseAsynchronousChannel)

+ * @{

+ */

+/**

  * @brief   Returns the I/O condition event source.

  * @details The event source is broadcasted when an I/O condition happens.

  *

@@ -299,7 +316,7 @@ typedef struct {
 #define chIOGetEventSource(ip) (&((ip)->event))

 

 /**

- * @brief   Adds condition flags to the channel's mask.

+ * @brief   Adds status flags to the channel's mask.

  * @details This function is usually called from the I/O ISTs in order to

  *          notify I/O conditions such as data events, errors, signal

  *          changes etc.

@@ -316,7 +333,7 @@ typedef struct {
 }

 

 /**

- * @brief   Returns and clears the errors mask associated to the channel.

+ * @brief   Returns and clears the status flags associated to the channel.

  *

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

  *                      class

@@ -326,6 +343,7 @@ typedef struct {
  * @api

  */

 #define chIOGetAndClearFlags(ip) ((ip)->vmt->getflags(ip))

+/** @} */

 

 /**

  * @brief   Default implementation of the @p getflags virtual method.

diff --git a/os/kernel/include/chmboxes.h b/os/kernel/include/chmboxes.h
index 4a1706302..60cb7a5c1 100644
--- a/os/kernel/include/chmboxes.h
+++ b/os/kernel/include/chmboxes.h
@@ -73,6 +73,10 @@ extern "C" {
 #endif

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Returns the mailbox buffer size.

  *

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

@@ -120,6 +124,7 @@ extern "C" {
  * @iclass

  */

 #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 1803c719d..2bae02dea 100644
--- a/os/kernel/include/chmsg.h
+++ b/os/kernel/include/chmsg.h
@@ -32,6 +32,10 @@
 #if CH_USE_MESSAGES || defined(__DOXYGEN__)

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

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

  *

  * @iclass

@@ -74,6 +78,7 @@
  * @sclass

  */

 #define chMsgReleaseS(tp, msg) chSchWakeupS(tp, msg)

+/** @} */

 

 #ifdef __cplusplus

 extern "C" {

diff --git a/os/kernel/include/chmtx.h b/os/kernel/include/chmtx.h
index 9f2d5a0d3..831d48a89 100644
--- a/os/kernel/include/chmtx.h
+++ b/os/kernel/include/chmtx.h
@@ -77,12 +77,17 @@ extern "C" {
 #define MUTEX_DECL(name) Mutex name = _MUTEX_DATA(name)

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

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

  *          thread.

  *

  * @sclass

  */

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

+/** @} */

 

 #endif /* CH_USE_MUTEXES */

 

diff --git a/os/kernel/include/chqueues.h b/os/kernel/include/chqueues.h
index fa217710b..4917ac837 100644
--- a/os/kernel/include/chqueues.h
+++ b/os/kernel/include/chqueues.h
@@ -71,6 +71,10 @@ struct GenericQueue {
 };

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Returns the queue's buffer size.

  *

  * @param[in] qp        pointer to a @p GenericQueue structure.

@@ -90,7 +94,8 @@ struct GenericQueue {
  *

  * @iclass

  */

-#define chQSpaceI(qp) ((size_t)((qp)->q_counter))

+#define chQSpaceI(qp) ((qp)->q_counter)

+/** @} */

 

 /**

  * @extends GenericQueue

@@ -106,6 +111,10 @@ struct GenericQueue {
 typedef GenericQueue InputQueue;

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Returns the filled space into an input queue.

  *

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

@@ -165,6 +174,7 @@ typedef GenericQueue InputQueue;
  * @api

  */

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

+/** @} */

 

 /**

  * @brief   Data part of a static input queue initializer.

@@ -212,15 +222,19 @@ typedef GenericQueue InputQueue;
  */

 typedef GenericQueue OutputQueue;

 

- /**

-  * @brief   Returns the filled space into an output queue.

-  *

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

-  * @return              The number of full bytes in the queue.

-  * @retval 0            if the queue is empty.

-  *

-  * @iclass

-  */

+/**

+ * @name    Macro Functions

+ * @{

+ */

+/**

+ * @brief   Returns the filled space into an output queue.

+ *

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

+ * @return              The number of full bytes in the queue.

+ * @retval 0            if the queue is empty.

+ *

+ * @iclass

+ */

 #define chOQGetFullI(oqp) (chQSizeI(oqp) - chQSpaceI(oqp))

 

 /**

@@ -274,6 +288,7 @@ typedef GenericQueue OutputQueue;
  * @api

  */

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

+ /** @} */

 

 /**

  * @brief   Data part of a static output queue initializer.

diff --git a/os/kernel/include/chregistry.h b/os/kernel/include/chregistry.h
index 0967f699e..8f7ebd4b9 100644
--- a/os/kernel/include/chregistry.h
+++ b/os/kernel/include/chregistry.h
@@ -31,6 +31,10 @@
 

 #if CH_USE_REGISTRY || defined(__DOXYGEN__)

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Sets the current thread name.

  * @pre     This function only stores the pointer to the name if the option

  *          @p CH_USE_REGISTRY is enabled else no action is performed.

@@ -52,13 +56,13 @@
  * @retval NULL         if the thread name has not been set.

  */

 #define chRegGetThreadName(tp) ((tp)->p_name)

+/** @} */

 #else /* !CH_USE_REGISTRY */

 #define chRegSetThreadName(p)

 #define chRegGetThreadName(tp) NULL

 #endif /* !CH_USE_REGISTRY */

 

 #if CH_USE_REGISTRY || defined(__DOXYGEN__)

-

 /**

  * @brief   Removes a thread from the registry list.

  * @note    This macro is not meant for use in application code.

diff --git a/os/kernel/include/chschd.h b/os/kernel/include/chschd.h
index 27f6b9222..0e490c26a 100644
--- a/os/kernel/include/chschd.h
+++ b/os/kernel/include/chschd.h
@@ -162,6 +162,10 @@ extern "C" {
 #endif

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Determines if the current thread must reschedule.

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

  *          higher priority.

@@ -223,6 +227,7 @@ extern "C" {
     chSchDoReschedule();                                                    \

 }

 #endif /* CH_TIME_QUANTUM == 0 */

+/** @} */

 

 #endif /* _CHSCHD_H_ */

 

diff --git a/os/kernel/include/chsem.h b/os/kernel/include/chsem.h
index 04e079466..5f1c37a0a 100644
--- a/os/kernel/include/chsem.h
+++ b/os/kernel/include/chsem.h
@@ -83,6 +83,10 @@ extern "C" {
 #define SEMAPHORE_DECL(name, n) Semaphore name = _SEMAPHORE_DATA(name, n)

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Decreases the semaphore counter.

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

  *

@@ -105,6 +109,7 @@ extern "C" {
  * @iclass

  */

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

+/** @} */

 

 #endif /* CH_USE_SEMAPHORES */

 

diff --git a/os/kernel/include/chstreams.h b/os/kernel/include/chstreams.h
index 0bd763366..57883601d 100644
--- a/os/kernel/include/chstreams.h
+++ b/os/kernel/include/chstreams.h
@@ -74,6 +74,10 @@ typedef struct {
 } BaseSequentialStream;

 

 /**

+ * @name    Macro Functions (BaseSequentialStream)

+ * @{

+ */

+/**

  * @brief   Sequential Stream write.

  * @details The function writes data from a buffer to a stream.

  *

@@ -103,6 +107,7 @@ typedef struct {
  * @api

  */

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

+/** @} */

 

 #endif /* _CHSTREAMS_H_ */

 

diff --git a/os/kernel/include/chsys.h b/os/kernel/include/chsys.h
index f807182ac..b69736a1d 100644
--- a/os/kernel/include/chsys.h
+++ b/os/kernel/include/chsys.h
@@ -29,6 +29,10 @@
 #ifndef _CHSYS_H_

 #define _CHSYS_H_

 

+/**

+ * @name    Macro Functions

+ * @{

+ */

 #if !CH_NO_IDLE_THREAD || defined(__DOXYGEN__)

 /**

  * @brief   Returns a pointer to the idle thread.

@@ -177,8 +181,12 @@
   dbg_check_unlock_from_isr();                                              \

   port_unlock_from_isr();                                                   \

 }

+/** @} */

 

 /**

+ * @name    ISRs abstraction macros

+ */

+/**

  * @brief   IRQ handler enter code.

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

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

@@ -211,8 +219,12 @@
  * @special

  */

 #define CH_IRQ_HANDLER(id) PORT_IRQ_HANDLER(id)

+/** @} */

 

 /**

+ * @name    Fast ISRs abstraction macros

+ */

+/**

  * @brief   Standard fast IRQ handler declaration.

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

  *          port implementation.

@@ -221,6 +233,7 @@
  * @special

  */

 #define CH_FAST_IRQ_HANDLER(id) PORT_FAST_IRQ_HANDLER(id)

+/** @} */

 

 #ifdef __cplusplus

 extern "C" {

diff --git a/os/kernel/include/chthreads.h b/os/kernel/include/chthreads.h
index eb3d8bb14..bd3f21296 100644
--- a/os/kernel/include/chthreads.h
+++ b/os/kernel/include/chthreads.h
@@ -59,9 +59,10 @@
  */

 #define THD_MEM_MODE_MASK       3   /**< @brief Thread memory mode mask.    */

 #define THD_MEM_MODE_STATIC     0   /**< @brief Static thread.              */

-#define THD_MEM_MODE_HEAP       1   /**< @brief Thread allocated from Heap. */

-#define THD_MEM_MODE_MEMPOOL    2   /**< @brief Thread allocated from Memory

-                                         Pool.                              */

+#define THD_MEM_MODE_HEAP       1   /**< @brief Thread allocated from a

+                                         Memory Heap.                       */

+#define THD_MEM_MODE_MEMPOOL    2   /**< @brief Thread allocated from a

+                                         Memory Pool.                       */

 #define THD_TERMINATE           4   /**< @brief Termination requested flag. */

 /** @} */

 

@@ -205,6 +206,10 @@ struct Thread {
 typedef msg_t (*tfunc_t)(void *);

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

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

  *

  * @api

@@ -258,7 +263,7 @@ typedef msg_t (*tfunc_t)(void *);
 #define chThdShouldTerminate() (currp->p_flags & THD_TERMINATE)

 

 /**

- * @brief   Resumes a thread created with @p chThdInit().

+ * @brief   Resumes a thread created with @p chThdCreateI().

  *

  * @param[in] tp        pointer to the thread

  *

@@ -317,6 +322,7 @@ typedef msg_t (*tfunc_t)(void *);
  * @api

  */

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

+/** @} */

 

 /*

  * Threads APIs.

diff --git a/os/kernel/include/chvt.h b/os/kernel/include/chvt.h
index fe4ba11df..0038e3d0a 100644
--- a/os/kernel/include/chvt.h
+++ b/os/kernel/include/chvt.h
@@ -34,21 +34,21 @@
  * @{

  */

 /**

- * @brief   Time conversion utility.

+ * @brief   Seconds to system ticks.

  * @details Converts from seconds to system ticks number.

  * @note    The result is rounded upward to the next tick boundary.

  */

 #define S2ST(sec)   ((systime_t)((sec) * CH_FREQUENCY))

 

 /**

- * @brief   Time conversion utility.

+ * @brief   Milliseconds t0 system ticks.

  * @details Converts from milliseconds to system ticks number.

  * @note    The result is rounded upward to the next tick boundary.

  */

 #define MS2ST(msec) ((systime_t)(((((msec) - 1L) * CH_FREQUENCY) / 1000L) + 1L))

 

 /**

- * @brief   Time conversion utility.

+ * @brief   Microseconds to system ticks.

  * @details Converts from microseconds to system ticks number.

  * @note    The result is rounded upward to the next tick boundary.

  */

@@ -100,6 +100,10 @@ typedef struct {
 extern VTList vtlist;

 

 /**

+ * @name    Macro Functions

+ * @{

+ */

+/**

  * @brief   Virtual timers ticker.

  *

  * @iclass

@@ -139,6 +143,7 @@ extern VTList vtlist;
  * @api

  */

 #define chTimeNow() (vtlist.vt_systime)

+/** @} */

 

 /*

  * Virtual Timers APIs.

diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c
index 5002a892a..403df1580 100644
--- a/os/kernel/src/chmsg.c
+++ b/os/kernel/src/chmsg.c
@@ -109,7 +109,7 @@ Thread *chMsgWait(void) {
 }

 

 /**

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

+ * @brief   Releases a sender thread specifying a response message.

  * @pre     Invoke this function only after a message has been received

  *          using @p chMsgWait().

  *