source: rtems/c/src/exec/rtems/include/rtems/rtems/region.h @ 3235ad9

4.104.114.84.95
Last change on this file since 3235ad9 was 3235ad9, checked in by Joel Sherrill <joel.sherrill@…>, on 08/23/95 at 19:30:23

Support for variable length names added to Object Handler. This supports
both fixed length "raw" names and strings from the API's point of view.

Both inline and macro implementations were tested.

  • Property mode set to 100644
File size: 7.5 KB
Line 
1/*  region.h
2 *
3 *  This include file contains all the constants and structures associated
4 *  with the Region Manager.  This manager provides facilities to dynamically
5 *  allocate memory in variable sized units which are returned as segments.
6 *
7 *  Directives provided are:
8 *
9 *     + create a region
10 *     + get an ID of a region
11 *     + delete a region
12 *     + get a segment from a region
13 *     + return a segment to a region
14 *
15 *  COPYRIGHT (c) 1989, 1990, 1991, 1992, 1993, 1994.
16 *  On-Line Applications Research Corporation (OAR).
17 *  All rights assigned to U.S. Government, 1994.
18 *
19 *  This material may be reproduced by or for the U.S. Government pursuant
20 *  to the copyright license under the clause at DFARS 252.227-7013.  This
21 *  notice must appear in all copies of this file and its derivatives.
22 *
23 *  $Id$
24 */
25
26#ifndef __RTEMS_REGION_h
27#define __RTEMS_REGION_h
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33#include <rtems.h>
34#include <rtems/object.h>
35#include <rtems/threadq.h>
36#include <rtems/heap.h>
37#include <rtems/debug.h>
38
39/*
40 *  The following records define the control block used to manage
41 *  each region.
42 */
43
44typedef struct {
45  Objects_Control       Object;
46  Thread_queue_Control  Wait_queue;            /* waiting threads        */
47  void                 *starting_address;      /* physical start addr    */
48  unsigned32            length;                /* physical length(bytes) */
49  unsigned32            page_size;             /* in bytes               */
50  unsigned32            maximum_segment_size;  /* in bytes               */
51  rtems_attribute       attribute_set;
52  unsigned32            number_of_used_blocks; /* blocks allocated       */
53  Heap_Control          Memory;
54}  Region_Control;
55
56/*
57 *  The following defines the information control block used to
58 *  manage this class of objects.
59 */
60
61EXTERN Objects_Information _Region_Information;
62
63/*
64 *  _Region_Manager_initialization
65 *
66 *  DESCRIPTION:
67 *
68 *  This routine performs the initialization necessary for this manager.
69 */
70
71void _Region_Manager_initialization(
72  unsigned32 maximum_regions
73);
74
75/*
76 *  rtems_region_create
77 *
78 *  DESCRIPTION:
79 *
80 *  This routine implements the rtems_region_create directive.  The
81 *  region will have the name name.  The memory area managed by
82 *  the region is of length bytes and starts at starting_address.
83 *  The memory area will be divided into as many allocatable units of
84 *  page_size bytes as possible.   The attribute_set determines which
85 *  thread queue discipline is used by the region.  It returns the
86 *  id of the created region in ID.
87 */
88
89rtems_status_code rtems_region_create(
90  rtems_name          name,
91  void               *starting_address,
92  unsigned32          length,
93  unsigned32          page_size,
94  rtems_attribute  attribute_set,
95  Objects_Id         *id
96);
97
98/*
99 *  rtems_region_extend
100 *
101 *  DESCRIPTION:
102 *
103 *  This routine implements the rtems_region_extend directive.  The
104 *  region will have the name name.  The memory area managed by
105 *  the region will be attempted to be grown by length bytes using
106 *  the memory starting at starting_address.
107 */
108
109rtems_status_code rtems_region_extend(
110  Objects_Id          id,
111  void               *starting_address,
112  unsigned32          length
113);
114
115/*
116 *  rtems_region_ident
117 *
118 *  DESCRIPTION:
119 *
120 *  This routine implements the rtems_region_ident directive.
121 *  This directive returns the region ID associated with name.
122 *  If more than one region is named name, then the region
123 *  to which the ID belongs is arbitrary.
124 */
125
126rtems_status_code rtems_region_ident(
127  rtems_name    name,
128  Objects_Id   *id
129);
130
131/*
132 *  rtems_region_delete
133 *
134 *  DESCRIPTION:
135 *
136 *  This routine implements the rtems_region_delete directive.  The
137 *  region indicated by ID is deleted.
138 */
139
140rtems_status_code rtems_region_delete(
141  Objects_Id id
142);
143
144/*
145 *  rtems_region_get_segment
146 *
147 *  DESCRIPTION:
148 *
149 *  This routine implements the rtems_region_get_segment directive.  It
150 *  attempts to allocate a segment from the region associated with ID.
151 *  If a segment of the requested size can be allocated, its address
152 *  is returned in segment.  If no segment is available, then the task
153 *  may return immediately or block waiting for a segment with an optional
154 *  timeout of timeout clock ticks.  Whether the task blocks or returns
155 *  immediately is based on the no_wait option in the option_set.
156 */
157
158rtems_status_code rtems_region_get_segment(
159  Objects_Id         id,
160  unsigned32         size,
161  rtems_option    option_set,
162  rtems_interval  timeout,
163  void              **segment
164);
165
166/*
167 *  rtems_region_get_segment_size
168 *
169 *  DESCRIPTION:
170 *
171 *  This routine implements the rtems_region_get_segment_size directive.  It
172 *  returns the size in bytes of the specified user memory area.
173 */
174
175rtems_status_code rtems_region_get_segment_size(
176  Objects_Id         id,
177  void              *segment,
178  unsigned32        *size
179);
180
181/*
182 *  rtems_region_return_segment
183 *
184 *  DESCRIPTION:
185 *
186 *  This routine implements the rtems_region_return_segment directive.  It
187 *  frees the segment to the region associated with ID.  The segment must
188 *  have been previously allocated from the same region.  If freeing the
189 *  segment results in enough memory being available to satisfy the
190 *  rtems_region_get_segment of the first blocked task, then that task and as
191 *  many subsequent tasks as possible will be unblocked with their requests
192 *  satisfied.
193 */
194
195rtems_status_code rtems_region_return_segment(
196  Objects_Id  id,
197  void       *segment
198);
199
200/*
201 *  _Region_Allocate
202 *
203 *  DESCRIPTION:
204 *
205 *  This function allocates a region control block from
206 *  the inactive chain of free region control blocks.
207 */
208
209STATIC INLINE Region_Control *_Region_Allocate( void );
210
211/*
212 *  _Region_Free
213 *
214 *  DESCRIPTION:
215 *
216 *  This routine frees a region control block to the
217 *  inactive chain of free region control blocks.
218 */
219
220STATIC INLINE void _Region_Free (
221  Region_Control *the_region
222);
223
224/*
225 *  _Region_Get
226 *
227 *  DESCRIPTION:
228 *
229 *  This function maps region IDs to region control blocks.
230 *  If ID corresponds to a local region, then it returns
231 *  the_region control pointer which maps to ID and location
232 *  is set to OBJECTS_LOCAL.  Otherwise, location is set
233 *  to OBJECTS_ERROR and the_region is undefined.
234 */
235
236STATIC INLINE Region_Control *_Region_Get (
237  Objects_Id         id,
238  Objects_Locations *location
239);
240
241/*
242 *  _Region_Allocate_segment
243 *
244 *  DESCRIPTION:
245 *
246 *  This function attempts to allocate a segment from the_region.
247 *  If successful, it returns the address of the allocated segment.
248 *  Otherwise, it returns NULL.
249 */
250
251STATIC INLINE void *_Region_Allocate_segment (
252  Region_Control *the_region,
253  unsigned32      size
254);
255
256/*
257 *  _Region_Free_segment
258 *
259 *  DESCRIPTION:
260 *
261 *  This function frees the_segment to the_region.
262 */
263
264STATIC INLINE boolean _Region_Free_segment (
265  Region_Control *the_region,
266  void           *the_segment
267);
268
269/*
270 *  _Region_Is_null
271 *
272 *  DESCRIPTION:
273 *
274 *  This function returns TRUE if the_region is NULL and FALSE otherwise.
275 */
276
277STATIC INLINE boolean _Region_Is_null (
278  Region_Control *the_region
279);
280
281#include <rtems/region.inl>
282#include <rtems/regionmp.h>
283
284/*
285 *  _Region_Debug_Walk
286 *
287 *  DESCRIPTION:
288 *
289 *  This routine is invoked to verify the integrity of a heap associated
290 *  with the_region.
291 */
292
293#ifdef RTEMS_DEBUG
294
295#define _Region_Debug_Walk( _the_region, _source ) \
296  do { \
297    if ( _Debug_Is_enabled( RTEMS_DEBUG_REGION ) ) \
298      _Heap_Walk( &(_the_region)->Memory, _source, FALSE ); \
299  } while ( 0 )
300
301#else
302
303#define _Region_Debug_Walk( _the_region, _source )
304
305#endif
306
307#ifdef __cplusplus
308}
309#endif
310
311#endif
312/* end of include file */
Note: See TracBrowser for help on using the repository browser.