/** * @file * * @ingroup ScoreMutex * * @brief CORE Mutex Implementation */ /* * COPYRIGHT (c) 1989-2009. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.org/license/LICENSE. */ #ifndef _RTEMS_SCORE_COREMUTEXIMPL_H #define _RTEMS_SCORE_COREMUTEXIMPL_H #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * @addtogroup ScoreMutex */ /**@{**/ /** * @brief 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. */ typedef void ( *CORE_mutex_API_mp_support_callout )( Thread_Control *, Objects_Id ); /** * @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 Initializes the mutex based on the parameters passed. * * This routine initializes the mutex based on the parameters passed. * * @param[in,out] the_mutex is the mutex to initalize * @param[in,out] executing The currently executing thread. * @param[in] the_mutex_attributes is the attributes associated with this * mutex instance * @param[in] initially_locked If true, then the mutex is initially locked by * the executing thread. * * @retval This method returns CORE_MUTEX_STATUS_SUCCESSFUL if successful. */ CORE_mutex_Status _CORE_mutex_Initialize( CORE_mutex_Control *the_mutex, Thread_Control *executing, const CORE_mutex_Attributes *the_mutex_attributes, bool initially_locked ); RTEMS_INLINE_ROUTINE void _CORE_mutex_Destroy( CORE_mutex_Control *the_mutex ) { _Thread_queue_Destroy( &the_mutex->Wait_queue ); } /** * @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,out] executing The currently executing thread. * @param[in,out] the_mutex is the mutex to attempt to lock * @param[in] lock_context 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, Thread_Control *executing, ISR_lock_Context *lock_context ); #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] _executing points to the executing thread * @param[in] level_p is the interrupt level */ int _CORE_mutex_Seize_interrupt_trylock( CORE_mutex_Control *the_mutex, Thread_Control *executing, ISR_lock_Context *lock_context ); #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] _executing points to the executing thread * @param[in] _lock_context is the interrupt level */ #define _CORE_mutex_Seize_interrupt_trylock( _mutex, _executing, _lock_context ) \ _CORE_mutex_Seize_interrupt_trylock_body( _mutex, _executing, _lock_context ) #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,out] the_mutex is the mutex to attempt to lock * @param[in,out] executing The currently executing thread. * @param[in] timeout is the maximum number of ticks to block * @param[in] lock_context is the interrupt level */ void _CORE_mutex_Seize_interrupt_blocking( CORE_mutex_Control *the_mutex, Thread_Control *executing, Watchdog_Interval timeout, ISR_lock_Context *lock_context ); /** * @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. */ #define _CORE_mutex_Check_dispatch_for_seize(_wait) \ (!_Thread_Dispatch_is_enabled() \ && (_wait) \ && (_System_state_Get() >= SYSTEM_STATE_UP)) /** * @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] 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. */ 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 ) { if ( _CORE_mutex_Check_dispatch_for_seize( wait ) ) { _Terminate( INTERNAL_ERROR_CORE, false, INTERNAL_ERROR_MUTEX_OBTAIN_FROM_BAD_STATE ); } _Thread_queue_Acquire_critical( &the_mutex->Wait_queue, lock_context ); if ( _CORE_mutex_Seize_interrupt_trylock( the_mutex, executing, lock_context ) ) { if ( !wait ) { _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); executing->Wait.return_code = CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT; } else { executing->Wait.id = id; _CORE_mutex_Seize_interrupt_blocking( the_mutex, executing, timeout, lock_context ); } } } /** * This method is used to obtain a core mutex. * * @param[in] _the_mutex is the mutex to attempt to lock * @param[in] _executing The currently executing thread. * @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] _lock_context 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, Thread_Control *_executing, Objects_Id _id, bool _wait, Watchdog_Interval _timeout, ISR_lock_Context *_lock_context ); #else #define _CORE_mutex_Seize( \ _the_mutex, _executing, _id, _wait, _timeout, _lock_context ) \ _CORE_mutex_Seize_body( \ _the_mutex, _executing, _id, _wait, _timeout, _lock_context ) #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 * @param[in] lock_context is the interrupt level * * @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, ISR_lock_Context *lock_context ); /** * @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 ); /** * @brief Is mutex locked. * * This routine returns true if the mutex specified is locked and false * otherwise. * * @param[in] the_mutex is the mutex to check. * * @retval true The mutex is locked. * @retval false The mutex is not locked. */ RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_locked( const CORE_mutex_Control *the_mutex ) { return the_mutex->holder != NULL; } /** * @brief Does core mutex use FIFO blocking. * * This routine returns true if the mutex's wait discipline is FIFO and false * otherwise. * * @param[in] the_attribute is the attribute set of the mutex. * * @retval true The mutex is using FIFO blocking order. * @retval false The mutex is not using FIFO blocking order. */ RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_fifo( const CORE_mutex_Attributes *the_attribute ) { return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_FIFO; } /** * @brief Doex core mutex use priority blocking. * * This routine returns true if the mutex's wait discipline is PRIORITY and * false otherwise. * * @param[in] the_attribute is the attribute set of the mutex. * * @retval true The mutex is using priority blocking order. * @retval false The mutex is not using priority blocking order. * */ RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_priority( CORE_mutex_Attributes *the_attribute ) { return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY; } /** * @brief Does mutex use priority inheritance. * * This routine returns true if the mutex's wait discipline is * INHERIT_PRIORITY and false otherwise. * * @param[in] the_attribute is the attribute set of the mutex. * * @retval true The mutex is using priority inheritance. * @retval false The mutex is not using priority inheritance. */ RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_inherit_priority( CORE_mutex_Attributes *the_attribute ) { return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT; } /** * @brief Does mutex use priority ceiling. * * This routine returns true if the mutex's wait discipline is * PRIORITY_CEILING and false otherwise. * * @param[in] the_attribute is the attribute set of the mutex. * * @retval true The mutex is using priority ceiling. * @retval false The mutex is not using priority ceiling. */ RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_priority_ceiling( CORE_mutex_Attributes *the_attribute ) { return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING; } /* * Seize Mutex with Quick Success Path * * NOTE: There is no MACRO version of this routine. A body is in * coremutexseize.c that is duplicated from the .inl by hand. * * NOTE: The Doxygen for this routine is in the .h file. */ RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body( CORE_mutex_Control *the_mutex, Thread_Control *executing, ISR_lock_Context *lock_context ) { /* disabled when you get here */ executing->Wait.return_code = CORE_MUTEX_STATUS_SUCCESSFUL; if ( !_CORE_mutex_Is_locked( the_mutex ) ) { the_mutex->holder = executing; the_mutex->nest_count = 1; if ( _CORE_mutex_Is_inherit_priority( &the_mutex->Attributes ) || _CORE_mutex_Is_priority_ceiling( &the_mutex->Attributes ) ){ #ifdef __RTEMS_STRICT_ORDER_MUTEX__ _Chain_Prepend_unprotected( &executing->lock_mutex, &the_mutex->queue.lock_queue ); the_mutex->queue.priority_before = executing->current_priority; #endif executing->resource_count++; } if ( !_CORE_mutex_Is_priority_ceiling( &the_mutex->Attributes ) ) { _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); return 0; } /* else must be CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING * * we possibly bump the priority of the current holder -- which * happens to be _Thread_Executing. */ { Priority_Control ceiling; Priority_Control current; ceiling = the_mutex->Attributes.priority_ceiling; current = executing->current_priority; if ( current == ceiling ) { _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); return 0; } if ( current > ceiling ) { Per_CPU_Control *cpu_self; cpu_self = _Thread_Dispatch_disable_critical(); _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); _Thread_Change_priority( executing, ceiling, false ); _Thread_Dispatch_enable( cpu_self ); return 0; } /* if ( current < ceiling ) */ { executing->Wait.return_code = CORE_MUTEX_STATUS_CEILING_VIOLATED; the_mutex->holder = NULL; the_mutex->nest_count = 0; /* undo locking above */ executing->resource_count--; /* undo locking above */ _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); return 0; } } return 0; } /* * At this point, we know the mutex was not available. If this thread * is the thread that has locked the mutex, let's see if we are allowed * to nest access. */ if ( _Thread_Is_executing( the_mutex->holder ) ) { switch ( the_mutex->Attributes.lock_nesting_behavior ) { case CORE_MUTEX_NESTING_ACQUIRES: the_mutex->nest_count++; _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); return 0; #if defined(RTEMS_POSIX_API) case CORE_MUTEX_NESTING_IS_ERROR: executing->Wait.return_code = CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED; _Thread_queue_Release( &the_mutex->Wait_queue, lock_context ); return 0; #endif case CORE_MUTEX_NESTING_BLOCKS: break; } } /* * The mutex is not available and the caller must deal with the possibility * of blocking. */ return 1; } /** @} */ #ifdef __cplusplus } #endif #endif /* end of include file */