MdePkg/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 - 2008, Intel Corporation
  10 All rights reserved. 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.
  87
  88   If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
  89   then ASSERT().
  90   If Pages is zero, then ASSERT().
  91
  92   @param  Buffer                Pointer to the buffer of pages to free.
  93   @param  Pages                 The number of 4 KB pages to free.
  94
  95 **/
  96 VOID
  97 EFIAPI
  98 FreePages (
  99   IN VOID   *Buffer,
 100   IN UINTN  Pages
 101   );
 102
 103 /**
 104   Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
 105
 106   Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
 107   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 108   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 109   request, then NULL is returned.
 110
 111   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 112
 113   @param  Pages                 The number of 4 KB pages to allocate.
 114   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 115                                 If Alignment is zero, then byte alignment is used.
 116
 117   @return A pointer to the allocated buffer or NULL if allocation fails.
 118
 119 **/
 120 VOID *
 121 EFIAPI
 122 AllocateAlignedPages (
 123   IN UINTN  Pages,
 124   IN UINTN  Alignment
 125   );
 126
 127 /**
 128   Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
 129
 130   Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
 131   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 132   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 133   request, then NULL is returned.
 134
 135   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 136
 137   @param  Pages                 The number of 4 KB pages to allocate.
 138   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 139                                 If Alignment is zero, then byte alignment is used.
 140
 141   @return A pointer to the allocated buffer or NULL if allocation fails.
 142
 143 **/
 144 VOID *
 145 EFIAPI
 146 AllocateAlignedRuntimePages (
 147   IN UINTN  Pages,
 148   IN UINTN  Alignment
 149   );
 150
 151 /**
 152   Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
 153
 154   Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
 155   alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
 156   returned.  If there is not enough memory at the specified alignment remaining to satisfy the
 157   request, then NULL is returned.
 158
 159   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 160
 161   @param  Pages                 The number of 4 KB pages to allocate.
 162   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 163                                 If Alignment is zero, then byte alignment is used.
 164
 165   @return A pointer to the allocated buffer or NULL if allocation fails.
 166
 167 **/
 168 VOID *
 169 EFIAPI
 170 AllocateAlignedReservedPages (
 171   IN UINTN  Pages,
 172   IN UINTN  Alignment
 173   );
 174
 175 /**
 176   Frees one or more 4KB pages that were previously allocated with one of the aligned page
 177   allocation functions in the Memory Allocation Library.
 178
 179   Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
 180   must have been allocated on a previous call to the aligned page allocation services of the Memory
 181   Allocation Library.
 182
 183   If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
 184   Library, then ASSERT().
 185   If Pages is zero, then ASSERT().
 186
 187   @param  Buffer                Pointer to the buffer of pages to free.
 188   @param  Pages                 The number of 4 KB pages to free.
 189
 190 **/
 191 VOID
 192 EFIAPI
 193 FreeAlignedPages (
 194   IN VOID   *Buffer,
 195   IN UINTN  Pages
 196   );
 197
 198 /**
 199   Allocates a buffer of type EfiBootServicesData.
 200
 201   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
 202   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 203   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 204
 205   @param  AllocationSize        The number of bytes to allocate.
 206
 207   @return A pointer to the allocated buffer or NULL if allocation fails.
 208
 209 **/
 210 VOID *
 211 EFIAPI
 212 AllocatePool (
 213   IN UINTN  AllocationSize
 214   );
 215
 216 /**
 217   Allocates a buffer of type EfiRuntimeServicesData.
 218
 219   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
 220   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 221   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 222
 223   @param  AllocationSize        The number of bytes to allocate.
 224
 225   @return A pointer to the allocated buffer or NULL if allocation fails.
 226
 227 **/
 228 VOID *
 229 EFIAPI
 230 AllocateRuntimePool (
 231   IN UINTN  AllocationSize
 232   );
 233
 234 /**
 235   Allocates a buffer of type EfiReservedMemoryType.
 236
 237   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
 238   a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
 239   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
 240
 241   @param  AllocationSize        The number of bytes to allocate.
 242
 243   @return A pointer to the allocated buffer or NULL if allocation fails.
 244
 245 **/
 246 VOID *
 247 EFIAPI
 248 AllocateReservedPool (
 249   IN UINTN  AllocationSize
 250   );
 251
 252 /**
 253   Allocates and zeros a buffer of type EfiBootServicesData.
 254
 255   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
 256   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 257   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 258   request, then NULL is returned.
 259
 260   @param  AllocationSize        The number of bytes to allocate and zero.
 261
 262   @return A pointer to the allocated buffer or NULL if allocation fails.
 263
 264 **/
 265 VOID *
 266 EFIAPI
 267 AllocateZeroPool (
 268   IN UINTN  AllocationSize
 269   );
 270
 271 /**
 272   Allocates and zeros a buffer of type EfiRuntimeServicesData.
 273
 274   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
 275   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 276   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 277   request, then NULL is returned.
 278
 279   @param  AllocationSize        The number of bytes to allocate and zero.
 280
 281   @return A pointer to the allocated buffer or NULL if allocation fails.
 282
 283 **/
 284 VOID *
 285 EFIAPI
 286 AllocateRuntimeZeroPool (
 287   IN UINTN  AllocationSize
 288   );
 289
 290 /**
 291   Allocates and zeros a buffer of type EfiReservedMemoryType.
 292
 293   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
 294   buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
 295   valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
 296   request, then NULL is returned.
 297
 298   @param  AllocationSize        The number of bytes to allocate and zero.
 299
 300   @return A pointer to the allocated buffer or NULL if allocation fails.
 301
 302 **/
 303 VOID *
 304 EFIAPI
 305 AllocateReservedZeroPool (
 306   IN UINTN  AllocationSize
 307   );
 308
 309 /**
 310   Copies a buffer to an allocated buffer of type EfiBootServicesData.
 311
 312   Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
 313   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 314   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 315   is not enough memory remaining to satisfy the request, then NULL is returned.
 316
 317   If Buffer is NULL, then ASSERT().
 318   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 319
 320   @param  AllocationSize        The number of bytes to allocate and zero.
 321   @param  Buffer                The buffer to copy to the allocated buffer.
 322
 323   @return A pointer to the allocated buffer or NULL if allocation fails.
 324
 325 **/
 326 VOID *
 327 EFIAPI
 328 AllocateCopyPool (
 329   IN UINTN       AllocationSize,
 330   IN CONST VOID  *Buffer
 331   );
 332
 333 /**
 334   Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
 335
 336   Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
 337   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 338   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 339   is not enough memory remaining to satisfy the request, then NULL is returned.
 340
 341   If Buffer is NULL, then ASSERT().
 342   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 343
 344   @param  AllocationSize        The number of bytes to allocate and zero.
 345   @param  Buffer                The buffer to copy to the allocated buffer.
 346
 347   @return A pointer to the allocated buffer or NULL if allocation fails.
 348
 349 **/
 350 VOID *
 351 EFIAPI
 352 AllocateRuntimeCopyPool (
 353   IN UINTN       AllocationSize,
 354   IN CONST VOID  *Buffer
 355   );
 356
 357 /**
 358   Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
 359
 360   Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
 361   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 362   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 363   is not enough memory remaining to satisfy the request, then NULL is returned.
 364
 365   If Buffer is NULL, then ASSERT().
 366   If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 367
 368   @param  AllocationSize        The number of bytes to allocate and zero.
 369   @param  Buffer                The buffer to copy to the allocated buffer.
 370
 371   @return A pointer to the allocated buffer or NULL if allocation fails.
 372
 373 **/
 374 VOID *
 375 EFIAPI
 376 AllocateReservedCopyPool (
 377   IN UINTN       AllocationSize,
 378   IN CONST VOID  *Buffer
 379   );
 380
 381 /**
 382   Reallocates a buffer of type EfiBootServicesData.
 383
 384   Allocates and zeros the number bytes specified by NewSize from memory of type
 385   EfiBootServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 386   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 387   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 388   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 389   enough memory remaining to satisfy the request, then NULL is returned.
 390
 391   If OldBuffer is NULL, then ASSERT().
 392   If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 393   If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 394
 395   @param  OldSize        The size, in bytes, of OldBuffer.
 396   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 397   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 398                          parameter that may be NULL.
 399
 400   @return A pointer to the allocated buffer or NULL if allocation fails.
 401
 402 **/
 403 VOID *
 404 EFIAPI
 405 ReallocatePool (
 406   IN UINTN  OldSize,
 407   IN UINTN  NewSize,
 408   IN VOID   *OldBuffer  OPTIONAL
 409   );
 410
 411 /**
 412   Reallocates a buffer of type EfiRuntimeServicesData.
 413
 414   Allocates and zeros the number bytes specified by NewSize from memory of type
 415   EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 416   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 417   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 418   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 419   enough memory remaining to satisfy the request, then NULL is returned.
 420
 421   If OldBuffer is NULL, then ASSERT().
 422   If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 423   If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 424
 425   @param  OldSize        The size, in bytes, of OldBuffer.
 426   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 427   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 428                          parameter that may be NULL.
 429
 430   @return A pointer to the allocated buffer or NULL if allocation fails.
 431
 432 **/
 433 VOID *
 434 EFIAPI
 435 ReallocateRuntimePool (
 436   IN UINTN  OldSize,
 437   IN UINTN  NewSize,
 438   IN VOID   *OldBuffer  OPTIONAL
 439   );
 440
 441 /**
 442   Reallocates a buffer of type EfiReservedMemoryType.
 443
 444   Allocates and zeros the number bytes specified by NewSize from memory of type
 445   EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and
 446   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 447   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 448   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 449   enough memory remaining to satisfy the request, then NULL is returned.
 450
 451   If OldBuffer is NULL, then ASSERT().
 452   If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 453   If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 454
 455   @param  OldSize        The size, in bytes, of OldBuffer.
 456   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 457   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 458                          parameter that may be NULL.
 459
 460   @return A pointer to the allocated buffer or NULL if allocation fails.
 461
 462 **/
 463 VOID *
 464 EFIAPI
 465 ReallocateReservedPool (
 466   IN UINTN  OldSize,
 467   IN UINTN  NewSize,
 468   IN VOID   *OldBuffer  OPTIONAL
 469   );
 470
 471 /**
 472   Frees a buffer that was previously allocated with one of the pool allocation functions in the
 473   Memory Allocation Library.
 474
 475   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
 476   pool allocation services of the Memory Allocation Library.
 477
 478   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
 479   then ASSERT().
 480
 481   @param  Buffer                Pointer to the buffer to free.
 482
 483 **/
 484 VOID
 485 EFIAPI
 486 FreePool (
 487   IN VOID   *Buffer
 488   );
 489
 490 #endif