MdePkg/Library/DxeMemoryAllocationLib/MemoryAllocationLibInternals.h

   1 /** @file
   2   Internal include file of DXE Memory Allocation Library.
   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:  MemoryAllocationLibInternals.h
  14
  15 **/
  16
  17 #ifndef __DXE_MEMORY_ALLOCATION_LIB_INTERNALS_H__
  18 #define __DXE_MEMORY_ALLOCATION_LIB_INTERNALS_H__
  19
  20 //
  21 // Include common header file for this module.
  22 //
  23 #include "CommonHeader.h"
  24
  25 /**
  26   Allocates one or more 4KB pages of a certain memory type.
  27
  28   Allocates the number of 4KB pages of a certain memory type and returns a pointer to the allocated
  29   buffer.  The buffer returned is aligned on a 4KB boundary.  If Pages is 0, then NULL is returned.
  30   If there is not enough memory remaining to satisfy the request, then NULL is returned.
  31
  32   @param  MemoryType            The type of memory to allocate.
  33   @param  Pages                 The number of 4 KB pages to allocate.
  34
  35   @return A pointer to the allocated buffer or NULL if allocation fails.
  36
  37 **/
  38 VOID *
  39 InternalAllocatePages (
  40   IN EFI_MEMORY_TYPE  MemoryType,
  41   IN UINTN            Pages
  42   );
  43
  44 /**
  45   Allocates one or more 4KB pages of a certain memory type at a specified alignment.
  46
  47   Allocates the number of 4KB pages specified by Pages of a certain memory type with an alignment
  48   specified by Alignment.  The allocated buffer is returned.  If Pages is 0, then NULL is returned.
  49   If there is not enough memory at the specified alignment remaining to satisfy the request, then
  50   NULL is returned.
  51   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
  52
  53   @param  MemoryType            The type of memory to allocate.
  54   @param  Pages                 The number of 4 KB pages to allocate.
  55   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
  56                                 If Alignment is zero, then byte alignment is used.
  57
  58   @return A pointer to the allocated buffer or NULL if allocation fails.
  59
  60 **/
  61 VOID *
  62 InternalAllocateAlignedPages (
  63   IN EFI_MEMORY_TYPE  MemoryType,
  64   IN UINTN            Pages,
  65   IN UINTN            Alignment
  66   );
  67
  68 /**
  69   Allocates a buffer of a certain pool type.
  70
  71   Allocates the number bytes specified by AllocationSize of a certain pool type and returns a
  72   pointer to the allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is
  73   returned.  If there is not enough memory remaining to satisfy the request, then NULL is returned.
  74
  75   @param  MemoryType            The type of memory to allocate.
  76   @param  AllocationSize        The number of bytes to allocate.
  77
  78   @return A pointer to the allocated buffer or NULL if allocation fails.
  79
  80 **/
  81 VOID *
  82 InternalAllocatePool (
  83   IN EFI_MEMORY_TYPE  MemoryType,
  84   IN UINTN            AllocationSize
  85   );
  86
  87 /**
  88   Allocates and zeros a buffer of a certian pool type.
  89
  90   Allocates the number bytes specified by AllocationSize of a certian pool type, clears the buffer
  91   with zeros, and returns a pointer to the allocated buffer.  If AllocationSize is 0, then a valid
  92   buffer of 0 size is returned.  If there is not enough memory remaining to satisfy the request,
  93   then NULL is returned.
  94
  95   @param  PoolType              The type of memory to allocate.
  96   @param  AllocationSize        The number of bytes to allocate and zero.
  97
  98   @return A pointer to the allocated buffer or NULL if allocation fails.
  99
 100 **/
 101 VOID *
 102 InternalAllocateZeroPool (
 103   IN EFI_MEMORY_TYPE  PoolType,
 104   IN UINTN            AllocationSize
 105   );
 106
 107 /**
 108   Copies a buffer to an allocated buffer of a certian pool type.
 109
 110   Allocates the number bytes specified by AllocationSize of a certian pool type, copies
 111   AllocationSize bytes from Buffer to the newly allocated buffer, and returns a pointer to the
 112   allocated buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there
 113   is not enough memory remaining to satisfy the request, then NULL is returned.
 114   If Buffer is NULL, then ASSERT().
 115   If AllocationSize is greater than (MAX_ADDRESS ? Buffer + 1), then ASSERT().
 116
 117   @param  PoolType              The type of pool to allocate.
 118   @param  AllocationSize        The number of bytes to allocate and zero.
 119   @param  Buffer                The buffer to copy to the allocated buffer.
 120
 121   @return A pointer to the allocated buffer or NULL if allocation fails.
 122
 123 **/
 124 VOID *
 125 InternalAllocateCopyPool (
 126   IN EFI_MEMORY_TYPE  PoolType,
 127   IN UINTN            AllocationSize,
 128   IN CONST VOID       *Buffer
 129   );
 130
 131 /**
 132   Allocates a buffer of a certain pool type at a specified alignment.
 133
 134   Allocates the number bytes specified by AllocationSize of a certain pool type with an alignment
 135   specified by Alignment.  The allocated buffer is returned.  If AllocationSize is 0, then a valid
 136   buffer of 0 size is returned.  If there is not enough memory at the specified alignment remaining
 137   to satisfy the request, then NULL is returned.
 138   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 139
 140   @param  PoolType              The type of pool to allocate.
 141   @param  AllocationSize        The number of bytes to allocate.
 142   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.                            If Alignment is zero, then byte alignment is used.
 143                                 If Alignment is zero, then byte alignment is used.
 144
 145   @return A pointer to the allocated buffer or NULL if allocation fails.
 146
 147 **/
 148 VOID *
 149 InternalAllocateAlignedPool (
 150   IN EFI_MEMORY_TYPE  PoolType,
 151   IN UINTN            AllocationSize,
 152   IN UINTN            Alignment
 153   );
 154
 155 /**
 156   Allocates and zeros a buffer of a certain pool type at a specified alignment.
 157
 158   Allocates the number bytes specified by AllocationSize of a certain pool type with an alignment
 159   specified by Alignment, clears the buffer with zeros, and returns a pointer to the allocated
 160   buffer.  If AllocationSize is 0, then a valid buffer of 0 size is returned.  If there is not
 161   enough memory at the specified alignment remaining to satisfy the request, then NULL is returned.
 162   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 163
 164   @param  PoolType              The type of pool to allocate.
 165   @param  AllocationSize        The number of bytes 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 **/
 172 VOID *
 173 InternalAllocateAlignedZeroPool (
 174   IN EFI_MEMORY_TYPE  PoolType,
 175   IN UINTN            AllocationSize,
 176   IN UINTN            Alignment
 177   );
 178
 179 /**
 180   Copies a buffer to an allocated buffer of a certain pool type at a specified alignment.
 181
 182   Allocates the number bytes specified by AllocationSize of a certain pool type with an alignment
 183   specified by Alignment.  The allocated buffer is returned.  If AllocationSize is 0, then a valid
 184   buffer of 0 size is returned.  If there is not enough memory at the specified alignment remaining
 185   to satisfy the request, then NULL is returned.
 186   If Alignment is not a power of two and Alignment is not zero, then ASSERT().
 187
 188   @param  PoolType              The type of pool to allocate.
 189   @param  AllocationSize        The number of bytes to allocate.
 190   @param  Buffer                The buffer to copy to the allocated buffer.
 191   @param  Alignment             The requested alignment of the allocation.  Must be a power of two.
 192                                 If Alignment is zero, then byte alignment is used.
 193
 194   @return A pointer to the allocated buffer or NULL if allocation fails.
 195
 196 **/
 197 VOID *
 198 InternalAllocateAlignedCopyPool (
 199   IN EFI_MEMORY_TYPE  PoolType,
 200   IN UINTN            AllocationSize,
 201   IN CONST VOID       *Buffer,
 202   IN UINTN            Alignment
 203   );
 204
 205 #endif