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