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 488