MdeModulePkg/Library/PiSmmCoreMemoryAllocationLib/MemoryAllocationLib.c

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