]>
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 NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
392 If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
394 @param OldSize The size, in bytes, of OldBuffer.
395 @param NewSize The size, in bytes, of the buffer to reallocate.
396 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
397 parameter that may be NULL.
399 @return A pointer to the allocated buffer or NULL if allocation fails.
407 IN VOID
*OldBuffer OPTIONAL
411 Reallocates a buffer of type EfiRuntimeServicesData.
413 Allocates and zeros the number bytes specified by NewSize from memory of type
414 EfiRuntimeServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
415 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
416 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
417 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
418 enough memory remaining to satisfy the request, then NULL is returned.
420 If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
421 If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
423 @param OldSize The size, in bytes, of OldBuffer.
424 @param NewSize The size, in bytes, of the buffer to reallocate.
425 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
426 parameter that may be NULL.
428 @return A pointer to the allocated buffer or NULL if allocation fails.
433 ReallocateRuntimePool (
436 IN VOID
*OldBuffer OPTIONAL
440 Reallocates a buffer of type EfiReservedMemoryType.
442 Allocates and zeros the number bytes specified by NewSize from memory of type
443 EfiReservedMemoryType. If OldBuffer is not NULL, then the smaller of OldSize and
444 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
445 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
446 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
447 enough memory remaining to satisfy the request, then NULL is returned.
449 If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
450 If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
452 @param OldSize The size, in bytes, of OldBuffer.
453 @param NewSize The size, in bytes, of the buffer to reallocate.
454 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
455 parameter that may be NULL.
457 @return A pointer to the allocated buffer or NULL if allocation fails.
462 ReallocateReservedPool (
465 IN VOID
*OldBuffer OPTIONAL
469 Frees a buffer that was previously allocated with one of the pool allocation functions in the
470 Memory Allocation Library.
472 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
473 pool allocation services of the Memory Allocation Library.
475 If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
478 @param Buffer Pointer to the buffer to free.