Import Library Class from original MDE package. Also I added the EFI_PEI_CORE_ENTRY_P...
[mirror_edk2.git] / 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 one or more 4KB pages of type EfiBootServicesData.
22
23 Allocates the number of 4KB pages of type EfiBootServicesData and returns a pointer to the
24 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
25 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
26 returned.
27
28 @param Pages The number of 4 KB pages to allocate.
29
30 @return A pointer to the allocated buffer or NULL if allocation fails.
31
32 **/
33 VOID *
34 EFIAPI
35 AllocatePages (
36 IN UINTN Pages
37 );
38
39 /**
40 Allocates one or more 4KB pages of type EfiRuntimeServicesData.
41
42 Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
43 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
44 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
45 returned.
46
47 @param Pages The number of 4 KB pages to allocate.
48
49 @return A pointer to the allocated buffer or NULL if allocation fails.
50
51 **/
52 VOID *
53 EFIAPI
54 AllocateRuntimePages (
55 IN UINTN Pages
56 );
57
58 /**
59 Allocates one or more 4KB pages of type EfiReservedMemoryType.
60
61 Allocates the number of 4KB pages of type EfiReservedMemoryType and returns a pointer to the
62 allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
63 is returned. If there is not enough memory remaining to satisfy the request, then NULL is
64 returned.
65
66 @param Pages The number of 4 KB pages to allocate.
67
68 @return A pointer to the allocated buffer or NULL if allocation fails.
69
70 **/
71 VOID *
72 EFIAPI
73 AllocateReservedPages (
74 IN UINTN Pages
75 );
76
77 /**
78 Frees one or more 4KB pages that were previously allocated with one of the page allocation
79 functions in the Memory Allocation Library.
80
81 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
82 must have been allocated on a previous call to the page allocation services of the Memory
83 Allocation Library.
84 If Buffer was not allocated with a page allocation function in the Memory Allocation Library,
85 then ASSERT().
86 If Pages is zero, then ASSERT().
87
88 @param Buffer Pointer to the buffer of pages to free.
89 @param Pages The number of 4 KB pages to free.
90
91 **/
92 VOID
93 EFIAPI
94 FreePages (
95 IN VOID *Buffer,
96 IN UINTN Pages
97 );
98
99 /**
100 Allocates one or more 4KB pages of type EfiBootServicesData at a specified alignment.
101
102 Allocates the number of 4KB pages specified by Pages of type EfiBootServicesData with an
103 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
104 returned. If there is not enough memory at the specified alignment remaining to satisfy the
105 request, then NULL is returned.
106 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
107
108 @param Pages The number of 4 KB pages to allocate.
109 @param Alignment The requested alignment of the allocation. Must be a power of two.
110 If Alignment is zero, then byte alignment is used.
111
112 @return A pointer to the allocated buffer or NULL if allocation fails.
113
114 **/
115 VOID *
116 EFIAPI
117 AllocateAlignedPages (
118 IN UINTN Pages,
119 IN UINTN Alignment
120 );
121
122 /**
123 Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
124
125 Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
126 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
127 returned. If there is not enough memory at the specified alignment remaining to satisfy the
128 request, then NULL is returned.
129 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
130
131 @param Pages The number of 4 KB pages to allocate.
132 @param Alignment The requested alignment of the allocation. Must be a power of two.
133 If Alignment is zero, then byte alignment is used.
134
135 @return A pointer to the allocated buffer or NULL if allocation fails.
136
137 **/
138 VOID *
139 EFIAPI
140 AllocateAlignedRuntimePages (
141 IN UINTN Pages,
142 IN UINTN Alignment
143 );
144
145 /**
146 Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
147
148 Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
149 alignment specified by Alignment. The allocated buffer is returned. If Pages is 0, then NULL is
150 returned. If there is not enough memory at the specified alignment remaining to satisfy the
151 request, then NULL is returned.
152 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
153
154 @param Pages The number of 4 KB pages to allocate.
155 @param Alignment The requested alignment of the allocation. Must be a power of two.
156 If Alignment is zero, then byte alignment is used.
157
158 @return A pointer to the allocated buffer or NULL if allocation fails.
159
160 **/
161 VOID *
162 EFIAPI
163 AllocateAlignedReservedPages (
164 IN UINTN Pages,
165 IN UINTN Alignment
166 );
167
168 /**
169 Frees one or more 4KB pages that were previously allocated with one of the aligned page
170 allocation functions in the Memory Allocation Library.
171
172 Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer. Buffer
173 must have been allocated on a previous call to the aligned page allocation services of the Memory
174 Allocation Library.
175 If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
176 Library, then ASSERT().
177 If Pages is zero, then ASSERT().
178
179 @param Buffer Pointer to the buffer of pages to free.
180 @param Pages The number of 4 KB pages to free.
181
182 **/
183 VOID
184 EFIAPI
185 FreeAlignedPages (
186 IN VOID *Buffer,
187 IN UINTN Pages
188 );
189
190 /**
191 Allocates a buffer of type EfiBootServicesData.
192
193 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
194 pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
195 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
196
197 @param AllocationSize The number of bytes to allocate.
198
199 @return A pointer to the allocated buffer or NULL if allocation fails.
200
201 **/
202 VOID *
203 EFIAPI
204 AllocatePool (
205 IN UINTN AllocationSize
206 );
207
208 /**
209 Allocates a buffer of type EfiRuntimeServicesData.
210
211 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
212 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
213 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
214
215 @param AllocationSize The number of bytes to allocate.
216
217 @return A pointer to the allocated buffer or NULL if allocation fails.
218
219 **/
220 VOID *
221 EFIAPI
222 AllocateRuntimePool (
223 IN UINTN AllocationSize
224 );
225
226 /**
227 Allocates a buffer of type EfieservedMemoryType.
228
229 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType and returns
230 a pointer to the allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is
231 returned. If there is not enough memory remaining to satisfy the request, then NULL is returned.
232
233 @param AllocationSize The number of bytes to allocate.
234
235 @return A pointer to the allocated buffer or NULL if allocation fails.
236
237 **/
238 VOID *
239 EFIAPI
240 AllocateReservedPool (
241 IN UINTN AllocationSize
242 );
243
244 /**
245 Allocates and zeros a buffer of type EfiBootServicesData.
246
247 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
248 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
249 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
250 request, then NULL is returned.
251
252 @param AllocationSize The number of bytes to allocate and zero.
253
254 @return A pointer to the allocated buffer or NULL if allocation fails.
255
256 **/
257 VOID *
258 EFIAPI
259 AllocateZeroPool (
260 IN UINTN AllocationSize
261 );
262
263 /**
264 Allocates and zeros a buffer of type EfiRuntimeServicesData.
265
266 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
267 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
268 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
269 request, then NULL is returned.
270
271 @param AllocationSize The number of bytes to allocate and zero.
272
273 @return A pointer to the allocated buffer or NULL if allocation fails.
274
275 **/
276 VOID *
277 EFIAPI
278 AllocateRuntimeZeroPool (
279 IN UINTN AllocationSize
280 );
281
282 /**
283 Allocates and zeros a buffer of type EfiReservedMemoryType.
284
285 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
286 buffer with zeros, and returns a pointer to the allocated buffer. If AllocationSize is 0, then a
287 valid buffer of 0 size is returned. If there is not enough memory remaining to satisfy the
288 request, then NULL is returned.
289
290 @param AllocationSize The number of bytes to allocate and zero.
291
292 @return A pointer to the allocated buffer or NULL if allocation fails.
293
294 **/
295 VOID *
296 EFIAPI
297 AllocateReservedZeroPool (
298 IN UINTN AllocationSize
299 );
300
301 /**
302 Copies a buffer to an allocated buffer of type EfiBootServicesData.
303
304 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
305 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
306 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
307 is not enough memory remaining to satisfy the request, then NULL is returned.
308 If Buffer is NULL, then ASSERT().
309 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
310
311 @param AllocationSize The number of bytes to allocate and zero.
312 @param Buffer The buffer to copy to the allocated buffer.
313
314 @return A pointer to the allocated buffer or NULL if allocation fails.
315
316 **/
317 VOID *
318 EFIAPI
319 AllocateCopyPool (
320 IN UINTN AllocationSize,
321 IN CONST VOID *Buffer
322 );
323
324 /**
325 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
326
327 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
328 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
329 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
330 is not enough memory remaining to satisfy the request, then NULL is returned.
331 If Buffer is NULL, then ASSERT().
332 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
333
334 @param AllocationSize The number of bytes to allocate and zero.
335 @param Buffer The buffer to copy to the allocated buffer.
336
337 @return A pointer to the allocated buffer or NULL if allocation fails.
338
339 **/
340 VOID *
341 EFIAPI
342 AllocateRuntimeCopyPool (
343 IN UINTN AllocationSize,
344 IN CONST VOID *Buffer
345 );
346
347 /**
348 Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
349
350 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
351 AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
352 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
353 is not enough memory remaining to satisfy the request, then NULL is returned.
354 If Buffer is NULL, then ASSERT().
355 If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
356
357 @param AllocationSize The number of bytes to allocate and zero.
358 @param Buffer The buffer to copy to the allocated buffer.
359
360 @return A pointer to the allocated buffer or NULL if allocation fails.
361
362 **/
363 VOID *
364 EFIAPI
365 AllocateReservedCopyPool (
366 IN UINTN AllocationSize,
367 IN CONST VOID *Buffer
368 );
369
370 /**
371 Frees a buffer that was previously allocated with one of the pool allocation functions in the
372 Memory Allocation Library.
373
374 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
375 pool allocation services of the Memory Allocation Library.
376 If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
377 then ASSERT().
378
379 @param Buffer Pointer to the buffer to free.
380
381 **/
382 VOID
383 EFIAPI
384 FreePool (
385 IN VOID *Buffer
386 );
387
388 /**
389 Allocates a buffer of type EfiBootServicesData at a specified alignment.
390
391 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData with an
392 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
393 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
394 alignment remaining to satisfy the request, then NULL is returned.
395 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
396
397 @param AllocationSize The number of bytes to allocate.
398 @param Alignment The requested alignment of the allocation. Must be a power of two.
399 If Alignment is zero, then byte alignment is used.
400
401 @return A pointer to the allocated buffer or NULL if allocation fails.
402
403 **/
404 VOID *
405 EFIAPI
406 AllocateAlignedPool (
407 IN UINTN AllocationSize,
408 IN UINTN Alignment
409 );
410
411 /**
412 Allocates a buffer of type EfiRuntimeServicesData at a specified alignment.
413
414 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData with an
415 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
416 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
417 alignment remaining to satisfy the request, then NULL is returned.
418 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
419
420 @param AllocationSize The number of bytes to allocate.
421 @param Alignment The requested alignment of the allocation. Must be a power of two.
422 If Alignment is zero, then byte alignment is used.
423
424 @return A pointer to the allocated buffer or NULL if allocation fails.
425
426 **/
427 VOID *
428 EFIAPI
429 AllocateAlignedRuntimePool (
430 IN UINTN AllocationSize,
431 IN UINTN Alignment
432 );
433
434 /**
435 Allocates a buffer of type EfieservedMemoryType at a specified alignment.
436
437 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType with an
438 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
439 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
440 alignment remaining to satisfy the request, then NULL is returned.
441 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
442
443 @param AllocationSize The number of bytes to allocate.
444 @param Alignment The requested alignment of the allocation. Must be a power of two.
445 If Alignment is zero, then byte alignment is used.
446
447 @return A pointer to the allocated buffer or NULL if allocation fails.
448
449 **/
450 VOID *
451 EFIAPI
452 AllocateAlignedReservedPool (
453 IN UINTN AllocationSize,
454 IN UINTN Alignment
455 );
456
457 /**
458 Allocates and zeros a buffer of type EfiBootServicesData at a specified alignment.
459
460 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData with an
461 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the
462 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
463 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is
464 returned.
465 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
466
467 @param AllocationSize The number of bytes to allocate.
468 @param Alignment The requested alignment of the allocation. Must be a power of two.
469 If Alignment is zero, then byte alignment is used.
470
471 @return A pointer to the allocated buffer or NULL if allocation fails.
472
473 **/
474 VOID *
475 EFIAPI
476 AllocateAlignedZeroPool (
477 IN UINTN AllocationSize,
478 IN UINTN Alignment
479 );
480
481 /**
482 Allocates and zeros a buffer of type EfiRuntimeServicesData at a specified alignment.
483
484 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData with an
485 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the
486 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
487 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is
488 returned.
489 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
490
491 @param AllocationSize The number of bytes to allocate.
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 A pointer to the allocated buffer or NULL if allocation fails.
496
497 **/
498 VOID *
499 EFIAPI
500 AllocateAlignedRuntimeZeroPool (
501 IN UINTN AllocationSize,
502 IN UINTN Alignment
503 );
504
505 /**
506 Allocates and zeros a buffer of type EfieservedMemoryType at a specified alignment.
507
508 Allocates the number bytes specified by AllocationSize of type EfieservedMemoryType with an
509 alignment specified by Alignment, clears the buffer with zeros, and returns a pointer to the
510 allocated buffer. If AllocationSize is 0, then a valid buffer of 0 size is returned. If there
511 is not enough memory at the specified alignment remaining to satisfy the request, then NULL is
512 returned.
513 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
514
515 @param AllocationSize The number of bytes to allocate.
516 @param Alignment The requested alignment of the allocation. Must be a power of two.
517 If Alignment is zero, then byte alignment is used.
518
519 @return A pointer to the allocated buffer or NULL if allocation fails.
520
521 **/
522 VOID *
523 EFIAPI
524 AllocateAlignedReservedZeroPool (
525 IN UINTN AllocationSize,
526 IN UINTN Alignment
527 );
528
529 /**
530 Copies a buffer to an allocated buffer of type EfiBootServicesData at a specified alignment.
531
532 Allocates the number bytes specified by AllocationSize of type EfiBootServicesData type with an
533 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
534 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
535 alignment remaining to satisfy the request, then NULL is returned.
536 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
537
538 @param AllocationSize The number of bytes to allocate.
539 @param Buffer The buffer to copy to the allocated buffer.
540 @param Alignment The requested alignment of the allocation. Must be a power of two.
541 If Alignment is zero, then byte alignment is used.
542
543 @return A pointer to the allocated buffer or NULL if allocation fails.
544
545 **/
546 VOID *
547 EFIAPI
548 AllocateAlignedCopyPool (
549 IN UINTN AllocationSize,
550 IN CONST VOID *Buffer,
551 IN UINTN Alignment
552 );
553
554 /**
555 Copies a buffer to an allocated buffer of type EfiRuntimeServicesData at a specified alignment.
556
557 Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData type with an
558 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
559 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
560 alignment remaining to satisfy the request, then NULL is returned.
561 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
562
563 @param AllocationSize The number of bytes to allocate.
564 @param Buffer The buffer to copy to the allocated buffer.
565 @param Alignment The requested alignment of the allocation. Must be a power of two.
566 If Alignment is zero, then byte alignment is used.
567
568 @return A pointer to the allocated buffer or NULL if allocation fails.
569
570 **/
571 VOID *
572 EFIAPI
573 AllocateAlignedRuntimeCopyPool (
574 IN UINTN AllocationSize,
575 IN CONST VOID *Buffer,
576 IN UINTN Alignment
577 );
578
579 /**
580 Copies a buffer to an allocated buffer of type EfiReservedMemoryType at a specified alignment.
581
582 Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType type with an
583 alignment specified by Alignment. The allocated buffer is returned. If AllocationSize is 0,
584 then a valid buffer of 0 size is returned. If there is not enough memory at the specified
585 alignment remaining to satisfy the request, then NULL is returned.
586 If Alignment is not a power of two and Alignment is not zero, then ASSERT().
587
588 @param AllocationSize The number of bytes to allocate.
589 @param Buffer The buffer to copy to the allocated buffer.
590 @param Alignment The requested alignment of the allocation. Must be a power of two.
591 If Alignment is zero, then byte alignment is used.
592
593 @return A pointer to the allocated buffer or NULL if allocation fails.
594
595 **/
596 VOID *
597 EFIAPI
598 AllocateAlignedReservedCopyPool (
599 IN UINTN AllocationSize,
600 IN CONST VOID *Buffer,
601 IN UINTN Alignment
602 );
603
604 /**
605 Frees a buffer that was previously allocated with one of the aligned pool allocation functions
606 in the Memory Allocation Library.
607
608 Frees the buffer specified by Buffer. Buffer must have been allocated on a previous call to the
609 aligned pool allocation services of the Memory Allocation Library.
610 If Buffer was not allocated with an aligned pool allocation function in the Memory Allocation
611 Library, then ASSERT().
612
613 @param Buffer Pointer to the buffer to free.
614
615 **/
616 VOID
617 EFIAPI
618 FreeAlignedPool (
619 IN VOID *Buffer
620 );
621
622 #endif