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

4.115
Last change on this file since d8cd045c was d8cd045c, checked in by Joel Sherrill <joel.sherrill@…>, on 06/17/11 at 15:40:09

2011-06-17 Joel Sherrill <joel.sherrill@…>

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