source: rtems/cpukit/score/include/rtems/score/coresem.h @ f5c9b89

Last change on this file since f5c9b89 was f5c9b89, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 30, 2006 at 10:21:07 PM

2006-10-30 Joel Sherrill <joel@…>

PR 841/rtems

  • itron/inline/rtems/itron/semaphore.inl, itron/macros/rtems/itron/semaphore.inl, itron/src/twai_sem.c, posix/include/rtems/posix/semaphore.h, posix/inline/rtems/posix/semaphore.inl, posix/src/semaphorewaitsupp.c, posix/src/semtimedwait.c, posix/src/semwait.c, rtems/src/semobtain.c, rtems/src/semtranslatereturncode.c, score/include/rtems/score/coresem.h, score/src/coresemseize.c: Make sem_timedwait more conformant to Open Group specification.
  • Property mode set to 100644
File size: 7.3 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  /** This status indicates that the semaphore was not immediately
87   *  available and the caller passed a bad timeout value to the API
88   *  routine.  In this case, the API required that the validity check
89   *  for the timeout occur after the check that the semaphore was immediately
90   *  available.
91   */
92  CORE_SEMAPHORE_BAD_TIMEOUT_VALUE
93}   CORE_semaphore_Status;
94
95/**
96 *  The following defines the control block used to manage the
97 *  attributes of each semaphore.
98 */
99typedef struct {
100  /** This element indicates the maximum count this semaphore may have. */
101  uint32_t                    maximum_count;
102  /** This field indicates whether threads waiting on the semaphore block in
103   *  FIFO or priority order.
104   */
105  CORE_semaphore_Disciplines  discipline;
106}   CORE_semaphore_Attributes;
107
108/**
109 *  The following defines the control block used to manage each
110 *  counting semaphore.
111 */
112typedef struct {
113  /** This field is the Waiting Queue used to manage the set of tasks
114   *  which are blocked waiting to obtain the semaphore.
115   */
116  Thread_queue_Control        Wait_queue;
117  /** This element is the set of attributes which define this instance's
118   *  behavior.
119   */
120  CORE_semaphore_Attributes   Attributes;
121  /** This element contains the current count of this semaphore. */
122  uint32_t                    count;
123}   CORE_semaphore_Control;
124
125/**
126 *  The following enumerated type is the set of blocking options
127 *  available to seize operation.
128 */
129typedef enum {
130  /** This value indicates that the caller does not wish to block. */
131  CORE_SEMAPHORE_NO_WAIT,
132  /** This value indicates that the caller is willing to block forever. */
133  CORE_SEMAPHORE_BLOCK_FOREVER,
134  /** This value indicates that the caller is blocking with a timeout. */
135  CORE_SEMAPHORE_BLOCK_WITH_TIMEOUT,
136  /** This value indicates that the caller wanted to block but passed in
137   *  a bad timeout value to the API. Unfortunately, this is a weird case
138   *  where the timeout bad error is required to be generated only if
139   *  the semaphore is not available.
140   */
141  CORE_SEMAPHORE_BAD_TIMEOUT
142} Core_semaphore_Blocking_option;
143
144/**
145 *  This routine initializes the semaphore based on the parameters passed.
146 *
147 *  @param[in] the_semaphore is the semaphore to initialize
148 *  @param[in] the_semaphore_attributes define the behavior of this instance
149 *  @param[in] initial_value is the initial count of the semaphore
150 */
151void _CORE_semaphore_Initialize(
152  CORE_semaphore_Control       *the_semaphore,
153  CORE_semaphore_Attributes    *the_semaphore_attributes,
154  uint32_t                      initial_value
155);
156
157/**
158 *  This routine attempts to receive a unit from the_semaphore.
159 *  If a unit is available or if the wait flag is FALSE, then the routine
160 *  returns.  Otherwise, the calling task is blocked until a unit becomes
161 *  available.
162 *
163 *  @param[in] the_semaphore is the semaphore to seize
164 *  @param[in] id is the Id of the API level Semaphore object associated
165 *         with this instance of a SuperCore Semaphore
166 *  @param[in] wait is the blocking mode
167 *  @param[in] timeout is the number of ticks the calling thread is willing
168 *         to wait if @a wait is TRUE.
169 */
170void _CORE_semaphore_Seize(
171  CORE_semaphore_Control         *the_semaphore,
172  Objects_Id                      id,
173  Core_semaphore_Blocking_option  wait,
174  Watchdog_Interval               timeout
175);
176
177/**
178 *  This routine frees a unit to the semaphore.  If a task was blocked waiting
179 *  for a unit from this semaphore, then that task will be readied and the unit
180 *  given to that task.  Otherwise, the unit will be returned to the semaphore.
181 *
182 *  @param[in] the_semaphore is the semaphore to surrender
183 *  @param[in] id is the Id of the API level Semaphore object associated
184 *         with this instance of a SuperCore Semaphore
185 *  @param[in] api_semaphore_mp_support is the routine to invoke if the
186 *         thread unblocked is remote
187 *
188 *  @return an indication of whether the routine succeeded or failed
189 */
190CORE_semaphore_Status _CORE_semaphore_Surrender(
191  CORE_semaphore_Control                *the_semaphore,
192  Objects_Id                             id,
193  CORE_semaphore_API_mp_support_callout  api_semaphore_mp_support
194);
195
196/**
197 *  This routine assists in the deletion of a semaphore by flushing the
198 *  associated wait queue.
199 *
200 *  @param[in] the_semaphore is the semaphore to flush
201 *  @param[in] remote_extract_callout is the routine to invoke if the
202 *         thread unblocked is remote
203 *  @param[in] status is the status to be returned to the unblocked thread
204 */
205void _CORE_semaphore_Flush(
206  CORE_semaphore_Control         *the_semaphore,
207  Thread_queue_Flush_callout      remote_extract_callout,
208  uint32_t                        status
209);
210
211#ifndef __RTEMS_APPLICATION__
212#include <rtems/score/coresem.inl>
213#endif
214
215#ifdef __cplusplus
216}
217#endif
218
219/**@}*/
220
221#endif
222/*  end of include file */
Note: See TracBrowser for help on using the repository browser.