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