ChibiOS/RT  6.1.4
Counting Semaphores
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:

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 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)   {_CH_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 chSemResetWithMessage (semaphore_t *sp, cnt_t n, msg_t msg)
 Performs a reset operation on the semaphore. More...
 
void chSemResetWithMessageI (semaphore_t *sp, cnt_t n, msg_t msg)
 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 chSemReset (semaphore_t *sp, cnt_t n)
 Performs a reset operation on the semaphore. More...
 
static void chSemResetI (semaphore_t *sp, cnt_t n)
 Performs a reset operation on the semaphore. 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

◆ _SEMAPHORE_DATA

#define _SEMAPHORE_DATA (   name,
 
)    {_CH_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]namethe name of the semaphore variable
[in]nthe counter initial value, this value must be non-negative

Definition at line 71 of file chsem.h.

◆ SEMAPHORE_DECL

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

Static semaphore initializer.

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

Parameters
[in]namethe name of the semaphore variable
[in]nthe 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]sppointer to a semaphore_t structure
[in]ninitial 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 ch_queue_init(), chDbgCheck, ch_semaphore::cnt, and ch_semaphore::queue.

Referenced by _factory_init(), chBSemObjectInit(), chCacheObjectInit(), and chGuardedPoolObjectInitAligned().

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]sppointer to a semaphore_t structure
[in]nthe new value of the semaphore counter. The value must be non-negative.
[in]msgmessage 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]sppointer to a semaphore_t structure
[in]nthe new value of the semaphore counter. The value must be non-negative.
[in]msgmessage 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, 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]sppointer to a semaphore_t structure
Returns
A message specifying how the invoking thread has been released from the semaphore.
Return values
MSG_OKif the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESETif 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]sppointer to a semaphore_t structure
Returns
A message specifying how the invoking thread has been released from the semaphore.
Return values
MSG_OKif the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESETif 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(), chDbgAssert, chDbgCheck, chDbgCheckClassS(), ch_semaphore::cnt, currp, and ch_semaphore::queue.

Referenced by chBSemWaitS(), 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]sppointer to a semaphore_t structure
[in]timeoutthe 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_OKif the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESETif the semaphore has been reset using chSemReset().
MSG_TIMEOUTif 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 229 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]sppointer to a semaphore_t structure
[in]timeoutthe 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_OKif the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESETif the semaphore has been reset using chSemReset().
MSG_TIMEOUTif 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 258 of file chsem.c.

References ch_queue_isempty(), ch_queue_notempty(), chDbgAssert, chDbgCheck, chDbgCheckClassS(), ch_semaphore::cnt, currp, MSG_TIMEOUT, ch_semaphore::queue, and TIME_IMMEDIATE.

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]sppointer 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 288 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, and ch_semaphore::queue.

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]sppointer 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 313 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, and ch_thread::u.

Referenced by chBSemSignalI(), 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]sppointer to a semaphore_t structure
[in]nvalue 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 343 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, 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]spspointer to a semaphore_t structure to be signaled
[in]spwpointer 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_OKif the thread has not stopped on the semaphore or the semaphore has been signaled.
MSG_RESETif 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 372 of file chsem.c.

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

Here is the call graph for this function:

◆ chSemReset()

static 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]sppointer to a semaphore_t structure
[in]nthe 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()

static 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]sppointer to a semaphore_t structure
[in]nthe 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()

static 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]sppointer 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 chGuardedPoolAllocI().

Here is the call graph for this function:

◆ chSemFastSignalI()

static 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]sppointer 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.

Here is the call graph for this function:

◆ chSemGetCounterI()

static cnt_t chSemGetCounterI ( const semaphore_t sp)
inlinestatic

Returns the semaphore counter current value.

Parameters
[in]sppointer 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 chGuardedPoolAllocI(), and chGuardedPoolGetCounterI().

Here is the call graph for this function: