Semaphores
[Synchronization]

Collaboration diagram for Semaphores:

Description

Semaphores related APIs and services.

Operation mode

Semaphores are a flexible synchronization primitive, ChibiOS/RT implements semaphores in their "counting semaphores" variant as defined by Edsger Dijkstra plus several enhancements like:

Wait operation with timeout.
Reset operation.
Atomic wait+signal operation.
Return message from the wait operation (OK, RESET, TIMEOUT).

The binary semaphores variant can be easily implemented using counting semaphores.
Operations defined for semaphores:

Signal: The semaphore counter is increased and if the result is non-positive then a waiting thread is removed from the semaphore queue and made ready for execution.
Wait: The semaphore counter is decreased and if the result becomes negative the thread is queued in the semaphore and suspended.
Reset: The semaphore counter is reset to a non-negative value and all the threads in the queue are released.

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 Documentation

#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.

Parameters:

`[in]`	name	the name of the semaphore variable
`[in]`	n	the counter initial value, this value must be non-negative

Definition at line 77 of file chsem.h.

#define SEMAPHORE_DECL	(	name,
		n		)	Semaphore name = _SEMAPHORE_DATA(name, n)

Static semaphore initializer.

Statically initialized semaphores require no explicit initialization using chSemInit().

Parameters:

`[in]`	name	the name of the semaphore variable
`[in]`	n	the counter initial value, this value must be non-negative

Definition at line 88 of file chsem.h.

#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++)

Increases the semaphore counter.

This macro can be used when the counter is known to be not negative.

Definition at line 100 of file chsem.h.

#define chSemGetCounterI ( sp ) ((sp)->s_cnt)

Returns the semaphore counter current value.

Definition at line 105 of file chsem.h.

Typedef Documentation

typedef struct Semaphore Semaphore

Semaphore structure.

Function Documentation

void chSemInit	(	Semaphore *	sp,
		cnt_t	n
	)

Initializes a semaphore with the specified counter value.

Parameters:

`[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().

void chSemReset	(	Semaphore *	sp,
		cnt_t	n
	)

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 chSemWait() will return RDY_RESET instead of RDY_OK.

Parameters:

`[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().

Here is the call graph for this function:

void chSemResetI	(	Semaphore *	sp,
		cnt_t	n
	)

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 chSemWait() will return RDY_RESET instead of RDY_OK.; This function does not reschedule.

Parameters:

`[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, RDY_RESET, Thread::rdymsg, Semaphore::s_cnt, and Semaphore::s_queue.

Referenced by adcStopConversion(), canStop(), CH_IRQ_HANDLER(), chIQResetI(), chMBReset(), chOQResetI(), and chSemReset().

Here is the call graph for this function:

msg_t chSemWait ( Semaphore * sp )

Performs a wait operation on a semaphore.

Parameters:

[in] sp pointer to a Semaphore structure

Return values:

	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().

Here is the call graph for this function:

msg_t chSemWaitS ( Semaphore * sp )

Performs a wait operation on a semaphore.

Parameters:

[in] sp pointer to a Semaphore structure

Return values:

	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, RDY_OK, Semaphore::s_cnt, Semaphore::s_queue, and THD_STATE_WTSEM.

Referenced by chSemWait().

Here is the call graph for this function:

msg_t chSemWaitTimeout	(	Semaphore *	sp,
		systime_t	time
	)

Performs a wait operation on a semaphore with timeout specification.

Parameters:

[in] sp pointer to a Semaphore structure

[in]

time

the number of ticks before the operation timeouts, the following special values are allowed:

TIME_IMMEDIATE immediate timeout.
TIME_INFINITE no timeout.

Return values:

	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().

Here is the call graph for this function:

msg_t chSemWaitTimeoutS	(	Semaphore *	sp,
		systime_t	time
	)

Performs a wait operation on a semaphore with timeout specification.

Parameters:

[in] sp pointer to a Semaphore structure

[in]

time

the number of ticks before the operation timeouts, the following special values are allowed:

TIME_IMMEDIATE immediate timeout.
TIME_INFINITE no timeout.

Return values:

	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.