source: rtems/c/src/exec/score/include/rtems/score/coremutex.h @ 34a26792

4.104.114.84.95
Last change on this file since 34a26792 was e6faa6ac, checked in by Joel Sherrill <joel.sherrill@…>, on 07/06/00 at 20:01:23

Corrected call to _CORE_mutex_Seize_interrupt_blocking.

  • Property mode set to 100644
File size: 5.7 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.OARcorp.com/rtems/license.html.
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 
30/*
31 *  The following type defines the callout which the API provides
32 *  to support global/multiprocessor operations on mutexes.
33 */
34 
35typedef void ( *CORE_mutex_API_mp_support_callout )(
36                 Thread_Control *,
37                 Objects_Id
38             );
39
40/*
41 *  Blocking disciplines for a mutex.
42 */
43
44typedef enum {
45  CORE_MUTEX_DISCIPLINES_FIFO,
46  CORE_MUTEX_DISCIPLINES_PRIORITY,
47  CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT,
48  CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING
49}   CORE_mutex_Disciplines;
50
51/*
52 *  Mutex handler return statuses.
53 */
54 
55typedef enum {
56  CORE_MUTEX_STATUS_SUCCESSFUL,
57  CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
58  CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
59  CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
60  CORE_MUTEX_WAS_DELETED,
61  CORE_MUTEX_TIMEOUT,
62  CORE_MUTEX_STATUS_CEILING_VIOLATED
63}   CORE_mutex_Status;
64
65/*
66 *  Mutex lock nesting behavior
67 *
68 *  CORE_MUTEX_NESTING_ACQUIRES:
69 *    This sequence has no blocking or errors:
70 *         lock(m)
71 *         lock(m)
72 *         unlock(m)
73 *         unlock(m)
74 *
75 *  CORE_MUTEX_NESTING_IS_ERROR
76 *    This sequence returns an error at the indicated point:
77 *        lock(m)
78 *        lock(m)   - already locked error
79 *        unlock(m)
80 *
81 *  CORE_MUTEX_NESTING_BLOCKS
82 *    This sequence performs as indicated:
83 *        lock(m)
84 *        lock(m)   - deadlocks or timeouts
85 *        unlock(m) - releases
86 */
87
88typedef enum {
89  CORE_MUTEX_NESTING_ACQUIRES,
90  CORE_MUTEX_NESTING_IS_ERROR,
91  CORE_MUTEX_NESTING_BLOCKS
92}  CORE_mutex_Nesting_behaviors;
93 
94/*
95 *  Locked and unlocked values
96 */
97
98#define CORE_MUTEX_UNLOCKED 1
99#define CORE_MUTEX_LOCKED   0
100
101/*
102 *  The following defines the control block used to manage the
103 *  attributes of each mutex.
104 */
105
106typedef struct {
107  CORE_mutex_Nesting_behaviors lock_nesting_behavior;
108  boolean                      only_owner_release;
109  CORE_mutex_Disciplines       discipline;
110  Priority_Control             priority_ceiling;
111}   CORE_mutex_Attributes;
112 
113/*
114 *  The following defines the control block used to manage each mutex.
115 */
116 
117typedef struct {
118  Thread_queue_Control    Wait_queue;
119  CORE_mutex_Attributes   Attributes;
120  unsigned32              lock;
121  unsigned32              nest_count;
122  unsigned32              blocked_count;
123  Thread_Control         *holder;
124  Objects_Id              holder_id;
125}   CORE_mutex_Control;
126
127/*
128 *  _CORE_mutex_Initialize
129 *
130 *  DESCRIPTION:
131 *
132 *  This routine initializes the mutex based on the parameters passed.
133 */
134
135void _CORE_mutex_Initialize(
136  CORE_mutex_Control           *the_mutex,
137  Objects_Classes               the_class,
138  CORE_mutex_Attributes        *the_mutex_attributes,
139  unsigned32                    initial_lock,
140  Thread_queue_Extract_callout  proxy_extract_callout
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
157RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
158  CORE_mutex_Control  *the_mutex,
159  ISR_Level           *level_p
160);
161
162void _CORE_mutex_Seize_interrupt_blocking(
163  CORE_mutex_Control  *the_mutex,
164  Watchdog_Interval    timeout
165);
166
167#define _CORE_mutex_Seize( \
168  _the_mutex, _id, _wait, _timeout, _level ) \
169  do { \
170    if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
171      if ( !_wait ) { \
172        _ISR_Enable( _level ); \
173        _Thread_Executing->Wait.return_code = \
174          CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT; \
175      } else { \
176        _Thread_queue_Enter_critical_section( &(_the_mutex)->Wait_queue ); \
177        _Thread_Executing->Wait.queue = &(_the_mutex)->Wait_queue; \
178        _Thread_Executing->Wait.id    = _id; \
179        _Thread_Disable_dispatch(); \
180        _ISR_Enable( _level ); \
181       _CORE_mutex_Seize_interrupt_blocking( _the_mutex, _timeout ); \
182      } \
183    } \
184  } while (0)
185
186/*
187 *  _CORE_mutex_Surrender
188 *
189 *  DESCRIPTION:
190 *
191 *  This routine frees a unit to the mutex.  If a task was blocked waiting for
192 *  a unit from this mutex, then that task will be readied and the unit
193 *  given to that task.  Otherwise, the unit will be returned to the mutex.
194 */
195
196CORE_mutex_Status _CORE_mutex_Surrender(
197  CORE_mutex_Control                *the_mutex,
198  Objects_Id                         id,
199  CORE_mutex_API_mp_support_callout  api_mutex_mp_support
200);
201 
202/*
203 *  _CORE_mutex_Flush
204 *
205 *  DESCRIPTION:
206 *
207 *  This routine assists in the deletion of a mutex by flushing the associated
208 *  wait queue.
209 */
210 
211void _CORE_mutex_Flush(
212  CORE_mutex_Control         *the_mutex,
213  Thread_queue_Flush_callout  remote_extract_callout,
214  unsigned32                  status
215);
216 
217#ifndef __RTEMS_APPLICATION__
218#include <rtems/score/coremutex.inl>
219#endif
220
221#ifdef __cplusplus
222}
223#endif
224 
225#endif
226/*  end of include file */
227
Note: See TracBrowser for help on using the repository browser.