]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/MemoryAllocationLib.h
MdePkg: Apply uncrustify changes
[mirror_edk2.git] / MdePkg / Include / Library / MemoryAllocationLib.h
1 /** @file
2 Provides services to allocate and free memory buffers of various memory types and alignments.
3
4 The Memory Allocation Library abstracts various common memory allocation operations. This library
5 allows code to be written in a phase-independent manner because the allocation of memory in PEI, DXE,
6 and SMM (for example) is done via a different mechanism. Using a common library interface makes it
7 much easier to port algorithms from phase to phase.
8
9 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
10 SPDX-License-Identifier: BSD-2-Clause-Patent
11
12 **/
13
14 #ifndef __MEMORY_ALLOCATION_LIB_H__
15 #define __MEMORY_ALLOCATION_LIB_H__
16
17 /**
18 Allocates one or more 4KB pages of type EfiBootServicesData.
19
20 Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
21 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
22 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
23 returned.
24
25 @param Pages The number of 4 KB pages to allocate.
26
27 @return A pointer to the allocated buffer or NULL if allocation fails.
28
29 **/
30 VOID *
31 EFIAPI
32 AllocatePages (
33 IN UINTN Pages
34 );
35
36 /**
37 Allocates one or more 4KB pages of type EfiRuntimeServicesData.
38
39 Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
40 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
41 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
42 returned.
43
44 @param Pages The number of 4 KB pages to allocate.
45
46 @return A pointer to the allocated buffer or NULL if allocation fails.
47
48 **/
49 VOID *
50 EFIAPI
51 AllocateRuntimePages (
52 IN UINTN Pages
53 );
54
55 /**
56 Allocates one or more 4KB pages of type EfiReservedMemoryType.
57
58 Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
59 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
60 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
61 returned.
62
63 @param Pages The number of 4 KB pages to allocate.
64
65 @return A pointer to the allocated buffer or NULL if allocation fails.
66
67 **/
68 VOID *
69 EFIAPI
70 AllocateReservedPages (
71 IN UINTN Pages
72 );
73
74 /**
75 Frees one or more 4KB pages that were previously allocated with one of the page allocation
76 functions in the Memory Allocation Library.
77
78 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
79 must have been allocated on a previous call to the page allocation services of the Memory
80 Allocation Library. If it is not possible to free allocated pages, then this function will
81 perform no actions.
82
83 If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
84 then ASSERT().
85 If Pages is zero, then ASSERT().
86
87 @param Buffer Pointer to the buffer of pages to free.
88 @param Pages The number of 4 KB pages to free.
89
90 **/
91 VOID
92 EFIAPI
93 FreePages (
94 IN VOID *Buffer,
95 IN UINTN Pages
96 );
97
98 /**
99 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
100
101 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
102 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
103 returned. If there is not enough memory at the specified alignment remaining to satisfy the
104 request, then NULL is returned.
105
106 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
107 If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
108
109 @param Pages The number of 4 KB pages to allocate.
110 @param Alignment The requested alignment of the allocation. Must be a power of two.
111 If Alignment is zero, then byte alignment is used.
112
113 @return A pointer to the allocated buffer or NULL if allocation fails.
114
115 **/
116 VOID *
117 EFIAPI
118 AllocateAlignedPages (
119 IN UINTN Pages,
120 IN UINTN Alignment
121 );
122
123 /**
124 Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
125
126 Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
127 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
128 returned. If there is not enough memory at the specified alignment remaining to satisfy the
129 request, then NULL is returned.
130
131 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
132 If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
133
134 @param Pages The number of 4 KB pages to allocate.
135 @param Alignment The requested alignment of the allocation. Must be a power of two.
136 If Alignment is zero, then byte alignment is used.
137
138 @return A pointer to the allocated buffer or NULL if allocation fails.
139
140 **/
141 VOID *
142 EFIAPI
143 AllocateAlignedRuntimePages (
144 IN UINTN Pages,
145 IN UINTN Alignment
146 );
147
148 /**
149 Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
150
151 Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
152 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
153 returned. If there is not enough memory at the specified alignment remaining to satisfy the
154 request, then NULL is returned.
155
156 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
157 If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
158
159 @param Pages The number of 4 KB pages to allocate.
160 @param Alignment The requested alignment of the allocation. Must be a power of two.
161 If Alignment is zero, then byte alignment is used.
162
163 @return A pointer to the allocated buffer or NULL if allocation fails.
164
165 **/
166 VOID *
167 EFIAPI
168 AllocateAlignedReservedPages (
169 IN UINTN Pages,
170 IN UINTN Alignment
171 );
172
173 /**
174 Frees one or more 4KB pages that were previously allocated with one of the aligned page
175 allocation functions in the Memory Allocation Library.
176
177 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
178 must have been allocated on a previous call to the aligned page allocation services of the Memory
179 Allocation Library. If it is not possible to free allocated pages, then this function will
180 perform no actions.
181
182 If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
183 Library, then ASSERT().
184 If Pages is zero, then ASSERT().
185
186 @param Buffer Pointer to the buffer of pages to free.
187 @param Pages The number of 4 KB pages to free.
188
189 **/
190 VOID
191 EFIAPI
192 FreeAlignedPages (
193 IN VOID *Buffer,
194 IN UINTN Pages
195 );
196
197 /**
198 Allocates a buffer of type EfiBootServicesData.
199
200 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
201 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
202 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
203
204 @param AllocationSize The number of bytes to allocate.
205
206 @return A pointer to the allocated buffer or NULL if allocation fails.
207
208 **/
209 VOID *
210 EFIAPI
211 AllocatePool (
212 IN UINTN AllocationSize
213 );
214
215 /**
216 Allocates a buffer of type EfiRuntimeServicesData.
217
218 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
219 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
220 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
221
222 @param AllocationSize The number of bytes to allocate.
223
224 @return A pointer to the allocated buffer or NULL if allocation fails.
225
226 **/
227 VOID *
228 EFIAPI
229 AllocateRuntimePool (
230 IN UINTN AllocationSize
231 );
232
233 /**
234 Allocates a buffer of type EfiReservedMemoryType.
235
236 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
237 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
238 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
239
240 @param AllocationSize The number of bytes to allocate.
241
242 @return A pointer to the allocated buffer or NULL if allocation fails.
243
244 **/
245 VOID *
246 EFIAPI
247 AllocateReservedPool (
248 IN UINTN AllocationSize
249 );
250
251 /**
252 Allocates and zeros a buffer of type EfiBootServicesData.
253
254 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
255 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
256 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
257 request, then NULL is returned.
258
259 @param AllocationSize The number of bytes to allocate and zero.
260
261 @return A pointer to the allocated buffer or NULL if allocation fails.
262
263 **/
264 VOID *
265 EFIAPI
266 AllocateZeroPool (
267 IN UINTN AllocationSize
268 );
269
270 /**
271 Allocates and zeros a buffer of type EfiRuntimeServicesData.
272
273 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
274 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
275 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
276 request, then NULL is returned.
277
278 @param AllocationSize The number of bytes to allocate and zero.
279
280 @return A pointer to the allocated buffer or NULL if allocation fails.
281
282 **/
283 VOID *
284 EFIAPI
285 AllocateRuntimeZeroPool (
286 IN UINTN AllocationSize
287 );
288
289 /**
290 Allocates and zeros a buffer of type EfiReservedMemoryType.
291
292 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
293 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
294 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
295 request, then NULL is returned.
296
297 @param AllocationSize The number of bytes to allocate and zero.
298
299 @return A pointer to the allocated buffer or NULL if allocation fails.
300
301 **/
302 VOID *
303 EFIAPI
304 AllocateReservedZeroPool (
305 IN UINTN AllocationSize
306 );
307
308 /**
309 Copies a buffer to an allocated buffer of type EfiBootServicesData.
310
311 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
312 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
313 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
314 is not enough memory remaining to satisfy the request, then NULL is returned.
315
316 If Buffer is NULL, then ASSERT().
317 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
318
319 @param AllocationSize The number of bytes to allocate and zero.
320 @param Buffer The buffer to copy to the allocated buffer.
321
322 @return A pointer to the allocated buffer or NULL if allocation fails.
323
324 **/
325 VOID *
326 EFIAPI
327 AllocateCopyPool (
328 IN UINTN AllocationSize,
329 IN CONST VOID *Buffer
330 );
331
332 /**
333 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
334
335 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
336 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
337 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
338 is not enough memory remaining to satisfy the request, then NULL is returned.
339
340 If Buffer is NULL, then ASSERT().
341 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
342
343 @param AllocationSize The number of bytes to allocate and zero.
344 @param Buffer The buffer to copy to the allocated buffer.
345
346 @return A pointer to the allocated buffer or NULL if allocation fails.
347
348 **/
349 VOID *
350 EFIAPI
351 AllocateRuntimeCopyPool (
352 IN UINTN AllocationSize,
353 IN CONST VOID *Buffer
354 );
355
356 /**
357 Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
358
359 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
360 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
361 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
362 is not enough memory remaining to satisfy the request, then NULL is returned.
363
364 If Buffer is NULL, then ASSERT().
365 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
366
367 @param AllocationSize The number of bytes to allocate and zero.
368 @param Buffer The buffer to copy to the allocated buffer.
369
370 @return A pointer to the allocated buffer or NULL if allocation fails.
371
372 **/
373 VOID *
374 EFIAPI
375 AllocateReservedCopyPool (
376 IN UINTN AllocationSize,
377 IN CONST VOID *Buffer
378 );
379
380 /**
381 Reallocates a buffer of type EfiBootServicesData.
382
383 Allocates and zeros the number bytes specified by NewSize from memory of type
384 EfiBootServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
385 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
386 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
387 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
388 enough memory remaining to satisfy the request, then NULL is returned.
389
390 If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
391 is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
392
393 @param OldSize The size, in bytes, of OldBuffer.
394 @param NewSize The size, in bytes, of the buffer to reallocate.
395 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
396 parameter that may be NULL.
397
398 @return A pointer to the allocated buffer or NULL if allocation fails.
399
400 **/
401 VOID *
402 EFIAPI
403 ReallocatePool (
404 IN UINTN OldSize,
405 IN UINTN NewSize,
406 IN VOID *OldBuffer OPTIONAL
407 );
408
409 /**
410 Reallocates a buffer of type EfiRuntimeServicesData.
411
412 Allocates and zeros the number bytes specified by NewSize from memory of type
413 EfiRuntimeServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
414 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
415 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
416 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
417 enough memory remaining to satisfy the request, then NULL is returned.
418
419 If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
420 is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
421
422 @param OldSize The size, in bytes, of OldBuffer.
423 @param NewSize The size, in bytes, of the buffer to reallocate.
424 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
425 parameter that may be NULL.
426
427 @return A pointer to the allocated buffer or NULL if allocation fails.
428
429 **/
430 VOID *
431 EFIAPI
432 ReallocateRuntimePool (
433 IN UINTN OldSize,
434 IN UINTN NewSize,
435 IN VOID *OldBuffer OPTIONAL
436 );
437
438 /**
439 Reallocates a buffer of type EfiReservedMemoryType.
440
441 Allocates and zeros the number bytes specified by NewSize from memory of type
442 EfiReservedMemoryType. If OldBuffer is not NULL, then the smaller of OldSize and
443 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
444 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
445 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
446 enough memory remaining to satisfy the request, then NULL is returned.
447
448 If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
449 is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
450
451 @param OldSize The size, in bytes, of OldBuffer.
452 @param NewSize The size, in bytes, of the buffer to reallocate.
453 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
454 parameter that may be NULL.
455
456 @return A pointer to the allocated buffer or NULL if allocation fails.
457
458 **/
459 VOID *
460 EFIAPI
461 ReallocateReservedPool (
462 IN UINTN OldSize,
463 IN UINTN NewSize,
464 IN VOID *OldBuffer OPTIONAL
465 );
466
467 /**
468 Frees a buffer that was previously allocated with one of the pool allocation functions in the
469 Memory Allocation Library.
470
471 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
472 pool allocation services of the Memory Allocation Library. If it is not possible to free pool
473 resources, then this function will perform no actions.
474
475 If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
476 then ASSERT().
477
478 @param Buffer Pointer to the buffer to free.
479
480 **/
481 VOID
482 EFIAPI
483 FreePool (
484 IN VOID *Buffer
485 );
486
487 #endif