]>
git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/MemoryAllocationLib.h
2 Provides services to allocate and free memory buffers of various memory types and alignments.
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.
9 Copyright (c) 2006 - 2008, Intel Corporation
10 All rights reserved. This program and the accompanying materials
11 are licensed and made available under the terms and conditions of the BSD License
12 which accompanies this distribution. The full text of the license may be found at
13 http://opensource.org/licenses/bsd-license.php
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #ifndef __MEMORY_ALLOCATION_LIB_H__
21 #define __MEMORY_ALLOCATION_LIB_H__
24 Allocates one or more 4KB pages of type EfiBootServicesData.
26 Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
27 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
28 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
31 @param Pages The number of 4 KB pages to allocate.
33 @return A pointer to the allocated buffer or NULL if allocation fails.
43 Allocates one or more 4KB pages of type EfiRuntimeServicesData.
45 Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
46 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
47 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
50 @param Pages The number of 4 KB pages to allocate.
52 @return A pointer to the allocated buffer or NULL if allocation fails.
57 AllocateRuntimePages (
62 Allocates one or more 4KB pages of type EfiReservedMemoryType.
64 Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
65 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
66 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
69 @param Pages The number of 4 KB pages to allocate.
71 @return A pointer to the allocated buffer or NULL if allocation fails.
76 AllocateReservedPages (
81 Frees one or more 4KB pages that were previously allocated with one of the page allocation
82 functions in the Memory Allocation Library.
84 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
85 must have been allocated on a previous call to the page allocation services of the Memory
88 If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
90 If Pages is zero, then ASSERT().
92 @param Buffer Pointer to the buffer of pages to free.
93 @param Pages The number of 4 KB pages to free.
104 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
106 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
107 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
108 returned. If there is not enough memory at the specified alignment remaining to satisfy the
109 request, then NULL is returned.
111 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
113 @param Pages The number of 4 KB pages to allocate.
114 @param Alignment The requested alignment of the allocation. Must be a power of two.
115 If Alignment is zero, then byte alignment is used.
117 @return A pointer to the allocated buffer or NULL if allocation fails.
122 AllocateAlignedPages (
128 Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
130 Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
131 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
132 returned. If there is not enough memory at the specified alignment remaining to satisfy the
133 request, then NULL is returned.
135 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
137 @param Pages The number of 4 KB pages to allocate.
138 @param Alignment The requested alignment of the allocation. Must be a power of two.
139 If Alignment is zero, then byte alignment is used.
141 @return A pointer to the allocated buffer or NULL if allocation fails.
146 AllocateAlignedRuntimePages (
152 Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
154 Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
155 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
156 returned. If there is not enough memory at the specified alignment remaining to satisfy the
157 request, then NULL is returned.
159 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
161 @param Pages The number of 4 KB pages to allocate.
162 @param Alignment The requested alignment of the allocation. Must be a power of two.
163 If Alignment is zero, then byte alignment is used.
165 @return A pointer to the allocated buffer or NULL if allocation fails.
170 AllocateAlignedReservedPages (
176 Frees one or more 4KB pages that were previously allocated with one of the aligned page
177 allocation functions in the Memory Allocation Library.
179 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
180 must have been allocated on a previous call to the aligned page allocation services of the Memory
183 If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
184 Library, then ASSERT().
185 If Pages is zero, then ASSERT().
187 @param Buffer Pointer to the buffer of pages to free.
188 @param Pages The number of 4 KB pages to free.
199 Allocates a buffer of type EfiBootServicesData.
201 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
202 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
203 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
205 @param AllocationSize The number of bytes to allocate.
207 @return A pointer to the allocated buffer or NULL if allocation fails.
213 IN UINTN AllocationSize
217 Allocates a buffer of type EfiRuntimeServicesData.
219 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
220 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
221 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
223 @param AllocationSize The number of bytes to allocate.
225 @return A pointer to the allocated buffer or NULL if allocation fails.
230 AllocateRuntimePool (
231 IN UINTN AllocationSize
235 Allocates a buffer of type EfiReservedMemoryType.
237 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
238 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
239 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
241 @param AllocationSize The number of bytes to allocate.
243 @return A pointer to the allocated buffer or NULL if allocation fails.
248 AllocateReservedPool (
249 IN UINTN AllocationSize
253 Allocates and zeros a buffer of type EfiBootServicesData.
255 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
256 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
257 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
258 request, then NULL is returned.
260 @param AllocationSize The number of bytes to allocate and zero.
262 @return A pointer to the allocated buffer or NULL if allocation fails.
268 IN UINTN AllocationSize
272 Allocates and zeros a buffer of type EfiRuntimeServicesData.
274 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
275 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
276 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
277 request, then NULL is returned.
279 @param AllocationSize The number of bytes to allocate and zero.
281 @return A pointer to the allocated buffer or NULL if allocation fails.
286 AllocateRuntimeZeroPool (
287 IN UINTN AllocationSize
291 Allocates and zeros a buffer of type EfiReservedMemoryType.
293 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
294 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
295 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
296 request, then NULL is returned.
298 @param AllocationSize The number of bytes to allocate and zero.
300 @return A pointer to the allocated buffer or NULL if allocation fails.
305 AllocateReservedZeroPool (
306 IN UINTN AllocationSize
310 Copies a buffer to an allocated buffer of type EfiBootServicesData.
312 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
313 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
314 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
315 is not enough memory remaining to satisfy the request, then NULL is returned.
317 If Buffer is NULL, then ASSERT().
318 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
320 @param AllocationSize The number of bytes to allocate and zero.
321 @param Buffer The buffer to copy to the allocated buffer.
323 @return A pointer to the allocated buffer or NULL if allocation fails.
329 IN UINTN AllocationSize
,
330 IN CONST VOID
*Buffer
334 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
336 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
337 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
338 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
339 is not enough memory remaining to satisfy the request, then NULL is returned.
341 If Buffer is NULL, then ASSERT().
342 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
344 @param AllocationSize The number of bytes to allocate and zero.
345 @param Buffer The buffer to copy to the allocated buffer.
347 @return A pointer to the allocated buffer or NULL if allocation fails.
352 AllocateRuntimeCopyPool (
353 IN UINTN AllocationSize
,
354 IN CONST VOID
*Buffer
358 Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
360 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
361 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
362 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
363 is not enough memory remaining to satisfy the request, then NULL is returned.
365 If Buffer is NULL, then ASSERT().
366 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
368 @param AllocationSize The number of bytes to allocate and zero.
369 @param Buffer The buffer to copy to the allocated buffer.
371 @return A pointer to the allocated buffer or NULL if allocation fails.
376 AllocateReservedCopyPool (
377 IN UINTN AllocationSize
,
378 IN CONST VOID
*Buffer
382 Reallocates a buffer of type EfiBootServicesData.
384 Allocates and zeros the number bytes specified by NewSize from memory of type
385 EfiBootServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
386 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
387 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
388 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
389 enough memory remaining to satisfy the request, then NULL is returned.
391 If OldBuffer is NULL, then ASSERT().
392 If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
393 If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
395 @param OldSize The size, in bytes, of OldBuffer.
396 @param NewSize The size, in bytes, of the buffer to reallocate.
397 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
398 parameter that may be NULL.
400 @return A pointer to the allocated buffer or NULL if allocation fails.
408 IN VOID
*OldBuffer OPTIONAL
412 Reallocates a buffer of type EfiRuntimeServicesData.
414 Allocates and zeros the number bytes specified by NewSize from memory of type
415 EfiRuntimeServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
416 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
417 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
418 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
419 enough memory remaining to satisfy the request, then NULL is returned.
421 If OldBuffer is NULL, then ASSERT().
422 If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
423 If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
425 @param OldSize The size, in bytes, of OldBuffer.
426 @param NewSize The size, in bytes, of the buffer to reallocate.
427 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
428 parameter that may be NULL.
430 @return A pointer to the allocated buffer or NULL if allocation fails.
435 ReallocateRuntimePool (
438 IN VOID
*OldBuffer OPTIONAL
442 Reallocates a buffer of type EfiReservedMemoryType.
444 Allocates and zeros the number bytes specified by NewSize from memory of type
445 EfiReservedMemoryType. If OldBuffer is not NULL, then the smaller of OldSize and
446 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
447 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
448 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
449 enough memory remaining to satisfy the request, then NULL is returned.
451 If OldBuffer is NULL, then ASSERT().
452 If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
453 If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
455 @param OldSize The size, in bytes, of OldBuffer.
456 @param NewSize The size, in bytes, of the buffer to reallocate.
457 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
458 parameter that may be NULL.
460 @return A pointer to the allocated buffer or NULL if allocation fails.
465 ReallocateReservedPool (
468 IN VOID
*OldBuffer OPTIONAL
472 Frees a buffer that was previously allocated with one of the pool allocation functions in the
473 Memory Allocation Library.
475 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
476 pool allocation services of the Memory Allocation Library.
478 If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
481 @param Buffer Pointer to the buffer to free.