1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
|
/**
* @file rtems/score/protectedheap.h
*
* This include file contains the information pertaining to the
* Protected Heap Handler.
*
* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
* found in the file LICENSE in this distribution or at
* http://www.rtems.com/license/LICENSE.
*
* $Id$
*/
#ifndef _RTEMS_SCORE_PROTECTED_HEAP_H
#define _RTEMS_SCORE_PROTECTED_HEAP_H
#include <rtems/score/heap.h>
#include <rtems/score/apimutex.h>
/**
* @defgroup ScoreProtHeap Protected Heap Handler
*
* This handler encapsulates functionality which provides the foundation
* Protected Heap services.
*
* It is a simple wrapper for the help with the addition of the
* allocation mutex being used for protection.
*/
/**@{*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* This routine initializes @a the_heap record to manage the
* contiguous heap of @a size bytes which starts at @a starting_address.
* Blocks of memory are allocated from the heap in multiples of
* @a page_size byte units. If @a page_size is 0 or is not multiple of
* CPU_ALIGNMENT, it's aligned up to the nearest CPU_ALIGNMENT boundary.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] starting_address is the starting address of the memory for
* the heap
* @param[in] size is the size in bytes of the memory area for the heap
* @param[in] page_size is the size in bytes of the allocation unit
*
* @return This method returns the maximum memory available. If
* unsuccessful, 0 will be returned.
*/
static inline uint32_t _Protected_heap_Initialize(
Heap_Control *the_heap,
void *starting_address,
size_t size,
uint32_t page_size
)
{
return _Heap_Initialize( the_heap, starting_address, size, page_size );
}
/**
* This routine grows @a the_heap memory area using the size bytes which
* begin at @a starting_address.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] starting_address is the starting address of the memory
* to add to the heap
* @param[in] size is the size in bytes of the memory area to add
* @return a status indicating success or the reason for failure
*/
boolean _Protected_heap_Extend(
Heap_Control *the_heap,
void *starting_address,
size_t size
);
/**
* This function attempts to allocate a block of @a size bytes from
* @a the_heap. If insufficient memory is free in @a the_heap to allocate
* a block of the requested size, then NULL is returned.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] size is the amount of memory to allocate in bytes
* @return NULL if unsuccessful and a pointer to the block if successful
*/
void *_Protected_heap_Allocate(
Heap_Control *the_heap,
size_t size
);
/**
* This function attempts to allocate a memory block of @a size bytes from
* @a the_heap so that the start of the user memory is aligned on the
* @a alignment boundary. If @a alignment is 0, it is set to CPU_ALIGNMENT.
* Any other value of @a alignment is taken "as is", i.e., even odd
* alignments are possible.
* Returns pointer to the start of the memory block if success, NULL if
* failure.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] size is the amount of memory to allocate in bytes
* @param[in] alignment the required alignment
* @return NULL if unsuccessful and a pointer to the block if successful
*/
void *_Protected_heap_Allocate_aligned(
Heap_Control *the_heap,
size_t size,
uint32_t alignment
);
/**
* This function sets @a *size to the size of the block of user memory
* which begins at @a starting_address. The size returned in @a *size could
* be greater than the size requested for allocation.
* Returns TRUE if the @a starting_address is in the heap, and FALSE
* otherwise.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] starting_address is the starting address of the user block
* to obtain the size of
* @param[in] size points to a user area to return the size in
* @return TRUE if successfully able to determine the size, FALSE otherwise
* @return *size filled in with the size of the user area for this block
*/
boolean _Protected_heap_Get_block_size(
Heap_Control *the_heap,
void *starting_address,
size_t *size
);
/**
* This function tries to resize in place the block that is pointed to by the
* @a starting_address to the new @a size.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] starting_address is the starting address of the user block
* to be resized
* @param[in] size is the new size
*
* @return TRUE if successfully able to resize the block.
* FALSE if the block can't be resized in place.
*/
boolean _Protected_heap_Resize_block(
Heap_Control *the_heap,
void *starting_address,
size_t size
);
/**
* This routine returns the block of memory which begins
* at @a starting_address to @a the_heap. Any coalescing which is
* possible with the freeing of this routine is performed.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] start_address is the starting address of the user block
* to free
* @return TRUE if successfully freed, FALSE otherwise
*/
boolean _Protected_heap_Free(
Heap_Control *the_heap,
void *start_address
);
/**
* This routine walks the heap to verify its integrity.
*
* @param[in] the_heap is the heap to operate upon
* @param[in] source is a user specified integer which may be used to
* indicate where in the application this was invoked from
* @param[in] do_dump is set to TRUE if errors should be printed
* @return TRUE if the test passed fine, FALSE otherwise.
*/
boolean _Protected_heap_Walk(
Heap_Control *the_heap,
int source,
boolean do_dump
);
/**
* This routine walks the heap and tots up the free and allocated
* sizes.
*
* @param[in] the_heap pointer to heap header
* @param[in] the_info pointer to a status information area
*/
void _Protected_heap_Get_information(
Heap_Control *the_heap,
Heap_Information_block *the_info
);
/**
* This heap routine returns information about the free blocks
* in the specified heap.
*
* @param[in] the_heap pointer to heap header.
* @param[in] info pointer to the free block information.
*
* @return free block information filled in.
*/
void _Protected_heap_Get_free_information(
Heap_Control *the_heap,
Heap_Information *info
);
#ifdef __cplusplus
}
#endif
/**@}*/
#endif
/* end of include file */
|
