source: rtems/cpukit/score/include/rtems/score/coremutex.h @ d6154c7

4.104.114.84.95
Last change on this file since d6154c7 was d6154c7, checked in by Ralf Corsepius <ralf.corsepius@…>, on Mar 29, 2004 at 4:41:13 PM

2004-03-29 Ralf Corsepius <ralf_corsepius@…>

  • score/include/rtems/debug.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.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/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/coremsg.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/priority.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/inline/rtems/score/userext.inl, score/inline/rtems/score/wkspace.inl, score/macros/rtems/score/address.inl, score/macros/rtems/score/heap.inl, score/macros/rtems/score/object.inl, score/macros/rtems/score/priority.inl, score/macros/rtems/score/userext.inl: Convert to using c99 fixed size types.
  • Property mode set to 100644
File size: 5.9 KB
Line 
1/*  mutex.h
2 *
3 *  This include file contains all the constants and structures associated
4 *  with the Mutex Handler.  A mutex is an enhanced version of the standard
5 *  Dijkstra binary semaphore used to provide synchronization and mutual
6 *  exclusion capabilities.
7 *
8 *  COPYRIGHT (c) 1989-1999.
9 *  On-Line Applications Research Corporation (OAR).
10 *
11 *  The license and distribution terms for this file may be
12 *  found in the file LICENSE in this distribution or at
13 *  http://www.rtems.com/license/LICENSE.
14 *
15 *  $Id$
16 */
17 
18#ifndef __RTEMS_CORE_MUTEX_h
19#define __RTEMS_CORE_MUTEX_h
20 
21#ifdef __cplusplus
22extern "C" {
23#endif
24
25#include <rtems/score/thread.h>
26#include <rtems/score/threadq.h>
27#include <rtems/score/priority.h>
28#include <rtems/score/watchdog.h>
29#include <rtems/score/interr.h>
30#include <rtems/score/sysstate.h>
31 
32/*
33 *  The following type defines the callout which the API provides
34 *  to support global/multiprocessor operations on mutexes.
35 */
36 
37typedef void ( *CORE_mutex_API_mp_support_callout )(
38                 Thread_Control *,
39                 Objects_Id
40             );
41
42/*
43 *  Blocking disciplines for a mutex.
44 */
45
46typedef enum {
47  CORE_MUTEX_DISCIPLINES_FIFO,
48  CORE_MUTEX_DISCIPLINES_PRIORITY,
49  CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT,
50  CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING
51}   CORE_mutex_Disciplines;
52
53/*
54 *  Mutex handler return statuses.
55 */
56 
57typedef enum {
58  CORE_MUTEX_STATUS_SUCCESSFUL,
59  CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
60  CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
61  CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
62  CORE_MUTEX_WAS_DELETED,
63  CORE_MUTEX_TIMEOUT,
64  CORE_MUTEX_STATUS_CEILING_VIOLATED
65}   CORE_mutex_Status;
66
67/*
68 *  Mutex lock nesting behavior
69 *
70 *  CORE_MUTEX_NESTING_ACQUIRES:
71 *    This sequence has no blocking or errors:
72 *         lock(m)
73 *         lock(m)
74 *         unlock(m)
75 *         unlock(m)
76 *
77 *  CORE_MUTEX_NESTING_IS_ERROR
78 *    This sequence returns an error at the indicated point:
79 *        lock(m)
80 *        lock(m)   - already locked error
81 *        unlock(m)
82 *
83 *  CORE_MUTEX_NESTING_BLOCKS
84 *    This sequence performs as indicated:
85 *        lock(m)
86 *        lock(m)   - deadlocks or timeouts
87 *        unlock(m) - releases
88 */
89
90typedef enum {
91  CORE_MUTEX_NESTING_ACQUIRES,
92  CORE_MUTEX_NESTING_IS_ERROR,
93  CORE_MUTEX_NESTING_BLOCKS
94}  CORE_mutex_Nesting_behaviors;
95 
96/*
97 *  Locked and unlocked values
98 */
99
100#define CORE_MUTEX_UNLOCKED 1
101#define CORE_MUTEX_LOCKED   0
102
103/*
104 *  The following defines the control block used to manage the
105 *  attributes of each mutex.
106 */
107
108typedef struct {
109  CORE_mutex_Nesting_behaviors lock_nesting_behavior;
110  boolean                      only_owner_release;
111  CORE_mutex_Disciplines       discipline;
112  Priority_Control             priority_ceiling;
113}   CORE_mutex_Attributes;
114 
115/*
116 *  The following defines the control block used to manage each mutex.
117 */
118 
119typedef struct {
120  Thread_queue_Control    Wait_queue;
121  CORE_mutex_Attributes   Attributes;
122  uint32_t                lock;
123  uint32_t                nest_count;
124  uint32_t                blocked_count;
125  Thread_Control         *holder;
126  Objects_Id              holder_id;
127}   CORE_mutex_Control;
128
129/*
130 *  _CORE_mutex_Initialize
131 *
132 *  DESCRIPTION:
133 *
134 *  This routine initializes the mutex based on the parameters passed.
135 */
136
137void _CORE_mutex_Initialize(
138  CORE_mutex_Control           *the_mutex,
139  CORE_mutex_Attributes        *the_mutex_attributes,
140  uint32_t                      initial_lock
141);
142 
143/*
144 *  _CORE_mutex_Seize
145 *
146 *  DESCRIPTION:
147 *
148 *  This routine attempts to receive a unit from the_mutex.
149 *  If a unit is available or if the wait flag is FALSE, then the routine
150 *  returns.  Otherwise, the calling task is blocked until a unit becomes
151 *  available.
152 *
153 *  NOTE:  For performance reasons, this routine is implemented as
154 *         a macro that uses two support routines.
155 */
156
157
158#ifndef __RTEMS_APPLICATION__
159RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
160  CORE_mutex_Control  *the_mutex,
161  ISR_Level           *level_p
162);
163
164void _CORE_mutex_Seize_interrupt_blocking(
165  CORE_mutex_Control  *the_mutex,
166  Watchdog_Interval    timeout
167);
168
169#define _CORE_mutex_Seize( \
170  _the_mutex, _id, _wait, _timeout, _level ) \
171  do { \
172        if ( _Thread_Dispatch_disable_level \
173                && (_wait) \
174                && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
175           ) { \
176                _Internal_error_Occurred( \
177                                                        INTERNAL_ERROR_CORE, \
178                                                        FALSE, \
179                                                        18 /* called from wrong environment */); \
180        } \
181    if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
182      if ( !_wait ) { \
183        _ISR_Enable( _level ); \
184        _Thread_Executing->Wait.return_code = \
185          CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT; \
186      } else { \
187        _Thread_queue_Enter_critical_section( &(_the_mutex)->Wait_queue ); \
188        _Thread_Executing->Wait.queue = &(_the_mutex)->Wait_queue; \
189        _Thread_Executing->Wait.id    = _id; \
190        _Thread_Disable_dispatch(); \
191        _ISR_Enable( _level ); \
192       _CORE_mutex_Seize_interrupt_blocking( _the_mutex, _timeout ); \
193      } \
194    } \
195  } while (0)
196
197/*
198 *  _CORE_mutex_Surrender
199 *
200 *  DESCRIPTION:
201 *
202 *  This routine frees a unit to the mutex.  If a task was blocked waiting for
203 *  a unit from this mutex, then that task will be readied and the unit
204 *  given to that task.  Otherwise, the unit will be returned to the mutex.
205 */
206
207CORE_mutex_Status _CORE_mutex_Surrender(
208  CORE_mutex_Control                *the_mutex,
209  Objects_Id                         id,
210  CORE_mutex_API_mp_support_callout  api_mutex_mp_support
211);
212 
213/*
214 *  _CORE_mutex_Flush
215 *
216 *  DESCRIPTION:
217 *
218 *  This routine assists in the deletion of a mutex by flushing the associated
219 *  wait queue.
220 */
221 
222void _CORE_mutex_Flush(
223  CORE_mutex_Control         *the_mutex,
224  Thread_queue_Flush_callout  remote_extract_callout,
225  uint32_t                    status
226);
227 
228#include <rtems/score/coremutex.inl>
229#endif
230
231#ifdef __cplusplus
232}
233#endif
234 
235#endif
236/*  end of include file */
237
Note: See TracBrowser for help on using the repository browser.