312 lines
11 KiB
C
312 lines
11 KiB
C
|
/*
|
||
|
|
ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio.
|
||
|
|
|
||
|
|
This file is part of ChibiOS.
|
||
|
|
|
||
|
|
ChibiOS is free software; you can redistribute it and/or modify
|
||
|
|
it under the terms of the GNU General Public License as published by
|
||
|
|
the Free Software Foundation; either version 3 of the License, or
|
||
|
|
(at your option) any later version.
|
||
|
|
|
||
|
|
ChibiOS is distributed in the hope that it will be useful,
|
||
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
|
|
GNU General Public License for more details.
|
||
|
|
|
||
|
|
You should have received a copy of the GNU General Public License
|
||
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @file chbsem.h
|
||
|
|
* @brief Binary semaphores structures and macros.
|
||
|
|
* @details Binary semaphores related APIs and services.
|
||
|
|
* <h2>Operation mode</h2>
|
||
|
|
* Binary semaphores are implemented as a set of inline functions
|
||
|
|
* that use the existing counting semaphores primitives. The
|
||
|
|
* difference between counting and binary semaphores is that the
|
||
|
|
* counter of binary semaphores is not allowed to grow above the
|
||
|
|
* value 1. Repeated signal operation are ignored. A binary
|
||
|
|
* semaphore can thus have only two defined states:
|
||
|
|
* - <b>Taken</b>, when its counter has a value of zero or lower
|
||
|
|
* than zero. A negative number represent the number of threads
|
||
|
|
* queued on the binary semaphore.
|
||
|
|
* - <b>Not taken</b>, when its counter has a value of one.
|
||
|
|
* .
|
||
|
|
* Binary semaphores are different from mutexes because there is no
|
||
|
|
* concept of ownership, a binary semaphore can be taken by a
|
||
|
|
* thread and signaled by another thread or an interrupt handler,
|
||
|
|
* mutexes can only be taken and released by the same thread. Another
|
||
|
|
* difference is that binary semaphores, unlike mutexes, do not
|
||
|
|
* implement the priority inheritance protocol.<br>
|
||
|
|
* In order to use the binary semaphores APIs the
|
||
|
|
* @p CH_CFG_USE_SEMAPHORES option must be enabled in @p chconf.h.
|
||
|
|
*
|
||
|
|
* @addtogroup oslib_binary_semaphores
|
||
|
|
* @{
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef CHBSEM_H
|
||
|
|
#define CHBSEM_H
|
||
|
|
|
||
|
|
#if (CH_CFG_USE_SEMAPHORES == TRUE) || defined(__DOXYGEN__)
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* Module constants. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* Module pre-compile time settings. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* Derived constants and error checks. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* Module data structures and types. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @extends semaphore_t
|
||
|
|
*
|
||
|
|
* @brief Binary semaphore type.
|
||
|
|
*/
|
||
|
|
typedef struct ch_binary_semaphore {
|
||
|
|
semaphore_t sem;
|
||
|
|
} binary_semaphore_t;
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* Module macros. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Data part of a static semaphore initializer.
|
||
|
|
* @details This macro should be used when statically initializing a semaphore
|
||
|
|
* that is part of a bigger structure.
|
||
|
|
*
|
||
|
|
* @param[in] name the name of the semaphore variable
|
||
|
|
* @param[in] taken the semaphore initial state
|
||
|
|
*/
|
||
|
|
#define _BSEMAPHORE_DATA(name, taken) \
|
||
|
|
{_SEMAPHORE_DATA(name.sem, ((taken) ? 0 : 1))}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Static semaphore initializer.
|
||
|
|
* @details Statically initialized semaphores require no explicit
|
||
|
|
* initialization using @p chBSemInit().
|
||
|
|
*
|
||
|
|
* @param[in] name the name of the semaphore variable
|
||
|
|
* @param[in] taken the semaphore initial state
|
||
|
|
*/
|
||
|
|
#define BSEMAPHORE_DECL(name, taken) \
|
||
|
|
binary_semaphore_t name = _BSEMAPHORE_DATA(name, taken)
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* External declarations. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/*===========================================================================*/
|
||
|
|
/* Module inline functions. */
|
||
|
|
/*===========================================================================*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Initializes a binary semaphore.
|
||
|
|
*
|
||
|
|
* @param[out] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @param[in] taken initial state of the binary semaphore:
|
||
|
|
* - @a false, the initial state is not taken.
|
||
|
|
* - @a true, the initial state is taken.
|
||
|
|
* .
|
||
|
|
*
|
||
|
|
* @init
|
||
|
|
*/
|
||
|
|
static inline void chBSemObjectInit(binary_semaphore_t *bsp, bool taken) {
|
||
|
|
|
||
|
|
chSemObjectInit(&bsp->sem, taken ? (cnt_t)0 : (cnt_t)1);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Wait operation on the binary semaphore.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @return A message specifying how the invoking thread has been
|
||
|
|
* released from the semaphore.
|
||
|
|
* @retval MSG_OK if the binary semaphore has been successfully taken.
|
||
|
|
* @retval MSG_RESET if the binary semaphore has been reset using
|
||
|
|
* @p bsemReset().
|
||
|
|
*
|
||
|
|
* @api
|
||
|
|
*/
|
||
|
|
static inline msg_t chBSemWait(binary_semaphore_t *bsp) {
|
||
|
|
|
||
|
|
return chSemWait(&bsp->sem);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Wait operation on the binary semaphore.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @return A message specifying how the invoking thread has been
|
||
|
|
* released from the semaphore.
|
||
|
|
* @retval MSG_OK if the binary semaphore has been successfully taken.
|
||
|
|
* @retval MSG_RESET if the binary semaphore has been reset using
|
||
|
|
* @p bsemReset().
|
||
|
|
*
|
||
|
|
* @sclass
|
||
|
|
*/
|
||
|
|
static inline msg_t chBSemWaitS(binary_semaphore_t *bsp) {
|
||
|
|
|
||
|
|
chDbgCheckClassS();
|
||
|
|
|
||
|
|
return chSemWaitS(&bsp->sem);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Wait operation on the binary semaphore.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @param[in] timeout the number of ticks before the operation timeouts,
|
||
|
|
* the following special values are allowed:
|
||
|
|
* - @a TIME_IMMEDIATE immediate timeout.
|
||
|
|
* - @a TIME_INFINITE no timeout.
|
||
|
|
* .
|
||
|
|
* @return A message specifying how the invoking thread has been
|
||
|
|
* released from the semaphore.
|
||
|
|
* @retval MSG_OK if the binary semaphore has been successfully taken.
|
||
|
|
* @retval MSG_RESET if the binary semaphore has been reset using
|
||
|
|
* @p bsemReset().
|
||
|
|
* @retval MSG_TIMEOUT if the binary semaphore has not been signaled or reset
|
||
|
|
* within the specified timeout.
|
||
|
|
*
|
||
|
|
* @sclass
|
||
|
|
*/
|
||
|
|
static inline msg_t chBSemWaitTimeoutS(binary_semaphore_t *bsp,
|
||
|
|
sysinterval_t timeout) {
|
||
|
|
|
||
|
|
chDbgCheckClassS();
|
||
|
|
|
||
|
|
return chSemWaitTimeoutS(&bsp->sem, timeout);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Wait operation on the binary semaphore.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @param[in] timeout the number of ticks before the operation timeouts,
|
||
|
|
* the following special values are allowed:
|
||
|
|
* - @a TIME_IMMEDIATE immediate timeout.
|
||
|
|
* - @a TIME_INFINITE no timeout.
|
||
|
|
* .
|
||
|
|
* @return A message specifying how the invoking thread has been
|
||
|
|
* released from the semaphore.
|
||
|
|
* @retval MSG_OK if the binary semaphore has been successfully taken.
|
||
|
|
* @retval MSG_RESET if the binary semaphore has been reset using
|
||
|
|
* @p bsemReset().
|
||
|
|
* @retval MSG_TIMEOUT if the binary semaphore has not been signaled or reset
|
||
|
|
* within the specified timeout.
|
||
|
|
*
|
||
|
|
* @api
|
||
|
|
*/
|
||
|
|
static inline msg_t chBSemWaitTimeout(binary_semaphore_t *bsp,
|
||
|
|
sysinterval_t timeout) {
|
||
|
|
|
||
|
|
return chSemWaitTimeout(&bsp->sem, timeout);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Reset operation on the binary semaphore.
|
||
|
|
* @note The released threads can recognize they were waked up by a reset
|
||
|
|
* rather than a signal because the @p bsemWait() will return
|
||
|
|
* @p MSG_RESET instead of @p MSG_OK.
|
||
|
|
* @note This function does not reschedule.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @param[in] taken new state of the binary semaphore
|
||
|
|
* - @a false, the new state is not taken.
|
||
|
|
* - @a true, the new state is taken.
|
||
|
|
* .
|
||
|
|
*
|
||
|
|
* @iclass
|
||
|
|
*/
|
||
|
|
static inline void chBSemResetI(binary_semaphore_t *bsp, bool taken) {
|
||
|
|
|
||
|
|
chDbgCheckClassI();
|
||
|
|
|
||
|
|
chSemResetI(&bsp->sem, taken ? (cnt_t)0 : (cnt_t)1);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Reset operation on the binary semaphore.
|
||
|
|
* @note The released threads can recognize they were waked up by a reset
|
||
|
|
* rather than a signal because the @p bsemWait() will return
|
||
|
|
* @p MSG_RESET instead of @p MSG_OK.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @param[in] taken new state of the binary semaphore
|
||
|
|
* - @a false, the new state is not taken.
|
||
|
|
* - @a true, the new state is taken.
|
||
|
|
* .
|
||
|
|
*
|
||
|
|
* @api
|
||
|
|
*/
|
||
|
|
static inline void chBSemReset(binary_semaphore_t *bsp, bool taken) {
|
||
|
|
|
||
|
|
chSemReset(&bsp->sem, taken ? (cnt_t)0 : (cnt_t)1);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Performs a signal operation on a binary semaphore.
|
||
|
|
* @note This function does not reschedule.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
*
|
||
|
|
* @iclass
|
||
|
|
*/
|
||
|
|
static inline void chBSemSignalI(binary_semaphore_t *bsp) {
|
||
|
|
|
||
|
|
chDbgCheckClassI();
|
||
|
|
|
||
|
|
if (bsp->sem.cnt < (cnt_t)1) {
|
||
|
|
chSemSignalI(&bsp->sem);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Performs a signal operation on a binary semaphore.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
*
|
||
|
|
* @api
|
||
|
|
*/
|
||
|
|
static inline void chBSemSignal(binary_semaphore_t *bsp) {
|
||
|
|
|
||
|
|
chSysLock();
|
||
|
|
chBSemSignalI(bsp);
|
||
|
|
chSchRescheduleS();
|
||
|
|
chSysUnlock();
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Returns the binary semaphore current state.
|
||
|
|
*
|
||
|
|
* @param[in] bsp pointer to a @p binary_semaphore_t structure
|
||
|
|
* @return The binary semaphore current state.
|
||
|
|
* @retval false if the binary semaphore is not taken.
|
||
|
|
* @retval true if the binary semaphore is taken.
|
||
|
|
*
|
||
|
|
* @iclass
|
||
|
|
*/
|
||
|
|
static inline bool chBSemGetStateI(const binary_semaphore_t *bsp) {
|
||
|
|
|
||
|
|
chDbgCheckClassI();
|
||
|
|
|
||
|
|
return (bsp->sem.cnt > (cnt_t)0) ? false : true;
|
||
|
|
}
|
||
|
|
|
||
|
|
#endif /* CH_CFG_USE_SEMAPHORES == TRUE */
|
||
|
|
|
||
|
|
#endif /* CHBSEM_H */
|
||
|
|
|
||
|
|
/** @} */
|