EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.c

   1 /** @file
   2   Generic ARM implementation of DmaLib.h
   3
   4   Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>
   5
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include <Uefi.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/DmaLib.h>
  19 #include <Library/MemoryAllocationLib.h>
  20
  21
  22 STATIC
  23 PHYSICAL_ADDRESS
  24 HostToDeviceAddress (
  25   IN  VOID      *Address
  26   )
  27 {
  28   return (PHYSICAL_ADDRESS)(UINTN)Address + PcdGet64 (PcdDmaDeviceOffset);
  29 }
  30
  31 /**
  32   Provides the DMA controller-specific addresses needed to access system memory.
  33
  34   Operation is relative to the DMA bus master.
  35
  36   @param  Operation             Indicates if the bus master is going to read or write to system memory.
  37   @param  HostAddress           The system memory address to map to the DMA controller.
  38   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
  39                                 that were mapped.
  40   @param  DeviceAddress         The resulting map address for the bus master controller to use to
  41                                 access the hosts HostAddress.
  42   @param  Mapping               A resulting value to pass to Unmap().
  43
  44   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
  45   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
  46   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  47   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  48   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
  49
  50 **/
  51 EFI_STATUS
  52 EFIAPI
  53 DmaMap (
  54   IN     DMA_MAP_OPERATION              Operation,
  55   IN     VOID                           *HostAddress,
  56   IN OUT UINTN                          *NumberOfBytes,
  57   OUT    PHYSICAL_ADDRESS               *DeviceAddress,
  58   OUT    VOID                           **Mapping
  59   )
  60 {
  61   if (HostAddress == NULL ||
  62       NumberOfBytes == NULL ||
  63       DeviceAddress == NULL ||
  64       Mapping == NULL ) {
  65     return EFI_INVALID_PARAMETER;
  66   }
  67   *DeviceAddress = HostToDeviceAddress (HostAddress);
  68   *Mapping = NULL;
  69   return EFI_SUCCESS;
  70 }
  71
  72
  73 /**
  74   Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
  75   operation and releases any corresponding resources.
  76
  77   @param  Mapping               The mapping value returned from DmaMap*().
  78
  79   @retval EFI_SUCCESS           The range was unmapped.
  80   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
  81
  82 **/
  83 EFI_STATUS
  84 EFIAPI
  85 DmaUnmap (
  86   IN  VOID                         *Mapping
  87   )
  88 {
  89   return EFI_SUCCESS;
  90 }
  91
  92 /**
  93   Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
  94   mapping.
  95
  96   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
  97                                 EfiRuntimeServicesData.
  98   @param  Pages                 The number of pages to allocate.
  99   @param  HostAddress           A pointer to store the base system memory address of the
 100                                 allocated range.
 101
 102                                 @retval EFI_SUCCESS           The requested memory pages were allocated.
 103   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 104                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 105   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 106   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 107
 108 **/
 109 EFI_STATUS
 110 EFIAPI
 111 DmaAllocateBuffer (
 112   IN  EFI_MEMORY_TYPE              MemoryType,
 113   IN  UINTN                        Pages,
 114   OUT VOID                         **HostAddress
 115   )
 116 {
 117   return DmaAllocateAlignedBuffer (MemoryType, Pages, 0, HostAddress);
 118 }
 119
 120
 121 /**
 122   Allocates pages that are suitable for an DmaMap() of type
 123   MapOperationBusMasterCommonBuffer mapping, at the requested alignment.
 124
 125   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 126                                 EfiRuntimeServicesData.
 127   @param  Pages                 The number of pages to allocate.
 128   @param  Alignment             Alignment in bytes of the base of the returned
 129                                 buffer (must be a power of 2)
 130   @param  HostAddress           A pointer to store the base system memory address of the
 131                                 allocated range.
 132
 133   @retval EFI_SUCCESS           The requested memory pages were allocated.
 134   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 135                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 136   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 137   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 138
 139 **/
 140 EFI_STATUS
 141 EFIAPI
 142 DmaAllocateAlignedBuffer (
 143   IN  EFI_MEMORY_TYPE              MemoryType,
 144   IN  UINTN                        Pages,
 145   IN  UINTN                        Alignment,
 146   OUT VOID                         **HostAddress
 147   )
 148 {
 149   if (Alignment == 0) {
 150     Alignment = EFI_PAGE_SIZE;
 151   }
 152
 153   if (HostAddress == NULL ||
 154       (Alignment & (Alignment - 1)) != 0) {
 155     return EFI_INVALID_PARAMETER;
 156   }
 157
 158   //
 159   // The only valid memory types are EfiBootServicesData and EfiRuntimeServicesData
 160   //
 161   if (MemoryType == EfiBootServicesData) {
 162     *HostAddress = AllocateAlignedPages (Pages, Alignment);
 163   } else if (MemoryType == EfiRuntimeServicesData) {
 164     *HostAddress = AllocateAlignedRuntimePages (Pages, Alignment);
 165   } else {
 166     return EFI_INVALID_PARAMETER;
 167   }
 168
 169   if (*HostAddress == NULL) {
 170     return EFI_OUT_OF_RESOURCES;
 171   }
 172   return EFI_SUCCESS;
 173 }
 174
 175
 176 /**
 177   Frees memory that was allocated with DmaAllocateBuffer().
 178
 179   @param  Pages                 The number of pages to free.
 180   @param  HostAddress           The base system memory address of the allocated range.
 181
 182   @retval EFI_SUCCESS           The requested memory pages were freed.
 183   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 184                                 was not allocated with DmaAllocateBuffer().
 185
 186 **/
 187 EFI_STATUS
 188 EFIAPI
 189 DmaFreeBuffer (
 190   IN  UINTN                        Pages,
 191   IN  VOID                         *HostAddress
 192   )
 193 {
 194   if (HostAddress == NULL) {
 195      return EFI_INVALID_PARAMETER;
 196   }
 197
 198   FreePages (HostAddress, Pages);
 199   return EFI_SUCCESS;
 200 }
 201