source: rtems/cpukit/score/include/rtems/score/heap.h @ dd687d9

4.104.114.84.95
Last change on this file since dd687d9 was dd687d9, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 4, 2003 at 6:56:05 PM

2003-09-04 Joel Sherrill <joel@…>

  • include/rtems/debug.h, include/rtems/seterr.h, include/rtems/system.h, include/rtems/score/address.h, include/rtems/score/apiext.h, include/rtems/score/apimutex.h, include/rtems/score/bitfield.h, include/rtems/score/chain.h, include/rtems/score/context.h, include/rtems/score/copyrt.h, include/rtems/score/coremsg.h, include/rtems/score/coremutex.h, include/rtems/score/coresem.h, include/rtems/score/heap.h, include/rtems/score/interr.h, include/rtems/score/isr.h, include/rtems/score/mpci.h, include/rtems/score/mppkt.h, include/rtems/score/object.h, include/rtems/score/objectmp.h, include/rtems/score/priority.h, include/rtems/score/stack.h, include/rtems/score/states.h, include/rtems/score/sysstate.h, include/rtems/score/thread.h, include/rtems/score/threadmp.h, include/rtems/score/threadq.h, include/rtems/score/tod.h, include/rtems/score/tqdata.h, include/rtems/score/userext.h, include/rtems/score/watchdog.h, include/rtems/score/wkspace.h, inline/rtems/score/address.inl, inline/rtems/score/chain.inl, inline/rtems/score/coremsg.inl, inline/rtems/score/coremutex.inl, inline/rtems/score/coresem.inl, inline/rtems/score/heap.inl, inline/rtems/score/isr.inl, inline/rtems/score/mppkt.inl, inline/rtems/score/object.inl, inline/rtems/score/objectmp.inl, inline/rtems/score/priority.inl, inline/rtems/score/stack.inl, inline/rtems/score/states.inl, inline/rtems/score/sysstate.inl, inline/rtems/score/thread.inl, inline/rtems/score/threadmp.inl, inline/rtems/score/tod.inl, inline/rtems/score/tqdata.inl, inline/rtems/score/userext.inl, inline/rtems/score/watchdog.inl, inline/rtems/score/wkspace.inl, macros/rtems/score/address.inl, macros/rtems/score/chain.inl, macros/rtems/score/coremsg.inl, macros/rtems/score/coremutex.inl, macros/rtems/score/coresem.inl, macros/rtems/score/heap.inl, macros/rtems/score/isr.inl, macros/rtems/score/mppkt.inl, macros/rtems/score/object.inl, macros/rtems/score/objectmp.inl, macros/rtems/score/priority.inl, macros/rtems/score/stack.inl, macros/rtems/score/states.inl, macros/rtems/score/sysstate.inl, macros/rtems/score/thread.inl, macros/rtems/score/threadmp.inl, macros/rtems/score/tod.inl, macros/rtems/score/tqdata.inl, macros/rtems/score/userext.inl, macros/rtems/score/watchdog.inl, macros/rtems/score/wkspace.inl, src/apiext.c, src/chain.c, src/coremsg.c, src/coremsgbroadcast.c, src/coremsgclose.c, src/coremsgflush.c, src/coremsgflushsupp.c, src/coremsgflushwait.c, src/coremsginsert.c, src/coremsgseize.c, src/coremsgsubmit.c, src/coremutex.c, src/coremutexflush.c, src/coremutexseize.c, src/coremutexsurrender.c, src/coresem.c, src/coresemflush.c, src/coresemseize.c, src/coresemsurrender.c, src/coretod.c, src/coretodset.c, src/coretodtickle.c, src/coretodtoseconds.c, src/coretodvalidate.c, src/heap.c, src/heapallocate.c, src/heapextend.c, src/heapfree.c, src/heapgetinfo.c, src/heapsizeofuserarea.c, src/heapwalk.c, src/interr.c, src/isr.c, src/iterateoverthreads.c, src/mpci.c, src/object.c, src/objectallocate.c, src/objectallocatebyindex.c, src/objectclearname.c, src/objectcomparenameraw.c, src/objectcomparenamestring.c, src/objectcopynameraw.c, src/objectcopynamestring.c, src/objectextendinformation.c, src/objectfree.c, src/objectget.c, src/objectgetbyindex.c, src/objectgetisr.c, src/objectgetnext.c, src/objectgetnoprotection.c, src/objectidtoname.c, src/objectinitializeinformation.c, src/objectmp.c, src/objectnametoid.c, src/objectshrinkinformation.c, src/thread.c, src/threadchangepriority.c, src/threadclearstate.c, src/threadclose.c, src/threadcreateidle.c, src/threaddelayended.c, src/threaddispatch.c, src/threadevaluatemode.c, src/threadget.c, src/threadhandler.c, src/threadidlebody.c, src/threadinitialize.c, src/threadloadenv.c, src/threadmp.c, src/threadq.c, src/threadqdequeue.c, src/threadqdequeuefifo.c, src/threadqdequeuepriority.c, src/threadqenqueue.c, src/threadqenqueuefifo.c, src/threadqenqueuepriority.c, src/threadqextract.c, src/threadqextractfifo.c, src/threadqextractpriority.c, src/threadqextractwithproxy.c, src/threadqfirst.c, src/threadqfirstfifo.c, src/threadqfirstpriority.c, src/threadqflush.c, src/threadqtimeout.c, src/threadready.c, src/threadreset.c, src/threadresettimeslice.c, src/threadrestart.c, src/threadresume.c, src/threadrotatequeue.c, src/threadsetpriority.c, src/threadsetstate.c, src/threadsettransient.c, src/threadstackallocate.c, src/threadstackfree.c, src/threadstart.c, src/threadstartmultitasking.c, src/threadsuspend.c, src/threadtickletimeslice.c, src/threadyieldprocessor.c, src/userext.c, src/watchdog.c, src/watchdogadjust.c, src/watchdoginsert.c, src/watchdogremove.c, src/watchdogtickle.c, src/wkspace.c: URL for license changed.
  • Property mode set to 100644
File size: 6.8 KB
Line 
1/*  heap.h
2 *
3 *  This include file contains the information pertaining to the Heap
4 *  Handler.  A heap is a doubly linked list of variable size
5 *  blocks which are allocated using the first fit method.  Garbage
6 *  collection is performed each time a block is returned to the heap by
7 *  coalescing neighbor blocks.  Control information for both allocated
8 *  and unallocated blocks is contained in the heap space.  A heap header
9 *  contains control information for the heap.
10 *
11 *  COPYRIGHT (c) 1989-1999.
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_HEAP_h
22#define __RTEMS_HEAP_h
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28/*
29 *  Status codes for heap_extend
30 */
31
32typedef enum {
33  HEAP_EXTEND_SUCCESSFUL,
34  HEAP_EXTEND_ERROR,
35  HEAP_EXTEND_NOT_IMPLEMENTED
36}  Heap_Extend_status;
37
38/*
39 *  Status codes for _Heap_Get_information
40 */
41
42typedef enum {
43    HEAP_GET_INFORMATION_SUCCESSFUL = 0,
44    HEAP_GET_INFORMATION_SYSTEM_STATE_ERROR,
45    HEAP_GET_INFORMATION_BLOCK_ERROR
46}  Heap_Get_information_status;
47       
48/*
49 *  Information block returned by _Heap_Get_information
50 */
51
52typedef struct {
53  unsigned32   free_blocks;
54  unsigned32   free_size;
55  unsigned32   used_blocks;
56  unsigned32   used_size;
57} Heap_Information_block;
58
59/*
60 *  Constants used in the size/used field of each heap block to
61 *  indicate when a block is free or in use.
62 */
63
64#define HEAP_BLOCK_USED    1           /* indicates block is in use */
65#define HEAP_BLOCK_FREE    0           /* indicates block is free */
66
67/*
68 *  The size/used field value for the dummy front and back flags.
69 */
70
71#define HEAP_DUMMY_FLAG    (0 + HEAP_BLOCK_USED)
72
73/*
74 *  The following constants reflect various requirements of the
75 *  heap data structures which impact the management of a heap.
76 *
77 * NOTE:   Because free block overhead is greater than used block
78 *         overhead AND a portion of the allocated space is from
79 *         the extra free block overhead, the absolute lower bound
80 *         of the minimum fragment size is equal to the size of
81 *         the free block overhead.
82 */
83
84#define HEAP_OVERHEAD \
85  (sizeof( unsigned32 ) * 2)         /* size dummy first and last blocks */
86#define HEAP_BLOCK_USED_OVERHEAD \
87  (sizeof( void * ) * 2)             /* num bytes overhead in used block */
88#define HEAP_MINIMUM_SIZE \
89  (HEAP_OVERHEAD + sizeof (Heap_Block))
90                                     /* min number of bytes the user may */
91                                     /*   specify for the heap size      */
92
93/*
94 *  The following defines the data structure used to manage
95 *  individual blocks in a heap.   When the block is allocated, the
96 *  next and previous fields are not used by the Heap Handler
97 *  and thus the address returned for the block starts at
98 *  the address of the next field.
99 *
100 *  NOTE:  The next and previous pointers are only valid when the
101 *         block is free.  Caution must be exercised to insure that
102 *         allocated blocks are large enough to contain them and
103 *         that they are not accidentally overwritten when the
104 *         block is actually allocated.
105 */
106
107typedef struct Heap_Block_struct Heap_Block;
108
109struct Heap_Block_struct {
110  unsigned32  back_flag;   /* size and status of prev block */
111  unsigned32  front_flag;  /* size and status of block */
112  Heap_Block *next;        /* pointer to next block */
113  Heap_Block *previous;    /* pointer to previous block */
114};
115
116/*
117 *  The following defines the control block used to manage each heap.
118 *
119 *  NOTE:
120 *
121 *  This structure is layed out such that it can be used a a dummy
122 *  first and last block on the free block chain.  The extra padding
123 *  insures the dummy last block is the correct size.
124 *
125 *  The first Heap_Block starts at first while the second starts at
126 *  final.  This is effectively the same trick as is used in the Chain
127 *  Handler.
128 */
129
130typedef struct {
131  Heap_Block *start;       /* first valid block address in heap */
132  Heap_Block *final;       /* last valid block address in heap */
133
134  Heap_Block *first;       /* pointer to first block in heap */
135  Heap_Block *permanent_null;  /* always NULL pointer */
136  Heap_Block *last;        /* pointer to last block in heap */
137  unsigned32  page_size;   /* allocation unit */
138  unsigned32  reserved;
139}   Heap_Control;
140
141/*
142 *  _Heap_Initialize
143 *
144 *  DESCRIPTION:
145 *
146 *  This routine initializes the_heap record to manage the
147 *  contiguous heap of size bytes which starts at starting_address.
148 *  Blocks of memory are allocated from the heap in multiples of
149 *  page_size byte units.
150 */
151
152unsigned32 _Heap_Initialize(
153  Heap_Control *the_heap,
154  void         *starting_address,
155  unsigned32    size,
156  unsigned32    page_size
157);
158
159/*
160 *  _Heap_Extend
161 *
162 *  DESCRIPTION:
163 *
164 *  This routine grows the_heap memory area using the size bytes which
165 *  begin at starting_address.
166 */
167
168Heap_Extend_status _Heap_Extend(
169  Heap_Control *the_heap,
170  void         *starting_address,
171  unsigned32    size,
172  unsigned32   *amount_extended
173);
174
175/*
176 *  _Heap_Allocate
177 *
178 *  DESCRIPTION:
179 *
180 *  DESCRIPTION:
181 *
182 *  This function attempts to allocate a block of size bytes from
183 *  the_heap.  If insufficient memory is free in the_heap to allocate
184 *  a  block of the requested size, then NULL is returned.
185 */
186
187void *_Heap_Allocate(
188  Heap_Control *the_heap,
189  unsigned32    size
190);
191
192/*
193 *  _Heap_Size_of_user_area
194 *
195 *  DESCRIPTION:
196 *
197 *  This kernel routine sets size to the size of the given heap block.
198 *  It returns TRUE if the starting_address is in the heap, and FALSE
199 *  otherwise.
200 */
201
202boolean _Heap_Size_of_user_area(
203  Heap_Control        *the_heap,
204  void                *starting_address,
205  unsigned32          *size
206);
207
208/*
209 *  _Heap_Free
210 *
211 *  DESCRIPTION:
212 *
213 *  This routine returns the block of memory which begins
214 *  at starting_address to the_heap.  Any coalescing which is
215 *  possible with the freeing of this routine is performed.
216 */
217
218boolean _Heap_Free(
219  Heap_Control *the_heap,
220  void         *start_address
221);
222
223/*
224 *  _Heap_Walk
225 *
226 *  DESCRIPTION:
227 *
228 *  This routine walks the heap to verify its integrity.
229 */
230
231void _Heap_Walk(
232  Heap_Control *the_heap,
233  int           source,
234  boolean       do_dump
235);
236
237/*PAGE
238 *
239 *  _Heap_Get_information
240 *
241 *  This kernel routine walks the heap and tots up the free and allocated
242 *  sizes.  Derived from _Heap_Walk.
243 *
244 *  Input parameters:
245 *    the_heap  - pointer to heap header
246 *    the_info  - pointer to information block
247 *
248 *  Output parameters:
249 *    *the_info - status information
250 *    return 0=success, otherwise heap is corrupt.
251 */
252
253
254Heap_Get_information_status _Heap_Get_information(
255  Heap_Control            *the_heap,
256  Heap_Information_block  *the_info
257);
258
259
260#ifndef __RTEMS_APPLICATION__
261#include <rtems/score/heap.inl>
262#endif
263
264#ifdef __cplusplus
265}
266#endif
267
268#endif
269/* end of include file */
Note: See TracBrowser for help on using the repository browser.