]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/MemoryAllocationLib.h
2 Memory Allocation Library Services
4 Copyright (c) 2006, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 Module Name: MemoryAllocationLib.h
17 #ifndef __MEMORY_ALLOCATION_LIB_H__
18 #define __MEMORY_ALLOCATION_LIB_H__
21 Allocates one or more 4KB pages of type EfiBootServicesData.
23 Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
24 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
25 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
28 @param Pages The number of 4 KB pages to allocate.
30 @return A pointer to the allocated buffer or NULL if allocation fails.
40 Allocates one or more 4KB pages of type EfiRuntimeServicesData.
42 Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
43 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
44 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
47 @param Pages The number of 4 KB pages to allocate.
49 @return A pointer to the allocated buffer or NULL if allocation fails.
54 AllocateRuntimePages (
59 Allocates one or more 4KB pages of type EfiReservedMemoryType.
61 Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
62 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
63 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
66 @param Pages The number of 4 KB pages to allocate.
68 @return A pointer to the allocated buffer or NULL if allocation fails.
73 AllocateReservedPages (
78 Frees one or more 4KB pages that were previously allocated with one of the page allocation
79 functions in the Memory Allocation Library.
81 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
82 must have been allocated on a previous call to the page allocation services of the Memory
84 If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
86 If Pages is zero, then ASSERT().
88 @param Buffer Pointer to the buffer of pages to free.
89 @param Pages The number of 4 KB pages to free.
100 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
102 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
103 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
104 returned. If there is not enough memory at the specified alignment remaining to satisfy the
105 request, then NULL is returned.
106 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
108 @param Pages The number of 4 KB pages to allocate.
109 @param Alignment The requested alignment of the allocation. Must be a power of two.
110 If Alignment is zero, then byte alignment is used.
112 @return A pointer to the allocated buffer or NULL if allocation fails.
117 AllocateAlignedPages (
123 Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
125 Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
126 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
127 returned. If there is not enough memory at the specified alignment remaining to satisfy the
128 request, then NULL is returned.
129 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
131 @param Pages The number of 4 KB pages to allocate.
132 @param Alignment The requested alignment of the allocation. Must be a power of two.
133 If Alignment is zero, then byte alignment is used.
135 @return A pointer to the allocated buffer or NULL if allocation fails.
140 AllocateAlignedRuntimePages (
146 Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
148 Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
149 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
150 returned. If there is not enough memory at the specified alignment remaining to satisfy the
151 request, then NULL is returned.
152 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
154 @param Pages The number of 4 KB pages to allocate.
155 @param Alignment The requested alignment of the allocation. Must be a power of two.
156 If Alignment is zero, then byte alignment is used.
158 @return A pointer to the allocated buffer or NULL if allocation fails.
163 AllocateAlignedReservedPages (
169 Frees one or more 4KB pages that were previously allocated with one of the aligned page
170 allocation functions in the Memory Allocation Library.
172 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
173 must have been allocated on a previous call to the aligned page allocation services of the Memory
175 If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
176 Library, then ASSERT().
177 If Pages is zero, then ASSERT().
179 @param Buffer Pointer to the buffer of pages to free.
180 @param Pages The number of 4 KB pages to free.
191 Allocates a buffer of type EfiBootServicesData.
193 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
194 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
195 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
197 @param AllocationSize The number of bytes to allocate.
199 @return A pointer to the allocated buffer or NULL if allocation fails.
205 IN UINTN AllocationSize
209 Allocates a buffer of type EfiRuntimeServicesData.
211 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
212 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
213 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
215 @param AllocationSize The number of bytes to allocate.
217 @return A pointer to the allocated buffer or NULL if allocation fails.
222 AllocateRuntimePool (
223 IN UINTN AllocationSize
227 Allocates a buffer of type EfieservedMemoryType.
229 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType and returns
230 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
231 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
233 @param AllocationSize The number of bytes to allocate.
235 @return A pointer to the allocated buffer or NULL if allocation fails.
240 AllocateReservedPool (
241 IN UINTN AllocationSize
245 Allocates and zeros a buffer of type EfiBootServicesData.
247 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
248 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
249 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
250 request, then NULL is returned.
252 @param AllocationSize The number of bytes to allocate and zero.
254 @return A pointer to the allocated buffer or NULL if allocation fails.
260 IN UINTN AllocationSize
264 Allocates and zeros a buffer of type EfiRuntimeServicesData.
266 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
267 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
268 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
269 request, then NULL is returned.
271 @param AllocationSize The number of bytes to allocate and zero.
273 @return A pointer to the allocated buffer or NULL if allocation fails.
278 AllocateRuntimeZeroPool (
279 IN UINTN AllocationSize
283 Allocates and zeros a buffer of type EfiReservedMemoryType.
285 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
286 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
287 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
288 request, then NULL is returned.
290 @param AllocationSize The number of bytes to allocate and zero.
292 @return A pointer to the allocated buffer or NULL if allocation fails.
297 AllocateReservedZeroPool (
298 IN UINTN AllocationSize
302 Copies a buffer to an allocated buffer of type EfiBootServicesData.
304 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
305 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
306 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
307 is not enough memory remaining to satisfy the request, then NULL is returned.
308 If Buffer is NULL, then ASSERT().
309 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
311 @param AllocationSize The number of bytes to allocate and zero.
312 @param Buffer The buffer to copy to the allocated buffer.
314 @return A pointer to the allocated buffer or NULL if allocation fails.
320 IN UINTN AllocationSize
,
321 IN CONST VOID
*Buffer
325 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
327 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
328 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
329 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
330 is not enough memory remaining to satisfy the request, then NULL is returned.
331 If Buffer is NULL, then ASSERT().
332 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
334 @param AllocationSize The number of bytes to allocate and zero.
335 @param Buffer The buffer to copy to the allocated buffer.
337 @return A pointer to the allocated buffer or NULL if allocation fails.
342 AllocateRuntimeCopyPool (
343 IN UINTN AllocationSize
,
344 IN CONST VOID
*Buffer
348 Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
350 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
351 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
352 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
353 is not enough memory remaining to satisfy the request, then NULL is returned.
354 If Buffer is NULL, then ASSERT().
355 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
357 @param AllocationSize The number of bytes to allocate and zero.
358 @param Buffer The buffer to copy to the allocated buffer.
360 @return A pointer to the allocated buffer or NULL if allocation fails.
365 AllocateReservedCopyPool (
366 IN UINTN AllocationSize
,
367 IN CONST VOID
*Buffer
371 Frees a buffer that was previously allocated with one of the pool allocation functions in the
372 Memory Allocation Library.
374 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
375 pool allocation services of the Memory Allocation Library.
376 If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
379 @param Buffer Pointer to the buffer to free.
389 Allocates a buffer of type EfiBootServicesData at a specified alignment.
391 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData with an
392 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
393 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
394 alignment remaining to satisfy the request, then NULL is returned.
395 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
397 @param AllocationSize The number of bytes to allocate.
398 @param Alignment The requested alignment of the allocation. Must be a power of two.
399 If Alignment is zero, then byte alignment is used.
401 @return A pointer to the allocated buffer or NULL if allocation fails.
406 AllocateAlignedPool (
407 IN UINTN AllocationSize
,
412 Allocates a buffer of type EfiRuntimeServicesData at a specified alignment.
414 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData with an
415 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
416 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
417 alignment remaining to satisfy the request, then NULL is returned.
418 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
420 @param AllocationSize The number of bytes to allocate.
421 @param Alignment The requested alignment of the allocation. Must be a power of two.
422 If Alignment is zero, then byte alignment is used.
424 @return A pointer to the allocated buffer or NULL if allocation fails.
429 AllocateAlignedRuntimePool (
430 IN UINTN AllocationSize
,
435 Allocates a buffer of type EfieservedMemoryType at a specified alignment.
437 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType with an
438 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
439 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
440 alignment remaining to satisfy the request, then NULL is returned.
441 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
443 @param AllocationSize The number of bytes to allocate.
444 @param Alignment The requested alignment of the allocation. Must be a power of two.
445 If Alignment is zero, then byte alignment is used.
447 @return A pointer to the allocated buffer or NULL if allocation fails.
452 AllocateAlignedReservedPool (
453 IN UINTN AllocationSize
,
458 Allocates and zeros a buffer of type EfiBootServicesData at a specified alignment.
460 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData with an
461 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the
462 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
463 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is
465 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
467 @param AllocationSize The number of bytes to allocate.
468 @param Alignment The requested alignment of the allocation. Must be a power of two.
469 If Alignment is zero, then byte alignment is used.
471 @return A pointer to the allocated buffer or NULL if allocation fails.
476 AllocateAlignedZeroPool (
477 IN UINTN AllocationSize
,
482 Allocates and zeros a buffer of type EfiRuntimeServicesData at a specified alignment.
484 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData with an
485 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the
486 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
487 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is
489 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
491 @param AllocationSize The number of bytes to allocate.
492 @param Alignment The requested alignment of the allocation. Must be a power of two.
493 If Alignment is zero, then byte alignment is used.
495 @return A pointer to the allocated buffer or NULL if allocation fails.
500 AllocateAlignedRuntimeZeroPool (
501 IN UINTN AllocationSize
,
506 Allocates and zeros a buffer of type EfieservedMemoryType at a specified alignment.
508 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType with an
509 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the
510 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
511 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is
513 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
515 @param AllocationSize The number of bytes to allocate.
516 @param Alignment The requested alignment of the allocation. Must be a power of two.
517 If Alignment is zero, then byte alignment is used.
519 @return A pointer to the allocated buffer or NULL if allocation fails.
524 AllocateAlignedReservedZeroPool (
525 IN UINTN AllocationSize
,
530 Copies a buffer to an allocated buffer of type EfiBootServicesData at a specified alignment.
532 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData type with an
533 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
534 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
535 alignment remaining to satisfy the request, then NULL is returned.
536 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
538 @param AllocationSize The number of bytes to allocate.
539 @param Buffer The buffer to copy to the allocated buffer.
540 @param Alignment The requested alignment of the allocation. Must be a power of two.
541 If Alignment is zero, then byte alignment is used.
543 @return A pointer to the allocated buffer or NULL if allocation fails.
548 AllocateAlignedCopyPool (
549 IN UINTN AllocationSize
,
550 IN CONST VOID
*Buffer
,
555 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData at a specified alignment.
557 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData type with an
558 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
559 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
560 alignment remaining to satisfy the request, then NULL is returned.
561 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
563 @param AllocationSize The number of bytes to allocate.
564 @param Buffer The buffer to copy to the allocated buffer.
565 @param Alignment The requested alignment of the allocation. Must be a power of two.
566 If Alignment is zero, then byte alignment is used.
568 @return A pointer to the allocated buffer or NULL if allocation fails.
573 AllocateAlignedRuntimeCopyPool (
574 IN UINTN AllocationSize
,
575 IN CONST VOID
*Buffer
,
580 Copies a buffer to an allocated buffer of type EfiReservedMemoryType at a specified alignment.
582 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType type with an
583 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
584 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
585 alignment remaining to satisfy the request, then NULL is returned.
586 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
588 @param AllocationSize The number of bytes to allocate.
589 @param Buffer The buffer to copy to the allocated buffer.
590 @param Alignment The requested alignment of the allocation. Must be a power of two.
591 If Alignment is zero, then byte alignment is used.
593 @return A pointer to the allocated buffer or NULL if allocation fails.
598 AllocateAlignedReservedCopyPool (
599 IN UINTN AllocationSize
,
600 IN CONST VOID
*Buffer
,
605 Frees a buffer that was previously allocated with one of the aligned pool allocation functions
606 in the Memory Allocation Library.
608 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
609 aligned pool allocation services of the Memory Allocation Library.
610 If Buffer was not allocated with an aligned pool allocation function in the Memory Allocation
611 Library, then ASSERT().
613 @param Buffer Pointer to the buffer to free.