Mutex Handler


Data Structures
struct	CORE_mutex_Attributes
	Core Mutex Attributes. More...
struct	CORE_mutex_Control
	Core Mutex Control Structure. More...
Defines
#define	CORE_MUTEX_STATUS_LAST CORE_MUTEX_STATUS_CEILING_VIOLATED
	Core Mutex Last Status.
#define	CORE_MUTEX_UNLOCKED 1
#define	CORE_MUTEX_LOCKED 0
#define	_CORE_mutex_Seize_interrupt_trylock(_mutex, _level_p) _CORE_mutex_Seize_interrupt_trylock_body( _mutex, _level_p )
#define	_CORE_mutex_Seize_body(_the_mutex, _id, _wait, _timeout, _level)
	Sieze Interrupt Wrapper.
#define	_CORE_mutex_Seize(_the_mutex, _id, _wait, _timeout, _level) _CORE_mutex_Seize_body( _the_mutex, _id, _wait, _timeout, _level )
Typedefs
typedef void(*	CORE_mutex_API_mp_support_callout )(Thread_Control *, Objects_Id)
	MP Support Callback Prototype.
Enumerations
enum	CORE_mutex_Disciplines { CORE_MUTEX_DISCIPLINES_FIFO, CORE_MUTEX_DISCIPLINES_PRIORITY, CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING }
	Blocking Disciplines Enumerated Type. More...
enum	CORE_mutex_Status { CORE_MUTEX_STATUS_SUCCESSFUL, CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT, CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED, CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE, CORE_MUTEX_WAS_DELETED, CORE_MUTEX_TIMEOUT, CORE_MUTEX_STATUS_CEILING_VIOLATED }
	Mutex method return statuses. More...
enum	CORE_mutex_Nesting_behaviors { CORE_MUTEX_NESTING_ACQUIRES, CORE_MUTEX_NESTING_IS_ERROR, CORE_MUTEX_NESTING_BLOCKS }
	Mutex Lock Nesting Behavior Enumeration. More...
Functions
void	_CORE_mutex_Initialize (CORE_mutex_Control the_mutex, CORE_mutex_Attributes the_mutex_attributes, uint32_t initial_lock)
	Initialize a Core Mutex.
RTEMS_INLINE_ROUTINE int	_CORE_mutex_Seize_interrupt_trylock_body (CORE_mutex_Control the_mutex, ISR_Level level_p)
	Seize Mutex with Quick Success Path.
void	_CORE_mutex_Seize_interrupt_blocking (CORE_mutex_Control *the_mutex, Watchdog_Interval timeout)
	Seize Mutex with Blocking.
CORE_mutex_Status	_CORE_mutex_Surrender (CORE_mutex_Control *the_mutex, Objects_Id id, CORE_mutex_API_mp_support_callout api_mutex_mp_support)
	Surrender the Mutex.
void	_CORE_mutex_Flush (CORE_mutex_Control *the_mutex, Thread_queue_Flush_callout remote_extract_callout, uint32_t status)
	Flush all waiting threads.
RTEMS_INLINE_ROUTINE boolean	_CORE_mutex_Is_locked (CORE_mutex_Control *the_mutex)
	Is Mutex Locked.
RTEMS_INLINE_ROUTINE boolean	_CORE_mutex_Is_fifo (CORE_mutex_Attributes *the_attribute)
	Does Core Mutex Use FIFO Blocking.
RTEMS_INLINE_ROUTINE boolean	_CORE_mutex_Is_priority (CORE_mutex_Attributes *the_attribute)
	Doex Core Mutex Use Priority Blocking.
RTEMS_INLINE_ROUTINE boolean	_CORE_mutex_Is_inherit_priority (CORE_mutex_Attributes *the_attribute)
	Does Mutex Use Priority Inheritance.
RTEMS_INLINE_ROUTINE boolean	_CORE_mutex_Is_priority_ceiling (CORE_mutex_Attributes *the_attribute)
	Does Mutex Use Priority Ceiling.

Detailed Description

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

Define Documentation

#define _CORE_mutex_Seize	(	_the_mutex,
		_id,
		_wait,
		_timeout,
		_level	)	_CORE_mutex_Seize_body( _the_mutex, _id, _wait, _timeout, _level )

This method is used to obtain a core mutex.

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]`	_level	is a temporary variable used to contain the ISR disable level cookie

#define _CORE_mutex_Seize_body	(	_the_mutex,
		_id,
		_wait,
		_timeout,
		_level	)

Value:

do { \
    if ( _Thread_Dispatch_disable_level \
        && (_wait) \
        && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
       ) { \
        _Internal_error_Occurred( \
           INTERNAL_ERROR_CORE, \
           FALSE, \
           INTERNAL_ERROR_MUTEX_OBTAIN_FROM_BAD_STATE \
           ); \
    } \
    if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
      if ( !_wait ) { \
        _ISR_Enable( _level ); \
        _Thread_Executing->Wait.return_code = \
          CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT; \
      } else { \
        _Thread_queue_Enter_critical_section( &(_the_mutex)->Wait_queue ); \
        _Thread_Executing->Wait.queue = &(_the_mutex)->Wait_queue; \
        _Thread_Executing->Wait.id    = _id; \
        _Thread_Disable_dispatch(); \
        _ISR_Enable( _level ); \
       _CORE_mutex_Seize_interrupt_blocking( _the_mutex, _timeout ); \
      } \
    } \
  } while (0)

Sieze Interrupt Wrapper.

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]`	_level	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.

#define _CORE_mutex_Seize_interrupt_trylock	(	_mutex,
		_level_p		)	_CORE_mutex_Seize_interrupt_trylock_body( _mutex, _level_p )

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]`	_level_p	is the interrupt level holder

#define CORE_MUTEX_LOCKED 0

This is the value of a mutex when it is locked.

Referenced by _CORE_mutex_Is_locked(), and _CORE_mutex_Seize_interrupt_trylock_body().

#define CORE_MUTEX_STATUS_LAST CORE_MUTEX_STATUS_CEILING_VIOLATED

Core Mutex Last Status.

This is the last status value.

#define CORE_MUTEX_UNLOCKED 1

This is the value of a mutex when it is unlocked.

Typedef Documentation

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

MP Support Callback Prototype.

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

Enumeration Type Documentation

enum CORE_mutex_Disciplines

Blocking Disciplines Enumerated Type.

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.

enum CORE_mutex_Nesting_behaviors

Mutex Lock Nesting Behavior Enumeration.

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_IS_ERROR	This sequence returns an error at the indicated point: + lock(m) + lock(m) - already locked error + unlock(m)
CORE_MUTEX_NESTING_BLOCKS	This sequence performs as indicated: + lock(m) + lock(m) - deadlocks or timeouts + unlock(m) - releases

enum CORE_mutex_Status

Mutex method 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_NESTING_NOT_ALLOWED	This status indicates that an attempt was made to relock a mutex for which nesting is not configured.
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

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.

void _CORE_mutex_Initialize	(	CORE_mutex_Control *	the_mutex,
		CORE_mutex_Attributes *	the_mutex_attributes,
		uint32_t	initial_lock
	)

Initialize a Core Mutex.

This routine initializes the mutex based on the parameters passed.

Parameters:

`[in]`	the_mutex	is the mutex to initalize
`[in]`	the_mutex_attributes	is the attributes associated with this mutex instance
`[in]`	initial_lock	is the initial value of the mutex

RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_fifo ( 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

Returns:: This method returns TRUE if the mutex is using FIFO blocking order.

References CORE_MUTEX_DISCIPLINES_FIFO, and CORE_mutex_Attributes::discipline.

RTEMS_INLINE_ROUTINE boolean _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

Returns:: This method returns TRUE if the mutex is using priority inheritance.

References CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, and CORE_mutex_Attributes::discipline.

Referenced by _CORE_mutex_Seize_interrupt_trylock_body().

RTEMS_INLINE_ROUTINE boolean _CORE_mutex_Is_locked ( 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

Returns:: This method returns TRUE if the mutex is locked.

References CORE_MUTEX_LOCKED, and CORE_mutex_Control::lock.

Referenced by _CORE_mutex_Seize_interrupt_trylock_body().

RTEMS_INLINE_ROUTINE boolean _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

Returns:: This method returns TRUE if the mutex is using priority blocking order.

References CORE_MUTEX_DISCIPLINES_PRIORITY, and CORE_mutex_Attributes::discipline.

RTEMS_INLINE_ROUTINE boolean _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

Returns:: This method returns TRUE if the mutex is using priority ceiling.

References CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING, and CORE_mutex_Attributes::discipline.

Referenced by _CORE_mutex_Seize_interrupt_trylock_body().

void _CORE_mutex_Seize_interrupt_blocking	(	CORE_mutex_Control *	the_mutex,
		Watchdog_Interval	timeout
	)

Seize Mutex with Blocking.

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]`	the_mutex	is the mutex to attempt to lock
`[in]`	timeout	is the maximum number of ticks to block

RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body	(	CORE_mutex_Control *	the_mutex,
		ISR_Level *	level_p
	)

Seize Mutex with Quick Success Path.

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]`	the_mutex	is the mutex to attempt to lock
`[in]`	level_p	is the interrupt level holder

Returns:: 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(), _ISR_Enable, _Thread_Change_priority(), _Thread_Disable_dispatch(), _Thread_Enable_dispatch(), _Thread_Executing, _Thread_Is_executing(), CORE_mutex_Control::Attributes, CORE_MUTEX_LOCKED, CORE_MUTEX_NESTING_ACQUIRES, CORE_MUTEX_NESTING_BLOCKS, CORE_MUTEX_NESTING_IS_ERROR, CORE_MUTEX_STATUS_CEILING_VIOLATED, CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED, CORE_MUTEX_STATUS_SUCCESSFUL, Thread_Control_struct::current_priority, CORE_mutex_Control::holder, CORE_mutex_Control::holder_id, Objects_Control::id, CORE_mutex_Control::lock, CORE_mutex_Attributes::lock_nesting_behavior, CORE_mutex_Control::nest_count, Thread_Control_struct::Object, CORE_mutex_Attributes::priority_ceiling, Thread_Control_struct::resource_count, Thread_Wait_information::return_code, and Thread_Control_struct::Wait.

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

Surrender 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

Returns:: an indication of whether the routine succeeded or failed

Mutex Handler

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation