summaryrefslogtreecommitdiffstats
path: root/cpukit/score/include/rtems/score/apimutex.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--cpukit/score/include/rtems/score/apimutex.h88
1 files changed, 53 insertions, 35 deletions
diff --git a/cpukit/score/include/rtems/score/apimutex.h b/cpukit/score/include/rtems/score/apimutex.h
index ed345c7c76..ad30e0b18b 100644
--- a/cpukit/score/include/rtems/score/apimutex.h
+++ b/cpukit/score/include/rtems/score/apimutex.h
@@ -1,10 +1,13 @@
-/* apimutex.h
+/**
+ * @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-2002.
+ */
+
+/*
+ * COPYRIGHT (c) 1989-2004.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -17,6 +20,14 @@
#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
@@ -25,30 +36,29 @@ extern "C" {
#include <rtems/score/isr.h>
#include <rtems/score/object.h>
-/*
- * The following defines the control block used to manage each mutex.
+/**
+ * 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 defines the information control block used to manage
+/**
+ * The following variable is the information control block used to manage
* this class of objects.
*/
-
SCORE_EXTERN Objects_Information _API_Mutex_Information;
-/*
- * _API_Mutex_Initialization
- *
- * DESCRIPTION:
- *
+/**
* 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( \
@@ -75,14 +85,11 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
);
#endif
-/*
- * _API_Mutex_Allocate
- *
- * DESCRIPTION:
+/**
+ * This routine allocates an API mutex from the inactive set.
*
- * 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 = \
@@ -94,14 +101,11 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
&(_the_mutex)->Mutex, &attr, CORE_MUTEX_UNLOCKED ); \
} while (0)
-/*
- * _API_Mutex_Lock
+/**
+ * This routine acquires the specified API mutex.
*
- * DESCRIPTION:
- *
- * 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; \
@@ -110,12 +114,10 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
&(_the_mutex)->Mutex, (_the_mutex)->Object.id, TRUE, 0, (_level) ); \
} while (0)
-/*
- * _API_Mutex_Unlock
- *
- * DESCRIPTION:
+/**
+ * This routine releases the specified API mutex.
*
- * This routine releases the specified api mutex.
+ * @param _the_mutex (in) is the mutex to release.
*/
#define _API_Mutex_Unlock( _the_mutex ) \
@@ -126,15 +128,29 @@ SCORE_EXTERN Objects_Information _API_Mutex_Information;
_Thread_Enable_dispatch(); \
} while (0);
-/*XXX when the APIs all use this for allocation and deallocation
- *XXX protection, then they should be renamed and probably moved
+/**
+ * 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 )
@@ -150,5 +166,7 @@ SCORE_EXTERN API_Mutex_Control *_RTEMS_Allocator_Mutex;
}
#endif
+/*!@}*/
+
#endif
/* end of include file */