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   Copyright (c) 2015 - 2017, Linaro, Ltd. All rights reserved.<BR>
   6
   7   This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #include <PiDxe.h>
  18 #include <Library/BaseLib.h>
  19 #include <Library/DebugLib.h>
  20 #include <Library/DmaLib.h>
  21 #include <Library/DxeServicesTableLib.h>
  22 #include <Library/MemoryAllocationLib.h>
  23 #include <Library/UefiBootServicesTableLib.h>
  24 #include <Library/IoLib.h>
  25 #include <Library/BaseMemoryLib.h>
  26
  27 #include <Protocol/Cpu.h>
  28
  29 typedef struct {
  30   EFI_PHYSICAL_ADDRESS      HostAddress;
  31   VOID                      *BufferAddress;
  32   UINTN                     NumberOfBytes;
  33   DMA_MAP_OPERATION         Operation;
  34   BOOLEAN                   DoubleBuffer;
  35 } MAP_INFO_INSTANCE;
  36
  37
  38 typedef struct {
  39   LIST_ENTRY          Link;
  40   VOID                *HostAddress;
  41   UINTN               NumPages;
  42   UINT64              Attributes;
  43 } UNCACHED_ALLOCATION;
  44
  45 STATIC EFI_CPU_ARCH_PROTOCOL      *mCpu;
  46 STATIC LIST_ENTRY                 UncachedAllocationList;
  47
  48 STATIC
  49 PHYSICAL_ADDRESS
  50 HostToDeviceAddress (
  51   IN  VOID      *Address
  52   )
  53 {
  54   return (PHYSICAL_ADDRESS)(UINTN)Address + PcdGet64 (PcdArmDmaDeviceOffset);
  55 }
  56
  57 /**
  58   Provides the DMA controller-specific addresses needed to access system memory.
  59
  60   Operation is relative to the DMA bus master.
  61
  62   @param  Operation             Indicates if the bus master is going to read or write to system memory.
  63   @param  HostAddress           The system memory address to map to the DMA controller.
  64   @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes
  65                                 that were mapped.
  66   @param  DeviceAddress         The resulting map address for the bus master controller to use to
  67                                 access the hosts HostAddress.
  68   @param  Mapping               A resulting value to pass to Unmap().
  69
  70   @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.
  71   @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.
  72   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  73   @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.
  74   @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.
  75
  76 **/
  77 EFI_STATUS
  78 EFIAPI
  79 DmaMap (
  80   IN     DMA_MAP_OPERATION              Operation,
  81   IN     VOID                           *HostAddress,
  82   IN OUT UINTN                          *NumberOfBytes,
  83   OUT    PHYSICAL_ADDRESS               *DeviceAddress,
  84   OUT    VOID                           **Mapping
  85   )
  86 {
  87   EFI_STATUS                      Status;
  88   MAP_INFO_INSTANCE               *Map;
  89   VOID                            *Buffer;
  90   EFI_GCD_MEMORY_SPACE_DESCRIPTOR GcdDescriptor;
  91   UINTN                           AllocSize;
  92
  93   if (HostAddress == NULL || NumberOfBytes == NULL || DeviceAddress == NULL || Mapping == NULL ) {
  94     return EFI_INVALID_PARAMETER;
  95   }
  96
  97   if (Operation >= MapOperationMaximum) {
  98     return EFI_INVALID_PARAMETER;
  99   }
 100
 101   *DeviceAddress = HostToDeviceAddress (HostAddress);
 102
 103   // Remember range so we can flush on the other side
 104   Map = AllocatePool (sizeof (MAP_INFO_INSTANCE));
 105   if (Map == NULL) {
 106     return  EFI_OUT_OF_RESOURCES;
 107   }
 108
 109   if (Operation != MapOperationBusMasterRead &&
 110       ((((UINTN)HostAddress & (mCpu->DmaBufferAlignment - 1)) != 0) ||
 111        ((*NumberOfBytes & (mCpu->DmaBufferAlignment - 1)) != 0))) {
 112
 113     // Get the cacheability of the region
 114     Status = gDS->GetMemorySpaceDescriptor ((UINTN)HostAddress, &GcdDescriptor);
 115     if (EFI_ERROR(Status)) {
 116       goto FreeMapInfo;
 117     }
 118
 119     // If the mapped buffer is not an uncached buffer
 120     if ((GcdDescriptor.Attributes & (EFI_MEMORY_WB | EFI_MEMORY_WT)) != 0) {
 121       //
 122       // Operations of type MapOperationBusMasterCommonBuffer are only allowed
 123       // on uncached buffers.
 124       //
 125       if (Operation == MapOperationBusMasterCommonBuffer) {
 126         DEBUG ((EFI_D_ERROR,
 127           "%a: Operation type 'MapOperationBusMasterCommonBuffer' is only supported\n"
 128           "on memory regions that were allocated using DmaAllocateBuffer ()\n",
 129           __FUNCTION__));
 130         Status = EFI_UNSUPPORTED;
 131         goto FreeMapInfo;
 132       }
 133
 134       //
 135       // If the buffer does not fill entire cache lines we must double buffer
 136       // into a suitably aligned allocation that allows us to invalidate the
 137       // cache without running the risk of corrupting adjacent unrelated data.
 138       // Note that pool allocations are guaranteed to be 8 byte aligned, so
 139       // we only have to add (alignment - 8) worth of padding.
 140       //
 141       Map->DoubleBuffer = TRUE;
 142       AllocSize = ALIGN_VALUE (*NumberOfBytes, mCpu->DmaBufferAlignment) +
 143                   (mCpu->DmaBufferAlignment - 8);
 144       Map->BufferAddress = AllocatePool (AllocSize);
 145       if (Map->BufferAddress == NULL) {
 146         Status = EFI_OUT_OF_RESOURCES;
 147         goto FreeMapInfo;
 148       }
 149
 150       Buffer = ALIGN_POINTER (Map->BufferAddress, mCpu->DmaBufferAlignment);
 151       *DeviceAddress = HostToDeviceAddress (Buffer);
 152
 153       //
 154       // Get rid of any dirty cachelines covering the double buffer. This
 155       // prevents them from being written back unexpectedly, potentially
 156       // overwriting the data we receive from the device.
 157       //
 158       mCpu->FlushDataCache (mCpu, (UINTN)Buffer, *NumberOfBytes,
 159               EfiCpuFlushTypeWriteBack);
 160     } else {
 161       Map->DoubleBuffer  = FALSE;
 162     }
 163   } else {
 164     Map->DoubleBuffer  = FALSE;
 165
 166     DEBUG_CODE_BEGIN ();
 167
 168     //
 169     // The operation type check above only executes if the buffer happens to be
 170     // misaligned with respect to CWG, but even if it is aligned, we should not
 171     // allow arbitrary buffers to be used for creating consistent mappings.
 172     // So duplicate the check here when running in DEBUG mode, just to assert
 173     // that we are not trying to create a consistent mapping for cached memory.
 174     //
 175     Status = gDS->GetMemorySpaceDescriptor ((UINTN)HostAddress, &GcdDescriptor);
 176     ASSERT_EFI_ERROR(Status);
 177
 178     ASSERT (Operation != MapOperationBusMasterCommonBuffer ||
 179             (GcdDescriptor.Attributes & (EFI_MEMORY_WB | EFI_MEMORY_WT)) == 0);
 180
 181     DEBUG_CODE_END ();
 182
 183     // Flush the Data Cache (should not have any effect if the memory region is uncached)
 184     mCpu->FlushDataCache (mCpu, (UINTN)HostAddress, *NumberOfBytes,
 185             EfiCpuFlushTypeWriteBackInvalidate);
 186   }
 187
 188   Map->HostAddress   = (UINTN)HostAddress;
 189   Map->NumberOfBytes = *NumberOfBytes;
 190   Map->Operation     = Operation;
 191
 192   *Mapping = Map;
 193
 194   return EFI_SUCCESS;
 195
 196 FreeMapInfo:
 197   FreePool (Map);
 198
 199   return Status;
 200 }
 201
 202
 203 /**
 204   Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()
 205   operation and releases any corresponding resources.
 206
 207   @param  Mapping               The mapping value returned from DmaMap*().
 208
 209   @retval EFI_SUCCESS           The range was unmapped.
 210   @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.
 211   @retval EFI_INVALID_PARAMETER An inconsistency was detected between the mapping type
 212                                 and the DoubleBuffer field
 213
 214 **/
 215 EFI_STATUS
 216 EFIAPI
 217 DmaUnmap (
 218   IN  VOID                         *Mapping
 219   )
 220 {
 221   MAP_INFO_INSTANCE *Map;
 222   EFI_STATUS        Status;
 223   VOID              *Buffer;
 224
 225   if (Mapping == NULL) {
 226     ASSERT (FALSE);
 227     return EFI_INVALID_PARAMETER;
 228   }
 229
 230   Map = (MAP_INFO_INSTANCE *)Mapping;
 231
 232   Status = EFI_SUCCESS;
 233   if (Map->DoubleBuffer) {
 234     ASSERT (Map->Operation == MapOperationBusMasterWrite);
 235
 236     if (Map->Operation != MapOperationBusMasterWrite) {
 237       Status = EFI_INVALID_PARAMETER;
 238     } else {
 239       Buffer = ALIGN_POINTER (Map->BufferAddress, mCpu->DmaBufferAlignment);
 240
 241       mCpu->FlushDataCache (mCpu, (UINTN)Buffer, Map->NumberOfBytes,
 242               EfiCpuFlushTypeInvalidate);
 243
 244       CopyMem ((VOID *)(UINTN)Map->HostAddress, Buffer, Map->NumberOfBytes);
 245
 246       FreePool (Map->BufferAddress);
 247     }
 248   } else {
 249     if (Map->Operation == MapOperationBusMasterWrite) {
 250       //
 251       // Make sure we read buffer from uncached memory and not the cache
 252       //
 253       mCpu->FlushDataCache (mCpu, Map->HostAddress, Map->NumberOfBytes,
 254               EfiCpuFlushTypeInvalidate);
 255     }
 256   }
 257
 258   FreePool (Map);
 259
 260   return Status;
 261 }
 262
 263 /**
 264   Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.
 265   mapping.
 266
 267   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 268                                 EfiRuntimeServicesData.
 269   @param  Pages                 The number of pages to allocate.
 270   @param  HostAddress           A pointer to store the base system memory address of the
 271                                 allocated range.
 272
 273   @retval EFI_SUCCESS           The requested memory pages were allocated.
 274   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 275                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 276   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 277   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 278
 279 **/
 280 EFI_STATUS
 281 EFIAPI
 282 DmaAllocateBuffer (
 283   IN  EFI_MEMORY_TYPE              MemoryType,
 284   IN  UINTN                        Pages,
 285   OUT VOID                         **HostAddress
 286   )
 287 {
 288   return DmaAllocateAlignedBuffer (MemoryType, Pages, 0, HostAddress);
 289 }
 290
 291 /**
 292   Allocates pages that are suitable for an DmaMap() of type
 293   MapOperationBusMasterCommonBuffer mapping, at the requested alignment.
 294
 295   @param  MemoryType            The type of memory to allocate, EfiBootServicesData or
 296                                 EfiRuntimeServicesData.
 297   @param  Pages                 The number of pages to allocate.
 298   @param  Alignment             Alignment in bytes of the base of the returned
 299                                 buffer (must be a power of 2)
 300   @param  HostAddress           A pointer to store the base system memory address of the
 301                                 allocated range.
 302
 303   @retval EFI_SUCCESS           The requested memory pages were allocated.
 304   @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are
 305                                 MEMORY_WRITE_COMBINE and MEMORY_CACHED.
 306   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
 307   @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.
 308
 309 **/
 310 EFI_STATUS
 311 EFIAPI
 312 DmaAllocateAlignedBuffer (
 313   IN  EFI_MEMORY_TYPE              MemoryType,
 314   IN  UINTN                        Pages,
 315   IN  UINTN                        Alignment,
 316   OUT VOID                         **HostAddress
 317   )
 318 {
 319   EFI_GCD_MEMORY_SPACE_DESCRIPTOR   GcdDescriptor;
 320   VOID                              *Allocation;
 321   UINT64                            MemType;
 322   UNCACHED_ALLOCATION               *Alloc;
 323   EFI_STATUS                        Status;
 324
 325   if (Alignment == 0) {
 326     Alignment = EFI_PAGE_SIZE;
 327   }
 328
 329   if (HostAddress == NULL ||
 330       (Alignment & (Alignment - 1)) != 0) {
 331     return EFI_INVALID_PARAMETER;
 332   }
 333
 334   if (MemoryType == EfiBootServicesData) {
 335     Allocation = AllocateAlignedPages (Pages, Alignment);
 336   } else if (MemoryType == EfiRuntimeServicesData) {
 337     Allocation = AllocateAlignedRuntimePages (Pages, Alignment);
 338   } else {
 339     return EFI_INVALID_PARAMETER;
 340   }
 341
 342   if (Allocation == NULL) {
 343     return EFI_OUT_OF_RESOURCES;
 344   }
 345
 346   // Get the cacheability of the region
 347   Status = gDS->GetMemorySpaceDescriptor ((UINTN)Allocation, &GcdDescriptor);
 348   if (EFI_ERROR(Status)) {
 349     goto FreeBuffer;
 350   }
 351
 352   // Choose a suitable uncached memory type that is supported by the region
 353   if (GcdDescriptor.Capabilities & EFI_MEMORY_WC) {
 354     MemType = EFI_MEMORY_WC;
 355   } else if (GcdDescriptor.Capabilities & EFI_MEMORY_UC) {
 356     MemType = EFI_MEMORY_UC;
 357   } else {
 358     Status = EFI_UNSUPPORTED;
 359     goto FreeBuffer;
 360   }
 361
 362   Alloc = AllocatePool (sizeof *Alloc);
 363   if (Alloc == NULL) {
 364     goto FreeBuffer;
 365   }
 366
 367   Alloc->HostAddress = Allocation;
 368   Alloc->NumPages = Pages;
 369   Alloc->Attributes = GcdDescriptor.Attributes;
 370
 371   InsertHeadList (&UncachedAllocationList, &Alloc->Link);
 372
 373   // Remap the region with the new attributes
 374   Status = gDS->SetMemorySpaceAttributes ((PHYSICAL_ADDRESS)(UINTN)Allocation,
 375                                           EFI_PAGES_TO_SIZE (Pages),
 376                                           MemType);
 377   if (EFI_ERROR (Status)) {
 378     goto FreeAlloc;
 379   }
 380
 381   Status = mCpu->FlushDataCache (mCpu,
 382                                  (PHYSICAL_ADDRESS)(UINTN)Allocation,
 383                                  EFI_PAGES_TO_SIZE (Pages),
 384                                  EfiCpuFlushTypeInvalidate);
 385   if (EFI_ERROR (Status)) {
 386     goto FreeAlloc;
 387   }
 388
 389   *HostAddress = Allocation;
 390
 391   return EFI_SUCCESS;
 392
 393 FreeAlloc:
 394   RemoveEntryList (&Alloc->Link);
 395   FreePool (Alloc);
 396
 397 FreeBuffer:
 398   FreePages (Allocation, Pages);
 399   return Status;
 400 }
 401
 402
 403 /**
 404   Frees memory that was allocated with DmaAllocateBuffer().
 405
 406   @param  Pages                 The number of pages to free.
 407   @param  HostAddress           The base system memory address of the allocated range.
 408
 409   @retval EFI_SUCCESS           The requested memory pages were freed.
 410   @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages
 411                                 was not allocated with DmaAllocateBuffer().
 412
 413 **/
 414 EFI_STATUS
 415 EFIAPI
 416 DmaFreeBuffer (
 417   IN  UINTN                        Pages,
 418   IN  VOID                         *HostAddress
 419   )
 420 {
 421   LIST_ENTRY                       *Link;
 422   UNCACHED_ALLOCATION              *Alloc;
 423   BOOLEAN                          Found;
 424   EFI_STATUS                       Status;
 425
 426   if (HostAddress == NULL) {
 427      return EFI_INVALID_PARAMETER;
 428   }
 429
 430   for (Link = GetFirstNode (&UncachedAllocationList), Found = FALSE;
 431        !IsNull (&UncachedAllocationList, Link);
 432        Link = GetNextNode (&UncachedAllocationList, Link)) {
 433
 434     Alloc = BASE_CR (Link, UNCACHED_ALLOCATION, Link);
 435     if (Alloc->HostAddress == HostAddress && Alloc->NumPages == Pages) {
 436       Found = TRUE;
 437       break;
 438     }
 439   }
 440
 441   if (!Found) {
 442     ASSERT (FALSE);
 443     return EFI_INVALID_PARAMETER;
 444   }
 445
 446   RemoveEntryList (&Alloc->Link);
 447
 448   Status = gDS->SetMemorySpaceAttributes ((PHYSICAL_ADDRESS)(UINTN)HostAddress,
 449                                           EFI_PAGES_TO_SIZE (Pages),
 450                                           Alloc->Attributes);
 451   if (EFI_ERROR (Status)) {
 452     goto FreeAlloc;
 453   }
 454
 455   //
 456   // If we fail to restore the original attributes, it is better to leak the
 457   // memory than to return it to the heap
 458   //
 459   FreePages (HostAddress, Pages);
 460
 461 FreeAlloc:
 462   FreePool (Alloc);
 463   return Status;
 464 }
 465
 466
 467 EFI_STATUS
 468 EFIAPI
 469 ArmDmaLibConstructor (
 470   IN EFI_HANDLE       ImageHandle,
 471   IN EFI_SYSTEM_TABLE *SystemTable
 472   )
 473 {
 474   InitializeListHead (&UncachedAllocationList);
 475
 476   // Get the Cpu protocol for later use
 477   return gBS->LocateProtocol (&gEfiCpuArchProtocolGuid, NULL, (VOID **)&mCpu);
 478 }