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

4.104.114.84.95
Last change on this file since d6154c7 was d6154c7, checked in by Ralf Corsepius <ralf.corsepius@…>, on Mar 29, 2004 at 4:41:13 PM

2004-03-29 Ralf Corsepius <ralf_corsepius@…>

  • score/include/rtems/debug.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.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/object.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/coremsg.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/priority.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/inline/rtems/score/userext.inl, score/inline/rtems/score/wkspace.inl, score/macros/rtems/score/address.inl, score/macros/rtems/score/heap.inl, score/macros/rtems/score/object.inl, score/macros/rtems/score/priority.inl, score/macros/rtems/score/userext.inl: Convert to using c99 fixed size types.
  • 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  uint32_t     free_blocks;
54  uint32_t     free_size;
55  uint32_t     used_blocks;
56  uint32_t     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( uint32_t   ) * 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  uint32_t    back_flag;   /* size and status of prev block */
111  uint32_t    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  uint32_t    page_size;   /* allocation unit */
138  uint32_t    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
152uint32_t   _Heap_Initialize(
153  Heap_Control *the_heap,
154  void         *starting_address,
155  uint32_t      size,
156  uint32_t      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  uint32_t      size,
172  uint32_t     *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  uint32_t      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  uint32_t            *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.