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

4.104.114.84.95
Last change on this file since ef9505a9 was ef9505a9, checked in by Joel Sherrill <joel.sherrill@…>, on 07/01/02 at 22:30:12

2002-07-01 Joel Sherrill <joel@…>

  • Mega patch merge to change the format of the object IDs to loosen the dependency between the SCORE and the various APIs. There was considerable work to simplify the object name management and it appears that the name_table field is no longer needed. This patch also includes the addition of the internal mutex which is currently only used to protect some types of allocation and deallocation. This significantly can reduce context switch latency under certain circumstances. In particular, some heap/region operations were O(n) and had dispatching disabled. This should help enormously. With this merge, the patch is not as clean as it should be. In particular, the documentation has not been modified to reflect the new object ID layout, the IDs in the test screens are not updated, and _Objects_Get_information needs to be a real routine not inlined. As part of this patch a lot of MP code for thread/proxy blocking was made conditional and cleaned up.
  • include/Makefile.am, include/rtems/score/coremsg.h, include/rtems/score/coremutex.h, include/rtems/score/coresem.h, include/rtems/score/object.h, include/rtems/score/threadq.h, inline/rtems/score/object.inl, inline/rtems/score/thread.inl, macros/rtems/score/object.inl, src/Makefile.am, src/coremsg.c, src/coremutex.c, src/coresem.c, src/mpci.c, src/objectcomparenameraw.c, src/objectextendinformation.c, src/objectinitializeinformation.c, src/objectnametoid.c, src/thread.c, src/threadclose.c, src/threadget.c, src/threadq.c, src/threadqextractwithproxy.c: Modified as part of above.
  • include/rtems/score/apimutex.h, src/objectgetnoprotection.c: New files.
  • Property mode set to 100644
File size: 5.6 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  CORE_mutex_Attributes        *the_mutex_attributes,
138  unsigned32                    initial_lock
139);
140 
141/*
142 *  _CORE_mutex_Seize
143 *
144 *  DESCRIPTION:
145 *
146 *  This routine attempts to receive a unit from the_mutex.
147 *  If a unit is available or if the wait flag is FALSE, then the routine
148 *  returns.  Otherwise, the calling task is blocked until a unit becomes
149 *  available.
150 *
151 *  NOTE:  For performance reasons, this routine is implemented as
152 *         a macro that uses two support routines.
153 */
154
155#ifndef __RTEMS_APPLICATION__
156RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock(
157  CORE_mutex_Control  *the_mutex,
158  ISR_Level           *level_p
159);
160
161void _CORE_mutex_Seize_interrupt_blocking(
162  CORE_mutex_Control  *the_mutex,
163  Watchdog_Interval    timeout
164);
165
166#define _CORE_mutex_Seize( \
167  _the_mutex, _id, _wait, _timeout, _level ) \
168  do { \
169    if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
170      if ( !_wait ) { \
171        _ISR_Enable( _level ); \
172        _Thread_Executing->Wait.return_code = \
173          CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT; \
174      } else { \
175        _Thread_queue_Enter_critical_section( &(_the_mutex)->Wait_queue ); \
176        _Thread_Executing->Wait.queue = &(_the_mutex)->Wait_queue; \
177        _Thread_Executing->Wait.id    = _id; \
178        _Thread_Disable_dispatch(); \
179        _ISR_Enable( _level ); \
180       _CORE_mutex_Seize_interrupt_blocking( _the_mutex, _timeout ); \
181      } \
182    } \
183  } while (0)
184
185/*
186 *  _CORE_mutex_Surrender
187 *
188 *  DESCRIPTION:
189 *
190 *  This routine frees a unit to the mutex.  If a task was blocked waiting for
191 *  a unit from this mutex, then that task will be readied and the unit
192 *  given to that task.  Otherwise, the unit will be returned to the mutex.
193 */
194
195CORE_mutex_Status _CORE_mutex_Surrender(
196  CORE_mutex_Control                *the_mutex,
197  Objects_Id                         id,
198  CORE_mutex_API_mp_support_callout  api_mutex_mp_support
199);
200 
201/*
202 *  _CORE_mutex_Flush
203 *
204 *  DESCRIPTION:
205 *
206 *  This routine assists in the deletion of a mutex by flushing the associated
207 *  wait queue.
208 */
209 
210void _CORE_mutex_Flush(
211  CORE_mutex_Control         *the_mutex,
212  Thread_queue_Flush_callout  remote_extract_callout,
213  unsigned32                  status
214);
215 
216#include <rtems/score/coremutex.inl>
217#endif
218
219#ifdef __cplusplus
220}
221#endif
222 
223#endif
224/*  end of include file */
225
Note: See TracBrowser for help on using the repository browser.