This handler encapsulates functionality which provides the foundation Semaphore services used in all of the APIs supported by RTEMS. More...

Collaboration diagram for Semaphore Handler:

Files
file	coresem.c
	Core Semaphore Initialize.

Data Structures
struct	CORE_semaphore_Attributes
	The following defines the control block used to manage the attributes of each semaphore. More...

struct	CORE_semaphore_Control
	The following defines the control block used to manage each counting semaphore. More...

Macros
#define	CORE_SEMAPHORE_STATUS_LAST CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED
	Core semaphore last status value. More...

Typedefs
typedef void(*	CORE_semaphore_API_mp_support_callout) (Thread_Control *, Objects_Id)
	The following type defines the callout which the API provides to support global/multiprocessor operations on semaphores.

Enumerations
enum	CORE_semaphore_Disciplines { CORE_SEMAPHORE_DISCIPLINES_FIFO, CORE_SEMAPHORE_DISCIPLINES_PRIORITY }
	Blocking disciplines for a semaphore. More...

enum	CORE_semaphore_Status { CORE_SEMAPHORE_STATUS_SUCCESSFUL, CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT, CORE_SEMAPHORE_WAS_DELETED, CORE_SEMAPHORE_TIMEOUT, CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED }
	Core Semaphore handler return statuses. More...

Functions
void	_CORE_semaphore_Initialize (CORE_semaphore_Control the_semaphore, const CORE_semaphore_Attributes the_semaphore_attributes, uint32_t initial_value)
	Initialize the semaphore based on the parameters passed. More...

RTEMS_INLINE_ROUTINE void	_CORE_semaphore_Destroy (CORE_semaphore_Control *the_semaphore)

RTEMS_INLINE_ROUTINE CORE_semaphore_Status	_CORE_semaphore_Surrender (CORE_semaphore_Control the_semaphore, Objects_Id id, CORE_semaphore_API_mp_support_callout api_semaphore_mp_support, ISR_lock_Context lock_context)
	Surrender a unit to a semaphore. More...

RTEMS_INLINE_ROUTINE void	_CORE_semaphore_Flush (CORE_semaphore_Control *the_semaphore, Thread_queue_Flush_callout remote_extract_callout, uint32_t status)
	Core semaphore flush. More...

RTEMS_INLINE_ROUTINE bool	_CORE_semaphore_Is_priority (const CORE_semaphore_Attributes *the_attribute)
	This function returns true if the priority attribute is enabled in the attribute_set and false otherwise. More...

RTEMS_INLINE_ROUTINE uint32_t	_CORE_semaphore_Get_count (CORE_semaphore_Control *the_semaphore)
	This routine returns the current count associated with the semaphore. More...

RTEMS_INLINE_ROUTINE void	_CORE_semaphore_Seize (CORE_semaphore_Control the_semaphore, Thread_Control executing, Objects_Id id, bool wait, Watchdog_Interval timeout, ISR_lock_Context *lock_context)
	This routine attempts to receive a unit from the_semaphore. More...

Detailed Description

This handler encapsulates functionality which provides the foundation Semaphore services used in all of the APIs supported by RTEMS.

Macro Definition Documentation

◆ CORE_SEMAPHORE_STATUS_LAST

#define CORE_SEMAPHORE_STATUS_LAST CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED

Core semaphore last status value.

This is the last status value.

Referenced by _POSIX_Semaphore_Translate_core_semaphore_return_code().

Enumeration Type Documentation

◆ CORE_semaphore_Disciplines

enum CORE_semaphore_Disciplines

Blocking disciplines for a semaphore.

Enumerator
CORE_SEMAPHORE_DISCIPLINES_FIFO	This specifies that threads will wait for the semaphore in FIFO order.
CORE_SEMAPHORE_DISCIPLINES_PRIORITY	This specifies that threads will wait for the semaphore in priority order.

◆ CORE_semaphore_Status

enum CORE_semaphore_Status

Core Semaphore handler return statuses.

Enumerator
CORE_SEMAPHORE_STATUS_SUCCESSFUL	This status indicates that the operation completed successfully.
CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT	This status indicates that the calling task did not want to block and the operation was unable to complete immediately because the resource was unavailable.
CORE_SEMAPHORE_WAS_DELETED	This status indicates that the thread was blocked waiting for an operation to complete and the semaphore was deleted.
CORE_SEMAPHORE_TIMEOUT	This status indicates that the calling task was willing to block but the operation was unable to complete within the time allotted because the resource never became available.
CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED	This status indicates that an attempt was made to unlock the semaphore and this would have made its count greater than that allowed.

Function Documentation

◆ _CORE_semaphore_Flush()

RTEMS_INLINE_ROUTINE void _CORE_semaphore_Flush	(	CORE_semaphore_Control *	the_semaphore,
		Thread_queue_Flush_callout	remote_extract_callout,
		uint32_t	status
	)

Core semaphore flush.

This package is the implementation of the CORE Semaphore Handler. This core object utilizes standard Dijkstra counting semaphores to provide synchronization and mutual exclusion capabilities.

This routine assists in the deletion of a semaphore by flushing the associated wait queue.

Parameters

[in]	the_semaphore	is the semaphore to flush
[in]	remote_extract_callout	is the routine to invoke if the thread unblocked is remote
[in]	status	is the status to be returned to the unblocked thread

Referenced by _POSIX_Semaphore_Delete().

◆ _CORE_semaphore_Get_count()

RTEMS_INLINE_ROUTINE uint32_t _CORE_semaphore_Get_count ( CORE_semaphore_Control * the_semaphore )

This routine returns the current count associated with the semaphore.

Parameters

[in] the_semaphore is the semaphore to obtain the count of

Returns: the current count of this semaphore

References CORE_semaphore_Control::count.

◆ _CORE_semaphore_Initialize()

void _CORE_semaphore_Initialize	(	CORE_semaphore_Control *	the_semaphore,
		const CORE_semaphore_Attributes *	the_semaphore_attributes,
		uint32_t	initial_value
	)

Initialize the semaphore based on the parameters passed.

This package is the implementation of the CORE Semaphore Handler. This core object utilizes standard Dijkstra counting semaphores to provide synchronization and mutual exclusion capabilities.

This routine initializes the semaphore based on the parameters passed.

Parameters

[in]	the_semaphore	is the semaphore to initialize
[in]	the_semaphore_attributes	define the behavior of this instance
[in]	initial_value	is the initial count of the semaphore

References _CORE_semaphore_Is_priority(), _Thread_queue_Initialize(), CORE_semaphore_Control::Attributes, CORE_semaphore_Control::count, and CORE_semaphore_Control::Wait_queue.

Referenced by rtems_semaphore_create().

◆ _CORE_semaphore_Is_priority()

RTEMS_INLINE_ROUTINE bool _CORE_semaphore_Is_priority ( const CORE_semaphore_Attributes * the_attribute )

This function returns true if the priority attribute is enabled in the attribute_set and false otherwise.

Parameters

[in] the_attribute is the attribute set to test

Returns: true if the priority attribute is enabled

References CORE_SEMAPHORE_DISCIPLINES_PRIORITY, and CORE_semaphore_Attributes::discipline.

Referenced by _CORE_semaphore_Initialize().

◆ _CORE_semaphore_Seize()

RTEMS_INLINE_ROUTINE void _CORE_semaphore_Seize	(	CORE_semaphore_Control *	the_semaphore,
		Thread_Control *	executing,
		Objects_Id	id,
		bool	wait,
		Watchdog_Interval	timeout,
		ISR_lock_Context *	lock_context
	)

This routine attempts to receive a unit from the_semaphore.

If a unit is available or if the wait flag is false, then the routine returns. Otherwise, the calling task is blocked until a unit becomes available.

Parameters

[in]	the_semaphore	is the semaphore to obtain
[in,out]	executing	The currently executing thread.
[in]	id	is the Id of the owning API level Semaphore object
[in]	wait	is true if the thread is willing to wait
[in]	timeout	is the maximum number of ticks to block
[in]	lock_context	is a temporary variable used to contain the ISR disable level cookie

Note: There is currently no MACRO version of this routine.

Referenced by _MPCI_Receive_server().

◆ _CORE_semaphore_Surrender()

RTEMS_INLINE_ROUTINE CORE_semaphore_Status _CORE_semaphore_Surrender	(	CORE_semaphore_Control *	the_semaphore,
		Objects_Id	id,
		CORE_semaphore_API_mp_support_callout	api_semaphore_mp_support,
		ISR_lock_Context *	lock_context
	)

Surrender a unit to a semaphore.

This routine frees a unit to the semaphore. If a task was blocked waiting for a unit from this semaphore, then that task will be readied and the unit given to that task. Otherwise, the unit will be returned to the semaphore.

Parameters

[in]	the_semaphore	is the semaphore to surrender
[in]	id	is the Id of the API level Semaphore object associated with this instance of a SuperCore Semaphore
[in]	api_semaphore_mp_support	is the routine to invoke if the thread unblocked is remote
[in]	lock_context	is a temporary variable used to contain the ISR disable level cookie

Return values

an	indication of whether the routine succeeded or failed

Referenced by _MPCI_Announce().

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CORE_SEMAPHORE_STATUS_LAST

Enumeration Type Documentation

◆ CORE_semaphore_Disciplines

◆ CORE_semaphore_Status

Function Documentation

◆ _CORE_semaphore_Flush()

◆ _CORE_semaphore_Get_count()

◆ _CORE_semaphore_Initialize()

◆ _CORE_semaphore_Is_priority()

◆ _CORE_semaphore_Seize()

◆ _CORE_semaphore_Surrender()