MdePkg/Library/PeiMemoryAllocationLib/MemoryAllocationLibInternals.h

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