Collaboration diagram for Counting Semaphores:

Detailed 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 for example.
Semaphores usually use a FIFO queuing strategy but it is possible to make them order threads by priority by enabling CH_CFG_USE_SEMAPHORES_PRIORITY in chconf.h.

Precondition: In order to use the semaphore APIs the CH_CFG_USE_SEMAPHORES option must be enabled in chconf.h.

Macros
#define	_SEMAPHORE_DATA(name, n) {_THREADS_QUEUE_DATA(name.queue), n}
	Data part of a static semaphore initializer. More...

#define	SEMAPHORE_DECL(name, n) semaphore_t name = _SEMAPHORE_DATA(name, n)
	Static semaphore initializer. More...

Typedefs
typedef struct ch_semaphore	semaphore_t
	Semaphore structure. More...

Data Structures
struct	ch_semaphore
	Semaphore structure. More...

Functions
void	chSemObjectInit (semaphore_t *sp, cnt_t n)
	Initializes a semaphore with the specified counter value. More...

void	chSemReset (semaphore_t *sp, cnt_t n)
	Performs a reset operation on the semaphore. More...

void	chSemResetI (semaphore_t *sp, cnt_t n)
	Performs a reset operation on the semaphore. More...

msg_t	chSemWait (semaphore_t *sp)
	Performs a wait operation on a semaphore. More...

msg_t	chSemWaitS (semaphore_t *sp)
	Performs a wait operation on a semaphore. More...

msg_t	chSemWaitTimeout (semaphore_t *sp, sysinterval_t timeout)
	Performs a wait operation on a semaphore with timeout specification. More...

msg_t	chSemWaitTimeoutS (semaphore_t *sp, sysinterval_t timeout)
	Performs a wait operation on a semaphore with timeout specification. More...

void	chSemSignal (semaphore_t *sp)
	Performs a signal operation on a semaphore. More...

void	chSemSignalI (semaphore_t *sp)
	Performs a signal operation on a semaphore. More...

void	chSemAddCounterI (semaphore_t *sp, cnt_t n)
	Adds the specified value to the semaphore counter. More...

msg_t	chSemSignalWait (semaphore_t sps, semaphore_t spw)
	Performs atomic signal and wait operations on two semaphores. More...

static void	chSemFastWaitI (semaphore_t *sp)
	Decreases the semaphore counter. More...

static void	chSemFastSignalI (semaphore_t *sp)
	Increases the semaphore counter. More...

static cnt_t	chSemGetCounterI (const semaphore_t *sp)
	Returns the semaphore counter current value. More...

Macro Definition Documentation

#define _SEMAPHORE_DATA	(	name,
		n
	)	{_THREADS_QUEUE_DATA(name.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 71 of file chsem.h.

#define SEMAPHORE_DECL	(	name,
		n
	)	semaphore_t 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 82 of file chsem.h.

Typedef Documentation

typedef struct ch_semaphore semaphore_t

Semaphore structure.

Function Documentation

void chSemObjectInit	(	semaphore_t *	sp,
		cnt_t	n
	)

Initializes a semaphore with the specified counter value.

Parameters

[out]	sp	pointer to a `semaphore_t` structure
[in]	n	initial value of the semaphore counter. Must be non-negative.

Function Class:: Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 97 of file chsem.c.

References chDbgCheck, ch_semaphore::cnt, ch_semaphore::queue, and queue_init().

Referenced by _factory_init(), _heap_init(), chBSemObjectInit(), chFactoryCreateSemaphore(), chGuardedPoolObjectInitAligned(), and chHeapObjectInit().

Here is the call graph for this function:

void chSemReset	(	semaphore_t *	sp,
		cnt_t	n
	)

Performs a reset operation on the semaphore.

Postcondition: After invoking this function all the threads waiting on the semaphore, if any, are released and the semaphore counter is set to the specified, non negative, value.

Note: The released threads can recognize they were waked up by a reset rather than a signal because the chSemWait() will return MSG_RESET instead of MSG_OK.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	n	the new value of the semaphore counter. The value must be non-negative.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 120 of file chsem.c.

References chSchRescheduleS(), chSemResetI(), chSysLock(), and chSysUnlock().

Referenced by chBSemReset().

Here is the call graph for this function:

void chSemResetI	(	semaphore_t *	sp,
		cnt_t	n
	)

Performs a reset operation on the semaphore.

Postcondition: After invoking this function all the threads waiting on the semaphore, if any, are released and the semaphore counter is set to the specified, non negative, value.; This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Note: The released threads can recognize they were waked up by a reset rather than a signal because the chSemWait() will return MSG_RESET instead of MSG_OK.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	n	the new value of the semaphore counter. The value must be non-negative.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 147 of file chsem.c.

References chDbgAssert, chDbgCheck, chDbgCheckClassI(), chSchReadyI(), ch_semaphore::cnt, MSG_RESET, ch_semaphore::queue, queue_isempty(), queue_lifo_remove(), queue_notempty(), ch_thread::rdymsg, and ch_thread::u.

Referenced by chBSemResetI(), and chSemReset().

Here is the call graph for this function:

msg_t chSemWait ( semaphore_t * sp )

Performs a wait operation on a semaphore.

Parameters

[in] sp pointer to a semaphore_t structure

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESET	if the semaphore has been reset using `chSemReset()`.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 175 of file chsem.c.

References chSemWaitS(), chSysLock(), and chSysUnlock().

Referenced by chBSemWait().

Here is the call graph for this function:

msg_t chSemWaitS ( semaphore_t * sp )

Performs a wait operation on a semaphore.

Parameters

[in] sp pointer to a semaphore_t structure

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESET	if the semaphore has been reset using `chSemReset()`.

Function Class:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 197 of file chsem.c.

References CH_STATE_WTSEM, chDbgAssert, chDbgCheck, chDbgCheckClassS(), chSchGoSleepS(), ch_semaphore::cnt, currp, MSG_OK, ch_semaphore::queue, queue_isempty(), and queue_notempty().

Referenced by chBSemWaitS(), and chSemWait().

Here is the call graph for this function:

msg_t chSemWaitTimeout	(	semaphore_t *	sp,
		sysinterval_t	timeout
	)

Performs a wait operation on a semaphore with timeout specification.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESET	if the semaphore has been reset using `chSemReset()`.
MSG_TIMEOUT	if the semaphore has not been signaled or reset within the specified timeout.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 235 of file chsem.c.

References chSemWaitTimeoutS(), chSysLock(), and chSysUnlock().

Referenced by chBSemWaitTimeout().

Here is the call graph for this function:

msg_t chSemWaitTimeoutS	(	semaphore_t *	sp,
		sysinterval_t	timeout
	)

Performs a wait operation on a semaphore with timeout specification.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	timeout	the number of ticks before the operation timeouts, the following special values are allowed: TIME_IMMEDIATE immediate timeout. TIME_INFINITE no timeout.

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESET	if the semaphore has been reset using `chSemReset()`.
MSG_TIMEOUT	if the semaphore has not been signaled or reset within the specified timeout.

Function Class:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 264 of file chsem.c.

References CH_STATE_WTSEM, chDbgAssert, chDbgCheck, chDbgCheckClassS(), chSchGoSleepTimeoutS(), ch_semaphore::cnt, currp, MSG_OK, MSG_TIMEOUT, ch_semaphore::queue, queue_isempty(), queue_notempty(), and TIME_IMMEDIATE.

Referenced by chBSemWaitTimeoutS(), chGuardedPoolAllocTimeoutS(), and chSemWaitTimeout().

Here is the call graph for this function:

void chSemSignal ( semaphore_t * sp )

Performs a signal operation on a semaphore.

Parameters

[in] sp pointer to a semaphore_t structure

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 294 of file chsem.c.

References chDbgAssert, chDbgCheck, chSchWakeupS(), chSysLock(), chSysUnlock(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, queue_fifo_remove(), queue_isempty(), and queue_notempty().

Here is the call graph for this function:

void chSemSignalI ( semaphore_t * sp )

Performs a signal operation on a semaphore.

Postcondition: This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters

[in] sp pointer to a semaphore_t structure

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 319 of file chsem.c.

References chDbgAssert, chDbgCheck, chDbgCheckClassI(), chSchReadyI(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, queue_fifo_remove(), queue_isempty(), queue_notempty(), ch_thread::rdymsg, and ch_thread::u.

Referenced by chBSemSignalI(), and chGuardedPoolFreeI().

Here is the call graph for this function:

void chSemAddCounterI	(	semaphore_t *	sp,
		cnt_t	n
	)

Adds the specified value to the semaphore counter.

Postcondition: This function does not reschedule so a call to a rescheduling function must be performed before unlocking the kernel. Note that interrupt handlers always reschedule on exit so an explicit reschedule must not be performed in ISRs.

Parameters

[in]	sp	pointer to a `semaphore_t` structure
[in]	n	value to be added to the semaphore counter. The value must be positive.

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 349 of file chsem.c.

References chDbgAssert, chDbgCheck, chDbgCheckClassI(), chSchReadyI(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, queue_fifo_remove(), queue_isempty(), queue_notempty(), ch_thread::rdymsg, and ch_thread::u.

Here is the call graph for this function:

msg_t chSemSignalWait	(	semaphore_t *	sps,
		semaphore_t *	spw
	)

Performs atomic signal and wait operations on two semaphores.

Parameters

[in]	sps	pointer to a `semaphore_t` structure to be signaled
[in]	spw	pointer to a `semaphore_t` structure to wait on

Returns: A message specifying how the invoking thread has been released from the semaphore.

Return values

MSG_OK	if the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESET	if the semaphore has been reset using `chSemReset()`.