EmbeddedPkg: rename NullDmaLib to CoherentDmaLib

The name NullDmaLib suggests that this library is a placeholder that
only exists to fulfil formal dependencies on the DmaLib library class
without providing an actual implementation. This is not the case, though:
NullDmaLib does implement DmaLib fully, but doing so simply requires very
little effort on a cache coherent platform. So let's rename it to
CoherentDmaLib instead.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Ard Biesheuvel <ard.biesheuvel@linaro.org>
Reviewed-by: Leif Lindholm <leif.lindholm@linaro.org>

diff --git a/EmbeddedPkg/EmbeddedPkg.dsc b/EmbeddedPkg/EmbeddedPkg.dsc
index 09b1899c9b24c8020ffe0ed38d50458dd376876c..4f0a3438e13431fac7f952e6c0507ad672135d5e 100644 (file)
--- a/EmbeddedPkg/EmbeddedPkg.dsc
+++ b/EmbeddedPkg/EmbeddedPkg.dsc
@@ -250,7 +250,7 @@
   EmbeddedPkg/Library/TemplateResetSystemLib/TemplateResetSystemLib.inf\r
   EmbeddedPkg/Library/TemplateRealTimeClockLib/TemplateRealTimeClockLib.inf\r
   EmbeddedPkg/Library/LzmaHobCustomDecompressLib/LzmaHobCustomDecompressLib.inf\r
-  EmbeddedPkg/Library/NullDmaLib/NullDmaLib.inf\r
+  EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.inf\r
   EmbeddedPkg/Library/DxeDtPlatformDtbLoaderLibDefault/DxeDtPlatformDtbLoaderLibDefault.inf\r
 \r
   EmbeddedPkg/Ebl/Ebl.inf\r

diff --git a/EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.c b/EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.c
new file mode 100644 (file)
index 0000000..4cbe349
--- /dev/null
+++ b/EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.c
@@ -0,0 +1,187 @@
+/** @file\r
+  Generic ARM implementation of DmaLib.h\r
+\r
+  Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>\r
+\r
+  This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#include <Uefi.h>\r
+#include <Library/DebugLib.h>\r
+#include <Library/DmaLib.h>\r
+#include <Library/MemoryAllocationLib.h>\r
+\r
+\r
+\r
+/**\r
+  Provides the DMA controller-specific addresses needed to access system memory.\r
+\r
+  Operation is relative to the DMA bus master.\r
+\r
+  @param  Operation             Indicates if the bus master is going to read or write to system memory.\r
+  @param  HostAddress           The system memory address to map to the DMA controller.\r
+  @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes\r
+                                that were mapped.\r
+  @param  DeviceAddress         The resulting map address for the bus master controller to use to\r
+                                access the hosts HostAddress.\r
+  @param  Mapping               A resulting value to pass to Unmap().\r
+\r
+  @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.\r
+  @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.\r
+  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
+  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.\r
+  @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DmaMap (\r
+  IN     DMA_MAP_OPERATION              Operation,\r
+  IN     VOID                           *HostAddress,\r
+  IN OUT UINTN                          *NumberOfBytes,\r
+  OUT    PHYSICAL_ADDRESS               *DeviceAddress,\r
+  OUT    VOID                           **Mapping\r
+  )\r
+{\r
+  *DeviceAddress = (PHYSICAL_ADDRESS)(UINTN)HostAddress;\r
+  *Mapping = NULL;\r
+  return EFI_SUCCESS;\r
+}\r
+\r
+\r
+/**\r
+  Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()\r
+  operation and releases any corresponding resources.\r
+\r
+  @param  Mapping               The mapping value returned from DmaMap*().\r
+\r
+  @retval EFI_SUCCESS           The range was unmapped.\r
+  @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DmaUnmap (\r
+  IN  VOID                         *Mapping\r
+  )\r
+{\r
+  return EFI_SUCCESS;\r
+}\r
+\r
+/**\r
+  Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.\r
+  mapping.\r
+\r
+  @param  MemoryType            The type of memory to allocate, EfiBootServicesData or\r
+                                EfiRuntimeServicesData.\r
+  @param  Pages                 The number of pages to allocate.\r
+  @param  HostAddress           A pointer to store the base system memory address of the\r
+                                allocated range.\r
+\r
+                                @retval EFI_SUCCESS           The requested memory pages were allocated.\r
+  @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are\r
+                                MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
+  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
+  @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DmaAllocateBuffer (\r
+  IN  EFI_MEMORY_TYPE              MemoryType,\r
+  IN  UINTN                        Pages,\r
+  OUT VOID                         **HostAddress\r
+  )\r
+{\r
+  return DmaAllocateAlignedBuffer (MemoryType, Pages, 0, HostAddress);\r
+}\r
+\r
+\r
+/**\r
+  Allocates pages that are suitable for an DmaMap() of type\r
+  MapOperationBusMasterCommonBuffer mapping, at the requested alignment.\r
+\r
+  @param  MemoryType            The type of memory to allocate, EfiBootServicesData or\r
+                                EfiRuntimeServicesData.\r
+  @param  Pages                 The number of pages to allocate.\r
+  @param  Alignment             Alignment in bytes of the base of the returned\r
+                                buffer (must be a power of 2)\r
+  @param  HostAddress           A pointer to store the base system memory address of the\r
+                                allocated range.\r
+\r
+  @retval EFI_SUCCESS           The requested memory pages were allocated.\r
+  @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are\r
+                                MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
+  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
+  @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DmaAllocateAlignedBuffer (\r
+  IN  EFI_MEMORY_TYPE              MemoryType,\r
+  IN  UINTN                        Pages,\r
+  IN  UINTN                        Alignment,\r
+  OUT VOID                         **HostAddress\r
+  )\r
+{\r
+  if (Alignment == 0) {\r
+    Alignment = EFI_PAGE_SIZE;\r
+  }\r
+\r
+  if (HostAddress == NULL ||\r
+      (Alignment & (Alignment - 1)) != 0) {\r
+    return EFI_INVALID_PARAMETER;\r
+  }\r
+\r
+  //\r
+  // The only valid memory types are EfiBootServicesData and EfiRuntimeServicesData\r
+  //\r
+  if (MemoryType == EfiBootServicesData) {\r
+    *HostAddress = AllocateAlignedPages (Pages, Alignment);\r
+  } else if (MemoryType != EfiRuntimeServicesData) {\r
+    *HostAddress = AllocateAlignedRuntimePages (Pages, Alignment);\r
+  } else {\r
+    return EFI_INVALID_PARAMETER;\r
+  }\r
+\r
+  if (*HostAddress == NULL) {\r
+    return EFI_OUT_OF_RESOURCES;\r
+  }\r
+  return EFI_SUCCESS;\r
+}\r
+\r
+\r
+/**\r
+  Frees memory that was allocated with DmaAllocateBuffer().\r
+\r
+  @param  Pages                 The number of pages to free.\r
+  @param  HostAddress           The base system memory address of the allocated range.\r
+\r
+  @retval EFI_SUCCESS           The requested memory pages were freed.\r
+  @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages\r
+                                was not allocated with DmaAllocateBuffer().\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DmaFreeBuffer (\r
+  IN  UINTN                        Pages,\r
+  IN  VOID                         *HostAddress\r
+  )\r
+{\r
+  if (HostAddress == NULL) {\r
+     return EFI_INVALID_PARAMETER;\r
+  }\r
+\r
+  FreePages (HostAddress, Pages);\r
+  return EFI_SUCCESS;\r
+}\r
+\r

diff --git a/EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.inf b/EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.inf
new file mode 100644 (file)
index 0000000..c40a600
--- /dev/null
+++ b/EmbeddedPkg/Library/CoherentDmaLib/CoherentDmaLib.inf
@@ -0,0 +1,33 @@
+#/** @file\r
+#\r
+#  Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>\r
+#  Copyright (c) 2017, Linaro, Ltd. All rights reserved.<BR>\r
+#\r
+#  This program and the accompanying materials\r
+#  are licensed and made available under the terms and conditions of the BSD License\r
+#  which accompanies this distribution.  The full text of the license may be found at\r
+#  http://opensource.org/licenses/bsd-license.php\r
+#\r
+#  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+#  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+#\r
+#**/\r
+\r
+[Defines]\r
+  INF_VERSION                    = 0x00010019\r
+  BASE_NAME                      = CoherentDmaLib\r
+  FILE_GUID                      = 0F2A0816-D319-4ee7-A6B8-D58524E4428F\r
+  MODULE_TYPE                    = BASE\r
+  VERSION_STRING                 = 1.0\r
+  LIBRARY_CLASS                  = DmaLib\r
+\r
+[Sources]\r
+  CoherentDmaLib.c\r
+\r
+[Packages]\r
+  MdePkg/MdePkg.dec\r
+  EmbeddedPkg/EmbeddedPkg.dec\r
+\r
+[LibraryClasses]\r
+  DebugLib\r
+  MemoryAllocationLib\r

diff --git a/EmbeddedPkg/Library/NullDmaLib/NullDmaLib.c b/EmbeddedPkg/Library/NullDmaLib/NullDmaLib.c
deleted file mode 100644 (file)
index 4cbe349..0000000
--- a/EmbeddedPkg/Library/NullDmaLib/NullDmaLib.c
+++ /dev/null
@@ -1,187 +0,0 @@
-/** @file\r
-  Generic ARM implementation of DmaLib.h\r
-\r
-  Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>\r
-\r
-  This program and the accompanying materials\r
-  are licensed and made available under the terms and conditions of the BSD License\r
-  which accompanies this distribution.  The full text of the license may be found at\r
-  http://opensource.org/licenses/bsd-license.php\r
-\r
-  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
-\r
-**/\r
-\r
-#include <Uefi.h>\r
-#include <Library/DebugLib.h>\r
-#include <Library/DmaLib.h>\r
-#include <Library/MemoryAllocationLib.h>\r
-\r
-\r
-\r
-/**\r
-  Provides the DMA controller-specific addresses needed to access system memory.\r
-\r
-  Operation is relative to the DMA bus master.\r
-\r
-  @param  Operation             Indicates if the bus master is going to read or write to system memory.\r
-  @param  HostAddress           The system memory address to map to the DMA controller.\r
-  @param  NumberOfBytes         On input the number of bytes to map. On output the number of bytes\r
-                                that were mapped.\r
-  @param  DeviceAddress         The resulting map address for the bus master controller to use to\r
-                                access the hosts HostAddress.\r
-  @param  Mapping               A resulting value to pass to Unmap().\r
-\r
-  @retval EFI_SUCCESS           The range was mapped for the returned NumberOfBytes.\r
-  @retval EFI_UNSUPPORTED       The HostAddress cannot be mapped as a common buffer.\r
-  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
-  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack of resources.\r
-  @retval EFI_DEVICE_ERROR      The system hardware could not map the requested address.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-DmaMap (\r
-  IN     DMA_MAP_OPERATION              Operation,\r
-  IN     VOID                           *HostAddress,\r
-  IN OUT UINTN                          *NumberOfBytes,\r
-  OUT    PHYSICAL_ADDRESS               *DeviceAddress,\r
-  OUT    VOID                           **Mapping\r
-  )\r
-{\r
-  *DeviceAddress = (PHYSICAL_ADDRESS)(UINTN)HostAddress;\r
-  *Mapping = NULL;\r
-  return EFI_SUCCESS;\r
-}\r
-\r
-\r
-/**\r
-  Completes the DmaMapBusMasterRead(), DmaMapBusMasterWrite(), or DmaMapBusMasterCommonBuffer()\r
-  operation and releases any corresponding resources.\r
-\r
-  @param  Mapping               The mapping value returned from DmaMap*().\r
-\r
-  @retval EFI_SUCCESS           The range was unmapped.\r
-  @retval EFI_DEVICE_ERROR      The data was not committed to the target system memory.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-DmaUnmap (\r
-  IN  VOID                         *Mapping\r
-  )\r
-{\r
-  return EFI_SUCCESS;\r
-}\r
-\r
-/**\r
-  Allocates pages that are suitable for an DmaMap() of type MapOperationBusMasterCommonBuffer.\r
-  mapping.\r
-\r
-  @param  MemoryType            The type of memory to allocate, EfiBootServicesData or\r
-                                EfiRuntimeServicesData.\r
-  @param  Pages                 The number of pages to allocate.\r
-  @param  HostAddress           A pointer to store the base system memory address of the\r
-                                allocated range.\r
-\r
-                                @retval EFI_SUCCESS           The requested memory pages were allocated.\r
-  @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are\r
-                                MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
-  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
-  @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-DmaAllocateBuffer (\r
-  IN  EFI_MEMORY_TYPE              MemoryType,\r
-  IN  UINTN                        Pages,\r
-  OUT VOID                         **HostAddress\r
-  )\r
-{\r
-  return DmaAllocateAlignedBuffer (MemoryType, Pages, 0, HostAddress);\r
-}\r
-\r
-\r
-/**\r
-  Allocates pages that are suitable for an DmaMap() of type\r
-  MapOperationBusMasterCommonBuffer mapping, at the requested alignment.\r
-\r
-  @param  MemoryType            The type of memory to allocate, EfiBootServicesData or\r
-                                EfiRuntimeServicesData.\r
-  @param  Pages                 The number of pages to allocate.\r
-  @param  Alignment             Alignment in bytes of the base of the returned\r
-                                buffer (must be a power of 2)\r
-  @param  HostAddress           A pointer to store the base system memory address of the\r
-                                allocated range.\r
-\r
-  @retval EFI_SUCCESS           The requested memory pages were allocated.\r
-  @retval EFI_UNSUPPORTED       Attributes is unsupported. The only legal attribute bits are\r
-                                MEMORY_WRITE_COMBINE and MEMORY_CACHED.\r
-  @retval EFI_INVALID_PARAMETER One or more parameters are invalid.\r
-  @retval EFI_OUT_OF_RESOURCES  The memory pages could not be allocated.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-DmaAllocateAlignedBuffer (\r
-  IN  EFI_MEMORY_TYPE              MemoryType,\r
-  IN  UINTN                        Pages,\r
-  IN  UINTN                        Alignment,\r
-  OUT VOID                         **HostAddress\r
-  )\r
-{\r
-  if (Alignment == 0) {\r
-    Alignment = EFI_PAGE_SIZE;\r
-  }\r
-\r
-  if (HostAddress == NULL ||\r
-      (Alignment & (Alignment - 1)) != 0) {\r
-    return EFI_INVALID_PARAMETER;\r
-  }\r
-\r
-  //\r
-  // The only valid memory types are EfiBootServicesData and EfiRuntimeServicesData\r
-  //\r
-  if (MemoryType == EfiBootServicesData) {\r
-    *HostAddress = AllocateAlignedPages (Pages, Alignment);\r
-  } else if (MemoryType != EfiRuntimeServicesData) {\r
-    *HostAddress = AllocateAlignedRuntimePages (Pages, Alignment);\r
-  } else {\r
-    return EFI_INVALID_PARAMETER;\r
-  }\r
-\r
-  if (*HostAddress == NULL) {\r
-    return EFI_OUT_OF_RESOURCES;\r
-  }\r
-  return EFI_SUCCESS;\r
-}\r
-\r
-\r
-/**\r
-  Frees memory that was allocated with DmaAllocateBuffer().\r
-\r
-  @param  Pages                 The number of pages to free.\r
-  @param  HostAddress           The base system memory address of the allocated range.\r
-\r
-  @retval EFI_SUCCESS           The requested memory pages were freed.\r
-  @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages\r
-                                was not allocated with DmaAllocateBuffer().\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-DmaFreeBuffer (\r
-  IN  UINTN                        Pages,\r
-  IN  VOID                         *HostAddress\r
-  )\r
-{\r
-  if (HostAddress == NULL) {\r
-     return EFI_INVALID_PARAMETER;\r
-  }\r
-\r
-  FreePages (HostAddress, Pages);\r
-  return EFI_SUCCESS;\r
-}\r
-\r

diff --git a/EmbeddedPkg/Library/NullDmaLib/NullDmaLib.inf b/EmbeddedPkg/Library/NullDmaLib/NullDmaLib.inf
deleted file mode 100644 (file)
index 38261d5..0000000
--- a/EmbeddedPkg/Library/NullDmaLib/NullDmaLib.inf
+++ /dev/null
@@ -1,41 +0,0 @@
-#/** @file\r
-#\r
-#  Copyright (c) 2008 - 2010, Apple Inc. All rights reserved.<BR>\r
-#  This program and the accompanying materials\r
-#  are licensed and made available under the terms and conditions of the BSD License\r
-#  which accompanies this distribution.  The full text of the license may be found at\r
-#  http://opensource.org/licenses/bsd-license.php\r
-#\r
-#  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-#  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
-#\r
-#**/\r
-\r
-[Defines]\r
-  INF_VERSION                    = 0x00010005\r
-  BASE_NAME                      = NullDmaLib\r
-  FILE_GUID                      = 0F2A0816-D319-4ee7-A6B8-D58524E4428F\r
-  MODULE_TYPE                    = BASE\r
-  VERSION_STRING                 = 1.0\r
-  LIBRARY_CLASS                  = DmaLib\r
-\r
-[Sources.common]\r
-  NullDmaLib.c\r
-\r
-[Packages]\r
-  MdePkg/MdePkg.dec\r
-  EmbeddedPkg/EmbeddedPkg.dec\r
-\r
-[LibraryClasses]\r
-  DebugLib\r
-  MemoryAllocationLib\r
-\r
-\r
-[Protocols]\r
-\r
-[Guids]\r
-\r
-[Pcd]\r
-\r
-[Depex]\r
-  TRUE\r