Collaboration diagram for Binary Semaphores:

Detailed Description

Binary semaphores related APIs and services.

Operation mode

Binary semaphores are implemented as a set of macros that use the existing counting semaphores primitives. The difference between counting and binary semaphores is that the counter of binary semaphores is not allowed to grow above the value 1. Repeated signal operation are ignored. A binary semaphore can thus have only two defined states:

Taken, when its counter has a value of zero or lower than zero. A negative number represent the number of threads queued on the binary semaphore.
Not taken, when its counter has a value of one.

Binary semaphores are different from mutexes because there is no the concept of ownership, a binary semaphore can be taken by a thread and signaled by another thread or an interrupt handler, mutexes can only be taken and released by the same thread. Another difference is that binary semaphores, unlike mutexes, do not implement the priority inheritance protocol.
In order to use the binary semaphores APIs the CH_USE_SEMAPHORES option must be enabled in chconf.h.

Data Structures
struct	BinarySemaphore
	Binary semaphore type. More...
Macro Functions
#define	chBSemInit(bsp, taken) chSemInit(&(bsp)->bs_sem, (taken) ? 0 : 1)
	Initializes a binary semaphore.
#define	chBSemWait(bsp) chSemWait(&(bsp)->bs_sem)
	Wait operation on the binary semaphore.
#define	chBSemWaitS(bsp) chSemWaitS(&(bsp)->bs_sem)
	Wait operation on the binary semaphore.
#define	chBSemWaitTimeout(bsp, time) chSemWaitTimeout(&(bsp)->bs_sem, (time))
	Wait operation on the binary semaphore.
#define	chBSemWaitTimeoutS(bsp, time) chSemWaitTimeoutS(&(bsp)->bs_sem, (time))
	Wait operation on the binary semaphore.
#define	chBSemReset(bsp, taken) chSemReset(&(bsp)->bs_sem, (taken) ? 0 : 1)
	Reset operation on the binary semaphore.
#define	chBSemResetI(bsp, taken) chSemResetI(&(bsp)->bs_sem, (taken) ? 0 : 1)
	Reset operation on the binary semaphore.
#define	chBSemSignal(bsp)
	Performs a signal operation on a binary semaphore.
#define	chBSemSignalI(bsp)
	Performs a signal operation on a binary semaphore.
#define	chBSemGetStateI(bsp) ((bsp)->bs_sem.s_cnt > 0 ? FALSE : TRUE)
	Returns the binary semaphore current state.
Defines
#define	_BSEMAPHORE_DATA(name, taken) {_SEMAPHORE_DATA(name.bs_sem, ((taken) ? 0 : 1))}
	Data part of a static semaphore initializer.
#define	BSEMAPHORE_DECL(name, taken) BinarySemaphore name = _BSEMAPHORE_DATA(name, taken)
	Static semaphore initializer.

Define Documentation

#define _BSEMAPHORE_DATA	(	name,
		taken
	)	{_SEMAPHORE_DATA(name.bs_sem, ((taken) ? 0 : 1))}

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]	taken	the semaphore initial state

Definition at line 80 of file chbsem.h.

#define BSEMAPHORE_DECL	(	name,
		taken
	)	BinarySemaphore name = _BSEMAPHORE_DATA(name, taken)

Static semaphore initializer.

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

Parameters:

[in]	name	the name of the semaphore variable
[in]	taken	the semaphore initial state

Definition at line 91 of file chbsem.h.

#define chBSemInit	(	bsp,
		taken
	)	chSemInit(&(bsp)->bs_sem, (taken) ? 0 : 1)

Initializes a binary semaphore.

Parameters:

[out]	bsp	pointer to a `BinarySemaphore` structure
[in]	taken	initial state of the binary semaphore: FALSE, the initial state is not taken. TRUE, the initial state is taken.

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

Definition at line 109 of file chbsem.h.

#define chBSemWait ( bsp ) chSemWait(&(bsp)->bs_sem)

Wait operation on the binary semaphore.

Parameters:

[in] bsp pointer to a BinarySemaphore structure

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

Return values:

RDY_OK	if the binary semaphore has been successfully taken.
RDY_RESET	if the binary semaphore has been reset using `bsemReset()`.

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 chbsem.h.

#define chBSemWaitS ( bsp ) chSemWaitS(&(bsp)->bs_sem)

Wait operation on the binary semaphore.

Parameters:

[in] bsp pointer to a BinarySemaphore structure

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

Return values:

RDY_OK	if the binary semaphore has been successfully taken.
RDY_RESET	if the binary semaphore has been reset using `bsemReset()`.

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 137 of file chbsem.h.

#define chBSemWaitTimeout	(	bsp,
		time
	)	chSemWaitTimeout(&(bsp)->bs_sem, (time))

Wait operation on the binary semaphore.

Parameters:

[in]	bsp	pointer to a `BinarySemaphore` 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.

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

Return values:

RDY_OK	if the binary semaphore has been successfully taken.
RDY_RESET	if the binary semaphore has been reset using `bsemReset()`.
RDY_TIMEOUT	if the binary 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 158 of file chbsem.h.

#define chBSemWaitTimeoutS	(	bsp,
		time
	)	chSemWaitTimeoutS(&(bsp)->bs_sem, (time))

Wait operation on the binary semaphore.

Parameters:

[in]	bsp	pointer to a `BinarySemaphore` 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.

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

Return values:

RDY_OK	if the binary semaphore has been successfully taken.
RDY_RESET	if the binary semaphore has been reset using `bsemReset()`.
RDY_TIMEOUT	if the binary 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 179 of file chbsem.h.

#define chBSemReset	(	bsp,
		taken
	)	chSemReset(&(bsp)->bs_sem, (taken) ? 0 : 1)

Reset operation on the binary semaphore.

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

Parameters:

[in]	bsp	pointer to a `BinarySemaphore` structure
[in]	taken	new state of the binary semaphore FALSE, the new state is not taken. TRUE, the new state is taken.

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

Definition at line 195 of file chbsem.h.

#define chBSemResetI	(	bsp,
		taken
	)	chSemResetI(&(bsp)->bs_sem, (taken) ? 0 : 1)

Reset operation on the binary semaphore.

Note:: The released threads can recognize they were waked up by a reset rather than a signal because the bsemWait() will return RDY_RESET instead of RDY_OK.; This function does not reschedule.

Parameters:

[in]	bsp	pointer to a `BinarySemaphore` structure
[in]	taken	new state of the binary semaphore FALSE, the new state is not taken. TRUE, the new state is taken.

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 212 of file chbsem.h.

#define chBSemSignal ( bsp )

Value:

{                                                 \
  chSysLock();                                                              \
  chBSemSignalI((bsp));                                                     \
  chSchRescheduleS();                                                       \
  chSysUnlock();                                                            \
}

Performs a signal operation on a binary semaphore.

Parameters:

[in] bsp pointer to a BinarySemaphore structure

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

Definition at line 221 of file chbsem.h.

#define chBSemSignalI ( bsp )

Value:

{                                                \
  if ((bsp)->bs_sem.s_cnt < 1)                                              \
    chSemSignalI(&(bsp)->bs_sem);                                           \
}

Performs a signal operation on a binary semaphore.

Note:: This function does not reschedule.

Parameters:

[in] bsp pointer to a BinarySemaphore 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 236 of file chbsem.h.

#define chBSemGetStateI ( bsp ) ((bsp)->bs_sem.s_cnt > 0 ? FALSE : TRUE)

Returns the binary semaphore current state.

Parameters:

[in] bsp pointer to a BinarySemaphore structure

Returns:: The binary semaphore current state.

Return values:

FALSE	if the binary semaphore is not taken.
TRUE	if the binary semaphore is taken.

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 251 of file chbsem.h.

Detailed Description

Operation mode

Data Structures

Macro Functions

Defines

Define Documentation