score: Create mutex implementation header

Move implementation specific parts of coremutex.h and coremutex.inl into
new header file coremuteximpl.h.  The coremutex.h contains now only the
application visible API.

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 */