smp: New SMP lock API

Move the SMP lock implementation to the CPU port.  An optimal SMP lock
implementation is highly architecture dependent.  For example the memory
models may be fundamentally different.

The new SMP lock API has a flaw.  It does not provide the ability to use
a local context for acquire and release pairs.  Such a context is
necessary to implement for example the Mellor-Crummey and Scott (MCS)
locks.  The SMP lock is currently used in _Thread_Disable_dispatch() and
_Thread_Enable_dispatch() and makes them to a giant lock acquire and
release.  Since these functions do not pass state information via a
local context there is currently no use case for such a feature.

1 files changed, 74 insertions, 100 deletions

diff --git a/cpukit/score/include/rtems/score/smplock.h b/cpukit/score/include/rtems/score/smplock.h
index 6db8a43418..b3ef0e2cb0 100644
--- a/cpukit/score/include/rtems/score/smplock.h
+++ b/cpukit/score/include/rtems/score/smplock.h
@@ -1,149 +1,123 @@
 /**
- *  @file  rtems/score/smplock.h
+ * @file
  *
- *  @brief Interface for Atomic Locks
+ * @ingroup ScoreSMPLock
  *
- *  This include file defines the interface for atomic locks
- *  which can be used in multiprocessor configurations.
+ * @brief SMP Lock API
  */
 
 /*
- *  COPYRIGHT (c) 1989-2011.
- *  On-Line Applications Research Corporation (OAR).
+ * COPYRIGHT (c) 1989-2011.
+ * 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.com/license/LICENSE.
+ * Copyright (c) 2013 embedded brains GmbH
+ *
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.com/license/LICENSE.
  */
 
-#ifndef _RTEMS_LOCK_H
-#define _RTEMS_LOCK_H
+#ifndef _RTEMS_SCORE_SMPLOCK_H
+#define _RTEMS_SCORE_SMPLOCK_H
 
+#include <rtems/score/cpusmplock.h>
 #include <rtems/score/isr.h>
 
-/**
- *  @defgroup RTEMS Lock Interface
- *
- *  @ingroup Score
- *
- */
-
-/**@{*/
-
 #ifdef __cplusplus
 extern "C" {
-#endif
+#endif /* __cplusplus */
 
 /**
- *  This type is used to lock elements for atomic access.
- *  This spinlock is a simple non-nesting spinlock, and
- *  may be used for short non-nesting accesses.
+ * @defgroup ScoreSMPLock SMP Locks
+ *
+ * @ingroup Score
+ *
+ * The SMP lock implementation is architecture dependent.  The implementation
+ * should provide fairness in case of concurrent lock attempts.  A ticket lock
+ * is probably the most likely implementation.
+ *
+ * This SMP lock API has a flaw.  It does not provide the ability to use a
+ * local context for acquire and release pairs.  Such a context is necessary to
+ * implement for example the Mellor-Crummey and Scott (MCS) locks.  The SMP
+ * lock is currently used in _Thread_Disable_dispatch() and
+ * _Thread_Enable_dispatch() and makes them to a giant lock acquire and
+ * release.  Since these functions do not pass state information via a local
+ * context there is currently no use case for such a feature.
+ *
+ * @{
  */
-typedef uint32_t SMP_lock_spinlock_simple_Control;
 
 /**
- *  This type is used to lock elements for atomic access.
- *  This spinlock supports nesting, but is slightly more
- *  complicated to use.  Please see the descriptions of
- *  obtain and release prior to using in order to understand
- *  the callers responsibilty of managing short interupt disable
- *  times.
+ * @brief SMP lock control.
+ *
+ * This is an opaque type.  The SMP lock implementation is architecture
+ * dependent.
  */
-typedef struct {
-  SMP_lock_spinlock_simple_Control lock;
-  uint32_t  count;
-  int       cpu_id;
-} SMP_lock_spinlock_nested_Control;
+typedef CPU_SMP_lock_Control SMP_lock_Control;
 
 /**
- *  @brief Initialize a lock.
- *
- *  This method is used to initialize the lock at @a lock.
- *
- *  @param [in] lock is the address of the lock to obtain.
+ * @brief SMP lock control initializer for static initialization.
  */
-void _SMP_lock_spinlock_simple_Initialize(
-  SMP_lock_spinlock_simple_Control *lock
-);
+#define SMP_LOCK_INITIALIZER CPU_SMP_LOCK_INITIALIZER
 
 /**
- *  @brief Obtain a lock.
+ * @brief Initializes a SMP lock control.
  *
- *  This method is used to obtain the lock at @a lock.
+ * Concurrent initialization leads to unpredictable results.
  *
- *  @param [in] lock is the address of the lock to obtain.
- *
- *  @retval This method returns with processor interrupts disabled.
- *          The previous level is returned.
+ * @param[out] lock The SMP lock control.
  */
-ISR_Level _SMP_lock_spinlock_simple_Obtain(
-  SMP_lock_spinlock_simple_Control *lock
-);
+static inline void _SMP_lock_Initialize( SMP_lock_Control *lock )
+{
+  _CPU_SMP_lock_Initialize( lock );
+}
 
 /**
- *  @brief Release a lock.
+ * @brief Acquires a SMP lock.
  *
- *  This method is used to release the lock at @a lock.
+ * This function will not disable interrupts.  The caller must ensure that the
+ * current thread of execution is not interrupted indefinite once it obtained
+ * the SMP lock.
  *
- *  @param [in] lock is the address of the lock to obtain.
+ * @param[in/out] lock The SMP lock control.
  */
-void _SMP_lock_spinlock_simple_Release(
-  SMP_lock_spinlock_simple_Control  *lock,
-  ISR_Level                         level
-);
+static inline void _SMP_lock_Acquire( SMP_lock_Control *lock )
+{
+  _CPU_SMP_lock_Acquire( lock );
+}
 
 /**
- *  @brief Initialize a lock.
- *
- *  This method is used to initialize the lock at @a lock.
+ * @brief Releases a SMP lock.
  *
- *  @param [in] lock is the address of the lock to obtain.
+ * @param[in/out] lock The SMP lock control.
  */
-void _SMP_lock_spinlock_nested_Initialize(
-  SMP_lock_spinlock_nested_Control *lock
-);
+static inline void _SMP_lock_Release( SMP_lock_Control *lock )
+{
+  _CPU_SMP_lock_Release( lock );
+}
 
 /**
- *  @brief Obtain a lock.
- *
- *  This method is used to obtain the lock at @a lock.  ISR's are
- *  disabled when this routine returns and it is the callers responsibility
- *  to either:
- *
- *   # Do something very short and then call
- *      _SMP_lock_spinlock_nested_Release  or
- *   # Do something very sort, call isr enable, then when ready
- *      call isr_disable and _SMP_lock_spinlock_nested_Release
+ * @brief Disables interrupts and acquires the SMP lock.
  *
- *  @param [in] lock is the address of the lock to obtain.
- *
- *  @retval This method returns with processor interrupts disabled.
- *          The previous level is returned.
+ * @param[in/out] lock The SMP lock control.
+ * @param[out] isr_cookie The ISR cookie.
  */
-ISR_Level _SMP_lock_spinlock_nested_Obtain(
-  SMP_lock_spinlock_nested_Control *lock
-);
+#define _SMP_lock_ISR_disable_and_acquire( lock, isr_cookie ) \
+  _CPU_SMP_lock_ISR_disable_and_acquire( lock, isr_cookie )
 
 /**
- *  @brief Release a lock.
- *
- *  This method is used to release the lock at @a lock.
+ * @brief Releases the SMP lock and enables interrupts.
  *
- *  @note ISR's are reenabled by this method and are expected to be
- *  disabled upon entry to the method.
- *
- *  @param [in] lock is the address of the lock to obtain.
+ * @param[in/out] lock The SMP lock control.
+ * @param[in] isr_cookie The ISR cookie.
  */
-void _SMP_lock_spinlock_nested_Release(
-  SMP_lock_spinlock_nested_Control  *lock,
-  ISR_Level                         level
-);
+#define _SMP_lock_Release_and_ISR_enable( lock, isr_cookie ) \
+  _CPU_SMP_lock_Release_and_ISR_enable( lock, isr_cookie )
+
+/**@}*/
 
 #ifdef __cplusplus
 }
-#endif
-
-/**@}*/
+#endif /* __cplusplus */
 
-#endif
-/* end of include file */
+#endif /* _RTEMS_SCORE_SMPLOCK_H */