[Patch 03/15] MdePkg/BaseCacheMaintenanceLibNull: Add Null instance for host testing

["Michael D Kinney" <michael.d.kinney@intel.com>]

https://bugzilla.tianocore.org/show_bug.cgi?id=2799

The services in CacheMaintenanceLib usually generate exceptions in a
unit test host application.  Provide a Null instance that can be safely
used.

This Null instance can also be used as a template for implementing
new instances of CacheMaintenanceLib.

Cc: Liming Gao <liming.gao@intel.com>
Cc: Sean Brogan <sean.brogan@microsoft.com>
Cc: Bret Barkelew <Bret.Barkelew@microsoft.com>
Cc: Jiewen Yao <jiewen.yao@intel.com>
Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
---
 .../BaseCacheMaintenanceLibNull.c             | 225 ++++++++++++++++++
 .../BaseCacheMaintenanceLibNull.inf           |  29 +++
 .../BaseCacheMaintenanceLibNull.uni           |  12 +
 MdePkg/MdePkg.dsc                             |   1 +
 4 files changed, 267 insertions(+)
 create mode 100644 MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.c
 create mode 100644 MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.inf
 create mode 100644 MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.uni

diff --git a/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.c b/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.c
new file mode 100644
index 0000000000..fd5b9d4710
--- /dev/null
+++ b/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.c
@@ -0,0 +1,225 @@
+/** @file
+  Null Cache Maintenance Librfary implementation.
+
+  Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <Base.h>
+#include <Library/DebugLib.h>
+
+/**
+  Invalidates the entire instruction cache in cache coherency domain of the
+  calling CPU.
+
+**/
+VOID
+EFIAPI
+InvalidateInstructionCache (
+  VOID
+  )
+{
+}
+
+/**
+  Invalidates a range of instruction cache lines in the cache coherency domain
+  of the calling CPU.
+
+  Invalidates the instruction cache lines specified by Address and Length. If
+  Address is not aligned on a cache line boundary, then entire instruction
+  cache line containing Address is invalidated. If Address + Length is not
+  aligned on a cache line boundary, then the entire instruction cache line
+  containing Address + Length -1 is invalidated. This function may choose to
+  invalidate the entire instruction cache if that is more efficient than
+  invalidating the specified range. If Length is 0, then no instruction cache
+  lines are invalidated. Address is returned.
+
+  If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
+
+  @param  Address The base address of the instruction cache lines to
+                  invalidate. If the CPU is in a physical addressing mode, then
+                  Address is a physical address. If the CPU is in a virtual
+                  addressing mode, then Address is a virtual address.
+
+  @param  Length  The number of bytes to invalidate from the instruction cache.
+
+  @return Address.
+
+**/
+VOID *
+EFIAPI
+InvalidateInstructionCacheRange (
+  IN      VOID                      *Address,
+  IN      UINTN                     Length
+  )
+{
+  ASSERT (Length <= MAX_ADDRESS - (UINTN)Address + 1);
+  return Address;
+}
+
+/**
+  Writes back and invalidates the entire data cache in cache coherency domain
+  of the calling CPU.
+
+  Writes back and invalidates the entire data cache in cache coherency domain
+  of the calling CPU. This function guarantees that all dirty cache lines are
+  written back to system memory, and also invalidates all the data cache lines
+  in the cache coherency domain of the calling CPU.
+
+**/
+VOID
+EFIAPI
+WriteBackInvalidateDataCache (
+  VOID
+  )
+{
+}
+
+/**
+  Writes back and invalidates a range of data cache lines in the cache
+  coherency domain of the calling CPU.
+
+  Writes Back and Invalidate the data cache lines specified by Address and
+  Length. If Address is not aligned on a cache line boundary, then entire data
+  cache line containing Address is written back and invalidated. If Address +
+  Length is not aligned on a cache line boundary, then the entire data cache
+  line containing Address + Length -1 is written back and invalidated. This
+  function may choose to write back and invalidate the entire data cache if
+  that is more efficient than writing back and invalidating the specified
+  range. If Length is 0, then no data cache lines are written back and
+  invalidated. Address is returned.
+
+  If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
+
+  @param  Address The base address of the data cache lines to write back and
+                  invalidate. If the CPU is in a physical addressing mode, then
+                  Address is a physical address. If the CPU is in a virtual
+                  addressing mode, then Address is a virtual address.
+  @param  Length  The number of bytes to write back and invalidate from the
+                  data cache.
+
+  @return Address of cache invalidation.
+
+**/
+VOID *
+EFIAPI
+WriteBackInvalidateDataCacheRange (
+  IN      VOID                      *Address,
+  IN      UINTN                     Length
+  )
+{
+  ASSERT (Length <= MAX_ADDRESS - (UINTN)Address + 1);
+  return Address;
+}
+
+/**
+  Writes back the entire data cache in cache coherency domain of the calling
+  CPU.
+
+  Writes back the entire data cache in cache coherency domain of the calling
+  CPU. This function guarantees that all dirty cache lines are written back to
+  system memory. This function may also invalidate all the data cache lines in
+  the cache coherency domain of the calling CPU.
+
+**/
+VOID
+EFIAPI
+WriteBackDataCache (
+  VOID
+  )
+{
+}
+
+/**
+  Writes back a range of data cache lines in the cache coherency domain of the
+  calling CPU.
+
+  Writes back the data cache lines specified by Address and Length. If Address
+  is not aligned on a cache line boundary, then entire data cache line
+  containing Address is written back. If Address + Length is not aligned on a
+  cache line boundary, then the entire data cache line containing Address +
+  Length -1 is written back. This function may choose to write back the entire
+  data cache if that is more efficient than writing back the specified range.
+  If Length is 0, then no data cache lines are written back. This function may
+  also invalidate all the data cache lines in the specified range of the cache
+  coherency domain of the calling CPU. Address is returned.
+
+  If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
+
+  @param  Address The base address of the data cache lines to write back. If
+                  the CPU is in a physical addressing mode, then Address is a
+                  physical address. If the CPU is in a virtual addressing
+                  mode, then Address is a virtual address.
+  @param  Length  The number of bytes to write back from the data cache.
+
+  @return Address of cache written in main memory.
+
+**/
+VOID *
+EFIAPI
+WriteBackDataCacheRange (
+  IN      VOID                      *Address,
+  IN      UINTN                     Length
+  )
+{
+  ASSERT (Length <= MAX_ADDRESS - (UINTN)Address + 1);
+  return Address;
+}
+
+/**
+  Invalidates the entire data cache in cache coherency domain of the calling
+  CPU.
+
+  Invalidates the entire data cache in cache coherency domain of the calling
+  CPU. This function must be used with care because dirty cache lines are not
+  written back to system memory. It is typically used for cache diagnostics. If
+  the CPU does not support invalidation of the entire data cache, then a write
+  back and invalidate operation should be performed on the entire data cache.
+
+**/
+VOID
+EFIAPI
+InvalidateDataCache (
+  VOID
+  )
+{
+}
+
+/**
+  Invalidates a range of data cache lines in the cache coherency domain of the
+  calling CPU.
+
+  Invalidates the data cache lines specified by Address and Length. If Address
+  is not aligned on a cache line boundary, then entire data cache line
+  containing Address is invalidated. If Address + Length is not aligned on a
+  cache line boundary, then the entire data cache line containing Address +
+  Length -1 is invalidated. This function must never invalidate any cache lines
+  outside the specified range. If Length is 0, then no data cache lines are
+  invalidated. Address is returned. This function must be used with care
+  because dirty cache lines are not written back to system memory. It is
+  typically used for cache diagnostics. If the CPU does not support
+  invalidation of a data cache range, then a write back and invalidate
+  operation should be performed on the data cache range.
+
+  If Length is greater than (MAX_ADDRESS - Address + 1), then ASSERT().
+
+  @param  Address The base address of the data cache lines to invalidate. If
+                  the CPU is in a physical addressing mode, then Address is a
+                  physical address. If the CPU is in a virtual addressing mode,
+                  then Address is a virtual address.
+  @param  Length  The number of bytes to invalidate from the data cache.
+
+  @return Address.
+
+**/
+VOID *
+EFIAPI
+InvalidateDataCacheRange (
+  IN      VOID                      *Address,
+  IN      UINTN                     Length
+  )
+{
+  ASSERT (Length <= MAX_ADDRESS - (UINTN)Address + 1);
+  return Address;
+}
diff --git a/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.inf b/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.inf
new file mode 100644
index 0000000000..8d6eaaeaa0
--- /dev/null
+++ b/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.inf
@@ -0,0 +1,29 @@
+## @file
+#  Null Cache Maintenance Library implementation.
+#
+#  Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION                    = 0x00010005
+  BASE_NAME                      = BaseCacheMaintenanceLibNull
+  MODULE_UNI_FILE                = BaseCacheMaintenanceLibNull.uni
+  FILE_GUID                      = 13F13249-AC31-4373-8B2B-AFC5755A6FCD
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.1
+  LIBRARY_CLASS                  = CacheMaintenanceLib
+
+#
+#  VALID_ARCHITECTURES           = IA32 X64 EBC ARM AARCH64
+#
+
+[Sources]
+  BaseCacheMaintenanceLibNull.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+
+[LibraryClasses]
+  DebugLib
diff --git a/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.uni b/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.uni
new file mode 100644
index 0000000000..260c756190
--- /dev/null
+++ b/MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.uni
@@ -0,0 +1,12 @@
+// /** @file
+// Null Cache Maintenance Library implementation.
+//
+// Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
+// SPDX-License-Identifier: BSD-2-Clause-Patent
+//
+// **/
+
+#string STR_MODULE_ABSTRACT             #language en-US "Null instance of Cache Maintenance Library"
+
+#string STR_MODULE_DESCRIPTION          #language en-US "Null instance of the Cache Maintenance Library."
+
diff --git a/MdePkg/MdePkg.dsc b/MdePkg/MdePkg.dsc
index 3abe65ec7f..472fa37774 100644
--- a/MdePkg/MdePkg.dsc
+++ b/MdePkg/MdePkg.dsc
@@ -35,6 +35,7 @@ [LibraryClasses]
 [Components]
   MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.inf
   MdePkg/Library/BaseCacheMaintenanceLib/BaseCacheMaintenanceLib.inf
+  MdePkg/Library/BaseCacheMaintenanceLibNull/BaseCacheMaintenanceLibNull.inf
   MdePkg/Library/BaseCpuLib/BaseCpuLib.inf
   MdePkg/Library/BaseCpuLibNull/BaseCpuLibNull.inf
   MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf
-- 
2.21.0.windows.1