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   *DeviceAddress = HostToDeviceAddress (HostAddress);
  62   *Mapping = NULL;
  63   return EFI_SUCCESS;
  64 }
  65
  66
  67 /**
  68   Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
  69   operation and releases any corresponding resources.
  70
  71   @param  Mapping               The mapping value returned from DmaMap*().
  72
  73   @retval EFI_SUCCESS           The range was unmapped.
  74   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
  75
  76 **/
  77 EFI_STATUS
  78 EFIAPI
  79 DmaUnmap (
  80   IN  VOID                         *Mapping
  81   )
  82 {
  83   return EFI_SUCCESS;
  84 }
  85
  86 /**
  87   Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
  88   mapping.
  89
  90   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
  91                                 EfiRuntimeServicesData.
  92   @param  Pages                 The number of pages to allocate.
  93   @param  HostAddress           A pointer to store the base system memory address of the
  94                                 allocated range.
  95
  96                                 @retval EFI_SUCCESS           The requested memory pages were allocated.
  97   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
  98                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
  99   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 100   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 101
 102 **/
 103 EFI_STATUS
 104 EFIAPI
 105 DmaAllocateBuffer (
 106   IN  EFI_MEMORY_TYPE              MemoryType,
 107   IN  UINTN                        Pages,
 108   OUT VOID                         **HostAddress
 109   )
 110 {
 111   return DmaAllocateAlignedBuffer (MemoryType, Pages, 0, HostAddress);
 112 }
 113
 114
 115 /**
 116   Allocates pages that are suitable for an DmaMap() of type
 117   MapOperationBusMasterCommonBuffer mapping, at the requested alignment.
 118
 119   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 120                                 EfiRuntimeServicesData.
 121   @param  Pages                 The number of pages to allocate.
 122   @param  Alignment             Alignment in bytes of the base of the returned
 123                                 buffer (must be a power of 2)
 124   @param  HostAddress           A pointer to store the base system memory address of the
 125                                 allocated range.
 126
 127   @retval EFI_SUCCESS           The requested memory pages were allocated.
 128   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 129                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 130   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 131   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 132
 133 **/
 134 EFI_STATUS
 135 EFIAPI
 136 DmaAllocateAlignedBuffer (
 137   IN  EFI_MEMORY_TYPE              MemoryType,
 138   IN  UINTN                        Pages,
 139   IN  UINTN                        Alignment,
 140   OUT VOID                         **HostAddress
 141   )
 142 {
 143   if (Alignment == 0) {
 144     Alignment = EFI_PAGE_SIZE;
 145   }
 146
 147   if (HostAddress == NULL ||
 148       (Alignment & (Alignment - 1)) != 0) {
 149     return EFI_INVALID_PARAMETER;
 150   }
 151
 152   //
 153   // The only valid memory types are EfiBootServicesData and EfiRuntimeServicesData
 154   //
 155   if (MemoryType == EfiBootServicesData) {
 156     *HostAddress = AllocateAlignedPages (Pages, Alignment);
 157   } else if (MemoryType == EfiRuntimeServicesData) {
 158     *HostAddress = AllocateAlignedRuntimePages (Pages, Alignment);
 159   } else {
 160     return EFI_INVALID_PARAMETER;
 161   }
 162
 163   if (*HostAddress == NULL) {
 164     return EFI_OUT_OF_RESOURCES;
 165   }
 166   return EFI_SUCCESS;
 167 }
 168
 169
 170 /**
 171   Frees memory that was allocated with DmaAllocateBuffer().
 172
 173   @param  Pages                 The number of pages to free.
 174   @param  HostAddress           The base system memory address of the allocated range.
 175
 176   @retval EFI_SUCCESS           The requested memory pages were freed.
 177   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 178                                 was not allocated with DmaAllocateBuffer().
 179
 180 **/
 181 EFI_STATUS
 182 EFIAPI
 183 DmaFreeBuffer (
 184   IN  UINTN                        Pages,
 185   IN  VOID                         *HostAddress
 186   )
 187 {
 188   if (HostAddress == NULL) {
 189      return EFI_INVALID_PARAMETER;
 190   }
 191
 192   FreePages (HostAddress, Pages);
 193   return EFI_SUCCESS;
 194 }
 195