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 NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 392   If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 393
 394   @param  OldSize        The size, in bytes, of OldBuffer.
 395   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 396   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 397                          parameter that may be NULL.
 398
 399   @return A pointer to the allocated buffer or NULL if allocation fails.
 400
 401 **/
 402 VOID *
 403 EFIAPI
 404 ReallocatePool (
 405   IN UINTN  OldSize,
 406   IN UINTN  NewSize,
 407   IN VOID   *OldBuffer  OPTIONAL
 408   );
 409
 410 /**
 411   Reallocates a buffer of type EfiRuntimeServicesData.
 412
 413   Allocates and zeros the number bytes specified by NewSize from memory of type
 414   EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
 415   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 416   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 417   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 418   enough memory remaining to satisfy the request, then NULL is returned.
 419
 420   If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 421   If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 422
 423   @param  OldSize        The size, in bytes, of OldBuffer.
 424   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 425   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 426                          parameter that may be NULL.
 427
 428   @return A pointer to the allocated buffer or NULL if allocation fails.
 429
 430 **/
 431 VOID *
 432 EFIAPI
 433 ReallocateRuntimePool (
 434   IN UINTN  OldSize,
 435   IN UINTN  NewSize,
 436   IN VOID   *OldBuffer  OPTIONAL
 437   );
 438
 439 /**
 440   Reallocates a buffer of type EfiReservedMemoryType.
 441
 442   Allocates and zeros the number bytes specified by NewSize from memory of type
 443   EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and
 444   NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
 445   OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
 446   If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
 447   enough memory remaining to satisfy the request, then NULL is returned.
 448
 449   If NewSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 450   If OldSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
 451
 452   @param  OldSize        The size, in bytes, of OldBuffer.
 453   @param  NewSize        The size, in bytes, of the buffer to reallocate.
 454   @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
 455                          parameter that may be NULL.
 456
 457   @return A pointer to the allocated buffer or NULL if allocation fails.
 458
 459 **/
 460 VOID *
 461 EFIAPI
 462 ReallocateReservedPool (
 463   IN UINTN  OldSize,
 464   IN UINTN  NewSize,
 465   IN VOID   *OldBuffer  OPTIONAL
 466   );
 467
 468 /**
 469   Frees a buffer that was previously allocated with one of the pool allocation functions in the
 470   Memory Allocation Library.
 471
 472   Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
 473   pool allocation services of the Memory Allocation Library.
 474
 475   If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
 476   then ASSERT().
 477
 478   @param  Buffer                Pointer to the buffer to free.
 479
 480 **/
 481 VOID
 482 EFIAPI
 483 FreePool (
 484   IN VOID   *Buffer
 485   );
 486
 487 #endif