From 641f2c372605cf405f0dda8536b45a78e0e5e2e2 Mon Sep 17 00:00:00 2001 From: Giovanni Di Sirio Date: Tue, 16 Feb 2016 09:59:21 +0000 Subject: Tree reorganization. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@8899 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/common/oslib/include/chbsem.h | 311 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 311 insertions(+) create mode 100644 os/common/oslib/include/chbsem.h (limited to 'os/common/oslib/include/chbsem.h') diff --git a/os/common/oslib/include/chbsem.h b/os/common/oslib/include/chbsem.h new file mode 100644 index 000000000..ac2b37e9c --- /dev/null +++ b/os/common/oslib/include/chbsem.h @@ -0,0 +1,311 @@ +/* + ChibiOS - Copyright (C) 2006..2015 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 . +*/ + +/** + * @file chbsem.h + * @brief Binary semaphores structures and macros. + * + * @addtogroup binary_semaphores + * @details Binary semaphores related APIs and services. + *

Operation mode

+ * 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: + * - Taken, 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. + * - Not taken, 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.
+ * In order to use the binary semaphores APIs the + * @p CH_CFG_USE_SEMAPHORES option must be enabled in @p chconf.h. + * @{ + */ + +#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 { + 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] 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. + * . + * @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, + systime_t time) { + + chDbgCheckClassS(); + + return chSemWaitTimeoutS(&bsp->sem, time); +} + +/** + * @brief Wait operation on the binary semaphore. + * + * @param[in] bsp pointer to a @p binary_semaphore_t 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. + * . + * @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, + systime_t time) { + + return chSemWaitTimeout(&bsp->sem, time); +} + +/** + * @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(binary_semaphore_t *bsp) { + + chDbgCheckClassI(); + + return (bsp->sem.cnt > (cnt_t)0) ? false : true; +} + +#endif /* CH_CFG_USE_SEMAPHORES == TRUE */ + +#endif /* _CHBSEM_H_ */ + +/** @} */ -- cgit v1.2.3