Mutex Handler

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

Collaboration diagram for Mutex Handler:

Files
file	coremuteximpl.h
	CORE Mutex Implementation.
file	coremutex.c
	Initialize a Core Mutex.
file	coremutexflush.c
	Flush all waiting threads.
file	coremutexseize.c
	Seize Mutex with Blocking.
file	coremutexseizeintr.c
	Trylock CORE Mutex Seize Interrupt.
file	coremutexsurrender.c
	Surrender the Mutex.

Data Structures
struct	CORE_mutex_Attributes
	The control block used to manage attributes of each mutex. More...
struct	CORE_mutex_Control
	Control block used to manage each mutex. More...

Macros
#define	CORE_MUTEX_STATUS_LAST   CORE_MUTEX_STATUS_CEILING_VIOLATED
	The last status value. More...
#define	_CORE_mutex_Seize_interrupt_trylock(_mutex, _executing, _lock_context)   _CORE_mutex_Seize_interrupt_trylock_body( _mutex, _executing, _lock_context )
	The default is to favor speed and inlining this definitely saves a few instructions. More...
#define	_CORE_mutex_Check_dispatch_for_seize(_wait)
	Verifies that a mutex blocking seize is performed safely. More...
#define	_CORE_mutex_Seize(_the_mutex, _executing, _id, _wait, _timeout, _lock_context)
	This method is used to obtain a core mutex. More...

Typedefs
typedef void(*	CORE_mutex_API_mp_support_callout) (Thread_Control *, Objects_Id)
	Callout which provides to support global/multiprocessor operations. More...

Enumerations
enum	CORE_mutex_Disciplines { CORE_MUTEX_DISCIPLINES_FIFO, CORE_MUTEX_DISCIPLINES_PRIORITY, CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING }
	The blocking disciplines for a mutex. More...
enum	CORE_mutex_Nesting_behaviors { CORE_MUTEX_NESTING_ACQUIRES, CORE_MUTEX_NESTING_BLOCKS }
	The possible behaviors for lock nesting. More...
enum	CORE_mutex_Status {   CORE_MUTEX_STATUS_SUCCESSFUL, CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT, CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE, CORE_MUTEX_WAS_DELETED,   CORE_MUTEX_TIMEOUT, CORE_MUTEX_STATUS_CEILING_VIOLATED }
	The possible Mutex handler return statuses. More...

Functions
CORE_mutex_Status	_CORE_mutex_Initialize (CORE_mutex_Control *the_mutex, Thread_Control *executing, const CORE_mutex_Attributes *the_mutex_attributes, bool initially_locked)
	Initializes the mutex based on the parameters passed. More...
RTEMS_INLINE_ROUTINE void	_CORE_mutex_Destroy (CORE_mutex_Control *the_mutex)
RTEMS_INLINE_ROUTINE int	_CORE_mutex_Seize_interrupt_trylock_body (CORE_mutex_Control *the_mutex, Thread_Control *executing, ISR_lock_Context *lock_context)
	Attempt to receive a unit from the_mutex. More...
void	_CORE_mutex_Seize_interrupt_blocking (CORE_mutex_Control *the_mutex, Thread_Control *executing, Watchdog_Interval timeout, ISR_lock_Context *lock_context)
	Performs the blocking portion of a mutex obtain. More...
RTEMS_INLINE_ROUTINE void	_CORE_mutex_Seize_body (CORE_mutex_Control *the_mutex, Thread_Control *executing, Objects_Id id, bool wait, Watchdog_Interval timeout, ISR_lock_Context *lock_context)
	Attempt to obtain the mutex. More...
CORE_mutex_Status	_CORE_mutex_Surrender (CORE_mutex_Control *the_mutex, Objects_Id id, CORE_mutex_API_mp_support_callout api_mutex_mp_support, ISR_lock_Context *lock_context)
	Frees a unit to the mutex. More...
void	_CORE_mutex_Flush (CORE_mutex_Control *the_mutex, Thread_queue_Flush_callout remote_extract_callout, uint32_t status)
	Flush all waiting threads. More...
RTEMS_INLINE_ROUTINE bool	_CORE_mutex_Is_locked (const CORE_mutex_Control *the_mutex)
	Is mutex locked. More...
RTEMS_INLINE_ROUTINE bool	_CORE_mutex_Is_fifo (const CORE_mutex_Attributes *the_attribute)
	Does core mutex use FIFO blocking. More...
RTEMS_INLINE_ROUTINE bool	_CORE_mutex_Is_priority (CORE_mutex_Attributes *the_attribute)
	Doex core mutex use priority blocking. More...
RTEMS_INLINE_ROUTINE bool	_CORE_mutex_Is_inherit_priority (CORE_mutex_Attributes *the_attribute)
	Does mutex use priority inheritance. More...
RTEMS_INLINE_ROUTINE bool	_CORE_mutex_Is_priority_ceiling (CORE_mutex_Attributes *the_attribute)
	Does mutex use priority ceiling. More...

Detailed Description

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

Macro Definition Documentation

_CORE_mutex_Check_dispatch_for_seize

#define _CORE_mutex_Check_dispatch_for_seize

(

_wait

)

Value:

(!_Thread_Dispatch_is_enabled() \
    && (_wait) \
    && (_System_state_Get() >= SYSTEM_STATE_UP))

Verifies that a mutex blocking seize is performed safely.

This macro is to verify that a mutex blocking seize is performed from a safe system state. For example, one cannot block inside an isr.

Return values

this	method returns true if dispatch is in an unsafe state.

_CORE_mutex_Seize

#define _CORE_mutex_Seize	(		_the_mutex,
			_executing,
			_id,
			_wait,
			_timeout,
			_lock_context
	)

Value:

_CORE_mutex_Seize_body( \
         _the_mutex, _executing, _id, _wait, _timeout, _lock_context )

This method is used to obtain a core mutex.

Parameters

[in]	_the_mutex	is the mutex to attempt to lock
[in]	_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

_CORE_mutex_Seize_interrupt_trylock

#define _CORE_mutex_Seize_interrupt_trylock	(		_mutex,
			_executing,
			_lock_context
	)		_CORE_mutex_Seize_interrupt_trylock_body( _mutex, _executing, _lock_context )

The default is to favor speed and inlining this definitely saves a few instructions.

This is very important for mutex performance.

Parameters

[in]	_mutex	will attempt to lock
[in]	_executing	points to the executing thread
[in]	_lock_context	is the interrupt level

CORE_MUTEX_STATUS_LAST

#define CORE_MUTEX_STATUS_LAST   CORE_MUTEX_STATUS_CEILING_VIOLATED

The last status value.

This is the last status value.

Referenced by _POSIX_Mutex_Translate_core_mutex_return_code().

Typedef Documentation

CORE_mutex_API_mp_support_callout

typedef void( * CORE_mutex_API_mp_support_callout) (Thread_Control *, Objects_Id)

Callout which provides to support global/multiprocessor operations.

The following type defines the callout which the API provides to support global/multiprocessor operations on mutexes.

Enumeration Type Documentation

CORE_mutex_Disciplines

enum CORE_mutex_Disciplines

The blocking disciplines for a mutex.

This enumerated type defines the blocking disciplines for a mutex.

Enumerator
CORE_MUTEX_DISCIPLINES_FIFO	This specifies that threads will wait for the mutex in FIFO order.
CORE_MUTEX_DISCIPLINES_PRIORITY	This specifies that threads will wait for the mutex in priority order.
CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT	This specifies that threads will wait for the mutex in priority order. Additionally, the Priority Inheritance Protocol will be in effect.
CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING	This specifies that threads will wait for the mutex in priority order. Additionally, the Priority Ceiling Protocol will be in effect.

CORE_mutex_Nesting_behaviors

enum CORE_mutex_Nesting_behaviors

The possible behaviors for lock nesting.

This enumerated type defines the possible behaviors for lock nesting.

Enumerator
CORE_MUTEX_NESTING_ACQUIRES	This sequence has no blocking or errors: lock(m) lock(m) unlock(m) unlock(m)
CORE_MUTEX_NESTING_BLOCKS	This sequence performs as indicated: lock(m) lock(m) - deadlocks or timeouts unlock(m) - releases

CORE_mutex_Status

enum CORE_mutex_Status

The possible Mutex handler return statuses.

This enumerated type defines the possible Mutex handler return statuses.

Enumerator
CORE_MUTEX_STATUS_SUCCESSFUL	This status indicates that the operation completed successfully.
CORE_MUTEX_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_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE	This status indicates that an attempt was made to release a mutex by a thread other than the thread which locked it.
CORE_MUTEX_WAS_DELETED	This status indicates that the thread was blocked waiting for an operation to complete and the mutex was deleted.
CORE_MUTEX_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_MUTEX_STATUS_CEILING_VIOLATED	This status indicates that a thread of logically greater importance than the ceiling priority attempted to lock this mutex.

Function Documentation

_CORE_mutex_Flush()

void _CORE_mutex_Flush	(	CORE_mutex_Control *	the_mutex,
		Thread_queue_Flush_callout	remote_extract_callout,
		uint32_t	status
	)

Flush all waiting threads.

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

Parameters

[in]	the_mutex	is the mutex to flush
[in]	remote_extract_callout	is the routine to invoke when a remote thread is extracted
[in]	status	is the status value which each unblocked thread will return to its caller.

_CORE_mutex_Initialize()

CORE_mutex_Status _CORE_mutex_Initialize	(	CORE_mutex_Control *	the_mutex,
		Thread_Control *	executing,
		const CORE_mutex_Attributes *	the_mutex_attributes,
		bool	initially_locked
	)

Initializes the mutex based on the parameters passed.

This routine initializes the mutex based on the parameters passed.

Parameters

[in,out]	the_mutex	is the mutex to initalize
[in,out]	executing	The currently executing thread.
[in]	the_mutex_attributes	is the attributes associated with this mutex instance
[in]	initially_locked	If true, then the mutex is initially locked by the executing thread.

Return values

This	method returns CORE_MUTEX_STATUS_SUCCESSFUL if successful.

References _Chain_Prepend_unprotected(), _CORE_mutex_Is_fifo(), _CORE_mutex_Is_inherit_priority(), _CORE_mutex_Is_priority_ceiling(), _Thread_Dispatch_disable(), _Thread_Dispatch_enable(), _Thread_queue_Initialize(), _Thread_Raise_priority(), CORE_mutex_Control::Attributes, CORE_MUTEX_STATUS_CEILING_VIOLATED, Thread_Control::current_priority, CORE_mutex_Control::holder, CORE_mutex_Control::nest_count, CORE_mutex_Attributes::priority_ceiling, Thread_Control::resource_count, and CORE_mutex_Control::Wait_queue.

Referenced by _API_Mutex_Allocate(), and rtems_semaphore_create().

_CORE_mutex_Is_fifo()

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_fifo

(

const CORE_mutex_Attributes *

the_attribute

)

Does core mutex use FIFO blocking.

This routine returns true if the mutex's wait discipline is FIFO and false otherwise.

Parameters

[in]

the_attribute

is the attribute set of the mutex.

Return values

true	The mutex is using FIFO blocking order.
false	The mutex is not using FIFO blocking order.

References CORE_MUTEX_DISCIPLINES_FIFO, and CORE_mutex_Attributes::discipline.

Referenced by _CORE_mutex_Initialize().

_CORE_mutex_Is_inherit_priority()

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_inherit_priority

(

CORE_mutex_Attributes *

the_attribute

)

Does mutex use priority inheritance.

This routine returns true if the mutex's wait discipline is INHERIT_PRIORITY and false otherwise.

Parameters

[in]

the_attribute

is the attribute set of the mutex.

Return values

true	The mutex is using priority inheritance.
false	The mutex is not using priority inheritance.

References CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, and CORE_mutex_Attributes::discipline.

Referenced by _CORE_mutex_Initialize(), and _CORE_mutex_Seize_interrupt_trylock_body().

_CORE_mutex_Is_locked()

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_locked

(

const CORE_mutex_Control *

the_mutex

)

Is mutex locked.

This routine returns true if the mutex specified is locked and false otherwise.

Parameters

[in]

the_mutex

is the mutex to check.

Return values

true	The mutex is locked.
false	The mutex is not locked.

References CORE_mutex_Control::holder.

Referenced by _CORE_mutex_Seize_interrupt_trylock_body().

_CORE_mutex_Is_priority()

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_priority

(

CORE_mutex_Attributes *

the_attribute

)

Doex core mutex use priority blocking.

This routine returns true if the mutex's wait discipline is PRIORITY and false otherwise.

Parameters

[in]

the_attribute

is the attribute set of the mutex.

Return values

true	The mutex is using priority blocking order.
false	The mutex is not using priority blocking order.

References CORE_MUTEX_DISCIPLINES_PRIORITY, and CORE_mutex_Attributes::discipline.

_CORE_mutex_Is_priority_ceiling()

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_priority_ceiling

(

CORE_mutex_Attributes *

the_attribute

)

Does mutex use priority ceiling.

This routine returns true if the mutex's wait discipline is PRIORITY_CEILING and false otherwise.

Parameters

[in]

the_attribute

is the attribute set of the mutex.

Return values

true	The mutex is using priority ceiling.
false	The mutex is not using priority ceiling.

References CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING, and CORE_mutex_Attributes::discipline.

Referenced by _CORE_mutex_Initialize(), and _CORE_mutex_Seize_interrupt_trylock_body().

_CORE_mutex_Seize_body()

RTEMS_INLINE_ROUTINE void _CORE_mutex_Seize_body	(	CORE_mutex_Control *	the_mutex,
		Thread_Control *	executing,
		Objects_Id	id,
		bool	wait,
		Watchdog_Interval	timeout,
		ISR_lock_Context *	lock_context
	)

Attempt to obtain the mutex.

This routine attempts to obtain the mutex. If the mutex is available, then it will return immediately. Otherwise, it will invoke the support routine _Core_mutex_Seize_interrupt_blocking.

Parameters

[in]	the_mutex	is the mutex to attempt to lock
[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

If the mutex is called from an interrupt service routine, with context switching disabled, or before multitasking, then a fatal error is generated.

The logic on this routine is as follows:

• If incorrect system state return an error
• If mutex is available without any contention or blocking obtain it with interrupts disabled and returned
• If the caller is willing to wait then they are blocked.

_CORE_mutex_Seize_interrupt_blocking()

void _CORE_mutex_Seize_interrupt_blocking	(	CORE_mutex_Control *	the_mutex,
		Thread_Control *	executing,
		Watchdog_Interval	timeout,
		ISR_lock_Context *	lock_context
	)

Performs the blocking portion of a mutex obtain.

This routine performs the blocking portion of a mutex obtain. It is an actual subroutine and is not implemented as something that may be inlined.

Parameters

[in,out]	the_mutex	is the mutex to attempt to lock
[in,out]	executing	The currently executing thread.
[in]	timeout	is the maximum number of ticks to block
[in]	lock_context	is the interrupt level

_CORE_mutex_Seize_interrupt_trylock_body()

RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body	(	CORE_mutex_Control *	the_mutex,
		Thread_Control *	executing,
		ISR_lock_Context *	lock_context
	)

Attempt to receive a unit from the_mutex.

This routine attempts to receive a unit from the_mutex. 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,out]	executing	The currently executing thread.
[in,out]	the_mutex	is the mutex to attempt to lock
[in]	lock_context	is the interrupt level

Return values

This	routine returns 0 if "trylock" can resolve whether or not the mutex is immediately obtained or there was an error attempting to get it. It returns 1 to indicate that the caller cannot obtain the mutex and will have to block to do so.

Note

For performance reasons, this routine is implemented as a macro that uses two support routines.

References _Chain_Prepend_unprotected(), _CORE_mutex_Is_inherit_priority(), _CORE_mutex_Is_locked(), _CORE_mutex_Is_priority_ceiling(), CORE_mutex_Control::Attributes, CORE_MUTEX_STATUS_SUCCESSFUL, Thread_Control::current_priority, CORE_mutex_Control::holder, CORE_mutex_Control::nest_count, Thread_Control::resource_count, Thread_Wait_information::return_code, and Thread_Control::Wait.

_CORE_mutex_Surrender()

CORE_mutex_Status _CORE_mutex_Surrender	(	CORE_mutex_Control *	the_mutex,
		Objects_Id	id,
		CORE_mutex_API_mp_support_callout	api_mutex_mp_support,
		ISR_lock_Context *	lock_context
	)

Frees a unit to the mutex.

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

Parameters

[in]	the_mutex	is the mutex to surrender
[in]	id	is the id of the RTEMS Object associated with this mutex
[in]	api_mutex_mp_support	is the routine that will be called when unblocking a remote mutex
[in]	lock_context	is the interrupt level

Return values

an	indication of whether the routine succeeded or failed

References _ISR_lock_ISR_enable, _Thread_Is_executing(), CORE_mutex_Control::Attributes, CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE, CORE_mutex_Control::holder, and CORE_mutex_Attributes::only_owner_release.

Referenced by _API_Mutex_Unlock().