diff options
Diffstat (limited to 'cpukit/score/include/rtems/score/coremutex.h')
-rw-r--r-- | cpukit/score/include/rtems/score/coremutex.h | 329 |
1 files changed, 17 insertions, 312 deletions
diff --git a/cpukit/score/include/rtems/score/coremutex.h b/cpukit/score/include/rtems/score/coremutex.h index f6c377c2a0..bf0ac1efac 100644 --- a/cpukit/score/include/rtems/score/coremutex.h +++ b/cpukit/score/include/rtems/score/coremutex.h @@ -1,12 +1,12 @@ /** - * @file rtems/score/coremutex.h + * @file * - * @brief Constants and Structures Associated with the Mutex Handler + * @brief CORE Mutex API * - * This include file contains all the constants and structures associated - * with the Mutex Handler. A mutex is an enhanced version of the standard - * Dijkstra binary semaphore used to provide synchronization and mutual - * exclusion capabilities. + * This include file contains all the constants and structures associated with + * the Mutex Handler. A mutex is an enhanced version of the standard Dijkstra + * binary semaphore used to provide synchronization and mutual exclusion + * capabilities. */ /* @@ -20,19 +20,6 @@ #ifndef _RTEMS_SCORE_COREMUTEX_H #define _RTEMS_SCORE_COREMUTEX_H -/** - * @defgroup ScoreMutex Mutex Handler - * - * @ingroup Score - * - * This handler encapsulates functionality which provides the foundation - * Mutex services used in all of the APIs supported by RTEMS. - */ -/**@{*/ - -#ifdef __cplusplus -extern "C" { -#endif #include <rtems/score/thread.h> #include <rtems/score/threadq.h> @@ -41,16 +28,19 @@ extern "C" { #include <rtems/score/interr.h> #include <rtems/score/sysstate.h> +#ifdef __cplusplus +extern "C" { +#endif + /** - * @brief Callout which provides to support global/multiprocessor operations. + * @defgroup ScoreMutex Mutex Handler * - * The following type defines the callout which the API provides - * to support global/multiprocessor operations on mutexes. + * @ingroup Score + * + * This handler encapsulates functionality which provides the foundation + * Mutex services used in all of the APIs supported by RTEMS. */ -typedef void ( *CORE_mutex_API_mp_support_callout )( - Thread_Control *, - Objects_Id - ); +/**@{*/ /** * @brief The blocking disciplines for a mutex. @@ -73,60 +63,6 @@ typedef enum { } CORE_mutex_Disciplines; /** - * @brief The possible Mutex handler return statuses. - * - * This enumerated type defines the possible Mutex handler return statuses. - */ -typedef enum { - /** This status indicates that the operation completed successfully. */ - CORE_MUTEX_STATUS_SUCCESSFUL, - /** 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_UNSATISFIED_NOWAIT, -#if defined(RTEMS_POSIX_API) - /** This status indicates that an attempt was made to relock a mutex - * for which nesting is not configured. - */ - CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED, -#endif - /** This status indicates that an attempt was made to release a mutex - * by a thread other than the thread which locked it. - */ - CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE, - /** This status indicates that the thread was blocked waiting for an - * operation to complete and the mutex was deleted. - */ - CORE_MUTEX_WAS_DELETED, - /** 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_TIMEOUT, - -#if defined(__RTEMS_STRICT_ORDER_MUTEX__) - /** This status indicates that a thread not release the mutex which has - * the priority inheritance property in a right order. - */ - CORE_MUTEX_RELEASE_NOT_ORDER, -#endif - - /** This status indicates that a thread of logically greater importance - * than the ceiling priority attempted to lock this mutex. - */ - CORE_MUTEX_STATUS_CEILING_VIOLATED - -} CORE_mutex_Status; - -/** - * @brief The last status value. - * - * This is the last status value. - */ -#define CORE_MUTEX_STATUS_LAST CORE_MUTEX_STATUS_CEILING_VIOLATED - -/** * @brief The possible behaviors for lock nesting. * * This enumerated type defines the possible behaviors for @@ -162,16 +98,6 @@ typedef enum { } CORE_mutex_Nesting_behaviors; /** - * This is the value of a mutex when it is unlocked. - */ -#define CORE_MUTEX_UNLOCKED 1 - -/** - * This is the value of a mutex when it is locked. - */ -#define CORE_MUTEX_LOCKED 0 - -/** * @brief The control block used to manage attributes of each mutex. * * The following defines the control block used to manage the @@ -253,232 +179,11 @@ typedef struct { } CORE_mutex_Control; -/** - * @brief Initializes the mutex based on the parameters passed. - * - * This routine initializes the mutex based on the parameters passed. - * - * @param[in] the_mutex is the mutex to initalize - * @param[in] the_mutex_attributes is the attributes associated with this - * mutex instance - * @param[in] initial_lock is the initial value of the mutex - * - * @retval This method returns CORE_MUTEX_STATUS_SUCCESSFUL if successful. - */ -CORE_mutex_Status _CORE_mutex_Initialize( - CORE_mutex_Control *the_mutex, - CORE_mutex_Attributes *the_mutex_attributes, - uint32_t initial_lock -); - -#ifndef __RTEMS_APPLICATION__ -/** - * @brief 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. - * - * @param[in] the_mutex is the mutex to attempt to lock - * @param[in] level is the interrupt level - * - * @retval 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. - */ - -RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body( - CORE_mutex_Control *the_mutex, - ISR_Level level -); - -#if defined(__RTEMS_DO_NOT_INLINE_CORE_MUTEX_SEIZE__) - /** - * @brief Interrupt trylock CORE mutex seize. - * - * When doing test coverage analysis or trying to minimize the code - * space for RTEMS, it is often helpful to not inline this method - * multiple times. It is fairly large and has a high branch complexity - * which makes it harder to get full binary test coverage. - * - * @param[in] the_mutex will attempt to lock - * @param[in] level_p is the interrupt level - */ - int _CORE_mutex_Seize_interrupt_trylock( - CORE_mutex_Control *the_mutex, - ISR_Level level - ); -#else - /** - * The default is to favor speed and inlining this definitely saves - * a few instructions. This is very important for mutex performance. - * - * @param[in] _mutex will attempt to lock - * @param[in] _level is the interrupt level - */ - #define _CORE_mutex_Seize_interrupt_trylock( _mutex, _level ) \ - _CORE_mutex_Seize_interrupt_trylock_body( _mutex, _level ) -#endif - -/** - * @brief 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. - * - * @param[in] the_mutex is the mutex to attempt to lock - * @param[in] timeout is the maximum number of ticks to block - */ -void _CORE_mutex_Seize_interrupt_blocking( - CORE_mutex_Control *the_mutex, - Watchdog_Interval timeout -); -/** - * @brief 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. - * - * @retval this method returns true if dispatch is in an unsafe state. - */ -#ifdef RTEMS_SMP - #define _CORE_mutex_Check_dispatch_for_seize(_wait) 0 -#else - #define _CORE_mutex_Check_dispatch_for_seize(_wait) \ - (!_Thread_Dispatch_is_enabled() \ - && (_wait) \ - && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING)) -#endif - -/** - * @brief 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 @a _Core_mutex_Seize_interrupt_blocking. - * - * @param[in] _the_mutex is the mutex to attempt to lock - * @param[in] _id is the Id of the owning API level Semaphore object - * @param[in] _wait is true if the thread is willing to wait - * @param[in] _timeout is the maximum number of ticks to block - * @param[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_body( \ - _the_mutex, _id, _wait, _timeout, _level ) \ - do { \ - if ( _CORE_mutex_Check_dispatch_for_seize(_wait) ) { \ - _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) - -/** - * This method is used to obtain a core mutex. - * - * @param[in] _the_mutex is the mutex to attempt to lock - * @param[in] _id is the Id of the owning API level Semaphore object - * @param[in] _wait is true if the thread is willing to wait - * @param[in] _timeout is the maximum number of ticks to block - * @param[in] _level is a temporary variable used to contain the ISR - * disable level cookie - */ -#if defined(__RTEMS_DO_NOT_INLINE_CORE_MUTEX_SEIZE__) - void _CORE_mutex_Seize( - CORE_mutex_Control *_the_mutex, - Objects_Id _id, - bool _wait, - Watchdog_Interval _timeout, - ISR_Level _level - ); -#else - #define _CORE_mutex_Seize( _the_mutex, _id, _wait, _timeout, _level ) \ - _CORE_mutex_Seize_body( _the_mutex, _id, _wait, _timeout, _level ) -#endif - -/** - * @brief 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. - * - * @param[in] the_mutex is the mutex to surrender - * @param[in] id is the id of the RTEMS Object associated with this mutex - * @param[in] api_mutex_mp_support is the routine that will be called when - * unblocking a remote mutex - * - * @retval an indication of whether the routine succeeded or failed - */ -CORE_mutex_Status _CORE_mutex_Surrender( - CORE_mutex_Control *the_mutex, - Objects_Id id, - CORE_mutex_API_mp_support_callout api_mutex_mp_support -); - -/** - * @brief Flush all waiting threads. - * - * This routine assists in the deletion of a mutex by flushing the associated - * wait queue. - * - * @param[in] the_mutex is the mutex to flush - * @param[in] remote_extract_callout is the routine to invoke when a remote - * thread is extracted - * @param[in] status is the status value which each unblocked thread will - * return to its caller. - */ -void _CORE_mutex_Flush( - CORE_mutex_Control *the_mutex, - Thread_queue_Flush_callout remote_extract_callout, - uint32_t status -); - -#include <rtems/score/coremutex.inl> -#endif +/**@}*/ #ifdef __cplusplus } #endif -/**@}*/ - #endif /* end of include file */ |