Second set of changes based on a review of the code comments in the Include directory...

[mirror_edk2.git] / MdePkg / Include / Library / MemoryAllocationLib.h

diff --git a/MdePkg/Include/Library/MemoryAllocationLib.h b/MdePkg/Include/Library/MemoryAllocationLib.h
index 347e45a24eb6c5b055922b108e8412f21a3c01ef..5199e17ce81d6781b31862370d5f056a8bc9b113 100644 (file)
--- a/MdePkg/Include/Library/MemoryAllocationLib.h
+++ b/MdePkg/Include/Library/MemoryAllocationLib.h
@@ -83,7 +83,8 @@ AllocateReservedPages (
 \r
   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer\r
   must have been allocated on a previous call to the page allocation services of the Memory\r
-  Allocation Library.\r
+  Allocation Library.  If it is not possible to free allocated pages, then this function will\r
+  perform no actions.\r
   \r
   If Buffer was not allocated with a page allocation function in the Memory Allocation Library,\r
   then ASSERT().\r
@@ -178,7 +179,8 @@ AllocateAlignedReservedPages (
 \r
   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer\r
   must have been allocated on a previous call to the aligned page allocation services of the Memory\r
-  Allocation Library.\r
+  Allocation Library.  If it is not possible to free allocated pages, then this function will \r
+  perform no actions.\r
   \r
   If Buffer was not allocated with an aligned page allocation function in the Memory Allocation\r
   Library, then ASSERT().\r
@@ -378,12 +380,100 @@ AllocateReservedCopyPool (
   IN CONST VOID  *Buffer\r
   );\r
 \r
+/**\r
+  Reallocates a buffer of type EfiBootServicesData.\r
+\r
+  Allocates and zeros the number bytes specified by NewSize from memory of type\r
+  EfiBootServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and \r
+  NewSize bytes are copied from OldBuffer to the newly allocated buffer, and \r
+  OldBuffer is freed.  A pointer to the newly allocated buffer is returned.  \r
+  If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not \r
+  enough memory remaining to satisfy the request, then NULL is returned.\r
+  \r
+  If the allocation of the new buffer is successful and the smaller of NewSize and OldSize\r
+  is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().\r
+\r
+  @param  OldSize        The size, in bytes, of OldBuffer.\r
+  @param  NewSize        The size, in bytes, of the buffer to reallocate.\r
+  @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional \r
+                         parameter that may be NULL.\r
+\r
+  @return A pointer to the allocated buffer or NULL if allocation fails.\r
+\r
+**/\r
+VOID *\r
+EFIAPI\r
+ReallocatePool (\r
+  IN UINTN  OldSize,\r
+  IN UINTN  NewSize,\r
+  IN VOID   *OldBuffer  OPTIONAL\r
+  );\r
+\r
+/**\r
+  Reallocates a buffer of type EfiRuntimeServicesData.\r
+\r
+  Allocates and zeros the number bytes specified by NewSize from memory of type\r
+  EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and \r
+  NewSize bytes are copied from OldBuffer to the newly allocated buffer, and \r
+  OldBuffer is freed.  A pointer to the newly allocated buffer is returned.  \r
+  If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not \r
+  enough memory remaining to satisfy the request, then NULL is returned.\r
+\r
+  If the allocation of the new buffer is successful and the smaller of NewSize and OldSize\r
+  is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().\r
+\r
+  @param  OldSize        The size, in bytes, of OldBuffer.\r
+  @param  NewSize        The size, in bytes, of the buffer to reallocate.\r
+  @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional \r
+                         parameter that may be NULL.\r
+\r
+  @return A pointer to the allocated buffer or NULL if allocation fails.\r
+\r
+**/\r
+VOID *\r
+EFIAPI\r
+ReallocateRuntimePool (\r
+  IN UINTN  OldSize,\r
+  IN UINTN  NewSize,\r
+  IN VOID   *OldBuffer  OPTIONAL\r
+  );\r
+\r
+/**\r
+  Reallocates a buffer of type EfiReservedMemoryType.\r
+\r
+  Allocates and zeros the number bytes specified by NewSize from memory of type\r
+  EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and \r
+  NewSize bytes are copied from OldBuffer to the newly allocated buffer, and \r
+  OldBuffer is freed.  A pointer to the newly allocated buffer is returned.  \r
+  If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not \r
+  enough memory remaining to satisfy the request, then NULL is returned.\r
+\r
+  If the allocation of the new buffer is successful and the smaller of NewSize and OldSize\r
+  is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().\r
+\r
+  @param  OldSize        The size, in bytes, of OldBuffer.\r
+  @param  NewSize        The size, in bytes, of the buffer to reallocate.\r
+  @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional \r
+                         parameter that may be NULL.\r
+\r
+  @return A pointer to the allocated buffer or NULL if allocation fails.\r
+\r
+**/\r
+VOID *\r
+EFIAPI\r
+ReallocateReservedPool (\r
+  IN UINTN  OldSize,\r
+  IN UINTN  NewSize,\r
+  IN VOID   *OldBuffer  OPTIONAL\r
+  );\r
+\r
 /**\r
   Frees a buffer that was previously allocated with one of the pool allocation functions in the\r
   Memory Allocation Library.\r
 \r
   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the\r
-  pool allocation services of the Memory Allocation Library.\r
+  pool allocation services of the Memory Allocation Library.  If it is not possible to free pool\r
+  resources, then this function will perform no actions.\r
   \r
   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,\r
   then ASSERT().\r