1 /*++ 2 3 Copyright (c) 2004 - 2006, Intel Corporation. All rights reserved.<BR> 4 This program and the accompanying materials 5 are licensed and made available under the terms and conditions of the BSD License 6 which accompanies this distribution. The full text of the license may be found at 7 http://opensource.org/licenses/bsd-license.php 8 9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 11 12 13 Module Name: 14 15 EdkIIGlueMemoryAllocationLib.h 16 17 Abstract: 18 19 Public header file for Memory Allocation Lib 20 21 --*/ 22 23 #ifndef __EDKII_GLUE_MEMORY_ALLOCATION_LIB_H__ 24 #define __EDKII_GLUE_MEMORY_ALLOCATION_LIB_H__ 25 26 27 #define AllocatePages(_PAGES) GlueAllocatePages(_PAGES) 28 #define FreePages(_BUFFER, _PAGES) GlueFreePages(_BUFFER, _PAGES) 29 #define AllocatePool(_SIZE) GlueAllocatePool(_SIZE) 30 #define AllocateZeroPool(_ALLOCATIONSIZE) GlueAllocateZeroPool(_ALLOCATIONSIZE) 31 #define AllocateCopyPool(_ALLOCATIONSIZE, _BUFFER) GlueAllocateCopyPool(_ALLOCATIONSIZE, _BUFFER) 32 #define FreePool(_BUFFER) GlueFreePool(_BUFFER) 33 34 35 /** 36 Allocates one or more 4KB pages of type EfiBootServicesData. 37 38 Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the 39 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL 40 is returned. If there is not enough memory remaining to satisfy the request, then NULL is 41 returned. 42 43 @param Pages The number of 4 KB pages to allocate. 44 45 @return A pointer to the allocated buffer or NULL if allocation fails. 46 47 **/ 48 VOID * 49 EFIAPI 50 GlueAllocatePages ( 51 IN UINTN Pages 52 ); 53 54 /** 55 Allocates one or more 4KB pages of type EfiRuntimeServicesData. 56 57 Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the 58 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL 59 is returned. If there is not enough memory remaining to satisfy the request, then NULL is 60 returned. 61 62 @param Pages The number of 4 KB pages to allocate. 63 64 @return A pointer to the allocated buffer or NULL if allocation fails. 65 66 **/ 67 VOID * 68 EFIAPI 69 AllocateRuntimePages ( 70 IN UINTN Pages 71 ); 72 73 /** 74 Allocates one or more 4KB pages of type EfiReservedMemoryType. 75 76 Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the 77 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL 78 is returned. If there is not enough memory remaining to satisfy the request, then NULL is 79 returned. 80 81 @param Pages The number of 4 KB pages to allocate. 82 83 @return A pointer to the allocated buffer or NULL if allocation fails. 84 85 **/ 86 VOID * 87 EFIAPI 88 AllocateReservedPages ( 89 IN UINTN Pages 90 ); 91 92 /** 93 Frees one or more 4KB pages that were previously allocated with one of the page allocation 94 functions in the Memory Allocation Library. 95 96 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer 97 must have been allocated on a previous call to the page allocation services of the Memory 98 Allocation Library. 99 If Buffer was not allocated with a page allocation function in the Memory Allocation Library, 100 then ASSERT(). 101 If Pages is zero, then ASSERT(). 102 103 @param Buffer Pointer to the buffer of pages to free. 104 @param Pages The number of 4 KB pages to free. 105 106 **/ 107 VOID 108 EFIAPI 109 GlueFreePages ( 110 IN VOID *Buffer, 111 IN UINTN Pages 112 ); 113 114 /** 115 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment. 116 117 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an 118 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is 119 returned. If there is not enough memory at the specified alignment remaining to satisfy the 120 request, then NULL is returned. 121 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 122 123 @param Pages The number of 4 KB pages to allocate. 124 @param Alignment The requested alignment of the allocation. Must be a power of two. 125 If Alignment is zero, then byte alignment is used. 126 127 @return A pointer to the allocated buffer or NULL if allocation fails. 128 129 **/ 130 VOID * 131 EFIAPI 132 AllocateAlignedPages ( 133 IN UINTN Pages, 134 IN UINTN Alignment 135 ); 136 137 /** 138 Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment. 139 140 Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an 141 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is 142 returned. If there is not enough memory at the specified alignment remaining to satisfy the 143 request, then NULL is returned. 144 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 145 146 @param Pages The number of 4 KB pages to allocate. 147 @param Alignment The requested alignment of the allocation. Must be a power of two. 148 If Alignment is zero, then byte alignment is used. 149 150 @return A pointer to the allocated buffer or NULL if allocation fails. 151 152 **/ 153 VOID * 154 EFIAPI 155 AllocateAlignedRuntimePages ( 156 IN UINTN Pages, 157 IN UINTN Alignment 158 ); 159 160 /** 161 Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment. 162 163 Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an 164 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is 165 returned. If there is not enough memory at the specified alignment remaining to satisfy the 166 request, then NULL is returned. 167 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 168 169 @param Pages The number of 4 KB pages to allocate. 170 @param Alignment The requested alignment of the allocation. Must be a power of two. 171 If Alignment is zero, then byte alignment is used. 172 173 @return A pointer to the allocated buffer or NULL if allocation fails. 174 175 **/ 176 VOID * 177 EFIAPI 178 AllocateAlignedReservedPages ( 179 IN UINTN Pages, 180 IN UINTN Alignment 181 ); 182 183 /** 184 Frees one or more 4KB pages that were previously allocated with one of the aligned page 185 allocation functions in the Memory Allocation Library. 186 187 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer 188 must have been allocated on a previous call to the aligned page allocation services of the Memory 189 Allocation Library. 190 If Buffer was not allocated with an aligned page allocation function in the Memory Allocation 191 Library, then ASSERT(). 192 If Pages is zero, then ASSERT(). 193 194 @param Buffer Pointer to the buffer of pages to free. 195 @param Pages The number of 4 KB pages to free. 196 197 **/ 198 VOID 199 EFIAPI 200 FreeAlignedPages ( 201 IN VOID *Buffer, 202 IN UINTN Pages 203 ); 204 205 /** 206 Allocates a buffer of type EfiBootServicesData. 207 208 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a 209 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is 210 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. 211 212 @param AllocationSize The number of bytes to allocate. 213 214 @return A pointer to the allocated buffer or NULL if allocation fails. 215 216 **/ 217 VOID * 218 EFIAPI 219 GlueAllocatePool ( 220 IN UINTN AllocationSize 221 ); 222 223 /** 224 Allocates a buffer of type EfiRuntimeServicesData. 225 226 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns 227 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is 228 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. 229 230 @param AllocationSize The number of bytes to allocate. 231 232 @return A pointer to the allocated buffer or NULL if allocation fails. 233 234 **/ 235 VOID * 236 EFIAPI 237 AllocateRuntimePool ( 238 IN UINTN AllocationSize 239 ); 240 241 /** 242 Allocates a buffer of type EfieservedMemoryType. 243 244 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType and returns 245 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is 246 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned. 247 248 @param AllocationSize The number of bytes to allocate. 249 250 @return A pointer to the allocated buffer or NULL if allocation fails. 251 252 **/ 253 VOID * 254 EFIAPI 255 AllocateReservedPool ( 256 IN UINTN AllocationSize 257 ); 258 259 /** 260 Allocates and zeros a buffer of type EfiBootServicesData. 261 262 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the 263 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a 264 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the 265 request, then NULL is returned. 266 267 @param AllocationSize The number of bytes to allocate and zero. 268 269 @return A pointer to the allocated buffer or NULL if allocation fails. 270 271 **/ 272 VOID * 273 EFIAPI 274 GlueAllocateZeroPool ( 275 IN UINTN AllocationSize 276 ); 277 278 /** 279 Allocates and zeros a buffer of type EfiRuntimeServicesData. 280 281 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the 282 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a 283 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the 284 request, then NULL is returned. 285 286 @param AllocationSize The number of bytes to allocate and zero. 287 288 @return A pointer to the allocated buffer or NULL if allocation fails. 289 290 **/ 291 VOID * 292 EFIAPI 293 AllocateRuntimeZeroPool ( 294 IN UINTN AllocationSize 295 ); 296 297 /** 298 Allocates and zeros a buffer of type EfiReservedMemoryType. 299 300 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the 301 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a 302 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the 303 request, then NULL is returned. 304 305 @param AllocationSize The number of bytes to allocate and zero. 306 307 @return A pointer to the allocated buffer or NULL if allocation fails. 308 309 **/ 310 VOID * 311 EFIAPI 312 AllocateReservedZeroPool ( 313 IN UINTN AllocationSize 314 ); 315 316 /** 317 Copies a buffer to an allocated buffer of type EfiBootServicesData. 318 319 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies 320 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the 321 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there 322 is not enough memory remaining to satisfy the request, then NULL is returned. 323 If Buffer is NULL, then ASSERT(). 324 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). 325 326 @param AllocationSize The number of bytes to allocate and zero. 327 @param Buffer The buffer to copy to the allocated buffer. 328 329 @return A pointer to the allocated buffer or NULL if allocation fails. 330 331 **/ 332 VOID * 333 EFIAPI 334 GlueAllocateCopyPool ( 335 IN UINTN AllocationSize, 336 IN CONST VOID *Buffer 337 ); 338 339 /** 340 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData. 341 342 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies 343 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the 344 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there 345 is not enough memory remaining to satisfy the request, then NULL is returned. 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 If Buffer is NULL, then ASSERT(). 370 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT(). 371 372 @param AllocationSize The number of bytes to allocate and zero. 373 @param Buffer The buffer to copy to the allocated buffer. 374 375 @return A pointer to the allocated buffer or NULL if allocation fails. 376 377 **/ 378 VOID * 379 EFIAPI 380 AllocateReservedCopyPool ( 381 IN UINTN AllocationSize, 382 IN CONST VOID *Buffer 383 ); 384 385 /** 386 Frees a buffer that was previously allocated with one of the pool allocation functions in the 387 Memory Allocation Library. 388 389 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the 390 pool allocation services of the Memory Allocation Library. 391 If Buffer was not allocated with a pool allocation function in the Memory Allocation Library, 392 then ASSERT(). 393 394 @param Buffer Pointer to the buffer to free. 395 396 **/ 397 VOID 398 EFIAPI 399 GlueFreePool ( 400 IN VOID *Buffer 401 ); 402 403 /** 404 Allocates a buffer of type EfiBootServicesData at a specified alignment. 405 406 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData with an 407 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0, 408 then a valid buffer of 0 size is returned. If there is not enough memory at the specified 409 alignment remaining to satisfy the request, then NULL is returned. 410 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 411 412 @param AllocationSize The number of bytes to allocate. 413 @param Alignment The requested alignment of the allocation. Must be a power of two. 414 If Alignment is zero, then byte alignment is used. 415 416 @return A pointer to the allocated buffer or NULL if allocation fails. 417 418 **/ 419 VOID * 420 EFIAPI 421 AllocateAlignedPool ( 422 IN UINTN AllocationSize, 423 IN UINTN Alignment 424 ); 425 426 /** 427 Allocates a buffer of type EfiRuntimeServicesData at a specified alignment. 428 429 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData with an 430 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0, 431 then a valid buffer of 0 size is returned. If there is not enough memory at the specified 432 alignment remaining to satisfy the request, then NULL is returned. 433 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 434 435 @param AllocationSize The number of bytes to allocate. 436 @param Alignment The requested alignment of the allocation. Must be a power of two. 437 If Alignment is zero, then byte alignment is used. 438 439 @return A pointer to the allocated buffer or NULL if allocation fails. 440 441 **/ 442 VOID * 443 EFIAPI 444 AllocateAlignedRuntimePool ( 445 IN UINTN AllocationSize, 446 IN UINTN Alignment 447 ); 448 449 /** 450 Allocates a buffer of type EfieservedMemoryType at a specified alignment. 451 452 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType with an 453 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0, 454 then a valid buffer of 0 size is returned. If there is not enough memory at the specified 455 alignment remaining to satisfy the request, then NULL is returned. 456 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 457 458 @param AllocationSize The number of bytes to allocate. 459 @param Alignment The requested alignment of the allocation. Must be a power of two. 460 If Alignment is zero, then byte alignment is used. 461 462 @return A pointer to the allocated buffer or NULL if allocation fails. 463 464 **/ 465 VOID * 466 EFIAPI 467 AllocateAlignedReservedPool ( 468 IN UINTN AllocationSize, 469 IN UINTN Alignment 470 ); 471 472 /** 473 Allocates and zeros a buffer of type EfiBootServicesData at a specified alignment. 474 475 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData with an 476 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the 477 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there 478 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is 479 returned. 480 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 481 482 @param AllocationSize The number of bytes to allocate. 483 @param Alignment The requested alignment of the allocation. Must be a power of two. 484 If Alignment is zero, then byte alignment is used. 485 486 @return A pointer to the allocated buffer or NULL if allocation fails. 487 488 **/ 489 VOID * 490 EFIAPI 491 AllocateAlignedZeroPool ( 492 IN UINTN AllocationSize, 493 IN UINTN Alignment 494 ); 495 496 /** 497 Allocates and zeros a buffer of type EfiRuntimeServicesData at a specified alignment. 498 499 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData with an 500 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the 501 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there 502 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is 503 returned. 504 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 505 506 @param AllocationSize The number of bytes to allocate. 507 @param Alignment The requested alignment of the allocation. Must be a power of two. 508 If Alignment is zero, then byte alignment is used. 509 510 @return A pointer to the allocated buffer or NULL if allocation fails. 511 512 **/ 513 VOID * 514 EFIAPI 515 AllocateAlignedRuntimeZeroPool ( 516 IN UINTN AllocationSize, 517 IN UINTN Alignment 518 ); 519 520 /** 521 Allocates and zeros a buffer of type EfieservedMemoryType at a specified alignment. 522 523 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType with an 524 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the 525 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there 526 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is 527 returned. 528 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 529 530 @param AllocationSize The number of bytes to allocate. 531 @param Alignment The requested alignment of the allocation. Must be a power of two. 532 If Alignment is zero, then byte alignment is used. 533 534 @return A pointer to the allocated buffer or NULL if allocation fails. 535 536 **/ 537 VOID * 538 EFIAPI 539 AllocateAlignedReservedZeroPool ( 540 IN UINTN AllocationSize, 541 IN UINTN Alignment 542 ); 543 544 /** 545 Copies a buffer to an allocated buffer of type EfiBootServicesData at a specified alignment. 546 547 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData type with an 548 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0, 549 then a valid buffer of 0 size is returned. If there is not enough memory at the specified 550 alignment remaining to satisfy the request, then NULL is returned. 551 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 552 553 @param AllocationSize The number of bytes to allocate. 554 @param Buffer The buffer to copy to the allocated buffer. 555 @param Alignment The requested alignment of the allocation. Must be a power of two. 556 If Alignment is zero, then byte alignment is used. 557 558 @return A pointer to the allocated buffer or NULL if allocation fails. 559 560 **/ 561 VOID * 562 EFIAPI 563 AllocateAlignedCopyPool ( 564 IN UINTN AllocationSize, 565 IN CONST VOID *Buffer, 566 IN UINTN Alignment 567 ); 568 569 /** 570 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData at a specified alignment. 571 572 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData type with an 573 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0, 574 then a valid buffer of 0 size is returned. If there is not enough memory at the specified 575 alignment remaining to satisfy the request, then NULL is returned. 576 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 577 578 @param AllocationSize The number of bytes to allocate. 579 @param Buffer The buffer to copy to the allocated buffer. 580 @param Alignment The requested alignment of the allocation. Must be a power of two. 581 If Alignment is zero, then byte alignment is used. 582 583 @return A pointer to the allocated buffer or NULL if allocation fails. 584 585 **/ 586 VOID * 587 EFIAPI 588 AllocateAlignedRuntimeCopyPool ( 589 IN UINTN AllocationSize, 590 IN CONST VOID *Buffer, 591 IN UINTN Alignment 592 ); 593 594 /** 595 Copies a buffer to an allocated buffer of type EfiReservedMemoryType at a specified alignment. 596 597 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType type with an 598 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0, 599 then a valid buffer of 0 size is returned. If there is not enough memory at the specified 600 alignment remaining to satisfy the request, then NULL is returned. 601 If Alignment is not a power of two and Alignment is not zero, then ASSERT(). 602 603 @param AllocationSize The number of bytes to allocate. 604 @param Buffer The buffer to copy to the allocated buffer. 605 @param Alignment The requested alignment of the allocation. Must be a power of two. 606 If Alignment is zero, then byte alignment is used. 607 608 @return A pointer to the allocated buffer or NULL if allocation fails. 609 610 **/ 611 VOID * 612 EFIAPI 613 AllocateAlignedReservedCopyPool ( 614 IN UINTN AllocationSize, 615 IN CONST VOID *Buffer, 616 IN UINTN Alignment 617 ); 618 619 /** 620 Frees a buffer that was previously allocated with one of the aligned pool allocation functions 621 in the Memory Allocation Library. 622 623 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the 624 aligned pool allocation services of the Memory Allocation Library. 625 If Buffer was not allocated with an aligned pool allocation function in the Memory Allocation 626 Library, then ASSERT(). 627 628 @param Buffer Pointer to the buffer to free. 629 630 **/ 631 VOID 632 EFIAPI 633 FreeAlignedPool ( 634 IN VOID *Buffer 635 ); 636 637 #endif 638