coremuteximpl.h

Go to the documentation of this file.

/*
 *  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 <rtems/score/coremutex.h>
#include <rtems/score/chainimpl.h>
#include <rtems/score/sysstate.h>
#include <rtems/score/threadimpl.h>
#include <rtems/score/threadqimpl.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef void ( *CORE_mutex_API_mp_support_callout )(
                 Thread_Control *,
                 Objects_Id
             );

typedef enum {
  CORE_MUTEX_STATUS_SUCCESSFUL,
  CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
#if defined(RTEMS_POSIX_API)

  CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
#endif

  CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
  CORE_MUTEX_WAS_DELETED,
  CORE_MUTEX_TIMEOUT,

#if defined(__RTEMS_STRICT_ORDER_MUTEX__)

  CORE_MUTEX_RELEASE_NOT_ORDER,
#endif

  CORE_MUTEX_STATUS_CEILING_VIOLATED

}   CORE_mutex_Status;

#define CORE_MUTEX_STATUS_LAST CORE_MUTEX_STATUS_CEILING_VIOLATED

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 );
}

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__)

  int _CORE_mutex_Seize_interrupt_trylock(
    CORE_mutex_Control  *the_mutex,
    Thread_Control      *executing,
    ISR_lock_Context    *lock_context
  );
#else

  #define _CORE_mutex_Seize_interrupt_trylock( _mutex, _executing, _lock_context ) \
     _CORE_mutex_Seize_interrupt_trylock_body( _mutex, _executing, _lock_context )
#endif

void _CORE_mutex_Seize_interrupt_blocking(
  CORE_mutex_Control  *the_mutex,
  Thread_Control      *executing,
  Watchdog_Interval    timeout,
  ISR_lock_Context    *lock_context
);

#define _CORE_mutex_Check_dispatch_for_seize(_wait) \
  (!_Thread_Dispatch_is_enabled() \
    && (_wait) \
    && (_System_state_Get() >= SYSTEM_STATE_UP))

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
      );
    }
  }
}

#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

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
);

void _CORE_mutex_Flush(
  CORE_mutex_Control         *the_mutex,
  Thread_queue_Flush_callout  remote_extract_callout,
  uint32_t                    status
);

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_locked(
  const CORE_mutex_Control *the_mutex
)
{
  return the_mutex->holder != NULL;
}

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_fifo(
  const CORE_mutex_Attributes *the_attribute
)
{
  return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_FIFO;
}

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_priority(
  CORE_mutex_Attributes *the_attribute
)
{
  return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY;
}

RTEMS_INLINE_ROUTINE bool _CORE_mutex_Is_inherit_priority(
  CORE_mutex_Attributes *the_attribute
)
{
  return the_attribute->discipline == CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT;
}

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( lock_context );
        _Thread_queue_Release( &the_mutex->Wait_queue, lock_context );
        _Thread_Raise_priority( executing, ceiling );
        _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 */