source: rtems/cpukit/score/include/rtems/score/coremutex.h @ 66a9239a

4.104.114.9
Last change on this file since 66a9239a was 66a9239a, checked in by Ralf Corsepius <ralf.corsepius@…>, on Jun 30, 2008 at 3:03:03 PM

Rename STRICT_ORDER_MUTEX to RTEMS_STRICT_ORDER_MUTEX.

  • Property mode set to 100644
File size: 14.7 KB
Line 
1/**
2 *  @file  rtems/score/coremutex.h
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the Mutex Handler.  A mutex is an enhanced version of the standard
6 *  Dijkstra binary semaphore used to provide synchronization and mutual
7 *  exclusion capabilities.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2008.
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_COREMUTEX_H
22#define _RTEMS_SCORE_COREMUTEX_H
23
24
25/**
26 *  @defgroup ScoreMutex Mutex Handler
27 *
28 *  This handler encapsulates functionality which provides the foundation
29 *  Mutex services used in all of the APIs supported by RTEMS.
30 */
31/**@{*/
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37#include <rtems/score/thread.h>
38#include <rtems/score/threadq.h>
39#include <rtems/score/priority.h>
40#include <rtems/score/watchdog.h>
41#include <rtems/score/interr.h>
42#include <rtems/score/sysstate.h>
43
44
45/**
46 *  @brief MP Support Callback Prototype
47 *
48 *  The following type defines the callout which the API provides
49 *  to support global/multiprocessor operations on mutexes.
50 */
51typedef void ( *CORE_mutex_API_mp_support_callout )(
52                 Thread_Control *,
53                 Objects_Id
54             );
55
56/**
57 *  @brief Blocking Disciplines Enumerated Type
58 *
59 *  This enumerated type defines the blocking disciplines for a mutex.
60 */
61typedef enum {
62  /** This specifies that threads will wait for the mutex in FIFO order. */
63  CORE_MUTEX_DISCIPLINES_FIFO,
64  /** This specifies that threads will wait for the mutex in priority order.  */
65  CORE_MUTEX_DISCIPLINES_PRIORITY,
66  /** This specifies that threads will wait for the mutex in priority order.
67   *  Additionally, the Priority Inheritance Protocol will be in effect.
68   */
69  CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT,
70  /** This specifies that threads will wait for the mutex in priority order.
71   *  Additionally, the Priority Ceiling Protocol will be in effect.
72   */
73  CORE_MUTEX_DISCIPLINES_PRIORITY_CEILING
74}   CORE_mutex_Disciplines;
75 
76/**
77 *  @brief Mutex method return statuses
78 *
79 *  This enumerated type defines the possible Mutex handler return statuses.
80 */
81typedef enum {
82  /** This status indicates that the operation completed successfully. */
83  CORE_MUTEX_STATUS_SUCCESSFUL,
84  /** This status indicates that the calling task did not want to block
85   *  and the operation was unable to complete immediately because the
86   *  resource was unavailable.
87   */
88  CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT,
89  /** This status indicates that an attempt was made to relock a mutex
90   *  for which nesting is not configured.
91   */
92  CORE_MUTEX_STATUS_NESTING_NOT_ALLOWED,
93  /** This status indicates that an attempt was made to release a mutex
94   *  by a thread other than the thread which locked it.
95   */
96  CORE_MUTEX_STATUS_NOT_OWNER_OF_RESOURCE,
97  /** This status indicates that the thread was blocked waiting for an
98   *  operation to complete and the mutex was deleted.
99   */
100  CORE_MUTEX_WAS_DELETED,
101  /** This status indicates that the calling task was willing to block
102   *  but the operation was unable to complete within the time allotted
103   *  because the resource never became available.
104   */
105  CORE_MUTEX_TIMEOUT,
106
107#ifdef __RTEMS_STRICT_ORDER_MUTEX__
108  /** This status indicates that a thread not release the mutex which has
109   *  the priority inheritance property in a right order.
110   */
111  CORE_MUTEX_RELEASE_NOT_ORDER,
112#endif
113
114  /** This status indicates that a thread of logically greater importance
115   *  than the ceiling priority attempted to lock this mutex.
116   */
117  CORE_MUTEX_STATUS_CEILING_VIOLATED,
118
119}   CORE_mutex_Status;
120
121/**
122 *  @brief Core Mutex Last Status
123 *
124 *  This is the last status value.
125 */
126#define CORE_MUTEX_STATUS_LAST CORE_MUTEX_STATUS_CEILING_VIOLATED
127
128/**
129 *  @brief Mutex Lock Nesting Behavior Enumeration
130 *
131 *  This enumerated type defines the possible behaviors for
132 *  lock nesting.
133 */
134typedef enum {
135  /**
136   *    This sequence has no blocking or errors:
137   *
138   *         + lock(m)
139   *         + lock(m)
140   *         + unlock(m)
141   *         + unlock(m)
142   */
143  CORE_MUTEX_NESTING_ACQUIRES,
144  /**
145   *    This sequence returns an error at the indicated point:
146   *
147   *        + lock(m)
148   *        + lock(m)   - already locked error
149   *        + unlock(m)
150   */
151  CORE_MUTEX_NESTING_IS_ERROR,
152  /**
153   *    This sequence performs as indicated:
154   *        + lock(m)
155   *        + lock(m)   - deadlocks or timeouts
156   *        + unlock(m) - releases
157   */
158  CORE_MUTEX_NESTING_BLOCKS
159}  CORE_mutex_Nesting_behaviors;
160
161/**
162 *  This is the value of a mutex when it is unlocked.
163 */
164#define CORE_MUTEX_UNLOCKED 1
165
166/**
167 *  This is the value of a mutex when it is locked.
168 */
169#define CORE_MUTEX_LOCKED   0
170
171/**
172 *  @brief Core Mutex Attributes
173 *
174 *  The following defines the control block used to manage the
175 *  attributes of each mutex.
176 */
177typedef struct {
178  /** This field determines what the behavior of this mutex instance will
179   *  be when attempting to acquire the mutex when it is already locked.
180   */
181  CORE_mutex_Nesting_behaviors lock_nesting_behavior;
182  /** When this field is TRUE, then only the thread that locked the mutex
183   *  is allowed to unlock it.
184   */
185  boolean                      only_owner_release;
186  /** This field indicates whether threads waiting on the mutex block in
187   *  FIFO or priority order.
188   */
189  CORE_mutex_Disciplines       discipline;
190  /** This field contains the ceiling priority to be used if that protocol
191   *  is selected.
192   */
193  Priority_Control             priority_ceiling;
194}   CORE_mutex_Attributes;
195
196#ifdef __RTEMS_STRICT_ORDER_MUTEX__
197/*@beief Core Mutex Lock_Chain Struct
198 *
199 * The following defines the control block used to manage lock chain of
200 * priority inheritance mutex.
201 */
202  typedef struct{
203    /** This field is a chian of locked mutex by a thread,new mutex will
204     *  be added to the head of queue, and the mutex which will be released
205     *  must be the head of queue.
206     */
207    Chain_Node                lock_queue;
208    /** This field is the priority of thread before locking this mutex
209     *
210     */
211    Priority_Control          priority_before;
212  }  CORE_mutex_order_list;
213#endif
214
215/**
216 *  @brief Core Mutex Control Structure
217 *
218 *  The following defines the control block used to manage each mutex.
219 */
220typedef struct {
221  /** This field is the Waiting Queue used to manage the set of tasks
222   *  which are blocked waiting to lock the mutex.
223   */
224  Thread_queue_Control    Wait_queue;
225  /** This element is the set of attributes which define this instance's
226   *  behavior.
227   */
228  CORE_mutex_Attributes   Attributes;
229  /** This element contains the current state of the mutex.
230   */
231  uint32_t                lock;
232  /** This element contains the number of times the mutex has been acquired
233   *  nested.  This must be zero (0) before the mutex is actually unlocked.
234   */
235  uint32_t                nest_count;
236  /** This is the number of waiting threads. */
237  uint32_t                blocked_count;
238  /** This element points to the thread which is currently holding this mutex.
239   *  The holder is the last thread to successfully lock the mutex and which
240   *  has not unlocked it.  If the thread is not locked, there is no holder.
241   */
242  Thread_Control         *holder;
243  /** This element contains the object Id of the holding thread.  */
244  Objects_Id              holder_id;
245#ifdef __RTEMS_STRICT_ORDER_MUTEX__
246  /** This field is used to manipulate the priority inheritance mutex queue*/
247  CORE_mutex_order_list   queue;
248#endif
249 
250}   CORE_mutex_Control;
251
252/**
253 *  @brief Initialize a Core Mutex
254 *
255 *  This routine initializes the mutex based on the parameters passed.
256 *
257 *  @param[in] the_mutex is the mutex to initalize
258 *  @param[in] the_mutex_attributes is the attributes associated with this
259 *         mutex instance
260 *  @param[in] initial_lock is the initial value of the mutex
261 */
262void _CORE_mutex_Initialize(
263  CORE_mutex_Control           *the_mutex,
264  CORE_mutex_Attributes        *the_mutex_attributes,
265  uint32_t                      initial_lock
266);
267
268#ifndef __RTEMS_APPLICATION__
269/**
270 *  @brief Seize Mutex with Quick Success Path
271 *
272 *  This routine attempts to receive a unit from the_mutex.
273 *  If a unit is available or if the wait flag is FALSE, then the routine
274 *  returns.  Otherwise, the calling task is blocked until a unit becomes
275 *  available.
276 *
277 *  @param[in] the_mutex is the mutex to attempt to lock
278 *  @param[in] level_p is the interrupt level holder
279 *
280 *  @return This routine returns 0 if "trylock" can resolve whether or not
281 *  the mutex is immediately obtained or there was an error attempting to
282 *  get it.  It returns 1 to indicate that the caller cannot obtain
283 *  the mutex and will have to block to do so.
284 *
285 *  @note  For performance reasons, this routine is implemented as
286 *         a macro that uses two support routines.
287 */
288
289RTEMS_INLINE_ROUTINE int _CORE_mutex_Seize_interrupt_trylock_body(
290  CORE_mutex_Control  *the_mutex,
291  ISR_Level           *level_p
292);
293
294#if defined(__RTEMS_DO_NOT_INLINE_CORE_MUTEX_SEIZE__)
295  /**
296   *  When doing test coverage analysis or trying to minimize the code
297   *  space for RTEMS, it is often helpful to not inline this method
298   *  multiple times.  It is fairly large and has a high branch complexity
299   *  which makes it harder to get full binary test coverage.
300   *
301   *  @param[in] the_mutex will attempt to lock
302   *  @param[in] level_p is the interrupt level holder
303   */
304  int _CORE_mutex_Seize_interrupt_trylock(
305    CORE_mutex_Control  *the_mutex,
306    ISR_Level           *level_p
307  );
308#else
309  /**
310   *  The default is to favor speed and inlining this definitely saves
311   *  a few instructions.  This is very important for mutex performance.
312   * 
313   *  @param[in] _mutex will attempt to lock
314   *  @param[in] _level_p is the interrupt level holder
315   */
316  #define _CORE_mutex_Seize_interrupt_trylock( _mutex, _level_p ) \
317     _CORE_mutex_Seize_interrupt_trylock_body( _mutex, _level_p )
318#endif
319
320/**
321 *  @brief Seize Mutex with Blocking
322 *
323 *  This routine performs the blocking portion of a mutex obtain.
324 *  It is an actual subroutine and is not implemented as something
325 *  that may be inlined.
326 *
327 *  @param[in] the_mutex is the mutex to attempt to lock
328 *  @param[in] timeout is the maximum number of ticks to block
329 */
330void _CORE_mutex_Seize_interrupt_blocking(
331  CORE_mutex_Control  *the_mutex,
332  Watchdog_Interval    timeout
333);
334
335/**
336 *  @brief Sieze Interrupt Wrapper
337 *
338 *  This routine attempts to obtain the mutex.  If the mutex is available,
339 *  then it will return immediately.  Otherwise, it will invoke the
340 *  support routine @a _Core_mutex_Seize_interrupt_blocking.
341 *
342 *  @param[in] _the_mutex is the mutex to attempt to lock
343 *  @param[in] _id is the Id of the owning API level Semaphore object
344 *  @param[in] _wait is TRUE if the thread is willing to wait
345 *  @param[in] _timeout is the maximum number of ticks to block
346 *  @param[in] _level is a temporary variable used to contain the ISR
347 *         disable level cookie
348 *
349 *  @note If the mutex is called from an interrupt service routine,
350 *        with context switching disabled, or before multitasking,
351 *        then a fatal error is generated.
352 *
353 *  The logic on this routine is as follows:
354 *
355 *  * If incorrect system state
356 *      return an error
357 *  * If mutex is available without any contention or blocking
358 *      obtain it with interrupts disabled and returned
359 *  * If the caller is willing to wait
360 *      then they are blocked.
361 */
362
363#define _CORE_mutex_Seize_body( \
364  _the_mutex, _id, _wait, _timeout, _level ) \
365  do { \
366    if ( _Thread_Dispatch_disable_level \
367        && (_wait) \
368        && (_System_state_Get() >= SYSTEM_STATE_BEGIN_MULTITASKING ) \
369       ) { \
370        _Internal_error_Occurred( \
371           INTERNAL_ERROR_CORE, \
372           FALSE, \
373           INTERNAL_ERROR_MUTEX_OBTAIN_FROM_BAD_STATE \
374           ); \
375    } \
376    if ( _CORE_mutex_Seize_interrupt_trylock( _the_mutex, &_level ) ) {  \
377      if ( !_wait ) { \
378        _ISR_Enable( _level ); \
379        _Thread_Executing->Wait.return_code = \
380          CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT; \
381      } else { \
382        _Thread_queue_Enter_critical_section( &(_the_mutex)->Wait_queue ); \
383        _Thread_Executing->Wait.queue = &(_the_mutex)->Wait_queue; \
384        _Thread_Executing->Wait.id    = _id; \
385        _Thread_Disable_dispatch(); \
386        _ISR_Enable( _level ); \
387       _CORE_mutex_Seize_interrupt_blocking( _the_mutex, _timeout ); \
388      } \
389    } \
390  } while (0)
391
392/**
393 *  This method is used to obtain a core mutex.
394 *
395 *  @param[in] _the_mutex is the mutex to attempt to lock
396 *  @param[in] _id is the Id of the owning API level Semaphore object
397 *  @param[in] _wait is TRUE if the thread is willing to wait
398 *  @param[in] _timeout is the maximum number of ticks to block
399 *  @param[in] _level is a temporary variable used to contain the ISR
400 *         disable level cookie
401 */
402#if defined(__RTEMS_DO_NOT_INLINE_CORE_MUTEX_SEIZE__)
403  void _CORE_mutex_Seize(
404    CORE_mutex_Control  *_the_mutex,
405    Objects_Id           _id,
406    boolean              _wait,
407    Watchdog_Interval    _timeout,
408    ISR_Level            _level
409  );
410#else
411  #define _CORE_mutex_Seize( _the_mutex, _id, _wait, _timeout, _level ) \
412     _CORE_mutex_Seize_body( _the_mutex, _id, _wait, _timeout, _level )
413#endif
414/**
415 *  @brief Surrender the Mutex
416 *
417 *  This routine frees a unit to the mutex.  If a task was blocked waiting for
418 *  a unit from this mutex, then that task will be readied and the unit
419 *  given to that task.  Otherwise, the unit will be returned to the mutex.
420 *
421 *  @param[in] the_mutex is the mutex to surrender
422 *  @param[in] id is the id of the RTEMS Object associated with this mutex
423 *  @param[in] api_mutex_mp_support is the routine that will be called when
424 *         unblocking a remote mutex
425 *
426 *  @return an indication of whether the routine succeeded or failed
427 */
428CORE_mutex_Status _CORE_mutex_Surrender(
429  CORE_mutex_Control                *the_mutex,
430  Objects_Id                         id,
431  CORE_mutex_API_mp_support_callout  api_mutex_mp_support
432);
433
434/**
435 *  @brief Flush all waiting threads
436 *
437 *  This routine assists in the deletion of a mutex by flushing the associated
438 *  wait queue.
439 *
440 *  @param[in] the_mutex is the mutex to flush
441 *  @param[in] remote_extract_callout is the routine to invoke when a remote
442 *         thread is extracted
443 *  @param[in] status is the status value which each unblocked thread will
444 *         return to its caller.
445 */
446void _CORE_mutex_Flush(
447  CORE_mutex_Control         *the_mutex,
448  Thread_queue_Flush_callout  remote_extract_callout,
449  uint32_t                    status
450);
451
452#include <rtems/score/coremutex.inl>
453#endif
454
455#ifdef __cplusplus
456}
457#endif
458
459/**@}*/
460
461#endif
462/*  end of include file */
Note: See TracBrowser for help on using the repository browser.