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 - 2013, 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   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 255
 256   @param  MemoryType            The type of memory to allocate.
 257   @param  Pages                 The number of 4 KB pages to allocate.
 258   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 259                                 If Alignment is zero, then byte alignment is used.
 260
 261   @return A pointer to the allocated buffer or NULL if allocation fails.
 262
 263 **/
 264 VOID *
 265 InternalAllocateAlignedPages (
 266   IN EFI_MEMORY_TYPE  MemoryType,
 267   IN UINTN            Pages,
 268   IN UINTN            Alignment
 269   )
 270 {
 271   EFI_STATUS            Status;
 272   EFI_PHYSICAL_ADDRESS  Memory;
 273   UINTN                 AlignedMemory;
 274   UINTN                 AlignmentMask;
 275   UINTN                 UnalignedPages;
 276   UINTN                 RealPages;
 277
 278   //
 279   // Alignment must be a power of two or zero.
 280   //
 281   ASSERT ((Alignment & (Alignment - 1)) == 0);
 282
 283   if (Pages == 0) {
 284     return NULL;
 285   }
 286   if (Alignment > EFI_PAGE_SIZE) {
 287     //
 288     // Caculate the total number of pages since alignment is larger than page size.
 289     //
 290     AlignmentMask  = Alignment - 1;
 291     RealPages      = Pages + EFI_SIZE_TO_PAGES (Alignment);
 292     //
 293     // Make sure that Pages plus EFI_SIZE_TO_PAGES (Alignment) does not overflow.
 294     //
 295     ASSERT (RealPages > Pages);
 296
 297     Status         = SmmAllocatePages (AllocateAnyPages, MemoryType, RealPages, &Memory);
 298     if (EFI_ERROR (Status)) {
 299       return NULL;
 300     }
 301     AlignedMemory  = ((UINTN) Memory + AlignmentMask) & ~AlignmentMask;
 302     UnalignedPages = EFI_SIZE_TO_PAGES (AlignedMemory - (UINTN) Memory);
 303     if (UnalignedPages > 0) {
 304       //
 305       // Free first unaligned page(s).
 306       //
 307       Status = SmmFreePages (Memory, UnalignedPages);
 308       ASSERT_EFI_ERROR (Status);
 309     }
 310     Memory         = (EFI_PHYSICAL_ADDRESS) (AlignedMemory + EFI_PAGES_TO_SIZE (Pages));
 311     UnalignedPages = RealPages - Pages - UnalignedPages;
 312     if (UnalignedPages > 0) {
 313       //
 314       // Free last unaligned page(s).
 315       //
 316       Status = SmmFreePages (Memory, UnalignedPages);
 317       ASSERT_EFI_ERROR (Status);
 318     }
 319   } else {
 320     //
 321     // Do not over-allocate pages in this case.
 322     //
 323     Status = SmmAllocatePages (AllocateAnyPages, MemoryType, Pages, &Memory);
 324     if (EFI_ERROR (Status)) {
 325       return NULL;
 326     }
 327     AlignedMemory  = (UINTN) Memory;
 328   }
 329   return (VOID *) AlignedMemory;
 330 }
 331
 332 /**
 333   Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
 334
 335   Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
 336   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 337   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 338   request, then NULL is returned.
 339
 340   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 341   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 342
 343   @param  Pages                 The number of 4 KB pages to allocate.
 344   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 345                                 If Alignment is zero, then byte alignment is used.
 346
 347   @return A pointer to the allocated buffer or NULL if allocation fails.
 348
 349 **/
 350 VOID *
 351 EFIAPI
 352 AllocateAlignedPages (
 353   IN UINTN  Pages,
 354   IN UINTN  Alignment
 355   )
 356 {
 357   return InternalAllocateAlignedPages (EfiRuntimeServicesData, Pages, Alignment);
 358 }
 359
 360 /**
 361   Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
 362
 363   Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
 364   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 365   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 366   request, then NULL is returned.
 367
 368   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 369   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 370
 371   @param  Pages                 The number of 4 KB pages to allocate.
 372   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 373                                 If Alignment is zero, then byte alignment is used.
 374
 375   @return A pointer to the allocated buffer or NULL if allocation fails.
 376
 377 **/
 378 VOID *
 379 EFIAPI
 380 AllocateAlignedRuntimePages (
 381   IN UINTN  Pages,
 382   IN UINTN  Alignment
 383   )
 384 {
 385   return InternalAllocateAlignedPages (EfiRuntimeServicesData, Pages, Alignment);
 386 }
 387
 388 /**
 389   Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
 390
 391   Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
 392   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 393   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 394   request, then NULL is returned.
 395
 396   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 397   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 398
 399   @param  Pages                 The number of 4 KB pages to allocate.
 400   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 401                                 If Alignment is zero, then byte alignment is used.
 402
 403   @return A pointer to the allocated buffer or NULL if allocation fails.
 404
 405 **/
 406 VOID *
 407 EFIAPI
 408 AllocateAlignedReservedPages (
 409   IN UINTN  Pages,
 410   IN UINTN  Alignment
 411   )
 412 {
 413   return NULL;
 414 }
 415
 416 /**
 417   Frees one or more 4KB pages that were previously allocated with one of the aligned page
 418   allocation functions in the Memory Allocation Library.
 419
 420   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
 421   must have been allocated on a previous call to the aligned page allocation services of the Memory
 422   Allocation Library.  If it is not possible to free allocated pages, then this function will
 423   perform no actions.
 424
 425   If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
 426   Library, then ASSERT().
 427   If Pages is zero, then ASSERT().
 428
 429   @param  Buffer                Pointer to the buffer of pages to free.
 430   @param  Pages                 The number of 4 KB pages to free.
 431
 432 **/
 433 VOID
 434 EFIAPI
 435 FreeAlignedPages (
 436   IN VOID   *Buffer,
 437   IN UINTN  Pages
 438   )
 439 {
 440   EFI_STATUS  Status;
 441
 442   ASSERT (Pages != 0);
 443   if (BufferInSmram (Buffer)) {
 444     //
 445     // When Buffer is in SMRAM range, it should be allocated by SmmAllocatePages() service.
 446     // So, SmmFreePages() service is used to free it.
 447     //
 448     Status = SmmFreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) Buffer, Pages);
 449   } else {
 450     //
 451     // When Buffer is out of SMRAM range, it should be allocated by gBS->AllocatePages() service.
 452     // So, gBS->FreePages() service is used to free it.
 453     //
 454     Status = gBS->FreePages ((EFI_PHYSICAL_ADDRESS) (UINTN) Buffer, Pages);
 455   }
 456   ASSERT_EFI_ERROR (Status);
 457 }
 458
 459 /**
 460   Allocates a buffer of a certain pool type.
 461
 462   Allocates the number bytes specified by AllocationSize of a certain pool type and returns a
 463   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 464   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 465
 466   @param  MemoryType            The type of memory to allocate.
 467   @param  AllocationSize        The number of bytes to allocate.
 468
 469   @return A pointer to the allocated buffer or NULL if allocation fails.
 470
 471 **/
 472 VOID *
 473 InternalAllocatePool (
 474   IN EFI_MEMORY_TYPE  MemoryType,
 475   IN UINTN            AllocationSize
 476   )
 477 {
 478   EFI_STATUS  Status;
 479   VOID        *Memory;
 480
 481   Status = SmmAllocatePool (MemoryType, AllocationSize, &Memory);
 482   if (EFI_ERROR (Status)) {
 483     Memory = NULL;
 484   }
 485   return Memory;
 486 }
 487
 488 /**
 489   Allocates a buffer of type EfiBootServicesData.
 490
 491   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
 492   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 493   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 494
 495   @param  AllocationSize        The number of bytes to allocate.
 496
 497   @return A pointer to the allocated buffer or NULL if allocation fails.
 498
 499 **/
 500 VOID *
 501 EFIAPI
 502 AllocatePool (
 503   IN UINTN  AllocationSize
 504   )
 505 {
 506   return InternalAllocatePool (EfiRuntimeServicesData, AllocationSize);
 507 }
 508
 509 /**
 510   Allocates a buffer of type EfiRuntimeServicesData.
 511
 512   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
 513   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 514   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 515
 516   @param  AllocationSize        The number of bytes to allocate.
 517
 518   @return A pointer to the allocated buffer or NULL if allocation fails.
 519
 520 **/
 521 VOID *
 522 EFIAPI
 523 AllocateRuntimePool (
 524   IN UINTN  AllocationSize
 525   )
 526 {
 527   return InternalAllocatePool (EfiRuntimeServicesData, AllocationSize);
 528 }
 529
 530 /**
 531   Allocates a buffer of type EfiReservedMemoryType.
 532
 533   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
 534   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 535   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 536
 537   @param  AllocationSize        The number of bytes to allocate.
 538
 539   @return A pointer to the allocated buffer or NULL if allocation fails.
 540
 541 **/
 542 VOID *
 543 EFIAPI
 544 AllocateReservedPool (
 545   IN UINTN  AllocationSize
 546   )
 547 {
 548   return NULL;
 549 }
 550
 551 /**
 552   Allocates and zeros a buffer of a certain pool type.
 553
 554   Allocates the number bytes specified by AllocationSize of a certain pool type, clears the buffer
 555   with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a valid
 556   buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the request,
 557   then NULL is returned.
 558
 559   @param  PoolType              The type of memory to allocate.
 560   @param  AllocationSize        The number of bytes to allocate and zero.
 561
 562   @return A pointer to the allocated buffer or NULL if allocation fails.
 563
 564 **/
 565 VOID *
 566 InternalAllocateZeroPool (
 567   IN EFI_MEMORY_TYPE  PoolType,
 568   IN UINTN            AllocationSize
 569   )
 570 {
 571   VOID  *Memory;
 572
 573   Memory = InternalAllocatePool (PoolType, AllocationSize);
 574   if (Memory != NULL) {
 575     Memory = ZeroMem (Memory, AllocationSize);
 576   }
 577   return Memory;
 578 }
 579
 580 /**
 581   Allocates and zeros a buffer of type EfiBootServicesData.
 582
 583   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
 584   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 585   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 586   request, then NULL is returned.
 587
 588   @param  AllocationSize        The number of bytes to allocate and zero.
 589
 590   @return A pointer to the allocated buffer or NULL if allocation fails.
 591
 592 **/
 593 VOID *
 594 EFIAPI
 595 AllocateZeroPool (
 596   IN UINTN  AllocationSize
 597   )
 598 {
 599   return InternalAllocateZeroPool (EfiRuntimeServicesData, AllocationSize);
 600 }
 601
 602 /**
 603   Allocates and zeros a buffer of type EfiRuntimeServicesData.
 604
 605   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
 606   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 607   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 608   request, then NULL is returned.
 609
 610   @param  AllocationSize        The number of bytes to allocate and zero.
 611
 612   @return A pointer to the allocated buffer or NULL if allocation fails.
 613
 614 **/
 615 VOID *
 616 EFIAPI
 617 AllocateRuntimeZeroPool (
 618   IN UINTN  AllocationSize
 619   )
 620 {
 621   return InternalAllocateZeroPool (EfiRuntimeServicesData, AllocationSize);
 622 }
 623
 624 /**
 625   Allocates and zeros a buffer of type EfiReservedMemoryType.
 626
 627   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
 628   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 629   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 630   request, then NULL is returned.
 631
 632   @param  AllocationSize        The number of bytes to allocate and zero.
 633
 634   @return A pointer to the allocated buffer or NULL if allocation fails.
 635
 636 **/
 637 VOID *
 638 EFIAPI
 639 AllocateReservedZeroPool (
 640   IN UINTN  AllocationSize
 641   )
 642 {
 643   return NULL;
 644 }
 645
 646 /**
 647   Copies a buffer to an allocated buffer of a certain pool type.
 648
 649   Allocates the number bytes specified by AllocationSize of a certain pool type, copies
 650   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 651   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 652   is not enough memory remaining to satisfy the request, then NULL is returned.
 653   If Buffer is NULL, then ASSERT().
 654   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 655
 656   @param  PoolType              The type of pool to allocate.
 657   @param  AllocationSize        The number of bytes to allocate and zero.
 658   @param  Buffer                The buffer to copy to the allocated buffer.
 659
 660   @return A pointer to the allocated buffer or NULL if allocation fails.
 661
 662 **/
 663 VOID *
 664 InternalAllocateCopyPool (
 665   IN EFI_MEMORY_TYPE  PoolType,
 666   IN UINTN            AllocationSize,
 667   IN CONST VOID       *Buffer
 668   )
 669 {
 670   VOID  *Memory;
 671
 672   ASSERT (Buffer != NULL);
 673   ASSERT (AllocationSize <= (MAX_ADDRESS - (UINTN) Buffer + 1));
 674
 675   Memory = InternalAllocatePool (PoolType, AllocationSize);
 676   if (Memory != NULL) {
 677      Memory = CopyMem (Memory, Buffer, AllocationSize);
 678   }
 679   return Memory;
 680 }
 681
 682 /**
 683   Copies a buffer to an allocated buffer of type EfiBootServicesData.
 684
 685   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
 686   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 687   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 688   is not enough memory remaining to satisfy the request, then NULL is returned.
 689
 690   If Buffer is NULL, then ASSERT().
 691   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 692
 693   @param  AllocationSize        The number of bytes to allocate and zero.
 694   @param  Buffer                The buffer to copy to the allocated buffer.
 695
 696   @return A pointer to the allocated buffer or NULL if allocation fails.
 697
 698 **/
 699 VOID *
 700 EFIAPI
 701 AllocateCopyPool (
 702   IN UINTN       AllocationSize,
 703   IN CONST VOID  *Buffer
 704   )
 705 {
 706   return InternalAllocateCopyPool (EfiRuntimeServicesData, AllocationSize, Buffer);
 707 }
 708
 709 /**
 710   Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
 711
 712   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
 713   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 714   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 715   is not enough memory remaining to satisfy the request, then NULL is returned.
 716
 717   If Buffer is NULL, then ASSERT().
 718   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 719
 720   @param  AllocationSize        The number of bytes to allocate and zero.
 721   @param  Buffer                The buffer to copy to the allocated buffer.
 722
 723   @return A pointer to the allocated buffer or NULL if allocation fails.
 724
 725 **/
 726 VOID *
 727 EFIAPI
 728 AllocateRuntimeCopyPool (
 729   IN UINTN       AllocationSize,
 730   IN CONST VOID  *Buffer
 731   )
 732 {
 733   return InternalAllocateCopyPool (EfiRuntimeServicesData, AllocationSize, Buffer);
 734 }
 735
 736 /**
 737   Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
 738
 739   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
 740   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 741   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 742   is not enough memory remaining to satisfy the request, then NULL is returned.
 743
 744   If Buffer is NULL, then ASSERT().
 745   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 746
 747   @param  AllocationSize        The number of bytes to allocate and zero.
 748   @param  Buffer                The buffer to copy to the allocated buffer.
 749
 750   @return A pointer to the allocated buffer or NULL if allocation fails.
 751
 752 **/
 753 VOID *
 754 EFIAPI
 755 AllocateReservedCopyPool (
 756   IN UINTN       AllocationSize,
 757   IN CONST VOID  *Buffer
 758   )
 759 {
 760   return NULL;
 761 }
 762
 763 /**
 764   Reallocates a buffer of a specified memory type.
 765
 766   Allocates and zeros the number bytes specified by NewSize from memory of the type
 767   specified by PoolType.  If OldBuffer is not NULL, then the smaller of OldSize and
 768   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 769   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 770   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 771   enough memory remaining to satisfy the request, then NULL is returned.
 772
 773   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 774   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 775
 776   @param  PoolType       The type of pool to allocate.
 777   @param  OldSize        The size, in bytes, of OldBuffer.
 778   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 779   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 780                          parameter that may be NULL.
 781
 782   @return A pointer to the allocated buffer or NULL if allocation fails.
 783
 784 **/
 785 VOID *
 786 InternalReallocatePool (
 787   IN EFI_MEMORY_TYPE  PoolType,
 788   IN UINTN            OldSize,
 789   IN UINTN            NewSize,
 790   IN VOID             *OldBuffer  OPTIONAL
 791   )
 792 {
 793   VOID  *NewBuffer;
 794
 795   NewBuffer = InternalAllocateZeroPool (PoolType, NewSize);
 796   if (NewBuffer != NULL && OldBuffer != NULL) {
 797     CopyMem (NewBuffer, OldBuffer, MIN (OldSize, NewSize));
 798     FreePool (OldBuffer);
 799   }
 800   return NewBuffer;
 801 }
 802
 803 /**
 804   Reallocates a buffer of type EfiBootServicesData.
 805
 806   Allocates and zeros the number bytes specified by NewSize from memory of type
 807   EfiBootServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 808   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 809   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 810   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 811   enough memory remaining to satisfy the request, then NULL is returned.
 812
 813   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 814   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 815
 816   @param  OldSize        The size, in bytes, of OldBuffer.
 817   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 818   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 819                          parameter that may be NULL.
 820
 821   @return A pointer to the allocated buffer or NULL if allocation fails.
 822
 823 **/
 824 VOID *
 825 EFIAPI
 826 ReallocatePool (
 827   IN UINTN  OldSize,
 828   IN UINTN  NewSize,
 829   IN VOID   *OldBuffer  OPTIONAL
 830   )
 831 {
 832   return InternalReallocatePool (EfiRuntimeServicesData, OldSize, NewSize, OldBuffer);
 833 }
 834
 835 /**
 836   Reallocates a buffer of type EfiRuntimeServicesData.
 837
 838   Allocates and zeros the number bytes specified by NewSize from memory of type
 839   EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 840   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 841   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 842   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 843   enough memory remaining to satisfy the request, then NULL is returned.
 844
 845   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 846   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 847
 848   @param  OldSize        The size, in bytes, of OldBuffer.
 849   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 850   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 851                          parameter that may be NULL.
 852
 853   @return A pointer to the allocated buffer or NULL if allocation fails.
 854
 855 **/
 856 VOID *
 857 EFIAPI
 858 ReallocateRuntimePool (
 859   IN UINTN  OldSize,
 860   IN UINTN  NewSize,
 861   IN VOID   *OldBuffer  OPTIONAL
 862   )
 863 {
 864   return InternalReallocatePool (EfiRuntimeServicesData, OldSize, NewSize, OldBuffer);
 865 }
 866
 867 /**
 868   Reallocates a buffer of type EfiReservedMemoryType.
 869
 870   Allocates and zeros the number bytes specified by NewSize from memory of type
 871   EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and
 872   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 873   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 874   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 875   enough memory remaining to satisfy the request, then NULL is returned.
 876
 877   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 878   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 879
 880   @param  OldSize        The size, in bytes, of OldBuffer.
 881   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 882   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 883                          parameter that may be NULL.
 884
 885   @return A pointer to the allocated buffer or NULL if allocation fails.
 886
 887 **/
 888 VOID *
 889 EFIAPI
 890 ReallocateReservedPool (
 891   IN UINTN  OldSize,
 892   IN UINTN  NewSize,
 893   IN VOID   *OldBuffer  OPTIONAL
 894   )
 895 {
 896   return NULL;
 897 }
 898
 899 /**
 900   Frees a buffer that was previously allocated with one of the pool allocation functions in the
 901   Memory Allocation Library.
 902
 903   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
 904   pool allocation services of the Memory Allocation Library.  If it is not possible to free pool
 905   resources, then this function will perform no actions.
 906
 907   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
 908   then ASSERT().
 909
 910   @param  Buffer                Pointer to the buffer to free.
 911
 912 **/
 913 VOID
 914 EFIAPI
 915 FreePool (
 916   IN VOID   *Buffer
 917   )
 918 {
 919   EFI_STATUS    Status;
 920
 921   if (BufferInSmram (Buffer)) {
 922     //
 923     // When Buffer is in SMRAM range, it should be allocated by SmmAllocatePool() service.
 924     // So, SmmFreePool() service is used to free it.
 925     //
 926     Status = SmmFreePool (Buffer);
 927   } else {
 928     //
 929     // When Buffer is out of SMRAM range, it should be allocated by gBS->AllocatePool() service.
 930     // So, gBS->FreePool() service is used to free it.
 931     //
 932     Status = gBS->FreePool (Buffer);
 933   }
 934   ASSERT_EFI_ERROR (Status);
 935 }
 936