source: rtems/cpukit/score/include/rtems/score/coresem.h @ 6a07436

4.104.114.84.95
Last change on this file since 6a07436 was 6a07436, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 16, 2006 at 3:13:58 PM

2006-01-16 Joel Sherrill <joel@…>

Large patch to improve Doxygen output. As a side-effect, grammar and
spelling errors were corrected, spacing errors were address, and some
variable names were improved.

  • libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS.
  • score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output.
  • 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/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/object.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/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes.
  • Property mode set to 100644
File size: 6.2 KB
Line 
1/**
2 *  @file  rtems/score/coresem.h
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the Counting Semaphore Handler.  A counting semaphore is the
6 *  standard Dijkstra binary semaphore used to provide synchronization
7 *  and mutual exclusion capabilities.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2006.
12 *  On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.com/license/LICENSE.
17 *
18 *  $Id$
19 */
20
21#ifndef _RTEMS_SCORE_CORESEM_H
22#define _RTEMS_SCORE_CORESEM_H
23
24/**
25 *  @defgroup ScoreSemaphore Semaphore Handler
26 *
27 *  This handler encapsulates functionality which provides the foundation
28 *  Semaphore services used in all of the APIs supported by RTEMS.
29 */
30/**@{*/
31
32#ifdef __cplusplus
33extern "C" {
34#endif
35
36#include <rtems/score/thread.h>
37#include <rtems/score/threadq.h>
38#include <rtems/score/priority.h>
39#include <rtems/score/watchdog.h>
40
41/**
42 *  The following type defines the callout which the API provides
43 *  to support global/multiprocessor operations on semaphores.
44 */
45typedef void ( *CORE_semaphore_API_mp_support_callout )(
46                 Thread_Control *,
47                 Objects_Id
48             );
49
50/**
51 *  Blocking disciplines for a semaphore.
52 */
53typedef enum {
54  /** This specifies that threads will wait for the semaphore in FIFO order. */
55  CORE_SEMAPHORE_DISCIPLINES_FIFO,
56  /** This specifies that threads will wait for the semaphore in
57   *  priority order.
58   */
59  CORE_SEMAPHORE_DISCIPLINES_PRIORITY
60}   CORE_semaphore_Disciplines;
61
62/**
63 *  Core Semaphore handler return statuses.
64 */
65typedef enum {
66  /** This status indicates that the operation completed successfully. */
67  CORE_SEMAPHORE_STATUS_SUCCESSFUL,
68  /** This status indicates that the calling task did not want to block
69   *  and the operation was unable to complete immediately because the
70   *  resource was unavailable.
71   */
72  CORE_SEMAPHORE_STATUS_UNSATISFIED_NOWAIT,
73  /** This status indicates that the thread was blocked waiting for an
74   *  operation to complete and the semaphore was deleted.
75   */
76  CORE_SEMAPHORE_WAS_DELETED,
77  /** This status indicates that the calling task was willing to block
78   *  but the operation was unable to complete within the time allotted
79   *  because the resource never became available.
80   */
81  CORE_SEMAPHORE_TIMEOUT,
82  /** This status indicates that an attempt was made to unlock the semaphore
83   *  and this would have made its count greater than that allowed.
84   */
85  CORE_SEMAPHORE_MAXIMUM_COUNT_EXCEEDED
86}   CORE_semaphore_Status;
87
88/**
89 *  The following defines the control block used to manage the
90 *  attributes of each semaphore.
91 */
92typedef struct {
93  /** This element indicates the maximum count this semaphore may have. */
94  uint32_t                    maximum_count;
95  /** This field indicates whether threads waiting on the semaphore block in
96   *  FIFO or priority order.
97   */
98  CORE_semaphore_Disciplines  discipline;
99}   CORE_semaphore_Attributes;
100
101/**
102 *  The following defines the control block used to manage each
103 *  counting semaphore.
104 */
105typedef struct {
106  /** This field is the Waiting Queue used to manage the set of tasks
107   *  which are blocked waiting to obtain the semaphore.
108   */
109  Thread_queue_Control        Wait_queue;
110  /** This element is the set of attributes which define this instance's
111   *  behavior.
112   */
113  CORE_semaphore_Attributes   Attributes;
114  /** This element contains the current count of this semaphore. */
115  uint32_t                    count;
116}   CORE_semaphore_Control;
117
118/**
119 *  This routine initializes the semaphore based on the parameters passed.
120 *
121 *  @param[in] the_semaphore is the semaphore to initialize
122 *  @param[in] the_semaphore_attributes define the behavior of this instance
123 *  @param[in] initial_value is the initial count of the semaphore
124 */
125void _CORE_semaphore_Initialize(
126  CORE_semaphore_Control       *the_semaphore,
127  CORE_semaphore_Attributes    *the_semaphore_attributes,
128  uint32_t                      initial_value
129);
130
131/**
132 *  This routine attempts to receive a unit from the_semaphore.
133 *  If a unit is available or if the wait flag is FALSE, then the routine
134 *  returns.  Otherwise, the calling task is blocked until a unit becomes
135 *  available.
136 *
137 *  @param[in] the_semaphore is the semaphore to seize
138 *  @param[in] id is the Id of the API level Semaphore object associated
139 *         with this instance of a SuperCore Semaphore
140 *  @param[in] wait is TRUE if the calling thread is willing to wait
141 *  @param[in] timeout is the number of ticks the calling thread is willing
142 *         to wait if @a wait is TRUE.
143 */
144void _CORE_semaphore_Seize(
145  CORE_semaphore_Control  *the_semaphore,
146  Objects_Id               id,
147  boolean                  wait,
148  Watchdog_Interval        timeout
149);
150
151/**
152 *  This routine frees a unit to the semaphore.  If a task was blocked waiting
153 *  for a unit from this semaphore, then that task will be readied and the unit
154 *  given to that task.  Otherwise, the unit will be returned to the semaphore.
155 *
156 *  @param[in] the_semaphore is the semaphore to surrender
157 *  @param[in] id is the Id of the API level Semaphore object associated
158 *         with this instance of a SuperCore Semaphore
159 *  @param[in] api_semaphore_mp_support is the routine to invoke if the
160 *         thread unblocked is remote
161 *
162 *  @return an indication of whether the routine succeeded or failed
163 */
164CORE_semaphore_Status _CORE_semaphore_Surrender(
165  CORE_semaphore_Control                *the_semaphore,
166  Objects_Id                             id,
167  CORE_semaphore_API_mp_support_callout  api_semaphore_mp_support
168);
169
170/**
171 *  This routine assists in the deletion of a semaphore by flushing the
172 *  associated wait queue.
173 *
174 *  @param[in] the_semaphore is the semaphore to flush
175 *  @param[in] remote_extract_callout is the routine to invoke if the
176 *         thread unblocked is remote
177 *  @param[in] status is the status to be returned to the unblocked thread
178 */
179void _CORE_semaphore_Flush(
180  CORE_semaphore_Control         *the_semaphore,
181  Thread_queue_Flush_callout      remote_extract_callout,
182  uint32_t                        status
183);
184
185#ifndef __RTEMS_APPLICATION__
186#include <rtems/score/coresem.inl>
187#endif
188
189#ifdef __cplusplus
190}
191#endif
192
193/**@}*/
194
195#endif
196/*  end of include file */
Note: See TracBrowser for help on using the repository browser.