MemoryAllocationLib.h revision 314880 
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
9Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR>
10This program and the accompanying materials
11are licensed and made available under the terms and conditions of the BSD License
12which accompanies this distribution.  The full text of the license may be found at
13http://opensource.org/licenses/bsd-license.php
14
15THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
16WITHOUT 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**/
36VOID *
37EFIAPI
38AllocatePages (
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**/
55VOID *
56EFIAPI
57AllocateRuntimePages (
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**/
74VOID *
75EFIAPI
76AllocateReservedPages (
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**/
97VOID
98EFIAPI
99FreePages (
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  If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
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 A pointer to the allocated buffer or NULL if allocation fails.
120
121**/
122VOID *
123EFIAPI
124AllocateAlignedPages (
125  IN UINTN  Pages,
126  IN UINTN  Alignment
127  );
128
129/**
130  Allocates one or more 4KB pages of type EfiRuntimeServicesData at a specified alignment.
131
132  Allocates the number of 4KB pages specified by Pages of type EfiRuntimeServicesData with an
133  alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
134  returned.  If there is not enough memory at the specified alignment remaining to satisfy the
135  request, then NULL is returned.
136
137  If Alignment is not a power of two and Alignment is not zero, then ASSERT().
138  If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
139
140  @param  Pages                 The number of 4 KB pages to allocate.
141  @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
142                                If Alignment is zero, then byte alignment is used.
143
144  @return A pointer to the allocated buffer or NULL if allocation fails.
145
146**/
147VOID *
148EFIAPI
149AllocateAlignedRuntimePages (
150  IN UINTN  Pages,
151  IN UINTN  Alignment
152  );
153
154/**
155  Allocates one or more 4KB pages of type EfiReservedMemoryType at a specified alignment.
156
157  Allocates the number of 4KB pages specified by Pages of type EfiReservedMemoryType with an
158  alignment specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is
159  returned.  If there is not enough memory at the specified alignment remaining to satisfy the
160  request, then NULL is returned.
161
162  If Alignment is not a power of two and Alignment is not zero, then ASSERT().
163  If Pages plus EFI_SIZE_TO_PAGES (Alignment) overflows, then ASSERT().
164
165  @param  Pages                 The number of 4 KB pages to allocate.
166  @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
167                                If Alignment is zero, then byte alignment is used.
168
169  @return A pointer to the allocated buffer or NULL if allocation fails.
170
171**/
172VOID *
173EFIAPI
174AllocateAlignedReservedPages (
175  IN UINTN  Pages,
176  IN UINTN  Alignment
177  );
178
179/**
180  Frees one or more 4KB pages that were previously allocated with one of the aligned page
181  allocation functions in the Memory Allocation Library.
182
183  Frees the number of 4KB pages specified by Pages from the buffer specified by Buffer.  Buffer
184  must have been allocated on a previous call to the aligned page allocation services of the Memory
185  Allocation Library.  If it is not possible to free allocated pages, then this function will
186  perform no actions.
187
188  If Buffer was not allocated with an aligned page allocation function in the Memory Allocation
189  Library, then ASSERT().
190  If Pages is zero, then ASSERT().
191
192  @param  Buffer                Pointer to the buffer of pages to free.
193  @param  Pages                 The number of 4 KB pages to free.
194
195**/
196VOID
197EFIAPI
198FreeAlignedPages (
199  IN VOID   *Buffer,
200  IN UINTN  Pages
201  );
202
203/**
204  Allocates a buffer of type EfiBootServicesData.
205
206  Allocates the number bytes specified by AllocationSize of type EfiBootServicesData and returns a
207  pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
208  returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
209
210  @param  AllocationSize        The number of bytes to allocate.
211
212  @return A pointer to the allocated buffer or NULL if allocation fails.
213
214**/
215VOID *
216EFIAPI
217AllocatePool (
218  IN UINTN  AllocationSize
219  );
220
221/**
222  Allocates a buffer of type EfiRuntimeServicesData.
223
224  Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData and returns
225  a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
226  returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
227
228  @param  AllocationSize        The number of bytes to allocate.
229
230  @return A pointer to the allocated buffer or NULL if allocation fails.
231
232**/
233VOID *
234EFIAPI
235AllocateRuntimePool (
236  IN UINTN  AllocationSize
237  );
238
239/**
240  Allocates a buffer of type EfiReservedMemoryType.
241
242  Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType and returns
243  a pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
244  returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
245
246  @param  AllocationSize        The number of bytes to allocate.
247
248  @return A pointer to the allocated buffer or NULL if allocation fails.
249
250**/
251VOID *
252EFIAPI
253AllocateReservedPool (
254  IN UINTN  AllocationSize
255  );
256
257/**
258  Allocates and zeros a buffer of type EfiBootServicesData.
259
260  Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, clears the
261  buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
262  valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
263  request, then NULL is returned.
264
265  @param  AllocationSize        The number of bytes to allocate and zero.
266
267  @return A pointer to the allocated buffer or NULL if allocation fails.
268
269**/
270VOID *
271EFIAPI
272AllocateZeroPool (
273  IN UINTN  AllocationSize
274  );
275
276/**
277  Allocates and zeros a buffer of type EfiRuntimeServicesData.
278
279  Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, clears the
280  buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
281  valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
282  request, then NULL is returned.
283
284  @param  AllocationSize        The number of bytes to allocate and zero.
285
286  @return A pointer to the allocated buffer or NULL if allocation fails.
287
288**/
289VOID *
290EFIAPI
291AllocateRuntimeZeroPool (
292  IN UINTN  AllocationSize
293  );
294
295/**
296  Allocates and zeros a buffer of type EfiReservedMemoryType.
297
298  Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, clears the
299  buffer with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a
300  valid buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the
301  request, then NULL is returned.
302
303  @param  AllocationSize        The number of bytes to allocate and zero.
304
305  @return A pointer to the allocated buffer or NULL if allocation fails.
306
307**/
308VOID *
309EFIAPI
310AllocateReservedZeroPool (
311  IN UINTN  AllocationSize
312  );
313
314/**
315  Copies a buffer to an allocated buffer of type EfiBootServicesData.
316
317  Allocates the number bytes specified by AllocationSize of type EfiBootServicesData, copies
318  AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
319  allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
320  is not enough memory remaining to satisfy the request, then NULL is returned.
321
322  If Buffer is NULL, then ASSERT().
323  If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
324
325  @param  AllocationSize        The number of bytes to allocate and zero.
326  @param  Buffer                The buffer to copy to the allocated buffer.
327
328  @return A pointer to the allocated buffer or NULL if allocation fails.
329
330**/
331VOID *
332EFIAPI
333AllocateCopyPool (
334  IN UINTN       AllocationSize,
335  IN CONST VOID  *Buffer
336  );
337
338/**
339  Copies a buffer to an allocated buffer of type EfiRuntimeServicesData.
340
341  Allocates the number bytes specified by AllocationSize of type EfiRuntimeServicesData, copies
342  AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
343  allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
344  is not enough memory remaining to satisfy the request, then NULL is returned.
345
346  If Buffer is NULL, then ASSERT().
347  If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
348
349  @param  AllocationSize        The number of bytes to allocate and zero.
350  @param  Buffer                The buffer to copy to the allocated buffer.
351
352  @return A pointer to the allocated buffer or NULL if allocation fails.
353
354**/
355VOID *
356EFIAPI
357AllocateRuntimeCopyPool (
358  IN UINTN       AllocationSize,
359  IN CONST VOID  *Buffer
360  );
361
362/**
363  Copies a buffer to an allocated buffer of type EfiReservedMemoryType.
364
365  Allocates the number bytes specified by AllocationSize of type EfiReservedMemoryType, copies
366  AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
367  allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
368  is not enough memory remaining to satisfy the request, then NULL is returned.
369
370  If Buffer is NULL, then ASSERT().
371  If AllocationSize is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
372
373  @param  AllocationSize        The number of bytes to allocate and zero.
374  @param  Buffer                The buffer to copy to the allocated buffer.
375
376  @return A pointer to the allocated buffer or NULL if allocation fails.
377
378**/
379VOID *
380EFIAPI
381AllocateReservedCopyPool (
382  IN UINTN       AllocationSize,
383  IN CONST VOID  *Buffer
384  );
385
386/**
387  Reallocates a buffer of type EfiBootServicesData.
388
389  Allocates and zeros the number bytes specified by NewSize from memory of type
390  EfiBootServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
391  NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
392  OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
393  If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
394  enough memory remaining to satisfy the request, then NULL is returned.
395
396  If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
397  is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
398
399  @param  OldSize        The size, in bytes, of OldBuffer.
400  @param  NewSize        The size, in bytes, of the buffer to reallocate.
401  @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
402                         parameter that may be NULL.
403
404  @return A pointer to the allocated buffer or NULL if allocation fails.
405
406**/
407VOID *
408EFIAPI
409ReallocatePool (
410  IN UINTN  OldSize,
411  IN UINTN  NewSize,
412  IN VOID   *OldBuffer  OPTIONAL
413  );
414
415/**
416  Reallocates a buffer of type EfiRuntimeServicesData.
417
418  Allocates and zeros the number bytes specified by NewSize from memory of type
419  EfiRuntimeServicesData.  If OldBuffer is not NULL, then the smaller of OldSize and
420  NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
421  OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
422  If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
423  enough memory remaining to satisfy the request, then NULL is returned.
424
425  If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
426  is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
427
428  @param  OldSize        The size, in bytes, of OldBuffer.
429  @param  NewSize        The size, in bytes, of the buffer to reallocate.
430  @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
431                         parameter that may be NULL.
432
433  @return A pointer to the allocated buffer or NULL if allocation fails.
434
435**/
436VOID *
437EFIAPI
438ReallocateRuntimePool (
439  IN UINTN  OldSize,
440  IN UINTN  NewSize,
441  IN VOID   *OldBuffer  OPTIONAL
442  );
443
444/**
445  Reallocates a buffer of type EfiReservedMemoryType.
446
447  Allocates and zeros the number bytes specified by NewSize from memory of type
448  EfiReservedMemoryType.  If OldBuffer is not NULL, then the smaller of OldSize and
449  NewSize bytes are copied from OldBuffer to the newly allocated buffer, and
450  OldBuffer is freed.  A pointer to the newly allocated buffer is returned.
451  If NewSize is 0, then a valid buffer of 0 size is  returned.  If there is not
452  enough memory remaining to satisfy the request, then NULL is returned.
453
454  If the allocation of the new buffer is successful and the smaller of NewSize and OldSize
455  is greater than (MAX_ADDRESS - OldBuffer + 1), then ASSERT().
456
457  @param  OldSize        The size, in bytes, of OldBuffer.
458  @param  NewSize        The size, in bytes, of the buffer to reallocate.
459  @param  OldBuffer      The buffer to copy to the allocated buffer.  This is an optional
460                         parameter that may be NULL.
461
462  @return A pointer to the allocated buffer or NULL if allocation fails.
463
464**/
465VOID *
466EFIAPI
467ReallocateReservedPool (
468  IN UINTN  OldSize,
469  IN UINTN  NewSize,
470  IN VOID   *OldBuffer  OPTIONAL
471  );
472
473/**
474  Frees a buffer that was previously allocated with one of the pool allocation functions in the
475  Memory Allocation Library.
476
477  Frees the buffer specified by Buffer.  Buffer must have been allocated on a previous call to the
478  pool allocation services of the Memory Allocation Library.  If it is not possible to free pool
479  resources, then this function will perform no actions.
480
481  If Buffer was not allocated with a pool allocation function in the Memory Allocation Library,
482  then ASSERT().
483
484  @param  Buffer                Pointer to the buffer to free.
485
486**/
487VOID
488EFIAPI
489FreePool (
490  IN VOID   *Buffer
491  );
492
493#endif
494