diff options
Diffstat (limited to 'os/kernel/src/chsem.c')
| -rw-r--r-- | os/kernel/src/chsem.c | 135 |
1 files changed, 65 insertions, 70 deletions
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;
|