Documentation improvements and code comments reformatting.

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

7 files changed, 102 insertions, 74 deletions

diff --git a/os/kernel/include/ch.h b/os/kernel/include/ch.h
index db96d4338..35b01af2c 100644
--- a/os/kernel/include/ch.h
+++ b/os/kernel/include/ch.h
@@ -43,6 +43,10 @@
 #define CH_KERNEL_VERSION       "2.3.3unstable"

 

 /**

+ * @name    Kernel version

+ * @{

+ */

+/**

  * @brief   Kernel version major number.

  */

 #define CH_KERNEL_MAJOR         2

@@ -56,6 +60,7 @@
  * @brief   Kernel version patch number.

  */

 #define CH_KERNEL_PATCH         3

+/** @} */

 

 /*

  * Common values.

diff --git a/os/kernel/include/chevents.h b/os/kernel/include/chevents.h
index e808caec3..f4314aeb2 100644
--- a/os/kernel/include/chevents.h
+++ b/os/kernel/include/chevents.h
@@ -78,10 +78,14 @@ typedef void (*evhandler_t)(eventid_t);
  */

 #define EVENTSOURCE_DECL(name) EventSource name = _EVENTSOURCE_DATA(name)

 

-/** All events allowed mask.*/

+/**

+ * @brief   All events allowed mask.

+ */

 #define ALL_EVENTS      ((eventmask_t)-1)

 

-/** Returns the event mask from the event identifier.*/

+/**

+ * @brief   Returns an event mask from an event identifier.

+ */

 #define EVENT_MASK(eid) ((eventmask_t)(1 << (eid)))

 

 /**

diff --git a/os/kernel/include/chmemcore.h b/os/kernel/include/chmemcore.h
index cf608c4e8..5f72a3585 100644
--- a/os/kernel/include/chmemcore.h
+++ b/os/kernel/include/chmemcore.h
@@ -37,6 +37,9 @@
 typedef void *(*memgetfunc_t)(size_t size);

 

 /**

+ * @name    Alignment support macros

+ */

+/**

  * @brief   Alignment size constant.

  */

 #define MEM_ALIGN_SIZE      sizeof(stkalign_t)

@@ -61,6 +64,7 @@ typedef void *(*memgetfunc_t)(size_t size);
  *          the type @p align_t.

  */

 #define MEM_IS_ALIGNED(p)   (((size_t)(p) & MEM_ALIGN_MASK) == 0)

+/** @} */

 

 #if CH_USE_MEMCORE || defined(__DOXYGEN__)

 

diff --git a/os/kernel/include/chqueues.h b/os/kernel/include/chqueues.h
index a2df59dad..fa217710b 100644
--- a/os/kernel/include/chqueues.h
+++ b/os/kernel/include/chqueues.h
@@ -31,16 +31,16 @@
 

 #if CH_USE_QUEUES || defined(__DOXYGEN__)

 

-/** @brief Returned by the queue functions if the operation is successful.*/

-#define Q_OK            RDY_OK

-/** @brief Returned by the queue functions if a timeout occurs.*/

-#define Q_TIMEOUT       RDY_TIMEOUT

-/** @brief Returned by the queue functions if the queue has been reset.*/

-#define Q_RESET         RDY_RESET

-/** @brief Returned by the queue functions if the queue is empty.*/

-#define Q_EMPTY         -3

-/** @brief Returned by the queue functions if the queue is full.*/

-#define Q_FULL          -4

+/**

+ * @name    Queue functions returned status value

+ * @{

+ */

+#define Q_OK            RDY_OK      /**< @brief Operation successful.       */

+#define Q_TIMEOUT       RDY_TIMEOUT /**< @brief Timeout condition.          */

+#define Q_RESET         RDY_RESET   /**< @brief Queue has been reset.       */

+#define Q_EMPTY         -3          /**< @brief Queue empty.                */

+#define Q_FULL          -4          /**< @brief Queue full,                 */

+/** @} */

 

 /**

  * @brief   Type of a generic I/O queue structure.

diff --git a/os/kernel/include/chschd.h b/os/kernel/include/chschd.h
index 0e933e8ba..27f6b9222 100644
--- a/os/kernel/include/chschd.h
+++ b/os/kernel/include/chschd.h
@@ -29,22 +29,35 @@
 #ifndef _CHSCHD_H_

 #define _CHSCHD_H_

 

-/** @brief Default thread wakeup low level message.*/

-#define RDY_OK          0

-/** @brief Low level message sent to a thread awakened by a timeout.*/

-#define RDY_TIMEOUT     -1

-/** @brief Low level message sent to a thread awakened by a reset operation.*/

-#define RDY_RESET       -2

+/**

+ * @name    Wakeup status codes

+ * @{

+ */

+#define RDY_OK          0           /**< @brief Normal wakeup message.      */

+#define RDY_TIMEOUT     -1          /**< @brief Wakeup caused by a timeout

+                                         condition.                         */

+#define RDY_RESET       -2          /**< @brief Wakeup caused by a reset

+                                         condition.                         */

+/** @} */

 

+/**

+ * @name    Priority constants

+ * @{

+ */

 #define NOPRIO          0           /**< @brief Ready list header priority. */

 #define IDLEPRIO        1           /**< @brief Idle thread priority.       */

 #define LOWPRIO         2           /**< @brief Lowest user priority.       */

 #define NORMALPRIO      64          /**< @brief Normal user priority.       */

 #define HIGHPRIO        127         /**< @brief Highest user priority.      */

 #define ABSPRIO         255         /**< @brief Greatest possible priority. */

+/** @} */

 

 /**

- * @brief   Zero time specification for some syscalls with a timeout

+ * @name    Special time constants

+ * @{

+ */

+/**

+ * @brief   Zero time specification for some functions with a timeout

  *          specification.

  * @note    Not all functions accept @p TIME_IMMEDIATE as timeout parameter,

  *          see the specific function documentation.

@@ -52,10 +65,11 @@
 #define TIME_IMMEDIATE  ((systime_t)0)

 

 /**

- * @brief   Infinite time specification for all the syscalls with a timeout

+ * @brief   Infinite time specification for all functions with a timeout

  *          specification.

  */

 #define TIME_INFINITE   ((systime_t)-1)

+/** @} */

 

 /**

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

diff --git a/os/kernel/include/chthreads.h b/os/kernel/include/chthreads.h
index a0a668df4..eb3d8bb14 100644
--- a/os/kernel/include/chthreads.h
+++ b/os/kernel/include/chthreads.h
@@ -30,6 +30,42 @@
 #define _CHTHREADS_H_

 

 /**

+ * @name    Thread states

+ * @{

+ */

+#define THD_STATE_READY         0   /**< @brief Waiting on the ready list.  */

+#define THD_STATE_CURRENT       1   /**< @brief Currently running.          */

+#define THD_STATE_SUSPENDED     2   /**< @brief Created in suspended state. */

+#define THD_STATE_WTSEM         3   /**< @brief Waiting on a semaphore.     */

+#define THD_STATE_WTMTX         4   /**< @brief Waiting on a mutex.         */

+#define THD_STATE_WTCOND        5   /**< @brief Waiting on a condition

+                                         variable.                          */

+#define THD_STATE_SLEEPING      6   /**< @brief Waiting in @p chThdSleep()

+                                         or @p chThdSleepUntil().           */

+#define THD_STATE_WTEXIT        7   /**< @brief Waiting in @p chThdWait().  */

+#define THD_STATE_WTOREVT       8   /**< @brief Waiting for an event.       */

+#define THD_STATE_WTANDEVT      9   /**< @brief Waiting for several events. */

+#define THD_STATE_SNDMSGQ       10  /**< @brief Sending a message, in queue.*/

+#define THD_STATE_SNDMSG        11  /**< @brief Sent a message, waiting

+                                         answer.                            */

+#define THD_STATE_WTMSG         12  /**< @brief Waiting for a message.      */

+#define THD_STATE_WTQUEUE       13  /**< @brief Waiting on an I/O queue.    */

+#define THD_STATE_FINAL         14  /**< @brief Thread terminated.          */

+/** @} */

+

+/**

+ * @name    Thread flags and attributes

+ * @{

+ */

+#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_TERMINATE           4   /**< @brief Termination requested flag. */

+/** @} */

+

+/**

  * @extends ThreadsQueue

  *

  * @brief   Structure representing a thread.

@@ -163,46 +199,6 @@ struct Thread {
 #endif

 };

 

-/** @brief Thread state: Ready to run, waiting on the ready list.*/

-#define THD_STATE_READY         0

-/** @brief Thread state: Currently running.*/

-#define THD_STATE_CURRENT       1

-/** @brief Thread state: Thread created in suspended state.*/

-#define THD_STATE_SUSPENDED     2

-/** @brief Thread state: Waiting on a semaphore.*/

-#define THD_STATE_WTSEM         3

-/** @brief Thread state: Waiting on a mutex.*/

-#define THD_STATE_WTMTX         4

-/** @brief Thread state: Waiting in @p chCondWait().*/

-#define THD_STATE_WTCOND        5

-/** @brief Thread state: Waiting in @p chThdSleep() or @p chThdSleepUntil().*/

-#define THD_STATE_SLEEPING      6

-/** @brief Thread state: Waiting in @p chThdWait().*/

-#define THD_STATE_WTEXIT        7

-/** @brief Thread state: Waiting in @p chEvtWaitXXX().*/

-#define THD_STATE_WTOREVT       8

-/** @brief Thread state: Waiting in @p chEvtWaitAllTimeout().*/

-#define THD_STATE_WTANDEVT      9

-/** @brief Thread state: Waiting in @p chMsgSend() (queued).*/

-#define THD_STATE_SNDMSGQ       10

-/** @brief Thread state: Waiting in @p chMsgSend() (not queued).*/

-#define THD_STATE_SNDMSG        11

-/** @brief Thread state: Waiting in @p chMsgWait().*/

-#define THD_STATE_WTMSG         12

-/** @brief Thread state: Waiting on an I/O queue.*/

-#define THD_STATE_WTQUEUE       13

-/** @brief Thread state: After termination.*/

-#define THD_STATE_FINAL         14

-

-/*

- * Various flags into the thread p_flags field.

- */

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

-#define THD_MEM_MODE_STATIC     0   /**< @brief Thread memory mode: static. */

-#define THD_MEM_MODE_HEAP       1   /**< @brief Thread memory mode: heap.   */

-#define THD_MEM_MODE_MEMPOOL    2   /**< @brief Thread memory mode: pool.   */

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

-

 /**

  * @brief Thread function.

  */

diff --git a/os/kernel/include/chvt.h b/os/kernel/include/chvt.h
index e75e966d5..fe4ba11df 100644
--- a/os/kernel/include/chvt.h
+++ b/os/kernel/include/chvt.h
@@ -30,6 +30,10 @@
 #define _CHVT_H_

 

 /**

+ * @name    Time conversion utilities

+ * @{

+ */

+/**

  * @brief   Time conversion utility.

  * @details Converts from seconds to system ticks number.

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

@@ -49,6 +53,7 @@
  * @note    The result is rounded upward to the next tick boundary.

  */

 #define US2ST(usec) ((systime_t)(((((usec) - 1L) * CH_FREQUENCY) / 1000000L) + 1L))

+/** @} */

 

 /**

  * @brief   Virtual Timer callback function.

@@ -115,20 +120,6 @@ extern VTList vtlist;
   }                                                                     \

 }

 

-/*

- * Virtual Timers APIs.

- */

-#ifdef __cplusplus

-extern "C" {

-#endif

-  void _vt_init(void);

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

-  void chVTResetI(VirtualTimer *vtp);

-  bool_t chTimeIsWithin(systime_t start, systime_t end);

-#ifdef __cplusplus

-}

-#endif

-

 /**

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

  *

@@ -149,6 +140,20 @@ extern "C" {
  */

 #define chTimeNow() (vtlist.vt_systime)

 

+/*

+ * Virtual Timers APIs.

+ */

+#ifdef __cplusplus

+extern "C" {

+#endif

+  void _vt_init(void);

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

+  void chVTResetI(VirtualTimer *vtp);

+  bool_t chTimeIsWithin(systime_t start, systime_t end);

+#ifdef __cplusplus

+}

+#endif

+

 #endif /* _CHVT_H_ */

 

 /** @} */