Documentation improvements, renamed some event APIs.

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

1 files changed, 52 insertions, 33 deletions

diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c
index 92e1a4eb4..71729139f 100644
--- a/os/kernel/src/chcond.c
+++ b/os/kernel/src/chcond.c
@@ -31,21 +31,20 @@
  *          <h2>Operation mode</h2>

  *          The condition variable is a synchronization object meant to be

  *          used inside a zone protected by a @p Mutex. Mutexes and CondVars

- *          together can implement a Monitor construct.<br>

- *          In order to use the Condition Variables APIs the @p CH_USE_CONDVARS

+ *          together can implement a Monitor construct.

+ * @pre     In order to use the condition variable APIs the @p CH_USE_CONDVARS

  *          option must be enabled in @p chconf.h.

  * @{

  */

 

 #include "ch.h"

 

-#if CH_USE_CONDVARS && CH_USE_MUTEXES

+#if (CH_USE_CONDVARS && CH_USE_MUTEXES) || defined(__DOXYGEN__)

 

 /**

  * @brief   Initializes s @p CondVar structure.

- * @note    This function can be invoked from within an interrupt handler even

- *          if it is not an I-Class API because it does not touch any critical

- *          kernel data structure.

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

  */

@@ -73,6 +72,10 @@ void chCondSignal(CondVar *cp) {
 

 /**

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

+ * @post    This function does not reschedule so a call to a rescheduling

+ *          function must be performed before unlocking the kernel. Note that

+ *          interrupt handlers always reschedule on exit so an explicit

+ *          reschedule must not be performed in ISRs.

  *

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

  */

@@ -99,6 +102,10 @@ void chCondBroadcast(CondVar *cp) {
 

 /**

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

+ * @post    This function does not reschedule so a call to a rescheduling

+ *          function must be performed before unlocking the kernel. Note that

+ *          interrupt handlers always reschedule on exit so an explicit

+ *          reschedule must not be performed in ISRs.

  *

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

  */

@@ -118,13 +125,15 @@ void chCondBroadcastI(CondVar *cp) {
  * @details Releases the currently owned mutex, waits on the condition

  *          variable, and finally acquires the mutex again. All the sequence

  *          is performed atomically.

- * @note    The invoking thread <b>must</b> have at least one owned mutex on

- *          entry.

+ * @pre     The invoking thread <b>must</b> have at least one owned mutex.

  *

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

- * @return              The wakep mode.

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

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

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

+ *                      released from the condition variable.

+ * @retval RDY_OK       if the condvar has been signaled using

+ *                      @p chCondSignal().

+ * @retval RDY_RESET    if the condvar has been signaled using

+ *                      @p chCondBroadcast().

  */

 msg_t chCondWait(CondVar *cp) {

   msg_t msg;

@@ -140,13 +149,15 @@ msg_t chCondWait(CondVar *cp) {
  * @details Releases the currently owned mutex, waits on the condition

  *          variable, and finally acquires the mutex again. All the sequence

  *          is performed atomically.

- * @note    The invoking thread <b>must</b> have at least one owned mutex on

- *          entry.

+ * @pre     The invoking thread <b>must</b> have at least one owned mutex.

  *

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

- * @return              The wakep mode.

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

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

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

+ *                      released from the condition variable.

+ * @retval RDY_OK       if the condvar has been signaled using

+ *                      @p chCondSignal().

+ * @retval RDY_RESET    if the condvar has been signaled using

+ *                      @p chCondBroadcast().

  */

 msg_t chCondWaitS(CondVar *cp) {

   Thread *ctp = currp;

@@ -167,15 +178,16 @@ msg_t chCondWaitS(CondVar *cp) {
   return msg;

 }

 

-#if CH_USE_CONDVARS_TIMEOUT

+#if CH_USE_CONDVARS_TIMEOUT || defined(__DOXYGEN__)

 /**

  * @brief   Waits on the condition variable releasing the mutex lock.

  * @details Releases the currently owned mutex, waits on the condition

  *          variable, and finally acquires the mutex again. All the sequence

  *          is performed atomically.

- * @note    The invoking thread <b>must</b> have at least one owned mutex on

- *          entry.

- * @note    Exiting the function because a timeout does not re-acquire the

+ * @pre     The invoking thread <b>must</b> have at least one owned mutex.

+ * @pre     The configuration option @p CH_USE_CONDVARS_TIMEOUT must be enabled

+ *          in order to use this function.

+ * @post    Exiting the function because a timeout does not re-acquire the

  *          mutex, the mutex ownership is lost.

  *

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

@@ -184,11 +196,14 @@ msg_t chCondWaitS(CondVar *cp) {
  *                      It is not possible to specify zero @p TIME_IMMEDIATE

  *                      as timeout specification because it would make no sense

  *                      in this function.

- * @return              The wakep mode.

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

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

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

- *                      timeout.

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

+ *                      released from the condition variable.

+ * @retval RDY_OK       if the condvar has been signaled using

+ *                      @p chCondSignal().

+ * @retval RDY_RESET    if the condvar has been signaled using

+ *                      @p chCondBroadcast().

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

+ *                      specified timeout.

  */

 msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {

   msg_t msg;

@@ -204,9 +219,10 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
  * @details Releases the currently owned mutex, waits on the condition

  *          variable, and finally acquires the mutex again. All the sequence

  *          is performed atomically.

- * @note    The invoking thread <b>must</b> have at least one owned mutex on

- *          entry.

- * @note    Exiting the function because a timeout does not re-acquire the

+ * @pre     The invoking thread <b>must</b> have at least one owned mutex.

+ * @pre     The configuration option @p CH_USE_CONDVARS_TIMEOUT must be enabled

+ *          in order to use this function.

+ * @post    Exiting the function because a timeout does not re-acquire the

  *          mutex, the mutex ownership is lost.

  *

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

@@ -215,11 +231,14 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
  *                      It is not possible to specify zero @p TIME_IMMEDIATE

  *                      as timeout specification because it would make no sense

  *                      in this function.

- * @return              The wakep mode.

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

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

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

- *                      timeout.

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

+ *                      released from the condition variable.

+ * @retval RDY_OK       if the condvar has been signaled using

+ *                      @p chCondSignal().

+ * @retval RDY_RESET    if the condvar has been signaled using

+ *                      @p chCondBroadcast().

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

+ *                      specified timeout.

  */

 msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {

   Mutex *mp;