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