]>
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
86 Allocation Library. If it is not possible to free allocated pages, then this function will
89 If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
91 If Pages is zero, then ASSERT().
93 @param Buffer Pointer to the buffer of pages to free.
94 @param Pages The number of 4 KB pages to free.
105 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
107 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
108 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
109 returned. If there is not enough memory at the specified alignment remaining to satisfy the
110 request, then NULL is returned.
112 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
114 @param Pages The number of 4 KB pages to allocate.
115 @param Alignment The requested alignment of the allocation. Must be a power of two.
116 If Alignment is zero, then byte alignment is used.
118 @return A pointer to the allocated buffer or NULL if allocation fails.
123 AllocateAlignedPages (
129 Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
131 Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
132 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
133 returned. If there is not enough memory at the specified alignment remaining to satisfy the
134 request, then NULL is returned.
136 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
138 @param Pages The number of 4 KB pages to allocate.
139 @param Alignment The requested alignment of the allocation. Must be a power of two.
140 If Alignment is zero, then byte alignment is used.
142 @return A pointer to the allocated buffer or NULL if allocation fails.
147 AllocateAlignedRuntimePages (
153 Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
155 Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
156 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
157 returned. If there is not enough memory at the specified alignment remaining to satisfy the
158 request, then NULL is returned.
160 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
162 @param Pages The number of 4 KB pages to allocate.
163 @param Alignment The requested alignment of the allocation. Must be a power of two.
164 If Alignment is zero, then byte alignment is used.
166 @return A pointer to the allocated buffer or NULL if allocation fails.
171 AllocateAlignedReservedPages (
177 Frees one or more 4KB pages that were previously allocated with one of the aligned page
178 allocation functions in the Memory Allocation Library.
180 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
181 must have been allocated on a previous call to the aligned page allocation services of the Memory
182 Allocation Library. If it is not possible to free allocated pages, then this function will
185 If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
186 Library, then ASSERT().
187 If Pages is zero, then ASSERT().
189 @param Buffer Pointer to the buffer of pages to free.
190 @param Pages The number of 4 KB pages to free.
201 Allocates a buffer of type EfiBootServicesData.
203 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
204 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
205 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
207 @param AllocationSize The number of bytes to allocate.
209 @return A pointer to the allocated buffer or NULL if allocation fails.
215 IN UINTN AllocationSize
219 Allocates a buffer of type EfiRuntimeServicesData.
221 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
222 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
223 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
225 @param AllocationSize The number of bytes to allocate.
227 @return A pointer to the allocated buffer or NULL if allocation fails.
232 AllocateRuntimePool (
233 IN UINTN AllocationSize
237 Allocates a buffer of type EfiReservedMemoryType.
239 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
240 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
241 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
243 @param AllocationSize The number of bytes to allocate.
245 @return A pointer to the allocated buffer or NULL if allocation fails.
250 AllocateReservedPool (
251 IN UINTN AllocationSize
255 Allocates and zeros a buffer of type EfiBootServicesData.
257 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
258 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
259 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
260 request, then NULL is returned.
262 @param AllocationSize The number of bytes to allocate and zero.
264 @return A pointer to the allocated buffer or NULL if allocation fails.
270 IN UINTN AllocationSize
274 Allocates and zeros a buffer of type EfiRuntimeServicesData.
276 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
277 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
278 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
279 request, then NULL is returned.
281 @param AllocationSize The number of bytes to allocate and zero.
283 @return A pointer to the allocated buffer or NULL if allocation fails.
288 AllocateRuntimeZeroPool (
289 IN UINTN AllocationSize
293 Allocates and zeros a buffer of type EfiReservedMemoryType.
295 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
296 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
297 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
298 request, then NULL is returned.
300 @param AllocationSize The number of bytes to allocate and zero.
302 @return A pointer to the allocated buffer or NULL if allocation fails.
307 AllocateReservedZeroPool (
308 IN UINTN AllocationSize
312 Copies a buffer to an allocated buffer of type EfiBootServicesData.
314 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
315 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
316 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
317 is not enough memory remaining to satisfy the request, then NULL is returned.
319 If Buffer is NULL, then ASSERT().
320 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
322 @param AllocationSize The number of bytes to allocate and zero.
323 @param Buffer The buffer to copy to the allocated buffer.
325 @return A pointer to the allocated buffer or NULL if allocation fails.
331 IN UINTN AllocationSize
,
332 IN CONST VOID
*Buffer
336 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
338 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
339 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
340 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
341 is not enough memory remaining to satisfy the request, then NULL is returned.
343 If Buffer is NULL, then ASSERT().
344 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
346 @param AllocationSize The number of bytes to allocate and zero.
347 @param Buffer The buffer to copy to the allocated buffer.
349 @return A pointer to the allocated buffer or NULL if allocation fails.
354 AllocateRuntimeCopyPool (
355 IN UINTN AllocationSize
,
356 IN CONST VOID
*Buffer
360 Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
362 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
363 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
364 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
365 is not enough memory remaining to satisfy the request, then NULL is returned.
367 If Buffer is NULL, then ASSERT().
368 If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
370 @param AllocationSize The number of bytes to allocate and zero.
371 @param Buffer The buffer to copy to the allocated buffer.
373 @return A pointer to the allocated buffer or NULL if allocation fails.
378 AllocateReservedCopyPool (
379 IN UINTN AllocationSize
,
380 IN CONST VOID
*Buffer
384 Reallocates a buffer of type EfiBootServicesData.
386 Allocates and zeros the number bytes specified by NewSize from memory of type
387 EfiBootServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
388 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
389 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
390 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
391 enough memory remaining to satisfy the request, then NULL is returned.
393 If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
394 is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
396 @param OldSize The size, in bytes, of OldBuffer.
397 @param NewSize The size, in bytes, of the buffer to reallocate.
398 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
399 parameter that may be NULL.
401 @return A pointer to the allocated buffer or NULL if allocation fails.
409 IN VOID
*OldBuffer OPTIONAL
413 Reallocates a buffer of type EfiRuntimeServicesData.
415 Allocates and zeros the number bytes specified by NewSize from memory of type
416 EfiRuntimeServicesData. If OldBuffer is not NULL, then the smaller of OldSize and
417 NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
418 OldBuffer is freed. A pointer to the newly allocated buffer is returned.
419 If NewSize is 0, then a valid buffer of 0 size is returned. If there is not
420 enough memory remaining to satisfy the request, then NULL is returned.
422 If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
423 is greater than (MAX_ADDRESS - OldBuffer + 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 the allocation of the new buffer is successful and the smaller of NewSize and OldSize
452 is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
454 @param OldSize The size, in bytes, of OldBuffer.
455 @param NewSize The size, in bytes, of the buffer to reallocate.
456 @param OldBuffer The buffer to copy to the allocated buffer. This is an optional
457 parameter that may be NULL.
459 @return A pointer to the allocated buffer or NULL if allocation fails.
464 ReallocateReservedPool (
467 IN VOID
*OldBuffer OPTIONAL
471 Frees a buffer that was previously allocated with one of the pool allocation functions in the
472 Memory Allocation Library.
474 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
475 pool allocation services of the Memory Allocation Library. If it is not possible to free pool
476 resources, then this function will perform no actions.
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.