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.

Collaboration diagram for Counting Semaphores:

Data Structures
struct	ch_semaphore
	Semaphore structure. More...

Macros
#define	sem_insert(qp, tp)
#define	__SEMAPHORE_DATA(name, n)
	Data part of a static semaphore initializer.
#define	SEMAPHORE_DECL(name, n)
	Static semaphore initializer.

Typedefs
typedef struct ch_semaphore	semaphore_t
	Semaphore structure.

Functions
void	chSemObjectInit (semaphore_t *sp, cnt_t n)
	Initializes a semaphore with the specified counter value.
void	chSemResetWithMessage (semaphore_t *sp, cnt_t n, msg_t msg)
	Performs a reset operation on the semaphore.
void	chSemResetWithMessageI (semaphore_t *sp, cnt_t n, msg_t msg)
	Performs a reset operation on the semaphore.
msg_t	chSemWait (semaphore_t *sp)
	Performs a wait operation on a semaphore.
msg_t	chSemWaitS (semaphore_t *sp)
	Performs a wait operation on a semaphore.
msg_t	chSemWaitTimeout (semaphore_t *sp, sysinterval_t timeout)
	Performs a wait operation on a semaphore with timeout specification.
msg_t	chSemWaitTimeoutS (semaphore_t *sp, sysinterval_t timeout)
	Performs a wait operation on a semaphore with timeout specification.
void	chSemSignal (semaphore_t *sp)
	Performs a signal operation on a semaphore.
void	chSemSignalI (semaphore_t *sp)
	Performs a signal operation on a semaphore.
void	chSemAddCounterI (semaphore_t *sp, cnt_t n)
	Adds the specified value to the semaphore counter.
msg_t	chSemSignalWait (semaphore_t sps, semaphore_t spw)
	Performs atomic signal and wait operations on two semaphores.
static void	chSemReset (semaphore_t *sp, cnt_t n)
	Performs a reset operation on the semaphore.
static void	chSemResetI (semaphore_t *sp, cnt_t n)
	Performs a reset operation on the semaphore.
static void	chSemFastWaitI (semaphore_t *sp)
	Decreases the semaphore counter.
static void	chSemFastSignalI (semaphore_t *sp)
	Increases the semaphore counter.
static cnt_t	chSemGetCounterI (const semaphore_t *sp)
	Returns the semaphore counter current value.

Macro Definition Documentation

◆ sem_insert

#define sem_insert	(		qp,
			tp )

Value:

ch_sch_prio_insert(qp, &tp->hdr.queue)

ch_sch_prio_insert

void ch_sch_prio_insert(ch_queue_t *qp, ch_queue_t *tp)

Inserts a thread into a priority ordered queue.

Definition chschd.c:250

Definition at line 79 of file chsem.c.

Referenced by chSemSignalWait(), chSemWaitS(), and chSemWaitTimeoutS().

◆ __SEMAPHORE_DATA

#define __SEMAPHORE_DATA	(		name,
			n )

Value:

{__CH_QUEUE_DATA(name.queue), n}

__CH_QUEUE_DATA

#define __CH_QUEUE_DATA(name)

Data part of a static queue object initializer.

Definition chlists.h:117

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.

◆ SEMAPHORE_DECL

#define SEMAPHORE_DECL	(		name,
			n )

Value:

semaphore_t name = __SEMAPHORE_DATA(name, n)

semaphore_t

struct ch_semaphore semaphore_t

Semaphore structure.

__SEMAPHORE_DATA

#define __SEMAPHORE_DATA(name, n)

Data part of a static semaphore initializer.

Definition chsem.h:71

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

◆ semaphore_t

typedef struct ch_semaphore semaphore_t

Semaphore structure.

Function Documentation

◆ chSemObjectInit()

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:: Object or module nitializer function.

Definition at line 97 of file chsem.c.

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

Referenced by __factory_init(), __heap_init(), chBSemObjectInit(), chCacheObjectInit(), chFactoryCreateSemaphore(), chGuardedPoolObjectInitAligned(), and chHeapObjectInit().

Here is the call graph for this function:

◆ chSemResetWithMessage()

void chSemResetWithMessage	(	semaphore_t *	sp,
		cnt_t	n,
		msg_t	msg )

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.

Parameters

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

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

Definition at line 118 of file chsem.c.

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

Referenced by chSemReset().

Here is the call graph for this function:

◆ chSemResetWithMessageI()

void chSemResetWithMessageI	(	semaphore_t *	sp,
		cnt_t	n,
		msg_t	msg )

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.

Parameters

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

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 143 of file chsem.c.

References ch_queue_isempty(), ch_queue_lifo_remove(), ch_queue_notempty(), chDbgAssert, chDbgCheck, chDbgCheckClassI, chSchReadyI(), ch_semaphore::cnt, ch_semaphore::queue, ch_thread::rdymsg, threadref, and ch_thread::u.

Referenced by chSemResetI(), and chSemResetWithMessage().

Here is the call graph for this function:

◆ chSemWait()

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 169 of file chsem.c.

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

Referenced by chBSemWait().

Here is the call graph for this function:

◆ chSemWaitS()

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 191 of file chsem.c.

References ch_queue_isempty(), ch_queue_notempty(), CH_STATE_WTSEM, chDbgAssert, chDbgCheck, chDbgCheckClassS, chSchGoSleepS(), chThdGetSelfX(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, ch_thread::rdymsg, sem_insert, ch_thread::u, and ch_thread::wtsemp.

Referenced by chBSemWaitS(), chCacheGetObject(), chSemWait(), and lru_get_last_s().

Here is the call graph for this function:

◆ chSemWaitTimeout()

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 230 of file chsem.c.

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

Referenced by chBSemWaitTimeout().

Here is the call graph for this function:

◆ chSemWaitTimeoutS()

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 259 of file chsem.c.

References ch_queue_isempty(), ch_queue_notempty(), CH_STATE_WTSEM, chDbgAssert, chDbgCheck, chDbgCheckClassS, chSchGoSleepTimeoutS(), chThdGetSelfX(), ch_semaphore::cnt, MSG_OK, MSG_TIMEOUT, ch_semaphore::queue, sem_insert, TIME_IMMEDIATE, ch_thread::u, unlikely, and ch_thread::wtsemp.

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

Here is the call graph for this function:

◆ chSemSignal()

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 290 of file chsem.c.

References ch_queue_fifo_remove(), ch_queue_isempty(), ch_queue_notempty(), chDbgAssert, chDbgCheck, chSchWakeupS(), chSysLock(), chSysUnlock(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, and threadref.

Here is the call graph for this function:

◆ chSemSignalI()

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 315 of file chsem.c.

References ch_queue_fifo_remove(), ch_queue_isempty(), ch_queue_notempty(), chDbgAssert, chDbgCheck, chDbgCheckClassI, chSchReadyI(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, ch_thread::rdymsg, threadref, and ch_thread::u.

Referenced by chBSemSignalI(), chCacheReleaseObjectI(), and chGuardedPoolFreeI().

Here is the call graph for this function:

◆ chSemAddCounterI()

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 345 of file chsem.c.

References ch_queue_fifo_remove(), ch_queue_isempty(), ch_queue_notempty(), chDbgAssert, chDbgCheck, chDbgCheckClassI, chSchReadyI(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, ch_thread::rdymsg, threadref, and ch_thread::u.

Here is the call graph for this function:

◆ chSemSignalWait()

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

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

Definition at line 374 of file chsem.c.

References ch_queue_fifo_remove(), ch_queue_isempty(), ch_queue_notempty(), CH_STATE_WTSEM, chDbgAssert, chDbgCheck, chSchGoSleepS(), chSchReadyI(), chSchRescheduleS(), chSysLock(), chSysUnlock(), chThdGetSelfX(), ch_semaphore::cnt, MSG_OK, ch_semaphore::queue, ch_thread::rdymsg, sem_insert, threadref, ch_thread::u, and ch_thread::wtsemp.

Here is the call graph for this function:

◆ chSemReset()

void chSemReset	(	semaphore_t *	sp,
		cnt_t	n )

inlinestatic

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: This function implicitly sends MSG_RESET as message.

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 123 of file chsem.h.

References chSemResetWithMessage(), and MSG_RESET.

Referenced by chBSemReset().

Here is the call graph for this function:

◆ chSemResetI()

void chSemResetI	(	semaphore_t *	sp,
		cnt_t	n )

inlinestatic

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: This function implicitly sends MSG_RESET as message.

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 145 of file chsem.h.

References chSemResetWithMessageI(), and MSG_RESET.

Referenced by chBSemResetI().

Here is the call graph for this function:

◆ chSemFastWaitI()

void chSemFastWaitI ( semaphore_t * sp )

inlinestatic

Decreases the semaphore counter.

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

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 158 of file chsem.h.

References chDbgCheckClassI, and ch_semaphore::cnt.

Referenced by chCacheGetObject(), chGuardedPoolAllocI(), and lru_get_last_s().

◆ chSemFastSignalI()

void chSemFastSignalI ( semaphore_t * sp )

inlinestatic

Increases the semaphore counter.

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

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 174 of file chsem.h.

References chDbgCheckClassI, and ch_semaphore::cnt.

Referenced by __sch_wakeup(), and chCacheReleaseObjectI().

◆ chSemGetCounterI()

cnt_t chSemGetCounterI ( const semaphore_t * sp )

inlinestatic

Returns the semaphore counter current value.

Parameters

[in] sp pointer to a semaphore_t structure

Returns: The semaphore counter value.

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 189 of file chsem.h.

References chDbgCheckClassI, and ch_semaphore::cnt.

Referenced by chCacheGetObject(), chCacheReleaseObjectI(), chGuardedPoolAllocI(), chGuardedPoolGetCounterI(), and lru_get_last_s().

Detailed Description

Operation mode

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ sem_insert

◆ __SEMAPHORE_DATA

◆ SEMAPHORE_DECL

Typedef Documentation

◆ semaphore_t

Function Documentation

◆ chSemObjectInit()

◆ chSemResetWithMessage()

◆ chSemResetWithMessageI()

◆ chSemWait()

◆ chSemWaitS()

◆ chSemWaitTimeout()

◆ chSemWaitTimeoutS()

◆ chSemSignal()

◆ chSemSignalI()

◆ chSemAddCounterI()

◆ chSemSignalWait()

◆ chSemReset()

◆ chSemResetI()

◆ chSemFastWaitI()

◆ chSemFastSignalI()

◆ chSemGetCounterI()