LXR 6.1/​cpukit/​include/​rtems/​score/​coremuteximpl.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:12

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSScoreMutex
  *
  * @brief This header file provides interfaces of the
  *   @ref RTEMSScoreMutex which are only used by the implementation.
  */
 
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef _RTEMS_SCORE_COREMUTEXIMPL_H
 #define _RTEMS_SCORE_COREMUTEXIMPL_H
 
 #include <rtems/score/coremutex.h>
 #include <rtems/score/chainimpl.h>
 #include <rtems/score/schedulerimpl.h>
 #include <rtems/score/status.h>
 #include <rtems/score/threadimpl.h>
 #include <rtems/score/threadqimpl.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @addtogroup RTEMSScoreMutex
  *
  * @{
  */
 
 #define CORE_MUTEX_TQ_OPERATIONS &_Thread_queue_Operations_priority
 
 #define CORE_MUTEX_TQ_PRIORITY_INHERIT_OPERATIONS \
   &_Thread_queue_Operations_priority_inherit
 
 /**
  * @brief Initializes the mutex.
  *
  * @param[out] the_mutex The mutex to initialize.
  */
 static inline void _CORE_mutex_Initialize(
   CORE_mutex_Control *the_mutex
 )
 {
   _Thread_queue_Object_initialize( &the_mutex->Wait_queue );
 }
 
 /**
  * @brief Destroys the mutex.
  *
  * @param[out] the_mutex the mutex to destroy.
  */
 static inline void _CORE_mutex_Destroy( CORE_mutex_Control *the_mutex )
 {
   _Thread_queue_Destroy( &the_mutex->Wait_queue );
 }
 
 /**
  * @brief Acquires the mutex critical.
  *
  * @param[in, out] the_mutex The mutex to acquire critical.
  * @param queue_context The queue context.
  */
 static inline void _CORE_mutex_Acquire_critical(
   CORE_mutex_Control   *the_mutex,
   Thread_queue_Context *queue_context
 )
 {
   _Thread_queue_Acquire_critical( &the_mutex->Wait_queue, queue_context );
 }
 
 /**
  * @brief Releases the mutex.
  *
  * @param[in, out] the_mutex The mutex to release.
  * @param queue_context The queue context.
  */
 static inline void _CORE_mutex_Release(
   CORE_mutex_Control   *the_mutex,
   Thread_queue_Context *queue_context
 )
 {
   _Thread_queue_Release( &the_mutex->Wait_queue, queue_context );
 }
 
 /**
  * @brief Gets the owner of the mutex.
  *
  * @param the_mutex The mutex to get the owner from.
  *
  * @return The owner of the mutex.
  */
 static inline Thread_Control *_CORE_mutex_Get_owner(
   const CORE_mutex_Control *the_mutex
 )
 {
   return the_mutex->Wait_queue.Queue.owner;
 }
 
 /**
  * @brief Checks if the mutex is locked.
  *
  * This routine returns true if the specified mutex is locked and false
  * otherwise.
  *
  * @param the_mutex The mutex to check if it is locked.
  *
  * @retval true The mutex is locked.
  * @retval false The mutex is not locked.
  */
 static inline bool _CORE_mutex_Is_locked(
   const CORE_mutex_Control *the_mutex
 )
 {
   return _CORE_mutex_Get_owner( the_mutex ) != NULL;
 }
 
 /**
  * @brief Seize the mutex slowly.
  *
  * @param[in, out] the_mutex The mutex to seize.
  * @param operations The thread queue operations.
  * @param executing The calling thread.
  * @param wait Indicates whether the calling thread is willing to wait.
  * @param queue_context The thread queue context.
  *
  * @retval _Thread_Wait_get_status The status of the executing thread.
  * @retval STATUS_UNAVAILABLE The calling thread is not willing to wait.
  */
 Status_Control _CORE_mutex_Seize_slow(
   CORE_mutex_Control            *the_mutex,
   const Thread_queue_Operations *operations,
   Thread_Control                *executing,
   bool                           wait,
   Thread_queue_Context          *queue_context
 );
 
 /**
  * @brief Sets the owner of the mutex.
  *
  * @param[out] the_mutex The mutex to set the owner from.
  * @param owner The new owner of the mutex.
  */
 static inline void _CORE_mutex_Set_owner(
   CORE_mutex_Control *the_mutex,
   Thread_Control     *owner
 )
 {
   the_mutex->Wait_queue.Queue.owner = owner;
 }
 
 /**
  * @brief Checks if the the thread is the owner of the mutex.
  *
  * @param the_mutex The mutex to check the owner of.
  * @param the_thread The thread to check if it is the owner of @a the_mutex.
  *
  * @retval true @a the_thread is the owner of @a the_mutex.
  * @retval false @a the_thread is not the owner of @a the_mutex.
  */
 static inline bool _CORE_mutex_Is_owner(
   const CORE_mutex_Control *the_mutex,
   const Thread_Control     *the_thread
 )
 {
   return _CORE_mutex_Get_owner( the_mutex ) == the_thread;
 }
 
 /**
  * @brief Initializes a recursive mutex.
  *
  * @param[out] the_mutex The recursive mutex to initialize.
  */
 static inline void _CORE_recursive_mutex_Initialize(
   CORE_recursive_mutex_Control *the_mutex
 )
 {
   _CORE_mutex_Initialize( &the_mutex->Mutex );
   the_mutex->nest_level = 0;
 }
 
 /**
  * @brief Seizes the recursive mutex nested.
  *
  * @param[out] the_mutex The recursive mutex to seize nested.
  *
  * @return STATUS_SUCCESSFUL, this method is always successful.
  */
 static inline Status_Control _CORE_recursive_mutex_Seize_nested(
   CORE_recursive_mutex_Control *the_mutex
 )
 {
   ++the_mutex->nest_level;
   return STATUS_SUCCESSFUL;
 }
 
 /**
  * @brief Seizes the recursive mutex.
  *
  * @param[in, out] the_mutex The recursive mutex to seize.
  * @param operations The thread queue operations.
  * @param[out] executing The executing thread.
  * @param wait Indicates whether the calling thread is willing to wait.
  * @param nested Returns the status of a recursive mutex.
  * @param queue_context The thread queue context.
  *
  * @retval STATUS_SUCCESSFUL The owner of the mutex was NULL, successful
  *      seizing of the mutex.
  * @retval _Thread_Wait_get_status The status of the executing thread.
  * @retval STATUS_UNAVAILABLE The calling thread is not willing to wait.
  */
 static inline Status_Control _CORE_recursive_mutex_Seize(
   CORE_recursive_mutex_Control  *the_mutex,
   const Thread_queue_Operations *operations,
   Thread_Control                *executing,
   bool                           wait,
   Status_Control              ( *nested )( CORE_recursive_mutex_Control * ),
   Thread_queue_Context          *queue_context
 )
 {
   Thread_Control *owner;
 
   _CORE_mutex_Acquire_critical( &the_mutex->Mutex, queue_context );
 
   owner = _CORE_mutex_Get_owner( &the_mutex->Mutex );
 
   if ( owner == NULL ) {
     _CORE_mutex_Set_owner( &the_mutex->Mutex, executing );
     _Thread_Resource_count_increment( executing );
     _CORE_mutex_Release( &the_mutex->Mutex, queue_context );
     return STATUS_SUCCESSFUL;
   }
 
   if ( owner == executing ) {
     Status_Control status;
 
     status = ( *nested )( the_mutex );
     _CORE_mutex_Release( &the_mutex->Mutex, queue_context );
     return status;
   }
 
   return _CORE_mutex_Seize_slow(
     &the_mutex->Mutex,
     operations,
     executing,
     wait,
     queue_context
   );
 }
 
 /**
  * @brief Surrenders the recursive mutex.
  *
  * @param[in, out] the_mutex The recursive mutex to surrender.
  * @param operations The thread queue operations.
  * @param executing The executing thread.
  * @param queue_context the thread queue context.
  *
  * @retval STATUS_SUCCESSFUL @a the_mutex is successfully surrendered.
  * @retval STATUS_NOT_OWNER The executing thread does not own @a the_mutex.
  */
 static inline Status_Control _CORE_recursive_mutex_Surrender(
   CORE_recursive_mutex_Control  *the_mutex,
   const Thread_queue_Operations *operations,
   Thread_Control                *executing,
   Thread_queue_Context          *queue_context
 )
 {
   unsigned int        nest_level;
   Thread_queue_Heads *heads;
 
   _CORE_mutex_Acquire_critical( &the_mutex->Mutex, queue_context );
 
   if ( !_CORE_mutex_Is_owner( &the_mutex->Mutex, executing ) ) {
     _CORE_mutex_Release( &the_mutex->Mutex, queue_context );
     return STATUS_NOT_OWNER;
   }
 
   nest_level = the_mutex->nest_level;
 
   if ( nest_level > 0 ) {
     the_mutex->nest_level = nest_level - 1;
     _CORE_mutex_Release( &the_mutex->Mutex, queue_context );
     return STATUS_SUCCESSFUL;
   }
 
   _Thread_Resource_count_decrement( executing );
   _CORE_mutex_Set_owner( &the_mutex->Mutex, NULL );
 
   heads = the_mutex->Mutex.Wait_queue.Queue.heads;
 
   if ( heads == NULL ) {
     _CORE_mutex_Release( &the_mutex->Mutex, queue_context );
     return STATUS_SUCCESSFUL;
   }
 
   _Thread_queue_Surrender(
     &the_mutex->Mutex.Wait_queue.Queue,
     heads,
     executing,
     queue_context,
     operations
   );
   return STATUS_SUCCESSFUL;
 }
 
 /**
  * @brief initializes a ceiling mutex.
  *
  * @param[out] the_mutex The ceiling mutex to initialize.
  * @param scheduler The scheduler for the new ceiling mutex.
  *      Only needed if RTEMS_SMP is defined
  * @param priority_ceiling The priority ceiling for the initialized mutex.
  */
 static inline void _CORE_ceiling_mutex_Initialize(
   CORE_ceiling_mutex_Control *the_mutex,
   const Scheduler_Control    *scheduler,
   Priority_Control            priority_ceiling
 )
 {
   _CORE_recursive_mutex_Initialize( &the_mutex->Recursive );
   _Priority_Node_initialize( &the_mutex->Priority_ceiling, priority_ceiling );
 #if defined(RTEMS_SMP)
   the_mutex->scheduler = scheduler;
 #endif
 }
 
 /**
  * @brief Gets the scheduler of the ceiling mutex.
  *
  * @param the_mutex The ceiling mutex to get the scheduler from.
  *
  * @return The scheduler of the mutex. If RTEMS_SMP is not defined, the first entry of the _Scheduler_Table is returned.
  */
 static inline const Scheduler_Control *
 _CORE_ceiling_mutex_Get_scheduler(
   const CORE_ceiling_mutex_Control *the_mutex
 )
 {
 #if defined(RTEMS_SMP)
   return the_mutex->scheduler;
 #else
   return &_Scheduler_Table[ 0 ];
 #endif
 }
 
 /**
  * @brief Sets the priority of the ceiling mutex.
  *
  * @param[out] the_mutex The ceiling mutex to set the priority of.
  * @param priority_ceiling The new priority ceiling of the mutex.
  */
 static inline void _CORE_ceiling_mutex_Set_priority(
   CORE_ceiling_mutex_Control *the_mutex,
   Priority_Control            priority_ceiling
 )
 {
   Thread_Control *owner;
 
   owner = _CORE_mutex_Get_owner( &the_mutex->Recursive.Mutex );
 
   if ( owner != NULL ) {
     Thread_queue_Context queue_context;
 
     _Thread_queue_Context_initialize( &queue_context );
     _Thread_queue_Context_clear_priority_updates( &queue_context );
     _Thread_Wait_acquire_critical( owner, &queue_context );
     _Thread_Priority_change(
       owner,
       &the_mutex->Priority_ceiling,
       priority_ceiling,
       PRIORITY_GROUP_LAST,
       &queue_context
     );
     _Thread_Wait_release_critical( owner, &queue_context );
   } else {
     the_mutex->Priority_ceiling.priority = priority_ceiling;
   }
 }
 
 /**
  * @brief Gets the priority of the ceiling mutex.
  *
  * @param the_mutex The mutex to get the priority from.
  *
  * @return The priority ceiling of @a the_mutex.
  */
 static inline Priority_Control _CORE_ceiling_mutex_Get_priority(
   const CORE_ceiling_mutex_Control *the_mutex
 )
 {
   return the_mutex->Priority_ceiling.priority;
 }
 
 /**
  * @brief Sets the owner of the ceiling mutex.
  *
  * @param[in, out] the_mutex The mutex to set the owner of.
  * @param owner The new owner of @a the_mutex.
  * @param queue_context The thread queue context.
  *
  * @retval STATUS_SUCCESSFUL The owner of the mutex was changed successfully.
  * @retval STATUS_MUTEX_CEILING_VIOLATED The owners wait priority
  *          is smaller than the priority of the ceiling mutex.
  */
 static inline Status_Control _CORE_ceiling_mutex_Set_owner(
   CORE_ceiling_mutex_Control *the_mutex,
   Thread_Control             *owner,
   Thread_queue_Context       *queue_context
 )
 {
   ISR_lock_Context  lock_context;
   Scheduler_Node   *scheduler_node;
   Per_CPU_Control  *cpu_self;
 
   _Thread_Wait_acquire_default_critical( owner, &lock_context );
 
   scheduler_node = _Thread_Scheduler_get_home_node( owner );
 
   if (
     _Priority_Get_priority( &scheduler_node->Wait.Priority )
       < the_mutex->Priority_ceiling.priority
   ) {
     _Thread_Wait_release_default_critical( owner, &lock_context );
     _CORE_mutex_Release( &the_mutex->Recursive.Mutex, queue_context );
     return STATUS_MUTEX_CEILING_VIOLATED;
   }
 
   _CORE_mutex_Set_owner( &the_mutex->Recursive.Mutex, owner );
   _Thread_Resource_count_increment( owner );
   _Thread_Priority_add(
     owner,
     &the_mutex->Priority_ceiling,
     queue_context
   );
   _Thread_Wait_release_default_critical( owner, &lock_context );
 
   cpu_self = _Thread_queue_Dispatch_disable( queue_context );
   _CORE_mutex_Release( &the_mutex->Recursive.Mutex, queue_context );
   _Thread_Priority_update( queue_context );
   _Thread_Dispatch_enable( cpu_self );
   return STATUS_SUCCESSFUL;
 }
 
 /**
  * @brief Seizes the ceiling mutex.
  *
  * @param[in, out] the_mutex The mutex to seize.
  * @param executing The executing thread.
  * @param wait Indicates whether the calling thread is willing to wait.
  * @param nested Function that returns the status of the recursive mutex
  * @param queue_context The thread queue context.
  *
  * @retval STATUS_SUCCESSFUL The owner of the mutex was changed successfully.
  * @retval STATUS_NOT_DEFINED If the scheduler of the executing thread is not equal to the owner of @a the_mutex .
  * @retval STATUS_MUTEX_CEILING_VIOLATED The owners wait priority
  *          is smaller than the priority of the ceiling mutex.
  * @retval other Return value of @a nested.
  */
 static inline Status_Control _CORE_ceiling_mutex_Seize(
   CORE_ceiling_mutex_Control    *the_mutex,
   Thread_Control                *executing,
   bool                           wait,
   Status_Control              ( *nested )( CORE_recursive_mutex_Control * ),
   Thread_queue_Context          *queue_context
 )
 {
   Thread_Control *owner;
 
   _CORE_mutex_Acquire_critical( &the_mutex->Recursive.Mutex, queue_context );
 
 #if defined(RTEMS_SMP)
   if (
     _Thread_Scheduler_get_home( executing )
       != _CORE_ceiling_mutex_Get_scheduler( the_mutex )
   ) {
     _CORE_mutex_Release( &the_mutex->Recursive.Mutex, queue_context );
     return STATUS_NOT_DEFINED;
   }
 #endif
 
   owner = _CORE_mutex_Get_owner( &the_mutex->Recursive.Mutex );
 
   if ( owner == NULL ) {
     _Thread_queue_Context_clear_priority_updates( queue_context );
     return _CORE_ceiling_mutex_Set_owner(
       the_mutex,
       executing,
       queue_context
     );
   }
 
   if ( owner == executing ) {
     Status_Control status;
 
     status = ( *nested )( &the_mutex->Recursive );
     _CORE_mutex_Release( &the_mutex->Recursive.Mutex, queue_context );
     return status;
   }
 
   return _CORE_mutex_Seize_slow(
     &the_mutex->Recursive.Mutex,
     CORE_MUTEX_TQ_OPERATIONS,
     executing,
     wait,
     queue_context
   );
 }
 
 /**
  * @brief Surrenders the ceiling mutex.
  *
  * @param[in, out] the_mutex The ceiling mutex to surrender.
  * @param executing The executing thread.
  * @param queue_context The thread queue context.
  *
  * @retval STATUS_SUCCESSFUL The ceiling mutex was successfullysurrendered.
  * @retval STATUS_NOT_OWNER The executing thread is not the owner of @a the_mutex.
  */
 static inline Status_Control _CORE_ceiling_mutex_Surrender(
   CORE_ceiling_mutex_Control *the_mutex,
   Thread_Control             *executing,
   Thread_queue_Context       *queue_context
 )
 {
   unsigned int nest_level;
 
   _CORE_mutex_Acquire_critical( &the_mutex->Recursive.Mutex, queue_context );
 
   if ( !_CORE_mutex_Is_owner( &the_mutex->Recursive.Mutex, executing ) ) {
     _CORE_mutex_Release( &the_mutex->Recursive.Mutex, queue_context );
     return STATUS_NOT_OWNER;
   }
 
   nest_level = the_mutex->Recursive.nest_level;
 
   if ( nest_level > 0 ) {
     the_mutex->Recursive.nest_level = nest_level - 1;
     _CORE_mutex_Release( &the_mutex->Recursive.Mutex, queue_context );
     return STATUS_SUCCESSFUL;
   }
 
   return _Thread_queue_Surrender_priority_ceiling(
     &the_mutex->Recursive.Mutex.Wait_queue.Queue,
     executing,
     &the_mutex->Priority_ceiling,
     queue_context,
     CORE_MUTEX_TQ_OPERATIONS
   );
 }
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif
 /* end of include file */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team