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