ArmPkg/Library/ArmDmaLib/ArmDmaLib.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 <PiDxe.h>
  17 #include <Library/DebugLib.h>
  18 #include <Library/DmaLib.h>
  19 #include <Library/DxeServicesTableLib.h>
  20 #include <Library/MemoryAllocationLib.h>
  21 #include <Library/UefiBootServicesTableLib.h>
  22 #include <Library/UncachedMemoryAllocationLib.h>
  23 #include <Library/IoLib.h>
  24 #include <Library/BaseMemoryLib.h>
  25 #include <Library/ArmLib.h>
  26
  27 #include <Protocol/Cpu.h>
  28
  29 typedef struct {
  30   EFI_PHYSICAL_ADDRESS      HostAddress;
  31   EFI_PHYSICAL_ADDRESS      DeviceAddress;
  32   UINTN                     NumberOfBytes;
  33   DMA_MAP_OPERATION         Operation;
  34   BOOLEAN                   DoubleBuffer;
  35 } MAP_INFO_INSTANCE;
  36
  37
  38
  39 EFI_CPU_ARCH_PROTOCOL      *gCpu;
  40 UINTN                      gCacheAlignment = 0;
  41
  42 /**
  43   Provides the DMA controller-specific addresses needed to access system memory.
  44
  45   Operation is relative to the DMA bus master.
  46
  47   @param  Operation             Indicates if the bus master is going to read or write to system memory.
  48   @param  HostAddress           The system memory address to map to the DMA controller.
  49   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
  50                                 that were mapped.
  51   @param  DeviceAddress         The resulting map address for the bus master controller to use to
  52                                 access the hosts HostAddress.
  53   @param  Mapping               A resulting value to pass to Unmap().
  54
  55   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
  56   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
  57   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  58   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  59   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
  60
  61 **/
  62 EFI_STATUS
  63 EFIAPI
  64 DmaMap (
  65   IN     DMA_MAP_OPERATION              Operation,
  66   IN     VOID                           *HostAddress,
  67   IN OUT UINTN                          *NumberOfBytes,
  68   OUT    PHYSICAL_ADDRESS               *DeviceAddress,
  69   OUT    VOID                           **Mapping
  70   )
  71 {
  72   EFI_STATUS                      Status;
  73   MAP_INFO_INSTANCE               *Map;
  74   VOID                            *Buffer;
  75   EFI_GCD_MEMORY_SPACE_DESCRIPTOR GcdDescriptor;
  76
  77   if (HostAddress == NULL || NumberOfBytes == NULL || DeviceAddress == NULL || Mapping == NULL ) {
  78     return EFI_INVALID_PARAMETER;
  79   }
  80
  81   if (Operation >= MapOperationMaximum) {
  82     return EFI_INVALID_PARAMETER;
  83   }
  84
  85   *DeviceAddress = ConvertToPhysicalAddress (HostAddress);
  86
  87   // Remember range so we can flush on the other side
  88   Map = AllocatePool (sizeof (MAP_INFO_INSTANCE));
  89   if (Map == NULL) {
  90     return  EFI_OUT_OF_RESOURCES;
  91   }
  92
  93   *Mapping = Map;
  94
  95   if ((((UINTN)HostAddress & (gCacheAlignment - 1)) != 0) ||
  96       ((*NumberOfBytes & (gCacheAlignment - 1)) != 0)) {
  97
  98     // Get the cacheability of the region
  99     Status = gDS->GetMemorySpaceDescriptor (*DeviceAddress, &GcdDescriptor);
 100     if (EFI_ERROR(Status)) {
 101       return Status;
 102     }
 103
 104     // If the mapped buffer is not an uncached buffer
 105     if ((GcdDescriptor.Attributes & (EFI_MEMORY_WB | EFI_MEMORY_WT)) != 0) {
 106       //
 107       // Operations of type MapOperationBusMasterCommonBuffer are only allowed
 108       // on uncached buffers.
 109       //
 110       if (Operation == MapOperationBusMasterCommonBuffer) {
 111         DEBUG ((EFI_D_ERROR,
 112           "%a: Operation type 'MapOperationBusMasterCommonBuffer' is only supported\n"
 113           "on memory regions that were allocated using DmaAllocateBuffer ()\n",
 114           __FUNCTION__));
 115         return EFI_UNSUPPORTED;
 116       }
 117
 118       //
 119       // If the buffer does not fill entire cache lines we must double buffer into
 120       // uncached memory. Device (PCI) address becomes uncached page.
 121       //
 122       Map->DoubleBuffer  = TRUE;
 123       Status = DmaAllocateBuffer (EfiBootServicesData, EFI_SIZE_TO_PAGES (*NumberOfBytes), &Buffer);
 124       if (EFI_ERROR (Status)) {
 125         return Status;
 126       }
 127
 128       if (Operation == MapOperationBusMasterRead) {
 129         CopyMem (Buffer, HostAddress, *NumberOfBytes);
 130       }
 131
 132       *DeviceAddress = (PHYSICAL_ADDRESS)(UINTN)Buffer;
 133     } else {
 134       Map->DoubleBuffer  = FALSE;
 135     }
 136   } else {
 137     Map->DoubleBuffer  = FALSE;
 138
 139     DEBUG_CODE_BEGIN ();
 140
 141     //
 142     // The operation type check above only executes if the buffer happens to be
 143     // misaligned with respect to CWG, but even if it is aligned, we should not
 144     // allow arbitrary buffers to be used for creating consistent mappings.
 145     // So duplicate the check here when running in DEBUG mode, just to assert
 146     // that we are not trying to create a consistent mapping for cached memory.
 147     //
 148     Status = gDS->GetMemorySpaceDescriptor (*DeviceAddress, &GcdDescriptor);
 149     ASSERT_EFI_ERROR(Status);
 150
 151     ASSERT (Operation != MapOperationBusMasterCommonBuffer ||
 152             (GcdDescriptor.Attributes & (EFI_MEMORY_WB | EFI_MEMORY_WT)) == 0);
 153
 154     DEBUG_CODE_END ();
 155
 156     // Flush the Data Cache (should not have any effect if the memory region is uncached)
 157     gCpu->FlushDataCache (gCpu, *DeviceAddress, *NumberOfBytes, EfiCpuFlushTypeWriteBackInvalidate);
 158   }
 159
 160   Map->HostAddress   = (UINTN)HostAddress;
 161   Map->DeviceAddress = *DeviceAddress;
 162   Map->NumberOfBytes = *NumberOfBytes;
 163   Map->Operation     = Operation;
 164
 165   return EFI_SUCCESS;
 166 }
 167
 168
 169 /**
 170   Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
 171   operation and releases any corresponding resources.
 172
 173   @param  Mapping               The mapping value returned from DmaMap*().
 174
 175   @retval EFI_SUCCESS           The range was unmapped.
 176   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 177   @retval EFI_INVALID_PARAMETER An inconsistency was detected between the mapping type
 178                                 and the DoubleBuffer field
 179
 180 **/
 181 EFI_STATUS
 182 EFIAPI
 183 DmaUnmap (
 184   IN  VOID                         *Mapping
 185   )
 186 {
 187   MAP_INFO_INSTANCE *Map;
 188   EFI_STATUS        Status;
 189
 190   if (Mapping == NULL) {
 191     ASSERT (FALSE);
 192     return EFI_INVALID_PARAMETER;
 193   }
 194
 195   Map = (MAP_INFO_INSTANCE *)Mapping;
 196
 197   Status = EFI_SUCCESS;
 198   if (Map->DoubleBuffer) {
 199     ASSERT (Map->Operation != MapOperationBusMasterCommonBuffer);
 200
 201     if (Map->Operation == MapOperationBusMasterCommonBuffer) {
 202       Status = EFI_INVALID_PARAMETER;
 203     } else if (Map->Operation == MapOperationBusMasterWrite) {
 204       CopyMem ((VOID *)(UINTN)Map->HostAddress, (VOID *)(UINTN)Map->DeviceAddress, Map->NumberOfBytes);
 205     }
 206
 207     DmaFreeBuffer (EFI_SIZE_TO_PAGES (Map->NumberOfBytes), (VOID *)(UINTN)Map->DeviceAddress);
 208
 209   } else {
 210     if (Map->Operation == MapOperationBusMasterWrite) {
 211       //
 212       // Make sure we read buffer from uncached memory and not the cache
 213       //
 214       gCpu->FlushDataCache (gCpu, Map->HostAddress, Map->NumberOfBytes, EfiCpuFlushTypeInvalidate);
 215     }
 216   }
 217
 218   FreePool (Map);
 219
 220   return Status;
 221 }
 222
 223 /**
 224   Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
 225   mapping.
 226
 227   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 228                                 EfiRuntimeServicesData.
 229   @param  Pages                 The number of pages to allocate.
 230   @param  HostAddress           A pointer to store the base system memory address of the
 231                                 allocated range.
 232
 233                                 @retval EFI_SUCCESS           The requested memory pages were allocated.
 234   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 235                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 236   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 237   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 238
 239 **/
 240 EFI_STATUS
 241 EFIAPI
 242 DmaAllocateBuffer (
 243   IN  EFI_MEMORY_TYPE              MemoryType,
 244   IN  UINTN                        Pages,
 245   OUT VOID                         **HostAddress
 246   )
 247 {
 248   VOID    *Allocation;
 249
 250   if (HostAddress == NULL) {
 251     return EFI_INVALID_PARAMETER;
 252   }
 253
 254   //
 255   // The only valid memory types are EfiBootServicesData and EfiRuntimeServicesData
 256   //
 257   // We used uncached memory to keep coherency
 258   //
 259   if (MemoryType == EfiBootServicesData) {
 260     Allocation = UncachedAllocatePages (Pages);
 261   } else if (MemoryType == EfiRuntimeServicesData) {
 262     Allocation = UncachedAllocateRuntimePages (Pages);
 263   } else {
 264     return EFI_INVALID_PARAMETER;
 265   }
 266
 267   if (Allocation == NULL) {
 268     return EFI_OUT_OF_RESOURCES;
 269   }
 270
 271   *HostAddress = Allocation;
 272
 273   return EFI_SUCCESS;
 274 }
 275
 276
 277 /**
 278   Frees memory that was allocated with DmaAllocateBuffer().
 279
 280   @param  Pages                 The number of pages to free.
 281   @param  HostAddress           The base system memory address of the allocated range.
 282
 283   @retval EFI_SUCCESS           The requested memory pages were freed.
 284   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 285                                 was not allocated with DmaAllocateBuffer().
 286
 287 **/
 288 EFI_STATUS
 289 EFIAPI
 290 DmaFreeBuffer (
 291   IN  UINTN                        Pages,
 292   IN  VOID                         *HostAddress
 293   )
 294 {
 295   if (HostAddress == NULL) {
 296      return EFI_INVALID_PARAMETER;
 297   }
 298
 299   UncachedFreePages (HostAddress, Pages);
 300   return EFI_SUCCESS;
 301 }
 302
 303
 304 EFI_STATUS
 305 EFIAPI
 306 ArmDmaLibConstructor (
 307   IN EFI_HANDLE       ImageHandle,
 308   IN EFI_SYSTEM_TABLE *SystemTable
 309   )
 310 {
 311   EFI_STATUS              Status;
 312
 313   // Get the Cpu protocol for later use
 314   Status = gBS->LocateProtocol (&gEfiCpuArchProtocolGuid, NULL, (VOID **)&gCpu);
 315   ASSERT_EFI_ERROR(Status);
 316
 317   gCacheAlignment = ArmCacheWritebackGranule ();
 318
 319   return Status;
 320 }
 321