MdePkg/Include/Library/MemoryAllocationLib.h

   1 /** @file
   2   Provides services to allocate and free memory buffers of various memory types and alignments.
   3
   4 Copyright (c) 2006 - 2008, Intel Corporation
   5 All rights reserved. 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 #ifndef __MEMORY_ALLOCATION_LIB_H__
  16 #define __MEMORY_ALLOCATION_LIB_H__
  17
  18 /**
  19   Allocates one or more 4KB pages of type EfiBootServicesData.
  20
  21   Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
  22   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  23   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  24   returned.
  25
  26   @param  Pages                 The number of 4 KB pages to allocate.
  27
  28   @return A pointer to the allocated buffer or NULL if allocation fails.
  29
  30 **/
  31 VOID *
  32 EFIAPI
  33 AllocatePages (
  34   IN UINTN  Pages
  35   );
  36
  37 /**
  38   Allocates one or more 4KB pages of type EfiRuntimeServicesData.
  39
  40   Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
  41   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  42   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  43   returned.
  44
  45   @param  Pages                 The number of 4 KB pages to allocate.
  46
  47   @return A pointer to the allocated buffer or NULL if allocation fails.
  48
  49 **/
  50 VOID *
  51 EFIAPI
  52 AllocateRuntimePages (
  53   IN UINTN  Pages
  54   );
  55
  56 /**
  57   Allocates one or more 4KB pages of type EfiReservedMemoryType.
  58
  59   Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
  60   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  61   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  62   returned.
  63
  64   @param  Pages                 The number of 4 KB pages to allocate.
  65
  66   @return A pointer to the allocated buffer or NULL if allocation fails.
  67
  68 **/
  69 VOID *
  70 EFIAPI
  71 AllocateReservedPages (
  72   IN UINTN  Pages
  73   );
  74
  75 /**
  76   Frees one or more 4KB pages that were previously allocated with one of the page allocation
  77   functions in the Memory Allocation Library.
  78
  79   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
  80   must have been allocated on a previous call to the page allocation services of the Memory
  81   Allocation Library.
  82   If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
  83   then ASSERT().
  84   If Pages is zero, then ASSERT().
  85
  86   @param  Buffer                Pointer to the buffer of pages to free.
  87   @param  Pages                 The number of 4 KB pages to free.
  88
  89 **/
  90 VOID
  91 EFIAPI
  92 FreePages (
  93   IN VOID   *Buffer,
  94   IN UINTN  Pages
  95   );
  96
  97 /**
  98   Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
  99
 100   Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
 101   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 102   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 103   request, then NULL is returned.
 104   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 105
 106   @param  Pages                 The number of 4 KB pages to allocate.
 107   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 108                                 If Alignment is zero, then byte alignment is used.
 109
 110   @return A pointer to the allocated buffer or NULL if allocation fails.
 111
 112 **/
 113 VOID *
 114 EFIAPI
 115 AllocateAlignedPages (
 116   IN UINTN  Pages,
 117   IN UINTN  Alignment
 118   );
 119
 120 /**
 121   Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
 122
 123   Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
 124   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 125   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 126   request, then NULL is returned.
 127   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 128
 129   @param  Pages                 The number of 4 KB pages to allocate.
 130   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 131                                 If Alignment is zero, then byte alignment is used.
 132
 133   @return A pointer to the allocated buffer or NULL if allocation fails.
 134
 135 **/
 136 VOID *
 137 EFIAPI
 138 AllocateAlignedRuntimePages (
 139   IN UINTN  Pages,
 140   IN UINTN  Alignment
 141   );
 142
 143 /**
 144   Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
 145
 146   Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
 147   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 148   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 149   request, then NULL is returned.
 150   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 151
 152   @param  Pages                 The number of 4 KB pages to allocate.
 153   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 154                                 If Alignment is zero, then byte alignment is used.
 155
 156   @return A pointer to the allocated buffer or NULL if allocation fails.
 157
 158 **/
 159 VOID *
 160 EFIAPI
 161 AllocateAlignedReservedPages (
 162   IN UINTN  Pages,
 163   IN UINTN  Alignment
 164   );
 165
 166 /**
 167   Frees one or more 4KB pages that were previously allocated with one of the aligned page
 168   allocation functions in the Memory Allocation Library.
 169
 170   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
 171   must have been allocated on a previous call to the aligned page allocation services of the Memory
 172   Allocation Library.
 173   If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
 174   Library, then ASSERT().
 175   If Pages is zero, then ASSERT().
 176
 177   @param  Buffer                Pointer to the buffer of pages to free.
 178   @param  Pages                 The number of 4 KB pages to free.
 179
 180 **/
 181 VOID
 182 EFIAPI
 183 FreeAlignedPages (
 184   IN VOID   *Buffer,
 185   IN UINTN  Pages
 186   );
 187
 188 /**
 189   Allocates a buffer of type EfiBootServicesData.
 190
 191   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
 192   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 193   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 194
 195   @param  AllocationSize        The number of bytes to allocate.
 196
 197   @return A pointer to the allocated buffer or NULL if allocation fails.
 198
 199 **/
 200 VOID *
 201 EFIAPI
 202 AllocatePool (
 203   IN UINTN  AllocationSize
 204   );
 205
 206 /**
 207   Allocates a buffer of type EfiRuntimeServicesData.
 208
 209   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
 210   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 211   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 212
 213   @param  AllocationSize        The number of bytes to allocate.
 214
 215   @return A pointer to the allocated buffer or NULL if allocation fails.
 216
 217 **/
 218 VOID *
 219 EFIAPI
 220 AllocateRuntimePool (
 221   IN UINTN  AllocationSize
 222   );
 223
 224 /**
 225   Allocates a buffer of type EfieservedMemoryType.
 226
 227   Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType and returns
 228   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 229   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 230
 231   @param  AllocationSize        The number of bytes to allocate.
 232
 233   @return A pointer to the allocated buffer or NULL if allocation fails.
 234
 235 **/
 236 VOID *
 237 EFIAPI
 238 AllocateReservedPool (
 239   IN UINTN  AllocationSize
 240   );
 241
 242 /**
 243   Allocates and zeros a buffer of type EfiBootServicesData.
 244
 245   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
 246   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 247   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 248   request, then NULL is returned.
 249
 250   @param  AllocationSize        The number of bytes to allocate and zero.
 251
 252   @return A pointer to the allocated buffer or NULL if allocation fails.
 253
 254 **/
 255 VOID *
 256 EFIAPI
 257 AllocateZeroPool (
 258   IN UINTN  AllocationSize
 259   );
 260
 261 /**
 262   Allocates and zeros a buffer of type EfiRuntimeServicesData.
 263
 264   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
 265   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 266   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 267   request, then NULL is returned.
 268
 269   @param  AllocationSize        The number of bytes to allocate and zero.
 270
 271   @return A pointer to the allocated buffer or NULL if allocation fails.
 272
 273 **/
 274 VOID *
 275 EFIAPI
 276 AllocateRuntimeZeroPool (
 277   IN UINTN  AllocationSize
 278   );
 279
 280 /**
 281   Allocates and zeros a buffer of type EfiReservedMemoryType.
 282
 283   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
 284   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 285   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 286   request, then NULL is returned.
 287
 288   @param  AllocationSize        The number of bytes to allocate and zero.
 289
 290   @return A pointer to the allocated buffer or NULL if allocation fails.
 291
 292 **/
 293 VOID *
 294 EFIAPI
 295 AllocateReservedZeroPool (
 296   IN UINTN  AllocationSize
 297   );
 298
 299 /**
 300   Copies a buffer to an allocated buffer of type EfiBootServicesData.
 301
 302   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
 303   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 304   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 305   is not enough memory remaining to satisfy the request, then NULL is returned.
 306   If Buffer is NULL, then ASSERT().
 307   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 308
 309   @param  AllocationSize        The number of bytes to allocate and zero.
 310   @param  Buffer                The buffer to copy to the allocated buffer.
 311
 312   @return A pointer to the allocated buffer or NULL if allocation fails.
 313
 314 **/
 315 VOID *
 316 EFIAPI
 317 AllocateCopyPool (
 318   IN UINTN       AllocationSize,
 319   IN CONST VOID  *Buffer
 320   );
 321
 322 /**
 323   Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
 324
 325   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
 326   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 327   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 328   is not enough memory remaining to satisfy the request, then NULL is returned.
 329   If Buffer is NULL, then ASSERT().
 330   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 331
 332   @param  AllocationSize        The number of bytes to allocate and zero.
 333   @param  Buffer                The buffer to copy to the allocated buffer.
 334
 335   @return A pointer to the allocated buffer or NULL if allocation fails.
 336
 337 **/
 338 VOID *
 339 EFIAPI
 340 AllocateRuntimeCopyPool (
 341   IN UINTN       AllocationSize,
 342   IN CONST VOID  *Buffer
 343   );
 344
 345 /**
 346   Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
 347
 348   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
 349   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 350   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 351   is not enough memory remaining to satisfy the request, then NULL is returned.
 352   If Buffer is NULL, then ASSERT().
 353   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 354
 355   @param  AllocationSize        The number of bytes to allocate and zero.
 356   @param  Buffer                The buffer to copy to the allocated buffer.
 357
 358   @return A pointer to the allocated buffer or NULL if allocation fails.
 359
 360 **/
 361 VOID *
 362 EFIAPI
 363 AllocateReservedCopyPool (
 364   IN UINTN       AllocationSize,
 365   IN CONST VOID  *Buffer
 366   );
 367
 368 /**
 369   Frees a buffer that was previously allocated with one of the pool allocation functions in the
 370   Memory Allocation Library.
 371
 372   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
 373   pool allocation services of the Memory Allocation Library.
 374   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
 375   then ASSERT().
 376
 377   @param  Buffer                Pointer to the buffer to free.
 378
 379 **/
 380 VOID
 381 EFIAPI
 382 FreePool (
 383   IN VOID   *Buffer
 384   );
 385
 386 #endif