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/chsem.c | 135 ++++++++++++++++++++++++-------------------------- 1 file changed, 65 insertions(+), 70 deletions(-) (limited to 'os/kernel/src/chsem.c') diff --git a/os/kernel/src/chsem.c b/os/kernel/src/chsem.c index c78d52f74..b4ff0d9bc 100644 --- a/os/kernel/src/chsem.c +++ b/os/kernel/src/chsem.c @@ -18,8 +18,9 @@ */ /** - * @file chsem.c - * @brief Semaphores code. + * @file chsem.c + * @brief Semaphores code. + * * @addtogroup semaphores * @{ */ @@ -35,13 +36,11 @@ #endif /** - * @brief Initializes a semaphore with the specified counter value. + * @brief Initializes a semaphore with the specified counter value. * - * @param[out] sp pointer to a @p Semaphore structure - * @param[in] n initial value of the semaphore counter. Must be non-negative. - * @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] sp pointer to a @p Semaphore structure + * @param[in] n initial value of the semaphore counter. Must be + * non-negative. */ void chSemInit(Semaphore *sp, cnt_t n) { @@ -52,13 +51,14 @@ void chSemInit(Semaphore *sp, cnt_t n) { } /** - * @brief Performs a reset operation on the semaphore. + * @brief Performs a reset operation on the semaphore. + * @note The released threads can recognize they were waked up by a reset + * rather than a signal because the @p chSemWait() will return + * @p RDY_RESET instead of @p RDY_OK. * - * @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. - * @note The released threads can recognize they were waked up by a reset - * instead than a signal because the @p chSemWait() will return - * @p RDY_RESET instead of @p RDY_OK. + * @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. */ void chSemReset(Semaphore *sp, cnt_t n) { @@ -69,14 +69,15 @@ void chSemReset(Semaphore *sp, cnt_t n) { } /** - * @brief Performs a reset operation on the semaphore. + * @brief Performs a reset operation on the semaphore. + * @note The released threads can recognize they were waked up by a reset + * rather than a signal because the @p chSemWait() will return + * @p RDY_RESET instead of @p RDY_OK. + * @note This function does not reschedule. * - * @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. - * @note The released threads can recognize they were waked up by a reset - * instead than a signal because the @p chSemWait() will return - * @p RDY_RESET instead of @p RDY_OK. - * @note This function does not reschedule. + * @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. */ void chSemResetI(Semaphore *sp, cnt_t n) { cnt_t cnt; @@ -90,11 +91,11 @@ void chSemResetI(Semaphore *sp, cnt_t n) { } /** - * @brief Performs a wait operation on a semaphore. + * @brief Performs a wait operation on a semaphore. * - * @param[in] sp pointer to a @p Semaphore structure - * @retval RDY_OK if the semaphore was signaled or not taken. - * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). + * @param[in] sp pointer to a @p Semaphore structure + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). */ msg_t chSemWait(Semaphore *sp) { msg_t msg; @@ -106,13 +107,11 @@ msg_t chSemWait(Semaphore *sp) { } /** - * @brief Performs a wait operation on a semaphore. + * @brief Performs a wait operation on a semaphore. * - * @param[in] sp pointer to a @p Semaphore structure - * @retval RDY_OK if the semaphore was signaled or not taken. - * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). - * @note This function must be called with interrupts disabled. - * @note This function cannot be called by an interrupt handler. + * @param[in] sp pointer to a @p Semaphore structure + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). */ msg_t chSemWaitS(Semaphore *sp) { @@ -128,18 +127,18 @@ msg_t chSemWaitS(Semaphore *sp) { } /** - * @brief Performs a wait operation on a semaphore with timeout specification. + * @brief Performs a wait operation on a semaphore with timeout specification. * - * @param[in] sp pointer to a @p Semaphore structure - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @retval RDY_OK if the semaphore was signaled or not taken. - * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). - * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the - * specified timeout. + * @param[in] sp pointer to a @p Semaphore structure + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). + * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the + * specified timeout. */ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) { msg_t msg; @@ -151,18 +150,18 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) { } /** - * @brief Performs a wait operation on a semaphore with timeout specification. + * @brief Performs a wait operation on a semaphore with timeout specification. * - * @param[in] sp pointer to a @p Semaphore structure - * @param[in] time the number of ticks before the operation timeouts, - * the following special values are allowed: - * - @a TIME_IMMEDIATE immediate timeout. - * - @a TIME_INFINITE no timeout. - * . - * @retval RDY_OK if the semaphore was signaled or not taken. - * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). - * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified - * timeout. + * @param[in] sp pointer to a @p Semaphore structure + * @param[in] time the number of ticks before the operation timeouts, + * the following special values are allowed: + * - @a TIME_IMMEDIATE immediate timeout. + * - @a TIME_INFINITE no timeout. + * . + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). + * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the + * specified timeout. */ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) { @@ -181,11 +180,9 @@ msg_t chSemWaitTimeoutS(Semaphore *sp, systime_t time) { } /** - * @brief Performs a signal operation on a semaphore. + * @brief Performs a signal operation on a semaphore. * - * @param[in] sp pointer to a @p Semaphore structure - * @note The function is available only if the @p CH_USE_SEMAPHORES - * option is enabled in @p chconf.h. + * @param[in] sp pointer to a @p Semaphore structure */ void chSemSignal(Semaphore *sp) { @@ -198,19 +195,17 @@ void chSemSignal(Semaphore *sp) { } /** - * @brief Performs a signal operation on a semaphore. + * @brief Performs a signal operation on a semaphore. + * @note This function does not reschedule. * - * @param[in] sp pointer to a @p Semaphore structure - * @note The function is available only if the @p CH_USE_SEMAPHORES - * option is enabled in @p chconf.h. - * @note This function does not reschedule. + * @param[in] sp pointer to a @p Semaphore structure */ void chSemSignalI(Semaphore *sp) { chDbgCheck(sp != NULL, "chSemSignalI"); if (sp->s_cnt++ < 0) { - /* NOTE: It is done this way in order to allow a tail call on + /* note, it is done this way in order to allow a tail call on chSchReadyI().*/ Thread *tp = fifo_remove(&sp->s_queue); tp->p_u.rdymsg = RDY_OK; @@ -220,14 +215,14 @@ void chSemSignalI(Semaphore *sp) { #if CH_USE_SEMSW /** - * @brief Performs atomic signal and wait operations on two semaphores. + * @brief Performs atomic signal and wait operations on two semaphores. + * @note The function is available only if the @p CH_USE_SEMSW + * option is enabled in @p chconf.h. * - * @param[in] sps pointer to a @p Semaphore structure to be signaled - * @param[in] spw pointer to a @p Semaphore structure to be wait on - * @retval RDY_OK if the semaphore was signaled or not taken. - * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). - * @note The function is available only if the @p CH_USE_SEMSW - * option is enabled in @p chconf.h. + * @param[in] sps pointer to a @p Semaphore structure to be signaled + * @param[in] spw pointer to a @p Semaphore structure to be wait on + * @retval RDY_OK if the semaphore was signaled or not taken. + * @retval RDY_RESET if the semaphore was reset using @p chSemReset(). */ msg_t chSemSignalWait(Semaphore *sps, Semaphore *spw) { msg_t msg; -- cgit v1.2.3