MdePkg/Include/Library/MemoryAllocationLib.h

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