From 4600bd7cfe1c960d394d8f70b3d665857e5040dd Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 9 Dec 2013 12:53:24 -0600 Subject: muteximpl.h: Comment clean up --- cpukit/posix/include/rtems/posix/muteximpl.h | 152 ++++++++------------------- 1 file changed, 44 insertions(+), 108 deletions(-) (limited to 'cpukit/posix') diff --git a/cpukit/posix/include/rtems/posix/muteximpl.h b/cpukit/posix/include/rtems/posix/muteximpl.h index 29e93c2af5..710af7b6c8 100644 --- a/cpukit/posix/include/rtems/posix/muteximpl.h +++ b/cpukit/posix/include/rtems/posix/muteximpl.h @@ -7,7 +7,7 @@ * inlined routines for POSIX mutex's. */ -/* COPYRIGHT (c) 1989-2011. +/* COPYRIGHT (c) 1989-2013. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -27,97 +27,61 @@ extern "C" { #endif -/* +/** * The following defines the information control block used to manage * this class of objects. */ - POSIX_EXTERN Objects_Information _POSIX_Mutex_Information; -/* +/** * The default mutex attributes structure. */ - POSIX_EXTERN pthread_mutexattr_t _POSIX_Mutex_Default_attributes; +/** + * This array contains a mapping from Score Mutex return codes to + * POSIX return codes. + */ extern const int _POSIX_Mutex_Return_codes[CORE_MUTEX_STATUS_LAST + 1]; -/* +/** * @brief POSIX Mutex Manager Initialization * - * DESCRIPTION: - * * This routine performs the initialization necessary for this manager. */ - void _POSIX_Mutex_Manager_initialization(void); -/* - * _POSIX_Mutex_Allocate - * - * DESCRIPTION: +/** + * @brief POSIX Mutex Allocate * * This function allocates a mutexes control block from * the inactive chain of free mutexes control blocks. */ +RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Allocate( void ) +{ + return (POSIX_Mutex_Control *) _Objects_Allocate( &_POSIX_Mutex_Information ); +} -RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Allocate( void ); - -/* - * _POSIX_Mutex_Free - * - * DESCRIPTION: +/** + * @brief POSIX Mutex Free * * This routine frees a mutexes control block to the * inactive chain of free mutexes control blocks. */ - -RTEMS_INLINE_ROUTINE void _POSIX_Mutex_Free ( +RTEMS_INLINE_ROUTINE void _POSIX_Mutex_Free( POSIX_Mutex_Control *the_mutex -); - -#if 0 -/* - * _POSIX_Mutex_Get - * - * DESCRIPTION: - * - * This function maps mutexes IDs to mutexes control blocks. - * If ID corresponds to a local mutexes, then it returns - * the_mutex control pointer which maps to ID and location - * is set to OBJECTS_LOCAL. if the mutexes ID is global and - * resides on a remote node, then location is set to OBJECTS_REMOTE, - * and the_mutex is undefined. Otherwise, location is set - * to OBJECTS_ERROR and the_mutex is undefined. - */ - -RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Get ( - Objects_Id *id, - Objects_Locations *location -); +) +{ + _Objects_Free( &_POSIX_Mutex_Information, &the_mutex->Object ); +} -/* - * _POSIX_Mutex_Is_null - * - * DESCRIPTION: - * - * This function returns TRUE if the_mutex is NULL and FALSE otherwise. - */ -RTEMS_INLINE_ROUTINE bool _POSIX_Mutex_Is_null ( - POSIX_Mutex_Control *the_mutex -); -#endif - -/* - * _POSIX_Mutex_Lock_support - * - * DESCRIPTION: +/** + * @brief POSIX Mutex Lock Support Method * * A support routine which implements guts of the blocking, non-blocking, and * timed wait version of mutex lock. */ - int _POSIX_Mutex_Lock_support( pthread_mutex_t *mutex, bool blocking, @@ -125,10 +89,7 @@ int _POSIX_Mutex_Lock_support( ); /** - * @brief Convert core mutex status codes into the appropriate POSIX status - * values. - * - * DESCRIPTION: + * @brief Convert Score mutex status codes into POSIX status values * * A support routine which converts core mutex status codes into the * appropriate POSIX status values. @@ -137,16 +98,17 @@ int _POSIX_Mutex_Lock_support( * * @retval 0 Mutex status code indicates the operation completed successfully. * @retval EBUSY Mutex status code indicates that the operation unable to - * complete immediately because the resource was unavailable. + * complete immediately because the resource was unavailable. * @retval EDEADLK Mutex status code indicates that an attempt was made to - * relock a mutex for which nesting is not configured. + * relock a mutex for which nesting is not configured. * @retval EPERM Mutex status code indicates that an attempt was made to - * release a mutex by a thread other than the thread which locked it. + * release a mutex by a thread other than the thread which locked it. * @retval EINVAL Mutex status code indicates that the thread was blocked - * waiting for an operation to complete and the mutex was deleted. + * waiting for an operation to complete and the mutex was deleted. * @retval ETIMEDOUT Mutex status code indicates that the calling task was - * willing to block but the operation was unable to complete within the time - * allotted because the resource never became available. + * willing to block but the operation was unable to complete + * within the time allotted because the resource never became + * available. */ RTEMS_INLINE_ROUTINE int _POSIX_Mutex_Translate_core_mutex_return_code( CORE_mutex_Status the_mutex_status @@ -162,67 +124,41 @@ RTEMS_INLINE_ROUTINE int _POSIX_Mutex_Translate_core_mutex_return_code( return _POSIX_Mutex_Return_codes[the_mutex_status]; } -/* - * _POSIX_Mutex_Get - * - * DESCRIPTION: +/** + * @brief POSIX Mutex Get (Thread Dispatch Disable) * * A support routine which translates the mutex id into a local pointer. * As a side-effect, it may create the mutex. * - * NOTE: - * - * This version of the method uses a dispatching critical section. + * @note This version of the method uses a dispatching critical section. */ - POSIX_Mutex_Control *_POSIX_Mutex_Get ( pthread_mutex_t *mutex, Objects_Locations *location ); -/* - * _POSIX_Mutex_Get - * - * DESCRIPTION: +/** + * @brief POSIX Mutex Get (Interrupt Disable) * * A support routine which translates the mutex id into a local pointer. * As a side-effect, it may create the mutex. * - * NOTE: - * - * This version of the method uses an interrupt critical section. + * @note: This version of the method uses an interrupt critical section. */ - POSIX_Mutex_Control *_POSIX_Mutex_Get_interrupt_disable ( pthread_mutex_t *mutex, Objects_Locations *location, ISR_Level *level ); -/* - * _POSIX_Mutex_Allocate - */ - -RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Allocate( void ) -{ - return (POSIX_Mutex_Control *) _Objects_Allocate( &_POSIX_Mutex_Information ); -} - -/* - * _POSIX_Mutex_Free - */ - -RTEMS_INLINE_ROUTINE void _POSIX_Mutex_Free ( - POSIX_Mutex_Control *the_mutex -) -{ - _Objects_Free( &_POSIX_Mutex_Information, &the_mutex->Object ); -} - -/* - * _POSIX_Mutex_Is_null +/** + * @brief POSIX Mutex Is NULL + * + * This method is used to determine if a pointer to a POSIX mutex is NULL. + * + * @return This method returns TRUE if @a the_mutex is NULL and FALSE + * otherwise. */ - RTEMS_INLINE_ROUTINE bool _POSIX_Mutex_Is_null ( POSIX_Mutex_Control *the_mutex ) -- cgit v1.2.3