source: rtems/cpukit/score/include/rtems/score/heap.h @ 9b3f187

4.104.114.84.95
Last change on this file since 9b3f187 was 9b3f187, checked in by Joel Sherrill <joel.sherrill@…>, on 11/29/04 at 22:45:43

2004-11-29 Joel Sherrill <joel@…>

  • libcsupport/src/mallocfreespace.c, rtems/Makefile.am, rtems/include/rtems/rtems/region.h, score/Makefile.am, score/include/rtems/score/heap.h, score/src/heapgetinfo.c: Add capability to return information about just the free blocks in a region or heap. Also changed the semantics of free space available to be the largest block of memory that can be allocated.
  • rtems/src/regiongetfreeinfo.c, score/src/heapgetfreeinfo.c: New files. : score/include/rtems/score/object.h, score/src/objectinitializeinformation.c: Remove warning.
  • Property mode set to 100644
File size: 9.2 KB
Line 
1/**
2 *  @file  rtems/score/heap.h
3 *
4 *  This include file contains the information pertaining to the Heap
5 *  Handler.  A heap is a doubly linked list of variable size
6 *  blocks which are allocated using the first fit method.  Garbage
7 *  collection is performed each time a block is returned to the heap by
8 *  coalescing neighbor blocks.  Control information for both allocated
9 *  and unallocated blocks is contained in the heap space.  A heap header
10 *  contains control information for the heap.
11 */
12
13/*
14 *  COPYRIGHT (c) 1989-2004.
15 *  On-Line Applications Research Corporation (OAR).
16 *
17 *  The license and distribution terms for this file may be
18 *  found in the file LICENSE in this distribution or at
19 *  http://www.rtems.com/license/LICENSE.
20 *
21 *  $Id$
22 */
23
24#ifndef __RTEMS_HEAP_h
25#define __RTEMS_HEAP_h
26
27/**
28 *  @defgroup ScoreHeap Heap Handler
29 *
30 *  This group contains functionality which provides the foundation
31 *  Heap services used in all of the APIs supported by RTEMS.
32 */
33/**@{*/
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/**
40 *  Status codes for heap_extend
41 */
42typedef enum {
43  HEAP_EXTEND_SUCCESSFUL,
44  HEAP_EXTEND_ERROR,
45  HEAP_EXTEND_NOT_IMPLEMENTED
46}  Heap_Extend_status;
47
48/**
49 *  Status codes for _Heap_Get_information
50 */
51typedef enum {
52    HEAP_GET_INFORMATION_SUCCESSFUL = 0,
53    HEAP_GET_INFORMATION_SYSTEM_STATE_ERROR,
54    HEAP_GET_INFORMATION_BLOCK_ERROR
55}  Heap_Get_information_status;
56
57/**
58 *  Information block returned by the Heap routines used to
59 *  obtain statistics.  This information is returned about
60 *  either free or used blocks.
61 */
62
63typedef struct {
64  /** Number of blocks of this type. */
65  uint32_t number;
66  /** Largest blocks of this type. */
67  uint32_t largest;
68  /** Total size of the blocks of this type. */
69  uint32_t total;
70
71} Heap_Information;
72
73
74/**
75 *  Information block returned by _Heap_Get_information
76 */
77typedef struct {
78  /** This field is information on the used blocks in the heap. */
79  Heap_Information Free;
80  /** This field is information on the used blocks in the heap. */
81  Heap_Information Used;
82} Heap_Information_block;
83
84/**
85 *  This constant is used in the size/used field of each heap block to
86 *  indicate when a block is in use.
87 */
88#define HEAP_BLOCK_USED    1
89
90/**
91 *  This constant is used in the size/used field of each heap block to
92 *  indicate when a block is free.
93 */
94#define HEAP_BLOCK_FREE    0
95
96/**
97 *  The size/used field value for the dummy front and back flags.
98 */
99#define HEAP_DUMMY_FLAG    (0 + HEAP_BLOCK_USED)
100
101/*
102 *  The following constants reflect various requirements of the
103 *  heap data structures which impact the management of a heap.
104 *
105 *  NOTE:  Because free block overhead is greater than used block
106 *         overhead AND a portion of the allocated space is from
107 *         the extra free block overhead, the absolute lower bound
108 *         of the minimum fragment size is equal to the size of
109 *         the free block overhead.
110 */
111
112/** size dummy first and last blocks */
113#define HEAP_OVERHEAD (sizeof( uint32_t   ) * 2)
114
115/** number of bytes of overhead in used block */
116#define HEAP_BLOCK_USED_OVERHEAD (sizeof( void * ) * 2)
117
118/** Minimum number of bytes the user may specify for the heap size */
119#define HEAP_MINIMUM_SIZE (HEAP_OVERHEAD + sizeof (Heap_Block))
120
121/**
122 *  Forward reference
123 *
124 *  @ref Heap_Block
125 */
126typedef struct Heap_Block_struct Heap_Block;
127
128/**
129 *  The following defines the data structure used to manage
130 *  individual blocks in a heap.   When the block is allocated, the
131 *  next and previous fields are not used by the Heap Handler
132 *  and thus the address returned for the block starts at
133 *  the address of the next field.
134 *
135 *  @note  The next and previous pointers are only valid when the
136 *         block is free.  Caution must be exercised to insure that
137 *         allocated blocks are large enough to contain them and
138 *         that they are not accidentally overwritten when the
139 *         block is actually allocated.
140 */
141struct Heap_Block_struct {
142  /** size and status of prev block */
143  uint32_t    back_flag;
144  /** size and status of block */
145  uint32_t    front_flag;
146  /** pointer to next block */
147  Heap_Block *next;
148  /** pointer to previous block */
149  Heap_Block *previous;
150};
151
152/**
153 *  The following defines the control block used to manage each heap.
154 *
155 *  @note This structure is layed out such that it can be used a a dummy
156 *  first and last block on the free block chain.  The extra padding
157 *  insures the dummy last block is the correct size.
158 *
159 *  The first Heap_Block starts at first while the second starts at
160 *  final.  This is effectively the same trick as is used in the Chain
161 *  Handler.
162 */
163typedef struct {
164  /** first valid block address in heap */
165  Heap_Block *start;
166  /** last valid block address in heap */
167  Heap_Block *final;
168
169  /** pointer to first block in heap */
170  Heap_Block *first;
171  /** always NULL pointer */
172  Heap_Block *permanent_null;
173  /** pointer to last block in heap */
174  Heap_Block *last;
175  /** allocation unit */
176  uint32_t    page_size;
177  /** reserved field */
178  uint32_t    reserved;
179}   Heap_Control;
180
181/**
182 *  This routine initializes @a the_heap record to manage the
183 *  contiguous heap of @a size bytes which starts at @a starting_address.
184 *  Blocks of memory are allocated from the heap in multiples of
185 *  @a page_size byte units.
186 *
187 *  @param the_heap (in) is the heap to operate upon
188 *  @param starting_address (in) is the starting address of the memory for
189 *         the heap
190 *  @param size (in) is the size in bytes of the memory area for the heap
191 *  @param page_size (in) is the size in bytes of the allocation unit
192 *  @return XXX
193 */
194uint32_t   _Heap_Initialize(
195  Heap_Control *the_heap,
196  void         *starting_address,
197  uint32_t      size,
198  uint32_t      page_size
199);
200
201/**
202 *  This routine grows @a the_heap memory area using the size bytes which
203 *  begin at @a starting_address.
204 *
205 *  @param the_heap (in) is the heap to operate upon
206 *  @param starting_address (in) is the starting address of the memory
207 *         to add to the heap
208 *  @param size (in) is the size in bytes of the memory area to add
209 *  @param amount_extended (in) points to a user area to return the
210 *  @return a status indicating success or the reason for failure
211 *  @return *size filled in with the amount of memory added to the heap
212 */
213Heap_Extend_status _Heap_Extend(
214  Heap_Control *the_heap,
215  void         *starting_address,
216  uint32_t      size,
217  uint32_t     *amount_extended
218);
219
220/**
221 *  This function attempts to allocate a block of size bytes from
222 *  @a the_heap.  If insufficient memory is free in @a the_heap to allocate
223 *  a  block of the requested size, then NULL is returned.
224 *
225 *  @param the_heap (in) is the heap to operate upon
226 *  @param size (in) is the amount of memory to allocate in bytes
227 *  @return NULL if unsuccessful and a pointer to the block if successful
228 */
229void *_Heap_Allocate(
230  Heap_Control *the_heap,
231  uint32_t      size
232);
233
234/**
235 *  This kernel routine sets size to the size of the given heap block.
236 *  It returns TRUE if the @a starting_address is in @a the_heap, and FALSE
237 *  otherwise.
238 *
239 *  @param the_heap (in) is the heap to operate upon
240 *  @param starting_address (in) is the starting address of the user block
241 *         to obtain the size of
242 *  @param size (in) points to a user area to return the size in
243 *  @return TRUE if successfully able to determine the size, FALSE otherwise
244 *  @return *size filled in with the size of the user area for this block
245 */
246boolean _Heap_Size_of_user_area(
247  Heap_Control        *the_heap,
248  void                *starting_address,
249  uint32_t            *size
250);
251
252/**
253 *  This routine returns the block of memory which begins
254 *  at @a starting_address to @a the_heap.  Any coalescing which is
255 *  possible with the freeing of this routine is performed.
256 *
257 *  @param the_heap (in) is the heap to operate upon
258 *  @param starting_address (in) is the starting address of the user block
259 *         to free
260 *  @return TRUE if successfully freed, FALSE otherwise
261 */
262boolean _Heap_Free(
263  Heap_Control *the_heap,
264  void         *start_address
265);
266
267/**
268 *  This routine walks the heap to verify its integrity.
269 * 
270 *  @param the_heap (in) is the heap to operate upon
271 *  @param source (in) XXX
272 *  @param do_dump (in) is set to TRUE if errors should be printed
273 */
274void _Heap_Walk(
275  Heap_Control *the_heap,
276  int           source,
277  boolean       do_dump
278);
279
280/**
281 *  This kernel routine walks the heap and tots up the free and allocated
282 *  sizes.  Derived from _Heap_Walk.
283 *
284 *  @param the_heap (in) pointer to heap header
285 *  @param the_info (in) pointer to a status information area
286 *  @return *the_info is filled with status information
287 *  @return 0=success, otherwise heap is corrupt.
288 */
289Heap_Get_information_status _Heap_Get_information(
290  Heap_Control            *the_heap,
291  Heap_Information_block  *the_info
292);
293
294/**
295 *  This heap routine returns information about the free blocks
296 *  in the specified heap.
297 * 
298 *  @param the_heap (in) pointer to heap header.
299 *  @param info (in) pointer to the free block information.
300 * 
301 *  @return free block information filled in.
302 */
303   
304void _Heap_Get_free_information(
305  Heap_Control        *the_heap,
306  Heap_Information    *info
307);
308
309#ifndef __RTEMS_APPLICATION__
310#include <rtems/score/heap.inl>
311#endif
312
313#ifdef __cplusplus
314}
315#endif
316
317/**@}*/
318
319#endif
320/* end of include file */
Note: See TracBrowser for help on using the repository browser.