Semaphores

This encapsulates functionality related to the Classic API Semaphore Manager. More...

Collaboration diagram for Semaphores:

Files
file	sem.h
	Classic Semaphores API.
file	semimpl.h
	Classic Semaphores Implementation.
file	sem.c
	Semaphore Manager Initialization.
file	semcreate.c
	rtems_semaphore_create
file	semdata.c
	Instantiate Semaphore Data.
file	semdelete.c
	RTEMS Delete Semaphore.
file	semflush.c
	RTEMS Semaphore Flush.
file	semident.c
	RTEMS Semaphore Name to Id.
file	semobtain.c
	RTEMS Obtain Semaphore.
file	semrelease.c
	RTEMS Semaphore ReleaseThis file contains the implementation of the Classic API directive rtems_semaphore_release().
file	semtranslatereturncode.c
	Semaphore Translate Core Mutex and Semaphore Return Code.

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

Functions
rtems_status_code	rtems_semaphore_create (rtems_name name, uint32_t count, rtems_attribute attribute_set, rtems_task_priority priority_ceiling, rtems_id *id)
	rtems_semaphore_create More...
rtems_status_code	rtems_semaphore_ident (rtems_name name, uint32_t node, rtems_id *id)
	RTEMS Semaphore Name to Id. More...
rtems_status_code	rtems_semaphore_delete (rtems_id id)
	RTEMS Delete Semaphore. More...
rtems_status_code	rtems_semaphore_obtain (rtems_id id, rtems_option option_set, rtems_interval timeout)
	RTEMS Obtain Semaphore. More...
rtems_status_code	rtems_semaphore_release (rtems_id id)
	RTEMS Semaphore Release. More...
rtems_status_code	rtems_semaphore_flush (rtems_id id)
	RTEMS Semaphore Flush. More...
rtems_status_code	rtems_semaphore_set_priority (rtems_id semaphore_id, rtems_id scheduler_id, rtems_task_priority new_priority, rtems_task_priority *old_priority)
	Sets the priority value with respect to the specified scheduler of a semaphore. More...

Detailed Description

This encapsulates functionality related to the Classic API Semaphore Manager.

Function Documentation

rtems_semaphore_create()

rtems_status_code rtems_semaphore_create	(	rtems_name	name,
		uint32_t	count,
		rtems_attribute	attribute_set,
		rtems_task_priority	priority_ceiling,
		rtems_id *	id
	)

rtems_semaphore_create

This routine implements the rtems_semaphore_create directive. The semaphore will have the name name. The starting count for the semaphore is count. The attribute_set determines if the semaphore is global or local and the thread queue discipline. It returns the id of the created semaphore in ID.

Semaphore Manager

References _Attributes_Has_at_most_one_protocol(), _Attributes_Is_binary_semaphore(), _Attributes_Is_counting_semaphore(), _Attributes_Is_inherit_priority(), _Attributes_Is_multiprocessor_resource_sharing(), _Attributes_Is_priority(), _Attributes_Is_priority_ceiling(), _CORE_mutex_Initialize(), _CORE_semaphore_Initialize(), _Objects_Allocator_unlock(), _Objects_MP_Allocate_and_open(), _Objects_Open(), _RTEMS_tasks_Priority_to_Core(), _Semaphore_Allocate(), _Semaphore_Free(), _Semaphore_Information, _Semaphore_MP_Send_process_packet(), _Thread_Get_executing(), Semaphore_Control::attribute_set, Semaphore_Control::Core_control, CORE_MUTEX_DISCIPLINES_FIFO, CORE_MUTEX_DISCIPLINES_PRIORITY, CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING, CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, CORE_MUTEX_NESTING_ACQUIRES, CORE_MUTEX_NESTING_BLOCKS, CORE_MUTEX_STATUS_CEILING_VIOLATED, CORE_SEMAPHORE_DISCIPLINES_FIFO, CORE_SEMAPHORE_DISCIPLINES_PRIORITY, CORE_semaphore_Attributes::discipline, CORE_mutex_Attributes::discipline, Objects_Control::id, CORE_mutex_Attributes::lock_nesting_behavior, CORE_semaphore_Attributes::maximum_count, Semaphore_Control::mutex, Semaphore_Control::Object, CORE_mutex_Attributes::only_owner_release, CORE_mutex_Attributes::priority_ceiling, PRIORITY_MINIMUM, RTEMS_INVALID_ADDRESS, RTEMS_INVALID_NAME, RTEMS_INVALID_NUMBER, RTEMS_INVALID_PRIORITY, rtems_is_name_valid(), RTEMS_MP_NOT_CONFIGURED, RTEMS_NOT_DEFINED, RTEMS_PRIORITY, RTEMS_PRIORITY_CEILING, RTEMS_TOO_MANY, and Semaphore_Control::semaphore.

Referenced by rpcUdpCleanup(), and rtems_rfs_mutex_create().

rtems_semaphore_delete()

rtems_status_code rtems_semaphore_delete

(

rtems_id

id

)

RTEMS Delete Semaphore.

This routine implements the rtems_semaphore_delete directive. The semaphore indicated by ID is deleted.

Parameters

[in]

id

is the semaphore id

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

References _Objects_Allocator_lock(), and _Semaphore_Get().

Referenced by i2c_bus_destroy(), and rtems_rfs_mutex_destroy().

rtems_semaphore_flush()

rtems_status_code rtems_semaphore_flush

(

rtems_id

id

)

RTEMS Semaphore Flush.

This method is the implementation of the flush directive of the Semaphore Manager.

This directive allows a thread to flush the threads pending on the semaphore.

Parameters

[in]

id

is the semaphore id

Return values

RTEMS_SUCCESSFUL

if successful or error code if unsuccessful

References _Semaphore_Get().

rtems_semaphore_ident()

rtems_status_code rtems_semaphore_ident	(	rtems_name	name,
		uint32_t	node,
		rtems_id *	id
	)

RTEMS Semaphore Name to Id.

This routine implements the rtems_semaphore_ident directive. This directive returns the semaphore ID associated with name. If more than one semaphore is named name, then the semaphore to which the ID belongs is arbitrary. node indicates the extent of the search for the ID of the semaphore named name. The search can be limited to a particular node or allowed to encompass all nodes.

Parameters

[in]	name	is the user defined semaphore name
[in]	node	is(are) the node(s) to be searched
[in]	id	is the pointer to semaphore id

Return values

RTEMS_SUCCESSFUL

if successful or error code if unsuccessful and *id filled in with the semaphore id

rtems_semaphore_obtain()

rtems_status_code rtems_semaphore_obtain	(	rtems_id	id,
		rtems_option	option_set,
		rtems_interval	timeout
	)

RTEMS Obtain Semaphore.

This routine implements the rtems_semaphore_obtain directive. It attempts to obtain a unit from the semaphore associated with ID. If a unit can be allocated, the calling task will return immediately. If no unit is available, then the task may return immediately or block waiting for a unit with an optional timeout of timeout clock ticks. Whether the task blocks or returns immediately is based on the RTEMS_NO_WAIT option in the option_set.

Parameters

[in]	id	is the semaphore id
[in]	option_set	is the wait option
[in]	timeout	is the number of ticks to wait (0 means wait forever)

Return values

This	method returns RTEMS_SUCCESSFUL if there was not an error. Otherwise, a status code is returned indicating the source of the error.

Referenced by i2c_bus_obtain(), rtems_termios_device_close(), rtems_termios_device_open(), and rtems_termios_device_remove().

rtems_semaphore_release()

rtems_status_code rtems_semaphore_release

(

rtems_id

id

)

RTEMS Semaphore Release.

Semaphore Manager

This routine implements the rtems_semaphore_release directive. It frees a unit to the semaphore associated with ID. 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.

References _Semaphore_Get_interrupt_disable().

Referenced by i2c_bus_release(), and rtems_rtl_unlock().

rtems_semaphore_set_priority()

rtems_status_code rtems_semaphore_set_priority	(	rtems_id	semaphore_id,
		rtems_id	scheduler_id,
		rtems_task_priority	new_priority,
		rtems_task_priority *	old_priority
	)

Sets the priority value with respect to the specified scheduler of a semaphore.

The special priority value RTEMS_CURRENT_PRIORITY can be used to get the current priority value without changing it.

The interpretation of the priority value depends on the protocol of the semaphore object.

• The Multiprocessor Resource Sharing Protocol needs a ceiling priority per scheduler instance. This operation can be used to specify these priority values.
• For the Priority Ceiling Protocol the ceiling priority is used with this operation.
• For other protocols this operation is not defined.

Parameters

[in]	semaphore_id	Identifier of the semaphore.
[in]	scheduler_id	Identifier of the scheduler.
[in]	new_priority	The new priority value. Use RTEMS_CURRENT_PRIORITY to not set a new priority and only get the current priority.
[out]	old_priority	Reference to store the old priority value.

Return values

RTEMS_SUCCESSFUL	Successful operation.
RTEMS_INVALID_ID	Invalid semaphore or scheduler identifier.
RTEMS_INVALID_ADDRESS	The old priority reference is NULL.
RTEMS_INVALID_PRIORITY	The new priority value is invalid.
RTEMS_NOT_DEFINED	The set priority operation is not defined for the protocol of this semaphore object.
RTEMS_ILLEGAL_ON_REMOTE_OBJECT	Not supported for remote semaphores.

See also

rtems_scheduler_ident() and rtems_task_set_priority().

References _RTEMS_tasks_Priority_is_valid(), RTEMS_CURRENT_PRIORITY, RTEMS_INVALID_ADDRESS, and RTEMS_INVALID_PRIORITY.