MdePkg/Library/PeiMemoryAllocationLib/MemoryAllocationLib.c

   1 /** @file
   2   Support routines for memory allocation routines
   3   based on PeiService for PEI phase drivers.
   4
   5   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10
  11 #include <PiPei.h>
  12
  13
  14 #include <Library/MemoryAllocationLib.h>
  15 #include <Library/PeiServicesLib.h>
  16 #include <Library/BaseMemoryLib.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/HobLib.h>
  19
  20
  21 /**
  22   Allocates one or more 4KB pages of a certain memory type.
  23
  24   Allocates the number of 4KB pages of a certain memory type and returns a pointer to the allocated
  25   buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL is returned.
  26   If there is not enough memory remaining to satisfy the request, then NULL is returned.
  27
  28   @param  MemoryType            The type of memory to allocate.
  29   @param  Pages                 The number of 4 KB pages to allocate.
  30
  31   @return A pointer to the allocated buffer or NULL if allocation fails.
  32
  33 **/
  34 VOID *
  35 InternalAllocatePages (
  36   IN EFI_MEMORY_TYPE  MemoryType,
  37   IN UINTN            Pages
  38   )
  39 {
  40   EFI_STATUS            Status;
  41   EFI_PHYSICAL_ADDRESS  Memory;
  42
  43   if (Pages == 0) {
  44     return NULL;
  45   }
  46
  47   Status = PeiServicesAllocatePages (MemoryType, Pages, &Memory);
  48   if (EFI_ERROR (Status)) {
  49     return NULL;
  50   }
  51
  52   return (VOID *) (UINTN) Memory;
  53 }
  54
  55 /**
  56   Allocates one or more 4KB pages of type EfiBootServicesData.
  57
  58   Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
  59   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  60   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  61   returned.
  62
  63   @param  Pages                 The number of 4 KB pages to allocate.
  64
  65   @return A pointer to the allocated buffer or NULL if allocation fails.
  66
  67 **/
  68 VOID *
  69 EFIAPI
  70 AllocatePages (
  71   IN UINTN  Pages
  72   )
  73 {
  74   return InternalAllocatePages (EfiBootServicesData, Pages);
  75 }
  76
  77 /**
  78   Allocates one or more 4KB pages of type EfiRuntimeServicesData.
  79
  80   Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
  81   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  82   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  83   returned.
  84
  85   @param  Pages                 The number of 4 KB pages to allocate.
  86
  87   @return A pointer to the allocated buffer or NULL if allocation fails.
  88
  89 **/
  90 VOID *
  91 EFIAPI
  92 AllocateRuntimePages (
  93   IN UINTN  Pages
  94   )
  95 {
  96   return InternalAllocatePages (EfiRuntimeServicesData, Pages);
  97 }
  98
  99 /**
 100   Allocates one or more 4KB pages of type EfiReservedMemoryType.
 101
 102   Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
 103   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
 104   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
 105   returned.
 106
 107   @param  Pages                 The number of 4 KB pages to allocate.
 108
 109   @return A pointer to the allocated buffer or NULL if allocation fails.
 110
 111 **/
 112 VOID *
 113 EFIAPI
 114 AllocateReservedPages (
 115   IN UINTN  Pages
 116   )
 117 {
 118   return InternalAllocatePages (EfiReservedMemoryType, Pages);
 119 }
 120
 121 /**
 122   Frees one or more 4KB pages that were previously allocated with one of the page allocation
 123   functions in the Memory Allocation Library.
 124
 125   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
 126   must have been allocated on a previous call to the page allocation services of the Memory
 127   Allocation Library.  If it is not possible to free allocated pages, then this function will
 128   perform no actions.
 129
 130   If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
 131   then ASSERT().
 132   If Pages is zero, then ASSERT().
 133
 134   @param  Buffer                The pointer to the buffer of pages to free.
 135   @param  Pages                 The number of 4 KB pages to free.
 136
 137 **/
 138 VOID
 139 EFIAPI
 140 FreePages (
 141   IN VOID   *Buffer,
 142   IN UINTN  Pages
 143   )
 144 {
 145   EFI_STATUS  Status;
 146
 147   ASSERT (Pages != 0);
 148   Status = PeiServicesFreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) Buffer, Pages);
 149   ASSERT_EFI_ERROR (Status);
 150 }
 151
 152 /**
 153   Allocates one or more 4KB pages of a certain memory type at a specified alignment.
 154
 155   Allocates the number of 4KB pages specified by Pages of a certain memory type with an alignment
 156   specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is returned.
 157   If there is not enough memory at the specified alignment remaining to satisfy the request, then
 158   NULL is returned.
 159   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 160   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 161
 162   @param  MemoryType            The type of memory to allocate.
 163   @param  Pages                 The number of 4 KB pages to allocate.
 164   @param  Alignment             The requested alignment of the allocation.
 165                                 Must be a power of two.
 166                                 If Alignment is zero, then byte alignment is used.
 167
 168   @return A pointer to the allocated buffer or NULL if allocation fails.
 169
 170 **/
 171 VOID *
 172 InternalAllocateAlignedPages (
 173   IN EFI_MEMORY_TYPE  MemoryType,
 174   IN UINTN            Pages,
 175   IN UINTN            Alignment
 176   )
 177 {
 178   EFI_STATUS            Status;
 179   EFI_PHYSICAL_ADDRESS  Memory;
 180   UINTN                 AlignedMemory;
 181   UINTN                 AlignmentMask;
 182   UINTN                 UnalignedPages;
 183   UINTN                 RealPages;
 184
 185   //
 186   // Alignment must be a power of two or zero.
 187   //
 188   ASSERT ((Alignment & (Alignment - 1)) == 0);
 189
 190   if (Pages == 0) {
 191     return NULL;
 192   }
 193   if (Alignment > EFI_PAGE_SIZE) {
 194     //
 195     // Calculate the total number of pages since alignment is larger than page size.
 196     //
 197     AlignmentMask  = Alignment - 1;
 198     RealPages      = Pages + EFI_SIZE_TO_PAGES (Alignment);
 199     //
 200     // Make sure that Pages plus EFI_SIZE_TO_PAGES (Alignment) does not overflow.
 201     //
 202     ASSERT (RealPages > Pages);
 203
 204     Status         = PeiServicesAllocatePages (MemoryType, RealPages, &Memory);
 205     if (EFI_ERROR (Status)) {
 206       return NULL;
 207     }
 208     AlignedMemory  = ((UINTN) Memory + AlignmentMask) & ~AlignmentMask;
 209     UnalignedPages = EFI_SIZE_TO_PAGES (AlignedMemory - (UINTN) Memory);
 210     if (UnalignedPages > 0) {
 211       //
 212       // Free first unaligned page(s).
 213       //
 214       Status = PeiServicesFreePages (Memory, UnalignedPages);
 215       ASSERT_EFI_ERROR (Status);
 216     }
 217     Memory         = AlignedMemory + EFI_PAGES_TO_SIZE (Pages);
 218     UnalignedPages = RealPages - Pages - UnalignedPages;
 219     if (UnalignedPages > 0) {
 220       //
 221       // Free last unaligned page(s).
 222       //
 223       Status = PeiServicesFreePages (Memory, UnalignedPages);
 224       ASSERT_EFI_ERROR (Status);
 225     }
 226   } else {
 227     //
 228     // Do not over-allocate pages in this case.
 229     //
 230     Status = PeiServicesAllocatePages (MemoryType, Pages, &Memory);
 231     if (EFI_ERROR (Status)) {
 232       return NULL;
 233     }
 234     AlignedMemory  = (UINTN) Memory;
 235   }
 236   return (VOID *) AlignedMemory;
 237 }
 238
 239 /**
 240   Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
 241
 242   Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
 243   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 244   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 245   request, then NULL is returned.
 246
 247   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 248   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 249
 250   @param  Pages                 The number of 4 KB pages to allocate.
 251   @param  Alignment             The requested alignment of the allocation.
 252                                 Must be a power of two.
 253                                 If Alignment is zero, then byte alignment is used.
 254
 255   @return A pointer to the allocated buffer or NULL if allocation fails.
 256
 257 **/
 258 VOID *
 259 EFIAPI
 260 AllocateAlignedPages (
 261   IN UINTN  Pages,
 262   IN UINTN  Alignment
 263   )
 264 {
 265   return InternalAllocateAlignedPages (EfiBootServicesData, Pages, Alignment);
 266 }
 267
 268 /**
 269   Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
 270
 271   Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
 272   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 273   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 274   request, then NULL is returned.
 275
 276   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 277   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 278
 279   @param  Pages                 The number of 4 KB pages to allocate.
 280   @param  Alignment             The requested alignment of the allocation.
 281                                 Must be a power of two.
 282                                 If Alignment is zero, then byte alignment is used.
 283
 284   @return A pointer to the allocated buffer or NULL if allocation fails.
 285
 286 **/
 287 VOID *
 288 EFIAPI
 289 AllocateAlignedRuntimePages (
 290   IN UINTN  Pages,
 291   IN UINTN  Alignment
 292   )
 293 {
 294   return InternalAllocateAlignedPages (EfiRuntimeServicesData, Pages, Alignment);
 295 }
 296
 297 /**
 298   Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
 299
 300   Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
 301   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 302   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 303   request, then NULL is returned.
 304
 305   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 306   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 307
 308   @param  Pages                 The number of 4 KB pages to allocate.
 309   @param  Alignment             The requested alignment of the allocation.
 310                                 Must be a power of two.
 311                                 If Alignment is zero, then byte alignment is used.
 312
 313   @return A pointer to the allocated buffer or NULL if allocation fails.
 314
 315 **/
 316 VOID *
 317 EFIAPI
 318 AllocateAlignedReservedPages (
 319   IN UINTN  Pages,
 320   IN UINTN  Alignment
 321   )
 322 {
 323   return InternalAllocateAlignedPages (EfiReservedMemoryType, Pages, Alignment);
 324 }
 325
 326 /**
 327   Frees one or more 4KB pages that were previously allocated with one of the aligned page
 328   allocation functions in the Memory Allocation Library.
 329
 330   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
 331   must have been allocated on a previous call to the aligned page allocation services of the Memory
 332   Allocation Library.  If it is not possible to free allocated pages, then this function will
 333   perform no actions.
 334
 335   If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
 336   Library, then ASSERT().
 337   If Pages is zero, then ASSERT().
 338
 339   @param  Buffer                The pointer to the buffer of pages to free.
 340   @param  Pages                 The number of 4 KB pages to free.
 341
 342 **/
 343 VOID
 344 EFIAPI
 345 FreeAlignedPages (
 346   IN VOID   *Buffer,
 347   IN UINTN  Pages
 348   )
 349 {
 350   EFI_STATUS  Status;
 351
 352   ASSERT (Pages != 0);
 353   Status = PeiServicesFreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) Buffer, Pages);
 354   ASSERT_EFI_ERROR (Status);
 355 }
 356
 357 /**
 358   Allocates a buffer of a certain pool type.
 359
 360   Allocates the number bytes specified by AllocationSize of a certain pool type and returns a
 361   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 362   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 363
 364   @param  MemoryType            The type of memory to allocate.
 365   @param  AllocationSize        The number of bytes to allocate.
 366
 367   @return A pointer to the allocated buffer or NULL if allocation fails.
 368
 369 **/
 370 VOID *
 371 InternalAllocatePool (
 372   IN EFI_MEMORY_TYPE  MemoryType,
 373   IN UINTN            AllocationSize
 374   )
 375 {
 376   //
 377   // If we need lots of small runtime/reserved memory type from PEI in the future,
 378   // we can consider providing a more complex algorithm that allocates runtime pages and
 379   // provide pool allocations from those pages.
 380   //
 381   return InternalAllocatePages (MemoryType, EFI_SIZE_TO_PAGES (AllocationSize));
 382 }
 383
 384 /**
 385   Allocates a buffer of type EfiBootServicesData.
 386
 387   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
 388   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 389   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 390
 391   @param  AllocationSize        The number of bytes to allocate.
 392
 393   @return A pointer to the allocated buffer or NULL if allocation fails.
 394
 395 **/
 396 VOID *
 397 EFIAPI
 398 AllocatePool (
 399   IN UINTN  AllocationSize
 400   )
 401 {
 402   EFI_STATUS        Status;
 403   VOID              *Buffer;
 404
 405   Status = PeiServicesAllocatePool (AllocationSize, &Buffer);
 406   if (EFI_ERROR (Status)) {
 407     Buffer = NULL;
 408   }
 409   return Buffer;
 410 }
 411
 412 /**
 413   Allocates a buffer of type EfiRuntimeServicesData.
 414
 415   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
 416   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 417   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 418
 419   @param  AllocationSize        The number of bytes to allocate.
 420
 421   @return A pointer to the allocated buffer or NULL if allocation fails.
 422
 423 **/
 424 VOID *
 425 EFIAPI
 426 AllocateRuntimePool (
 427   IN UINTN  AllocationSize
 428   )
 429 {
 430   return InternalAllocatePool (EfiRuntimeServicesData, AllocationSize);
 431 }
 432
 433 /**
 434   Allocates a buffer of type EfiReservedMemoryType.
 435
 436   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
 437   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 438   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 439
 440   @param  AllocationSize        The number of bytes to allocate.
 441
 442   @return A pointer to the allocated buffer or NULL if allocation fails.
 443
 444 **/
 445 VOID *
 446 EFIAPI
 447 AllocateReservedPool (
 448   IN UINTN  AllocationSize
 449   )
 450 {
 451   return InternalAllocatePool (EfiReservedMemoryType, AllocationSize);
 452 }
 453
 454 /**
 455   Allocates and zeros a buffer of a certain pool type.
 456
 457   Allocates the number bytes specified by AllocationSize of a certain pool type, clears the buffer
 458   with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a valid
 459   buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the request,
 460   then NULL is returned.
 461
 462   @param  PoolType              The type of memory to allocate.
 463   @param  AllocationSize        The number of bytes to allocate and zero.
 464
 465   @return A pointer to the allocated buffer or NULL if allocation fails.
 466
 467 **/
 468 VOID *
 469 InternalAllocateZeroPool (
 470   IN EFI_MEMORY_TYPE  PoolType,
 471   IN UINTN            AllocationSize
 472   )
 473 {
 474   VOID  *Memory;
 475
 476   Memory = InternalAllocatePool (PoolType, AllocationSize);
 477   if (Memory != NULL) {
 478     Memory = ZeroMem (Memory, AllocationSize);
 479   }
 480   return Memory;
 481 }
 482
 483 /**
 484   Allocates and zeros a buffer of type EfiBootServicesData.
 485
 486   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
 487   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 488   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 489   request, then NULL is returned.
 490
 491   @param  AllocationSize        The number of bytes to allocate and zero.
 492
 493   @return A pointer to the allocated buffer or NULL if allocation fails.
 494
 495 **/
 496 VOID *
 497 EFIAPI
 498 AllocateZeroPool (
 499   IN UINTN  AllocationSize
 500   )
 501 {
 502   VOID  *Memory;
 503
 504   Memory = AllocatePool (AllocationSize);
 505   if (Memory != NULL) {
 506     Memory = ZeroMem (Memory, AllocationSize);
 507   }
 508   return Memory;
 509 }
 510
 511 /**
 512   Allocates and zeros a buffer of type EfiRuntimeServicesData.
 513
 514   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
 515   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 516   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 517   request, then NULL is returned.
 518
 519   @param  AllocationSize        The number of bytes to allocate and zero.
 520
 521   @return A pointer to the allocated buffer or NULL if allocation fails.
 522
 523 **/
 524 VOID *
 525 EFIAPI
 526 AllocateRuntimeZeroPool (
 527   IN UINTN  AllocationSize
 528   )
 529 {
 530   return InternalAllocateZeroPool (EfiRuntimeServicesData, AllocationSize);
 531 }
 532
 533 /**
 534   Allocates and zeros a buffer of type EfiReservedMemoryType.
 535
 536   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
 537   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 538   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 539   request, then NULL is returned.
 540
 541   @param  AllocationSize        The number of bytes to allocate and zero.
 542
 543   @return A pointer to the allocated buffer or NULL if allocation fails.
 544
 545 **/
 546 VOID *
 547 EFIAPI
 548 AllocateReservedZeroPool (
 549   IN UINTN  AllocationSize
 550   )
 551 {
 552   return InternalAllocateZeroPool (EfiReservedMemoryType, AllocationSize);
 553 }
 554
 555 /**
 556   Copies a buffer to an allocated buffer of a certain pool type.
 557
 558   Allocates the number bytes specified by AllocationSize of a certain pool type, copies
 559   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 560   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 561   is not enough memory remaining to satisfy the request, then NULL is returned.
 562   If Buffer is NULL, then ASSERT().
 563   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 564
 565   @param  PoolType              The type of pool to allocate.
 566   @param  AllocationSize        The number of bytes to allocate and zero.
 567   @param  Buffer                The buffer to copy to the allocated buffer.
 568
 569   @return A pointer to the allocated buffer or NULL if allocation fails.
 570
 571 **/
 572 VOID *
 573 InternalAllocateCopyPool (
 574   IN EFI_MEMORY_TYPE  PoolType,
 575   IN UINTN            AllocationSize,
 576   IN CONST VOID       *Buffer
 577   )
 578 {
 579   VOID  *Memory;
 580
 581   ASSERT (Buffer != NULL);
 582   ASSERT (AllocationSize <= (MAX_ADDRESS - (UINTN) Buffer + 1));
 583
 584   Memory = InternalAllocatePool (PoolType, AllocationSize);
 585   if (Memory != NULL) {
 586      Memory = CopyMem (Memory, Buffer, AllocationSize);
 587   }
 588   return Memory;
 589 }
 590
 591 /**
 592   Copies a buffer to an allocated buffer of type EfiBootServicesData.
 593
 594   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
 595   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 596   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 597   is not enough memory remaining to satisfy the request, then NULL is returned.
 598
 599   If Buffer is NULL, then ASSERT().
 600   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 601
 602   @param  AllocationSize        The number of bytes to allocate and zero.
 603   @param  Buffer                The buffer to copy to the allocated buffer.
 604
 605   @return A pointer to the allocated buffer or NULL if allocation fails.
 606
 607 **/
 608 VOID *
 609 EFIAPI
 610 AllocateCopyPool (
 611   IN UINTN       AllocationSize,
 612   IN CONST VOID  *Buffer
 613   )
 614 {
 615   VOID  *Memory;
 616
 617   ASSERT (Buffer != NULL);
 618   ASSERT (AllocationSize <= (MAX_ADDRESS - (UINTN) Buffer + 1));
 619
 620   Memory = AllocatePool (AllocationSize);
 621   if (Memory != NULL) {
 622      Memory = CopyMem (Memory, Buffer, AllocationSize);
 623   }
 624   return Memory;
 625 }
 626
 627 /**
 628   Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
 629
 630   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
 631   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 632   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 633   is not enough memory remaining to satisfy the request, then NULL is returned.
 634
 635   If Buffer is NULL, then ASSERT().
 636   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 637
 638   @param  AllocationSize        The number of bytes to allocate and zero.
 639   @param  Buffer                The buffer to copy to the allocated buffer.
 640
 641   @return A pointer to the allocated buffer or NULL if allocation fails.
 642
 643 **/
 644 VOID *
 645 EFIAPI
 646 AllocateRuntimeCopyPool (
 647   IN UINTN       AllocationSize,
 648   IN CONST VOID  *Buffer
 649   )
 650 {
 651   return InternalAllocateCopyPool (EfiRuntimeServicesData, AllocationSize, Buffer);
 652 }
 653
 654 /**
 655   Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
 656
 657   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
 658   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 659   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 660   is not enough memory remaining to satisfy the request, then NULL is returned.
 661
 662   If Buffer is NULL, then ASSERT().
 663   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 664
 665   @param  AllocationSize        The number of bytes to allocate and zero.
 666   @param  Buffer                The buffer to copy to the allocated buffer.
 667
 668   @return A pointer to the allocated buffer or NULL if allocation fails.
 669
 670 **/
 671 VOID *
 672 EFIAPI
 673 AllocateReservedCopyPool (
 674   IN UINTN       AllocationSize,
 675   IN CONST VOID  *Buffer
 676   )
 677 {
 678   return InternalAllocateCopyPool (EfiReservedMemoryType, AllocationSize, Buffer);
 679 }
 680
 681 /**
 682   Reallocates a buffer of a specified memory type.
 683
 684   Allocates and zeros the number bytes specified by NewSize from memory of the type
 685   specified by PoolType.  If OldBuffer is not NULL, then the smaller of OldSize and
 686   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 687   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 688   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 689   enough memory remaining to satisfy the request, then NULL is returned.
 690
 691   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 692   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 693
 694   @param  PoolType       The type of pool to allocate.
 695   @param  OldSize        The size, in bytes, of OldBuffer.
 696   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 697   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an
 698                          optional parameter that may be NULL.
 699
 700   @return A pointer to the allocated buffer or NULL if allocation fails.
 701
 702 **/
 703 VOID *
 704 InternalReallocatePool (
 705   IN EFI_MEMORY_TYPE  PoolType,
 706   IN UINTN            OldSize,
 707   IN UINTN            NewSize,
 708   IN VOID             *OldBuffer  OPTIONAL
 709   )
 710 {
 711   VOID  *NewBuffer;
 712
 713   NewBuffer = InternalAllocateZeroPool (PoolType, NewSize);
 714   if (NewBuffer != NULL && OldBuffer != NULL) {
 715     CopyMem (NewBuffer, OldBuffer, MIN (OldSize, NewSize));
 716     FreePool (OldBuffer);
 717   }
 718   return NewBuffer;
 719 }
 720
 721 /**
 722   Reallocates a buffer of type EfiBootServicesData.
 723
 724   Allocates and zeros the number bytes specified by NewSize from memory of type
 725   EfiBootServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 726   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 727   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 728   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 729   enough memory remaining to satisfy the request, then NULL is returned.
 730
 731   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 732   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 733
 734   @param  OldSize        The size, in bytes, of OldBuffer.
 735   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 736   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 737                          parameter that may be NULL.
 738
 739   @return A pointer to the allocated buffer or NULL if allocation fails.
 740
 741 **/
 742 VOID *
 743 EFIAPI
 744 ReallocatePool (
 745   IN UINTN  OldSize,
 746   IN UINTN  NewSize,
 747   IN VOID   *OldBuffer  OPTIONAL
 748   )
 749 {
 750   return InternalReallocatePool (EfiBootServicesData, OldSize, NewSize, OldBuffer);
 751 }
 752
 753 /**
 754   Reallocates a buffer of type EfiRuntimeServicesData.
 755
 756   Allocates and zeros the number bytes specified by NewSize from memory of type
 757   EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 758   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 759   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 760   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 761   enough memory remaining to satisfy the request, then NULL is returned.
 762
 763   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 764   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 765
 766   @param  OldSize        The size, in bytes, of OldBuffer.
 767   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 768   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 769                          parameter that may be NULL.
 770
 771   @return A pointer to the allocated buffer or NULL if allocation fails.
 772
 773 **/
 774 VOID *
 775 EFIAPI
 776 ReallocateRuntimePool (
 777   IN UINTN  OldSize,
 778   IN UINTN  NewSize,
 779   IN VOID   *OldBuffer  OPTIONAL
 780   )
 781 {
 782   return InternalReallocatePool (EfiRuntimeServicesData, OldSize, NewSize, OldBuffer);
 783 }
 784
 785 /**
 786   Reallocates a buffer of type EfiReservedMemoryType.
 787
 788   Allocates and zeros the number bytes specified by NewSize from memory of type
 789   EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and
 790   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 791   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 792   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 793   enough memory remaining to satisfy the request, then NULL is returned.
 794
 795   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 796   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 797
 798   @param  OldSize        The size, in bytes, of OldBuffer.
 799   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 800   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an
 801                          optional parameter that may be NULL.
 802
 803   @return A pointer to the allocated buffer or NULL if allocation fails.
 804
 805 **/
 806 VOID *
 807 EFIAPI
 808 ReallocateReservedPool (
 809   IN UINTN  OldSize,
 810   IN UINTN  NewSize,
 811   IN VOID   *OldBuffer  OPTIONAL
 812   )
 813 {
 814   return InternalReallocatePool (EfiReservedMemoryType, OldSize, NewSize, OldBuffer);
 815 }
 816
 817 /**
 818   Frees a buffer that was previously allocated with one of the pool allocation functions in the
 819   Memory Allocation Library.
 820
 821   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
 822   pool allocation services of the Memory Allocation Library.  If it is not possible to free pool
 823   resources, then this function will perform no actions.
 824
 825   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
 826   then ASSERT().
 827
 828   @param  Buffer                The pointer to the buffer to free.
 829
 830 **/
 831 VOID
 832 EFIAPI
 833 FreePool (
 834   IN VOID   *Buffer
 835   )
 836 {
 837   //
 838   // PEI phase does not support to free pool, so leave it as NOP.
 839   //
 840 }
 841
 842