sys/contrib/edk2/Include/Library/MemoryAllocationLib.h

   1 /** @file
   2   Provides services to allocate and free memory buffers of various memory types and alignments.
   3
   4   The Memory Allocation Library abstracts various common memory allocation operations. This library
   5   allows code to be written in a phase-independent manner because the allocation of memory in PEI, DXE,
   6   and SMM (for example) is done via a different mechanism. Using a common library interface makes it
   7   much easier to port algorithms from phase to phase.
   8
   9 Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>
  10 This program and the accompanying materials
  11 are licensed and made available under the terms and conditions of the BSD License
  12 which accompanies this distribution.  The full text of the license may be found at
  13 http://opensource.org/licenses/bsd-license.php
  14
  15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  17
  18 **/
  19
  20 #ifndef __MEMORY_ALLOCATION_LIB_H__
  21 #define __MEMORY_ALLOCATION_LIB_H__
  22
  23 /**
  24   Allocates one or more 4KB pages of type EfiBootServicesData.
  25
  26   Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
  27   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  28   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  29   returned.
  30
  31   @param  Pages                 The number of 4 KB pages to allocate.
  32
  33   @return A pointer to the allocated buffer or NULL if allocation fails.
  34
  35 **/
  36 VOID *
  37 EFIAPI
  38 AllocatePages (
  39   IN UINTN  Pages
  40   );
  41
  42 /**
  43   Allocates one or more 4KB pages of type EfiRuntimeServicesData.
  44
  45   Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
  46   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  47   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  48   returned.
  49
  50   @param  Pages                 The number of 4 KB pages to allocate.
  51
  52   @return A pointer to the allocated buffer or NULL if allocation fails.
  53
  54 **/
  55 VOID *
  56 EFIAPI
  57 AllocateRuntimePages (
  58   IN UINTN  Pages
  59   );
  60
  61 /**
  62   Allocates one or more 4KB pages of type EfiReservedMemoryType.
  63
  64   Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
  65   allocated buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL
  66   is returned.  If there is not enough memory remaining to satisfy the request, then NULL is
  67   returned.
  68
  69   @param  Pages                 The number of 4 KB pages to allocate.
  70
  71   @return A pointer to the allocated buffer or NULL if allocation fails.
  72
  73 **/
  74 VOID *
  75 EFIAPI
  76 AllocateReservedPages (
  77   IN UINTN  Pages
  78   );
  79
  80 /**
  81   Frees one or more 4KB pages that were previously allocated with one of the page allocation
  82   functions in the Memory Allocation Library.
  83
  84   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
  85   must have been allocated on a previous call to the page allocation services of the Memory
  86   Allocation Library.  If it is not possible to free allocated pages, then this function will
  87   perform no actions.
  88
  89   If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
  90   then ASSERT().
  91   If Pages is zero, then ASSERT().
  92
  93   @param  Buffer                Pointer to the buffer of pages to free.
  94   @param  Pages                 The number of 4 KB pages to free.
  95
  96 **/
  97 VOID
  98 EFIAPI
  99 FreePages (
 100   IN VOID   *Buffer,
 101   IN UINTN  Pages
 102   );
 103
 104 /**
 105   Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
 106
 107   Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
 108   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 109   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 110   request, then NULL is returned.
 111
 112   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 113   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 114
 115   @param  Pages                 The number of 4 KB pages to allocate.
 116   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 117                                 If Alignment is zero, then byte alignment is used.
 118
 119   @return A pointer to the allocated buffer or NULL if allocation fails.
 120
 121 **/
 122 VOID *
 123 EFIAPI
 124 AllocateAlignedPages (
 125   IN UINTN  Pages,
 126   IN UINTN  Alignment
 127   );
 128
 129 /**
 130   Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
 131
 132   Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
 133   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 134   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 135   request, then NULL is returned.
 136
 137   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 138   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 139
 140   @param  Pages                 The number of 4 KB pages to allocate.
 141   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 142                                 If Alignment is zero, then byte alignment is used.
 143
 144   @return A pointer to the allocated buffer or NULL if allocation fails.
 145
 146 **/
 147 VOID *
 148 EFIAPI
 149 AllocateAlignedRuntimePages (
 150   IN UINTN  Pages,
 151   IN UINTN  Alignment
 152   );
 153
 154 /**
 155   Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
 156
 157   Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
 158   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 159   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 160   request, then NULL is returned.
 161
 162   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 163   If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
 164
 165   @param  Pages                 The number of 4 KB pages to allocate.
 166   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 167                                 If Alignment is zero, then byte alignment is used.
 168
 169   @return A pointer to the allocated buffer or NULL if allocation fails.
 170
 171 **/
 172 VOID *
 173 EFIAPI
 174 AllocateAlignedReservedPages (
 175   IN UINTN  Pages,
 176   IN UINTN  Alignment
 177   );
 178
 179 /**
 180   Frees one or more 4KB pages that were previously allocated with one of the aligned page
 181   allocation functions in the Memory Allocation Library.
 182
 183   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
 184   must have been allocated on a previous call to the aligned page allocation services of the Memory
 185   Allocation Library.  If it is not possible to free allocated pages, then this function will
 186   perform no actions.
 187
 188   If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
 189   Library, then ASSERT().
 190   If Pages is zero, then ASSERT().
 191
 192   @param  Buffer                Pointer to the buffer of pages to free.
 193   @param  Pages                 The number of 4 KB pages to free.
 194
 195 **/
 196 VOID
 197 EFIAPI
 198 FreeAlignedPages (
 199   IN VOID   *Buffer,
 200   IN UINTN  Pages
 201   );
 202
 203 /**
 204   Allocates a buffer of type EfiBootServicesData.
 205
 206   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
 207   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 208   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 209
 210   @param  AllocationSize        The number of bytes to allocate.
 211
 212   @return A pointer to the allocated buffer or NULL if allocation fails.
 213
 214 **/
 215 VOID *
 216 EFIAPI
 217 AllocatePool (
 218   IN UINTN  AllocationSize
 219   );
 220
 221 /**
 222   Allocates a buffer of type EfiRuntimeServicesData.
 223
 224   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
 225   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 226   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 227
 228   @param  AllocationSize        The number of bytes to allocate.
 229
 230   @return A pointer to the allocated buffer or NULL if allocation fails.
 231
 232 **/
 233 VOID *
 234 EFIAPI
 235 AllocateRuntimePool (
 236   IN UINTN  AllocationSize
 237   );
 238
 239 /**
 240   Allocates a buffer of type EfiReservedMemoryType.
 241
 242   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
 243   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 244   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 245
 246   @param  AllocationSize        The number of bytes to allocate.
 247
 248   @return A pointer to the allocated buffer or NULL if allocation fails.
 249
 250 **/
 251 VOID *
 252 EFIAPI
 253 AllocateReservedPool (
 254   IN UINTN  AllocationSize
 255   );
 256
 257 /**
 258   Allocates and zeros a buffer of type EfiBootServicesData.
 259
 260   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
 261   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 262   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 263   request, then NULL is returned.
 264
 265   @param  AllocationSize        The number of bytes to allocate and zero.
 266
 267   @return A pointer to the allocated buffer or NULL if allocation fails.
 268
 269 **/
 270 VOID *
 271 EFIAPI
 272 AllocateZeroPool (
 273   IN UINTN  AllocationSize
 274   );
 275
 276 /**
 277   Allocates and zeros a buffer of type EfiRuntimeServicesData.
 278
 279   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
 280   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 281   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 282   request, then NULL is returned.
 283
 284   @param  AllocationSize        The number of bytes to allocate and zero.
 285
 286   @return A pointer to the allocated buffer or NULL if allocation fails.
 287
 288 **/
 289 VOID *
 290 EFIAPI
 291 AllocateRuntimeZeroPool (
 292   IN UINTN  AllocationSize
 293   );
 294
 295 /**
 296   Allocates and zeros a buffer of type EfiReservedMemoryType.
 297
 298   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
 299   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 300   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 301   request, then NULL is returned.
 302
 303   @param  AllocationSize        The number of bytes to allocate and zero.
 304
 305   @return A pointer to the allocated buffer or NULL if allocation fails.
 306
 307 **/
 308 VOID *
 309 EFIAPI
 310 AllocateReservedZeroPool (
 311   IN UINTN  AllocationSize
 312   );
 313
 314 /**
 315   Copies a buffer to an allocated buffer of type EfiBootServicesData.
 316
 317   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
 318   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 319   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 320   is not enough memory remaining to satisfy the request, then NULL is returned.
 321
 322   If Buffer is NULL, then ASSERT().
 323   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 324
 325   @param  AllocationSize        The number of bytes to allocate and zero.
 326   @param  Buffer                The buffer to copy to the allocated buffer.
 327
 328   @return A pointer to the allocated buffer or NULL if allocation fails.
 329
 330 **/
 331 VOID *
 332 EFIAPI
 333 AllocateCopyPool (
 334   IN UINTN       AllocationSize,
 335   IN CONST VOID  *Buffer
 336   );
 337
 338 /**
 339   Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
 340
 341   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
 342   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 343   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 344   is not enough memory remaining to satisfy the request, then NULL is returned.
 345
 346   If Buffer is NULL, then ASSERT().
 347   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 348
 349   @param  AllocationSize        The number of bytes to allocate and zero.
 350   @param  Buffer                The buffer to copy to the allocated buffer.
 351
 352   @return A pointer to the allocated buffer or NULL if allocation fails.
 353
 354 **/
 355 VOID *
 356 EFIAPI
 357 AllocateRuntimeCopyPool (
 358   IN UINTN       AllocationSize,
 359   IN CONST VOID  *Buffer
 360   );
 361
 362 /**
 363   Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
 364
 365   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
 366   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 367   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 368   is not enough memory remaining to satisfy the request, then NULL is returned.
 369
 370   If Buffer is NULL, then ASSERT().
 371   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 372
 373   @param  AllocationSize        The number of bytes to allocate and zero.
 374   @param  Buffer                The buffer to copy to the allocated buffer.
 375
 376   @return A pointer to the allocated buffer or NULL if allocation fails.
 377
 378 **/
 379 VOID *
 380 EFIAPI
 381 AllocateReservedCopyPool (
 382   IN UINTN       AllocationSize,
 383   IN CONST VOID  *Buffer
 384   );
 385
 386 /**
 387   Reallocates a buffer of type EfiBootServicesData.
 388
 389   Allocates and zeros the number bytes specified by NewSize from memory of type
 390   EfiBootServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 391   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 392   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 393   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 394   enough memory remaining to satisfy the request, then NULL is returned.
 395
 396   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 397   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 398
 399   @param  OldSize        The size, in bytes, of OldBuffer.
 400   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 401   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 402                          parameter that may be NULL.
 403
 404   @return A pointer to the allocated buffer or NULL if allocation fails.
 405
 406 **/
 407 VOID *
 408 EFIAPI
 409 ReallocatePool (
 410   IN UINTN  OldSize,
 411   IN UINTN  NewSize,
 412   IN VOID   *OldBuffer  OPTIONAL
 413   );
 414
 415 /**
 416   Reallocates a buffer of type EfiRuntimeServicesData.
 417
 418   Allocates and zeros the number bytes specified by NewSize from memory of type
 419   EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 420   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 421   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 422   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 423   enough memory remaining to satisfy the request, then NULL is returned.
 424
 425   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 426   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 427
 428   @param  OldSize        The size, in bytes, of OldBuffer.
 429   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 430   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 431                          parameter that may be NULL.
 432
 433   @return A pointer to the allocated buffer or NULL if allocation fails.
 434
 435 **/
 436 VOID *
 437 EFIAPI
 438 ReallocateRuntimePool (
 439   IN UINTN  OldSize,
 440   IN UINTN  NewSize,
 441   IN VOID   *OldBuffer  OPTIONAL
 442   );
 443
 444 /**
 445   Reallocates a buffer of type EfiReservedMemoryType.
 446
 447   Allocates and zeros the number bytes specified by NewSize from memory of type
 448   EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and
 449   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 450   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 451   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 452   enough memory remaining to satisfy the request, then NULL is returned.
 453
 454   If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
 455   is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
 456
 457   @param  OldSize        The size, in bytes, of OldBuffer.
 458   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 459   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 460                          parameter that may be NULL.
 461
 462   @return A pointer to the allocated buffer or NULL if allocation fails.
 463
 464 **/
 465 VOID *
 466 EFIAPI
 467 ReallocateReservedPool (
 468   IN UINTN  OldSize,
 469   IN UINTN  NewSize,
 470   IN VOID   *OldBuffer  OPTIONAL
 471   );
 472
 473 /**
 474   Frees a buffer that was previously allocated with one of the pool allocation functions in the
 475   Memory Allocation Library.
 476
 477   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
 478   pool allocation services of the Memory Allocation Library.  If it is not possible to free pool
 479   resources, then this function will perform no actions.
 480
 481   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
 482   then ASSERT().
 483
 484   @param  Buffer                Pointer to the buffer to free.
 485
 486 **/
 487 VOID
 488 EFIAPI
 489 FreePool (
 490   IN VOID   *Buffer
 491   );
 492
 493 #endif