diff options
author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2004-11-01 13:22:41 +0000 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2004-11-01 13:22:41 +0000 |
commit | baff4dafe1ff85d128a55e7b73780ca28f5c7faf (patch) | |
tree | e2acdf92de467f283ecd11fe621a67e79301e1cc /cpukit/score/include/rtems/score/coresem.h | |
parent | 2004-11-01 Ralf Corsepius <ralf_corsepius@rtems.org> (diff) | |
download | rtems-baff4dafe1ff85d128a55e7b73780ca28f5c7faf.tar.bz2 |
2004-11-01 Joel Sherrill <joel@oarcorp.com>
* 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.
Diffstat (limited to 'cpukit/score/include/rtems/score/coresem.h')
-rw-r--r-- | cpukit/score/include/rtems/score/coresem.h | 115 |
1 files changed, 78 insertions, 37 deletions
diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h index e9be0036ab..333cd1874f 100644 --- a/cpukit/score/include/rtems/score/coresem.h +++ b/cpukit/score/include/rtems/score/coresem.h @@ -1,11 +1,14 @@ -/* core_sem.h +/** + * @file coresem.h * * This include file contains all the constants and structures associated * with the Counting Semaphore Handler. A counting semaphore is the * standard Dijkstra binary semaphore used to provide synchronization * and mutual exclusion capabilities. - * - * COPYRIGHT (c) 1989-1999. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -18,6 +21,14 @@ #ifndef __RTEMS_CORE_COUNTING_SEMAPHORE_h #define __RTEMS_CORE_COUNTING_SEMAPHORE_h +/** + * @defgroup ScoreSemaphore Semaphore Handler + * + * This group contains functionality which provides the foundation + * Semaphore services used in all of the APIs supported by RTEMS. + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif @@ -27,83 +38,108 @@ extern "C" { #include <rtems/score/priority.h> #include <rtems/score/watchdog.h> -/* +/** * The following type defines the callout which the API provides * to support global/multiprocessor operations on semaphores. */ - typedef void ( *CORE_semaphore_API_mp_support_callout )( Thread_Control *, Objects_Id ); -/* +/** * Blocking disciplines for a semaphore. */ - typedef enum { + /** This specifies that threads will wait for the semaphore in FIFO order. */ CORE_SEMAPHORE_DISCIPLINES_FIFO, + /** This specifies that threads will wait for the semaphore in + * priority order. + */ CORE_SEMAPHORE_DISCIPLINES_PRIORITY } CORE_semaphore_Disciplines; -/* +/** * Core Semaphore handler return statuses. */ - typedef enum { + /** This status indicates that the operation completed successfully. */ CORE_SEMAPHORE_STATUS_SUCCESSFUL, + /** This status indicates that the calling task did not want to block + * and the operation was unable to complete immediately because the + * resource was unavailable. + */ CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT, + /** This status indicates that the thread was blocked waiting for an + * operation to complete and the semaphore was deleted. + */ CORE_SEMAPHORE_WAS_DELETED, + /** This status 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. + */ CORE_SEMAPHORE_TIMEOUT, + /** This status indicates that an attempt was made to unlock the semaphore + * and this would have made its count greater than that allowed. CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED } CORE_semaphore_Status; -/* +/** * The following defines the control block used to manage the * attributes of each semaphore. */ - typedef struct { + /** This element indicates the maximum count this semaphore may have. */ uint32_t maximum_count; + /** This field indicates whether threads waiting on the semaphore block in + * FIFO or priority order. + */ CORE_semaphore_Disciplines discipline; } CORE_semaphore_Attributes; -/* +/** * The following defines the control block used to manage each * counting semaphore. */ - typedef struct { + /** This field is the Waiting Queue used to manage the set of tasks + * which are blocked waiting to obtain the semaphore. + */ Thread_queue_Control Wait_queue; + /** This element is the set of attributes which define this instance's + * behavior. + */ CORE_semaphore_Attributes Attributes; + /** This element contains the current count of this semaphore. */ uint32_t count; } CORE_semaphore_Control; -/* - * _CORE_semaphore_Initialize - * - * DESCRIPTION: - * +/** * This routine initializes the semaphore based on the parameters passed. + * + * @param the_semaphore (in) is the semaphore to initialize + * @param the_semaphore_attributes (in) define the behavior of this instance + * @param initial_value (in) is the initial count of the semaphore */ - void _CORE_semaphore_Initialize( CORE_semaphore_Control *the_semaphore, CORE_semaphore_Attributes *the_semaphore_attributes, uint32_t initial_value ); -/* - * _CORE_semaphore_Seize - * - * DESCRIPTION: - * +/** * This routine attempts to receive a unit from the_semaphore. * If a unit is available or if the wait flag is FALSE, then the routine * returns. Otherwise, the calling task is blocked until a unit becomes * available. + * + * @param the_semaphore (in) is the semaphore to seize + * @param id (in) is the Id of the API level Semaphore object associated + * with this instance of a SuperCore Semaphore + * @param wait (in) is TRUE if the calling thread is willing to wait + * @param timeout (in) is the number of ticks the calling thread is willing + * to wait if @a wait is TRUE. */ - void _CORE_semaphore_Seize( CORE_semaphore_Control *the_semaphore, Objects_Id id, @@ -111,31 +147,34 @@ void _CORE_semaphore_Seize( Watchdog_Interval timeout ); -/* - * _CORE_semaphore_Surrender - * - * DESCRIPTION: - * +/** * This routine frees a unit to the semaphore. If a task was blocked waiting * for a unit from this semaphore, then that task will be readied and the unit * given to that task. Otherwise, the unit will be returned to the semaphore. + * + * @param the_semaphore (in) is the semaphore to surrender + * @param id (in) is the Id of the API level Semaphore object associated + * with this instance of a SuperCore Semaphore + * @param api_semaphore_mp_support (in) is the routine to invoke if the + * thread unblocked is remote + * + * @return an indication of whether the routine succeeded or failed */ - CORE_semaphore_Status _CORE_semaphore_Surrender( CORE_semaphore_Control *the_semaphore, Objects_Id id, CORE_semaphore_API_mp_support_callout api_semaphore_mp_support ); -/* - * _CORE_semaphore_Flush - * - * DESCRIPTION: - * +/** * This routine assists in the deletion of a semaphore by flushing the * associated wait queue. + * + * @param the_semaphore (in) is the semaphore to flush + * @param remote_extract_callout (in) is the routine to invoke if the + * thread unblocked is remote + * @param status (in) is the status to be returned to the unblocked thread */ - void _CORE_semaphore_Flush( CORE_semaphore_Control *the_semaphore, Thread_queue_Flush_callout remote_extract_callout, @@ -150,5 +189,7 @@ void _CORE_semaphore_Flush( } #endif +/**@}*/ + #endif /* end of include file */ |