From baff4dafe1ff85d128a55e7b73780ca28f5c7faf Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 1 Nov 2004 13:22:41 +0000 Subject: 2004-11-01 Joel Sherrill * score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/copyrt.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremsg.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, score/inline/rtems/score/mppkt.inl, score/inline/rtems/score/objectmp.inl, score/inline/rtems/score/priority.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/states.inl, score/inline/rtems/score/sysstate.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/threadmp.inl, score/inline/rtems/score/tod.inl, score/inline/rtems/score/tqdata.inl, score/inline/rtems/score/userext.inl, score/inline/rtems/score/watchdog.inl, score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working modifications which are not complete and may have broken code. Committing so work and testing can proceed. * score/Doxyfile, score/mainpage.h: New files. --- cpukit/score/include/rtems/score/apimutex.h | 88 +++++++++++++++++------------ 1 file changed, 53 insertions(+), 35 deletions(-) (limited to 'cpukit/score/include/rtems/score/apimutex.h') 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 #include -/* - * 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 */ -- cgit v1.2.3