/**
* @file apimutex.h
*
* This include file contains all the constants and structures associated
* with the API Mutex Handler. This handler is used by API level
* routines to manage mutual exclusion.
*/
/*
* COPYRIGHT (c) 1989-2004.
* 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.
*
* $Id$
*/
#ifndef __API_MUTEX_h
#define __API_MUTEX_h
/**
* @defgroup ScoreAPIMutex API Mutex Handler
*
* This group contains functionality which provides mutexes to be used
* in the implementation of API functionality.
*/
/**@{*/
#ifdef __cplusplus
extern "C" {
#endif
#include <rtems/score/coremutex.h>
#include <rtems/score/isr.h>
#include <rtems/score/object.h>
/**
* The following defines the control block used to manage each API mutex.
* An API Mutex is an aggregration of an Object and a SuperCore Mutex.
*/
typedef struct {
/** This field allows each API Mutex to be a full-fledged RTEMS object.
Objects_Control Object;
/** This field contains the SuperCore mutex information. */
CORE_mutex_Control Mutex;
} API_Mutex_Control;
/**
* The following variable is the information control block used to manage
* this class of objects.
*/
SCORE_EXTERN Objects_Information _API_Mutex_Information;
/**
* This routine performs the initialization necessary for this handler.
*
* @param _maximum_mutexes (in) is the maximum number of API mutexes
* that may exist at any time
*/
#if defined(RTEMS_MULTIPROCESSING)
#define _API_Mutex_Initialization( _maximum_mutexes ) \
_Objects_Initialize_information( \
&_API_Mutex_Information, \
OBJECTS_INTERNAL_API, \
OBJECTS_INTERNAL_MUTEXES, \
_maximum_mutexes, \
sizeof( API_Mutex_Control ), \
FALSE, \
0, \
FALSE, \
NULL \
);
#else
#define _API_Mutex_Initialization( _maximum_mutexes ) \
_Objects_Initialize_information( \
&_API_Mutex_Information, \
OBJECTS_INTERNAL_API, \
OBJECTS_INTERNAL_MUTEXES, \
_maximum_mutexes, \
sizeof( API_Mutex_Control ), \
FALSE, \
0 \
);
#endif
/**
* This routine allocates an API mutex from the inactive set.
*
* @param _the_mutex (out) will contain the allocated mutex.
*/
#define _API_Mutex_Allocate( _the_mutex ) \
do { \
CORE_mutex_Attributes attr = \
{ CORE_MUTEX_NESTING_IS_ERROR, FALSE, \
CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, 0 }; \
(_the_mutex) = (API_Mutex_Control *) \
_Objects_Allocate( &_API_Mutex_Information ); \
_CORE_mutex_Initialize( \
&(_the_mutex)->Mutex, &attr, CORE_MUTEX_UNLOCKED ); \
} while (0)
/**
* This routine acquires the specified API mutex.
*
* @param _the_mutex (in) is the mutex to acquire.
*/
#define _API_Mutex_Lock( _the_mutex ) \
do { \
ISR_Level _level; \
_ISR_Disable( _level ); \
_CORE_mutex_Seize( \
&(_the_mutex)->Mutex, (_the_mutex)->Object.id, TRUE, 0, (_level) ); \
} while (0)
/**
* This routine releases the specified API mutex.
*
* @param _the_mutex (in) is the mutex to release.
*/
#define _API_Mutex_Unlock( _the_mutex ) \
do { \
_Thread_Disable_dispatch(); \
_CORE_mutex_Surrender( \
&(_the_mutex)->Mutex, (_the_mutex)->Object.id, NULL ); \
_Thread_Enable_dispatch(); \
} while (0);
/**
* This variable points to the API Mutex instance that is used
* to protect all memory allocation and deallocation in RTEMS.
*
* @note When the APIs all use this for allocation and deallocation
* protection, then this possibly should be renamed and moved to a
* higher level in the hierarchy.
*/
SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex;
/**
* This macro locks the RTEMS Allocation Mutex.
*
* @see _RTEMS_Allocator_Mutex
*/
#define _RTEMS_Lock_allocator() \
_API_Mutex_Lock( _RTEMS_Allocator_Mutex )
/**
* This macro unlocks the RTEMS Allocation Mutex.
*
* @see _RTEMS_Allocator_Mutex
*/
#define _RTEMS_Unlock_allocator() \
_API_Mutex_Unlock( _RTEMS_Allocator_Mutex )
/*
* There are no inlines for this handler.
*/
#ifndef __RTEMS_APPLICATION__
/* #include <rtems/score/apimutex.inl> */
#endif
#ifdef __cplusplus
}
#endif
/*!@}*/
#endif
/* end of include file */
