source: rtems/cpukit/score/include/rtems/score/apimutex.h @ b05ecca

4.104.114.84.95
Last change on this file since b05ecca was b05ecca, checked in by Ralf Corsepius <ralf.corsepius@…>, on 11/01/04 at 14:24:09

Fix typo.

  • Property mode set to 100644
File size: 4.2 KB
Line 
1/**
2 *  @file apimutex.h
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the API Mutex Handler.  This handler is used by API level
6 *  routines to manage mutual exclusion.
7 */
8
9/*
10 *  COPYRIGHT (c) 1989-2004.
11 *  On-Line Applications Research Corporation (OAR).
12 *
13 *  The license and distribution terms for this file may be
14 *  found in the file LICENSE in this distribution or at
15 *  http://www.rtems.com/license/LICENSE.
16 *
17 *  $Id$
18 */
19
20#ifndef __API_MUTEX_h
21#define __API_MUTEX_h
22
23/**
24 *  @defgroup ScoreAPIMutex API Mutex Handler
25 *
26 *  This group contains functionality which provides mutexes to be used
27 *  in the implementation of API functionality.
28 */
29/**@{*/
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35#include <rtems/score/coremutex.h>
36#include <rtems/score/isr.h>
37#include <rtems/score/object.h>
38
39/**
40 *  The following defines the control block used to manage each API mutex.
41 *  An API Mutex is an aggregration of an Object and a SuperCore Mutex.
42 */
43typedef struct {
44  /** This field allows each API Mutex to be a full-fledged RTEMS object. */
45  Objects_Control       Object;
46  /** This field contains the SuperCore mutex information. */
47  CORE_mutex_Control    Mutex;
48}   API_Mutex_Control;
49
50/**
51 *  The following variable is the information control block used to manage
52 *  this class of objects.
53 */
54SCORE_EXTERN Objects_Information  _API_Mutex_Information;
55
56/**
57 *  This routine performs the initialization necessary for this handler.
58 *
59 *  @param _maximum_mutexes (in) is the maximum number of API mutexes
60 *         that may exist at any time
61 */
62#if defined(RTEMS_MULTIPROCESSING)
63#define _API_Mutex_Initialization( _maximum_mutexes ) \
64  _Objects_Initialize_information( \
65    &_API_Mutex_Information, \
66    OBJECTS_INTERNAL_API, \
67    OBJECTS_INTERNAL_MUTEXES, \
68    _maximum_mutexes, \
69    sizeof( API_Mutex_Control ), \
70    FALSE, \
71    0, \
72    FALSE, \
73    NULL \
74  );
75#else
76#define _API_Mutex_Initialization( _maximum_mutexes ) \
77  _Objects_Initialize_information( \
78    &_API_Mutex_Information, \
79    OBJECTS_INTERNAL_API, \
80    OBJECTS_INTERNAL_MUTEXES, \
81    _maximum_mutexes, \
82    sizeof( API_Mutex_Control ), \
83    FALSE, \
84    0  \
85  );
86#endif
87
88/**
89 *  This routine allocates an API mutex from the inactive set.
90 *
91 *  @param _the_mutex (out) will contain the allocated mutex.
92 */
93#define _API_Mutex_Allocate( _the_mutex ) \
94  do { \
95    CORE_mutex_Attributes attr =  \
96      { CORE_MUTEX_NESTING_IS_ERROR, FALSE, \
97        CORE_MUTEX_DISCIPLINES_PRIORITY_INHERIT, 0 }; \
98    (_the_mutex) = (API_Mutex_Control *) \
99      _Objects_Allocate( &_API_Mutex_Information ); \
100    _CORE_mutex_Initialize( \
101       &(_the_mutex)->Mutex, &attr, CORE_MUTEX_UNLOCKED ); \
102  } while (0)
103
104/**
105 *  This routine acquires the specified API mutex.
106 *
107 *  @param _the_mutex (in) is the mutex to acquire.
108 */
109#define _API_Mutex_Lock( _the_mutex ) \
110  do { \
111    ISR_Level _level;  \
112    _ISR_Disable( _level ); \
113    _CORE_mutex_Seize( \
114      &(_the_mutex)->Mutex, (_the_mutex)->Object.id, TRUE, 0, (_level) ); \
115  } while (0)
116
117/**
118 *  This routine releases the specified API mutex.
119 *
120 *  @param _the_mutex (in) is the mutex to release.
121 */
122
123#define _API_Mutex_Unlock( _the_mutex ) \
124  do { \
125    _Thread_Disable_dispatch(); \
126      _CORE_mutex_Surrender( \
127        &(_the_mutex)->Mutex, (_the_mutex)->Object.id, NULL ); \
128    _Thread_Enable_dispatch(); \
129  } while (0);
130
131/**
132 *  This variable points to the API Mutex instance that is used
133 *  to protect all memory allocation and deallocation in RTEMS.
134 *
135 *  @note When the APIs all use this for allocation and deallocation
136 *  protection, then this possibly should be renamed and moved to a
137 *  higher level in the hierarchy.
138 */
139SCORE_EXTERN API_Mutex_Control  *_RTEMS_Allocator_Mutex;
140
141/**
142 *  This macro locks the RTEMS Allocation Mutex.
143 *
144 *  @see _RTEMS_Allocator_Mutex
145 */
146#define _RTEMS_Lock_allocator() \
147  _API_Mutex_Lock( _RTEMS_Allocator_Mutex )
148
149/**
150 *  This macro unlocks the RTEMS Allocation Mutex.
151 *
152 *  @see _RTEMS_Allocator_Mutex
153 */
154#define _RTEMS_Unlock_allocator() \
155  _API_Mutex_Unlock( _RTEMS_Allocator_Mutex )
156
157/*
158 *  There are no inlines for this handler.
159 */
160
161#ifndef __RTEMS_APPLICATION__
162/* #include <rtems/score/apimutex.inl> */
163#endif
164
165#ifdef __cplusplus
166}
167#endif
168
169/*!@}*/
170
171#endif
172/*  end of include file */
Note: See TracBrowser for help on using the repository browser.