From f17db1931e95f5ebb42f557b6eead2bf1320db5a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 6 Feb 2010 10:55:53 +0000 Subject: Reformatted doxygen tags into the kernel sources to make them more readable. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1567 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/src/chcond.c | 123 +++++++++++++++++++++++++------------------------ 1 file changed, 62 insertions(+), 61 deletions(-) (limited to 'os/kernel/src/chcond.c') diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c index 9e1a70cc4..21f3a22e2 100644 --- a/os/kernel/src/chcond.c +++ b/os/kernel/src/chcond.c @@ -22,8 +22,9 @@ */ /** - * @file chcond.c - * @brief Condition Variables code. + * @file chcond.c + * @brief Condition Variables code. + * * @addtogroup condvars Condition Variables * @{ */ @@ -33,12 +34,12 @@ #if CH_USE_CONDVARS && CH_USE_MUTEXES /** - * @brief Initializes s @p CondVar structure. + * @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. * - * @param[out] cp pointer to a @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. + * @param[out] cp pointer to a @p CondVar structure */ void chCondInit(CondVar *cp) { @@ -48,37 +49,37 @@ void chCondInit(CondVar *cp) { } /** - * @brief Signals one thread that is waiting on the condition variable. + * @brief Signals one thread that is waiting on the condition variable. * - * @param[in] cp pointer to the @p CondVar structure + * @param[in] cp pointer to the @p CondVar structure */ void chCondSignal(CondVar *cp) { chDbgCheck(cp != NULL, "chCondSignal"); chSysLock(); - if (notempty(&cp->c_queue)) /* any thread ? */ + if (notempty(&cp->c_queue)) chSchWakeupS(fifo_remove(&cp->c_queue), RDY_OK); chSysUnlock(); } /** - * @brief Signals one thread that is waiting on the condition variable. + * @brief Signals one thread that is waiting on the condition variable. * - * @param[in] cp pointer to the @p CondVar structure + * @param[in] cp pointer to the @p CondVar structure */ void chCondSignalI(CondVar *cp) { chDbgCheck(cp != NULL, "chCondSignalI"); - if (notempty(&cp->c_queue)) /* any thread ? */ + if (notempty(&cp->c_queue)) chSchReadyI(fifo_remove(&cp->c_queue))->p_u.rdymsg = RDY_OK; } /** - * @brief Signals all threads that are waiting on the condition variable. + * @brief Signals all threads that are waiting on the condition variable. * - * @param[in] cp pointer to the @p CondVar structure + * @param[in] cp pointer to the @p CondVar structure */ void chCondBroadcast(CondVar *cp) { @@ -89,32 +90,32 @@ void chCondBroadcast(CondVar *cp) { } /** - * @brief Signals all threads that are waiting on the condition variable. + * @brief Signals all threads that are waiting on the condition variable. * - * @param[in] cp pointer to the @p CondVar structure + * @param[in] cp pointer to the @p CondVar structure */ void chCondBroadcastI(CondVar *cp) { chDbgCheck(cp != NULL, "chCondBroadcastI"); /* Empties the condition variable queue and inserts all the Threads into the - * ready list in FIFO order. The wakeup message is set to @p RDY_RESET in - * order to make a chCondBroadcast() detectable from a chCondSignal().*/ + ready list in FIFO order. The wakeup message is set to @p RDY_RESET in + order to make a chCondBroadcast() detectable from a chCondSignal().*/ while (cp->c_queue.p_next != (void *)&cp->c_queue) chSchReadyI(fifo_remove(&cp->c_queue))->p_u.rdymsg = RDY_RESET; } /** - * @brief Waits on the condition variable releasing the mutex lock. + * @brief Waits on the condition variable releasing the mutex lock. * @details Releases the mutex, waits on the condition variable, and finally * acquires the mutex again. This is done atomically. + * @note The thread MUST already have locked the mutex when calling + * @p chCondWait(). * - * @param[in] cp pointer to the @p CondVar structure - * @return The wakep mode. - * @retval RDY_OK if the condvar was signaled using chCondSignal(). - * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). - * @note The thread MUST already have locked the mutex when calling - * @p chCondWait(). + * @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(). */ msg_t chCondWait(CondVar *cp) { msg_t msg; @@ -126,16 +127,16 @@ msg_t chCondWait(CondVar *cp) { } /** - * @brief Waits on the condition variable releasing the mutex lock. + * @brief Waits on the condition variable releasing the mutex lock. * @details Releases the mutex, waits on the condition variable, and finally * acquires the mutex again. This is done atomically. + * @note The thread MUST already have locked the mutex when calling + * @p chCondWaitS(). * - * @param[in] cp pointer to the @p CondVar structure - * @return The wakep mode. - * @retval RDY_OK if the condvar was signaled using chCondSignal(). - * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). - * @note The thread MUST already have locked the mutex when calling - * @p chCondWaitS(). + * @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(). */ msg_t chCondWaitS(CondVar *cp) { Thread *ctp = currp; @@ -158,23 +159,23 @@ msg_t chCondWaitS(CondVar *cp) { #if CH_USE_CONDVARS_TIMEOUT /** - * @brief Waits on the condition variable releasing the mutex lock. + * @brief Waits on the condition variable releasing the mutex lock. * @details Releases the mutex, waits on the condition variable, and finally * acquires the mutex again. This is done atomically. + * @note The thread MUST already have locked the mutex when calling + * @p chCondWaitTimeout(). * - * @param[in] cp pointer to the @p CondVar structure - * @param[in] time the number of ticks before the operation timeouts, - * the special value @p TIME_INFINITE is allowed. - * 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 chCondSignal(). - * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). - * @retval RDY_TIMEOUT if the condvar was not signaled within the specified - * timeout. - * @note The thread MUST already have locked the mutex when calling - * @p chCondWaitTimeout(). + * @param[in] cp pointer to the @p CondVar structure + * @param[in] time the number of ticks before the operation timeouts, + * the special value @p TIME_INFINITE is allowed. + * 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. */ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) { msg_t msg; @@ -186,23 +187,23 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) { } /** - * @brief Waits on the condition variable releasing the mutex lock. + * @brief Waits on the condition variable releasing the mutex lock. * @details Releases the mutex, waits on the condition variable, and finally * acquires the mutex again. This is done atomically. + * @note The thread MUST already have locked the mutex when calling + * @p chCondWaitTimeoutS(). * - * @param[in] cp pointer to the @p CondVar structure - * @param[in] time the number of ticks before the operation timeouts, - * the special value @p TIME_INFINITE is allowed. - * 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 chCondSignal(). - * @retval RDY_RESET if the condvar was signaled using chCondBroadcast(). - * @retval RDY_TIMEOUT if the condvar was not signaled within the specified - * timeout. - * @note The thread MUST already have locked the mutex when calling - * @p chCondWaitTimeoutS(). + * @param[in] cp pointer to the @p CondVar structure + * @param[in] time the number of ticks before the operation timeouts, + * the special value @p TIME_INFINITE is allowed. + * 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. */ msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) { Thread *ctp = currp; -- cgit v1.2.3