ChibiOS/RT Architecture - Reference Manual - Guides |
Semaphores related APIs and services.
Semaphores are a flexible synchronization primitive, ChibiOS/RT implements semaphores in their "counting semaphores" variant as defined by Edsger Dijkstra plus several enhancements like:
The binary semaphores variant can be easily implemented using counting semaphores.
Operations defined for semaphores:
Semaphores can be used as guards for mutual exclusion zones (note that mutexes are recommended for this kind of use) but also have other uses, queues guards and counters as example.
Semaphores usually use a FIFO queuing strategy but it is possible to make them order threads by priority by enabling CH_USE_SEMAPHORES_PRIORITY
in chconf.h
.
In order to use the Semaphores APIs the CH_USE_SEMAPHORES
option must be enabled in chconf.h
.
Data Structures | |
struct | Semaphore |
Semaphore structure. More... | |
Defines | |
#define | _SEMAPHORE_DATA(name, n) {_THREADSQUEUE_DATA(name.s_queue), n} |
Data part of a static semaphore initializer. | |
#define | SEMAPHORE_DECL(name, n) Semaphore name = _SEMAPHORE_DATA(name, n) |
Static semaphore initializer. | |
#define | chSemFastWaitI(sp) ((sp)->s_cnt--) |
Decreases the semaphore counter. | |
#define | chSemFastSignalI(sp) ((sp)->s_cnt++) |
Increases the semaphore counter. | |
#define | chSemGetCounterI(sp) ((sp)->s_cnt) |
Returns the semaphore counter current value. | |
Typedefs | |
typedef struct Semaphore | Semaphore |
Semaphore structure. | |
Functions | |
void | chSemInit (Semaphore *sp, cnt_t n) |
Initializes a semaphore with the specified counter value. | |
void | chSemReset (Semaphore *sp, cnt_t n) |
Performs a reset operation on the semaphore. | |
void | chSemResetI (Semaphore *sp, cnt_t n) |
Performs a reset operation on the semaphore. | |
msg_t | chSemWait (Semaphore *sp) |
Performs a wait operation on a semaphore. | |
msg_t | chSemWaitS (Semaphore *sp) |
Performs a wait operation on a semaphore. | |
msg_t | chSemWaitTimeout (Semaphore *sp, systime_t time) |
Performs a wait operation on a semaphore with timeout specification. | |
msg_t | chSemWaitTimeoutS (Semaphore *sp, systime_t time) |
Performs a wait operation on a semaphore with timeout specification. | |
void | chSemSignal (Semaphore *sp) |
Performs a signal operation on a semaphore. | |
void | chSemSignalI (Semaphore *sp) |
Performs a signal operation on a semaphore. | |
msg_t | chSemSignalWait (Semaphore *sps, Semaphore *spw) |
Performs atomic signal and wait operations on two semaphores. |
#define _SEMAPHORE_DATA | ( | name, | ||
n | ||||
) | {_THREADSQUEUE_DATA(name.s_queue), n} |
Data part of a static semaphore initializer.
This macro should be used when statically initializing a semaphore that is part of a bigger structure.
[in] | name | the name of the semaphore variable |
[in] | n | the counter initial value, this value must be non-negative |
#define SEMAPHORE_DECL | ( | name, | ||
n | ||||
) | Semaphore name = _SEMAPHORE_DATA(name, n) |
Static semaphore initializer.
Statically initialized semaphores require no explicit initialization using chSemInit()
.
[in] | name | the name of the semaphore variable |
[in] | n | the counter initial value, this value must be non-negative |
#define chSemFastWaitI | ( | sp | ) | ((sp)->s_cnt--) |
Decreases the semaphore counter.
This macro can be used when the counter is known to be positive.
Definition at line 94 of file chsem.h.
Referenced by chIQReadTimeout(), and chOQWriteTimeout().
#define chSemFastSignalI | ( | sp | ) | ((sp)->s_cnt++) |
#define chSemGetCounterI | ( | sp | ) | ((sp)->s_cnt) |
Initializes a semaphore with the specified counter value.
[out] | sp | pointer to a Semaphore structure |
[in] | n | initial value of the semaphore counter. Must be non-negative. |
Definition at line 83 of file chsem.c.
References chDbgCheck, queue_init, Semaphore::s_cnt, and Semaphore::s_queue.
Referenced by adcObjectInit(), canObjectInit(), chHeapInit(), chIQInit(), chMBInit(), chOQInit(), heap_init(), macObjectInit(), chibios_rt::Semaphore::Semaphore(), and spiObjectInit().
Performs a reset operation on the semaphore.
chSemWait()
will return RDY_RESET
instead of RDY_OK
.[in] | sp | pointer to a Semaphore structure |
[in] | n | the new value of the semaphore counter. The value must be non-negative. |
Definition at line 101 of file chsem.c.
References chSchRescheduleS(), chSemResetI(), chSysLock, and chSysUnlock.
Referenced by chibios_rt::Semaphore::Reset().
Performs a reset operation on the semaphore.
chSemWait()
will return RDY_RESET
instead of RDY_OK
. [in] | sp | pointer to a Semaphore structure |
[in] | n | the new value of the semaphore counter. The value must be non-negative. |
Definition at line 120 of file chsem.c.
References chDbgCheck, chSchReadyI(), lifo_remove(), Thread::p_u, Thread::rdymsg, Semaphore::s_cnt, and Semaphore::s_queue.
Referenced by adcStopConversion(), canStop(), CH_IRQ_HANDLER(), chIQResetI(), chMBReset(), chOQResetI(), and chSemReset().
Performs a wait operation on a semaphore.
[in] | sp | pointer to a Semaphore structure |
RDY_OK | if the semaphore was signaled or not taken. | |
RDY_RESET | if the semaphore was reset using chSemReset() . |
Definition at line 138 of file chsem.c.
References chSemWaitS(), chSysLock, and chSysUnlock.
Referenced by spiAcquireBus(), and chibios_rt::Semaphore::Wait().
Performs a wait operation on a semaphore.
[in] | sp | pointer to a Semaphore structure |
RDY_OK | if the semaphore was signaled or not taken. | |
RDY_RESET | if the semaphore was reset using chSemReset() . |
Definition at line 154 of file chsem.c.
References chDbgCheck, chSchGoSleepS(), currp, Semaphore::s_cnt, Semaphore::s_queue, and THD_STATE_WTSEM.
Referenced by chSemWait().
Performs a wait operation on a semaphore with timeout specification.
[in] | sp | pointer to a Semaphore structure |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
RDY_OK | if the semaphore was signaled or not taken. | |
RDY_RESET | if the semaphore was reset using chSemReset() . | |
RDY_TIMEOUT | if the semaphore was not signaled or reset within the specified timeout. |
Definition at line 181 of file chsem.c.
References chSemWaitTimeoutS(), chSysLock, and chSysUnlock.
Referenced by chibios_rt::Semaphore::WaitTimeout().
Performs a wait operation on a semaphore with timeout specification.
[in] | sp | pointer to a Semaphore structure |
[in] | time | the number of ticks before the operation timeouts, the following special values are allowed:
|
RDY_OK | if the semaphore was signaled or not taken. | |
RDY_RESET | if the semaphore was reset using chSemReset() . | |
RDY_TIMEOUT | if the semaphore was not signaled or reset within the specified timeout. |
Definition at line 204 of file chsem.c.
References chDbgCheck, chSchGoSleepTimeoutS(), currp, Semaphore::s_cnt, Semaphore::s_queue, THD_STATE_WTSEM, and TIME_IMMEDIATE.
Referenced by adcWaitConversion(), canReceive(), canTransmit(), chIQGetTimeout(), chIQReadTimeout(), chMBFetchS(), chMBPostAheadS(), chMBPostS(), chOQPutTimeout(), chOQWriteTimeout(), chSemWaitTimeout(), macWaitReceiveDescriptor(), and macWaitTransmitDescriptor().
void chSemSignal | ( | Semaphore * | sp | ) |
Performs a signal operation on a semaphore.
[in] | sp | pointer to a Semaphore structure |
Definition at line 225 of file chsem.c.
References chDbgCheck, chSchWakeupS(), chSysLock, chSysUnlock, fifo_remove(), RDY_OK, Semaphore::s_cnt, and Semaphore::s_queue.
Referenced by chibios_rt::Semaphore::Signal(), and spiReleaseBus().
void chSemSignalI | ( | Semaphore * | sp | ) |
Performs a signal operation on a semaphore.
[in] | sp | pointer to a Semaphore structure |
Definition at line 241 of file chsem.c.
References chDbgCheck, chSchReadyI(), fifo_remove(), Thread::p_u, Thread::rdymsg, Semaphore::s_cnt, and Semaphore::s_queue.
Referenced by chIQPutI(), chMBFetchS(), chMBPostAheadS(), chMBPostS(), and chOQGetI().
Performs atomic signal and wait operations on two semaphores.
CH_USE_SEMSW
option is enabled in chconf.h
.[in] | sps | pointer to a Semaphore structure to be signaled |
[in] | spw | pointer to a Semaphore structure to be wait on |
RDY_OK | if the semaphore was signaled or not taken. | |
RDY_RESET | if the semaphore was reset using chSemReset() . |
Definition at line 265 of file chsem.c.
References chDbgCheck, chSchGoSleepS(), chSchReadyI(), chSchRescheduleS(), chSysLock, chSysUnlock, fifo_remove(), Thread::p_u, Thread::rdymsg, Semaphore::s_cnt, Semaphore::s_queue, THD_STATE_WTSEM, and Thread::wtobjp.
Referenced by chibios_rt::Semaphore::SignalWait().