[patch V3 01/29] MdePkg: Add RegisterFilterLib class and NULL instance

["Dandan Bi" <dandan.bi@intel.com>]

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

1. Add a new library class (RegisterFilterLib) to filter
and trace port IO/MMIO/MSR access.
2. Add a NULL instance (RegisterFilterLibNull) can be used
to keep current behavior.

Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Zhiguang Liu <zhiguang.liu@intel.com>
Signed-off-by: Dandan Bi <dandan.bi@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
Reviewed-by: Abner Chang <abner.chang@hpe.com>
---
 MdePkg/Include/Library/RegisterFilterLib.h    | 243 ++++++++++++++++
 .../RegisterFilterLibNull.c                   | 271 ++++++++++++++++++
 .../RegisterFilterLibNull.inf                 |  23 ++
 .../RegisterFilterLibNull.uni                 |  13 +
 MdePkg/MdePkg.dec                             |   7 +-
 MdePkg/MdePkg.dsc                             |   4 +-
 6 files changed, 559 insertions(+), 2 deletions(-)
 create mode 100644 MdePkg/Include/Library/RegisterFilterLib.h
 create mode 100644 MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.c
 create mode 100644 MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf
 create mode 100644 MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.uni

diff --git a/MdePkg/Include/Library/RegisterFilterLib.h b/MdePkg/Include/Library/RegisterFilterLib.h
new file mode 100644
index 0000000000..c4402da7d8
--- /dev/null
+++ b/MdePkg/Include/Library/RegisterFilterLib.h
@@ -0,0 +1,243 @@
+/** @file
+  Public include file for the Port IO/MMIO/MSR RegisterFilterLib.
+
+Copyright (c) 2021, Intel Corporation. All rights reserved.<BR>
+
+SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#ifndef REGISTER_FILTER_LIB_H_
+#define REGISTER_FILTER_LIB_H_
+
+typedef enum {
+  FilterWidth8,
+  FilterWidth16,
+  FilterWidth32,
+  FilterWidth64
+} FILTER_IO_WIDTH;
+
+/**
+  Filter IO read operation before read IO port.
+  It is used to filter IO read operation.
+
+  It will return the flag to decide whether require read real IO port.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The destination buffer to store the results.
+
+  @retval TRUE         Need to excute the IO read.
+  @retval FALSE        Skip the IO read.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeIoRead (
+  IN FILTER_IO_WIDTH   Width,
+  IN UINTN             Address,
+  IN OUT VOID          *Buffer
+  );
+
+/**
+  Trace IO read operation after read IO port.
+  It is used to trace IO operation.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The destination buffer to store the results.
+
+**/
+VOID
+EFIAPI
+FilterAfterIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  );
+/**
+  Filter IO Write operation before wirte IO port.
+  It is used to filter IO operation.
+
+  It will return the flag to decide whether require read write IO port.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The source buffer from which to BeforeWrite data.
+
+  @retval TRUE         Need to excute the IO write.
+  @retval FALSE        Skip the IO write.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  );
+
+  /**
+  Trace IO Write operation after wirte IO port.
+  It is used to trace IO operation.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The source buffer from which to BeforeWrite data.
+
+**/
+VOID
+EFIAPI
+FilterAfterIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  );
+
+/**
+  Filter memory IO before Read operation.
+
+  It will return the flag to decide whether require read real MMIO.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The destination buffer to store the results.
+
+  @retval TRUE         Need to excute the MMIO read.
+  @retval FALSE        Skip the MMIO read.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMmIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN OUT VOID         *Buffer
+  );
+
+/**
+  Tracer memory IO after read operation
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The destination buffer to store the results.
+
+**/
+VOID
+EFIAPI
+FilterAfterMmIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  );
+
+/**
+  Filter memory IO before write operation
+
+  It will return the flag to decide whether require wirte real MMIO.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The source buffer from which to BeforeWrite data.
+
+  @retval TRUE         Need to excute the MMIO write.
+  @retval FALSE        Skip the MMIO write.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMmIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  );
+
+/**
+  Tracer memory IO after write operation
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The source buffer from which to BeforeWrite data.
+
+**/
+VOID
+EFIAPI
+FilterAfterMmIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  );
+
+/**
+  Filter MSR before read operation.
+
+  It will return the flag to decide whether require read real MSR.
+  It can be used for emulation environment.
+
+  @param  Index                     The 8-bit Machine Specific Register index to BeforeWrite.
+  @param  Value                     The 64-bit value to BeforeRead from the Machine Specific Register.
+
+  @retval TRUE         Need to excute the MSR read.
+  @retval FALSE        Skip the MSR read.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMsrRead (
+  IN UINT32           Index,
+  IN OUT UINT64       *Value
+  );
+
+/**
+  Trace MSR after read operation
+
+  @param  Index                     The 8-bit Machine Specific Register index to BeforeWrite.
+  @param  Value                     The 64-bit value to BeforeRead from the Machine Specific Register.
+
+**/
+VOID
+EFIAPI
+FilterAfterMsrRead (
+  IN UINT32            Index,
+  IN UINT64            *Value
+  );
+
+/**
+  Filter MSR before write operation
+
+  It will return the flag to decide whether require write real MSR.
+  It can be used for emulation environment.
+
+  @param  Index                     The 8-bit Machine Specific Register index to BeforeWrite.
+  @param  Value                     The 64-bit value to BeforeWrite to the Machine Specific Register.
+
+  @retval TRUE         Need to excute the MSR write.
+  @retval FALSE        Skip the MSR write.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMsrWrite (
+  IN UINT32           Index,
+  IN UINT64           *Value
+  );
+
+/**
+  Trace MSR after write operation
+
+  @param  Index                     The 8-bit Machine Specific Register index to BeforeWrite.
+  @param  Value                     The 64-bit value to BeforeWrite to the Machine Specific Register.
+
+**/
+VOID
+EFIAPI
+FilterAfterMsrWrite (
+  IN UINT32            Index,
+  IN UINT64            *Value
+  );
+
+#endif // REGISTER_FILTER_LIB_H_
diff --git a/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.c b/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.c
new file mode 100644
index 0000000000..7150f1ed5f
--- /dev/null
+++ b/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.c
@@ -0,0 +1,271 @@
+/** @file
+  Null instance of RegisterFilterLib.
+
+  Copyright (c) 2021 Intel Corporation. All rights reserved.<BR>
+
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <Library/RegisterFilterLib.h>
+
+/**
+  Filter IO read operation before read IO port.
+  It is used to filter IO read operation.
+
+  It will return the flag to decide whether require read real IO port.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in,out]   Buffer   The destination buffer to store the results.
+
+  @retval TRUE         Need to excute the IO read.
+  @retval FALSE        Skip the IO read.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN OUT VOID         *Buffer
+  )
+{
+  return TRUE;
+}
+
+/**
+  Trace IO read operation after read IO port.
+  It is used to trace IO operation.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The destination buffer to store the results.
+
+**/
+VOID
+EFIAPI
+FilterAfterIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  )
+{
+  return;
+}
+
+/**
+  Filter IO Write operation before wirte IO port.
+  It is used to filter IO operation.
+
+  It will return the flag to decide whether require read write IO port.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The source buffer from which to write data.
+
+  @retval TRUE         Need to excute the IO write.
+  @retval FALSE        Skip the IO write.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  )
+{
+  return TRUE;
+}
+
+  /**
+  Trace IO Write operation after wirte IO port.
+  It is used to trace IO operation.
+
+  @param[in]       Width    Signifies the width of the I/O operation.
+  @param[in]       Address  The base address of the I/O operation.
+  @param[in]       Buffer   The source buffer from which to Write data.
+
+**/
+VOID
+EFIAPI
+FilterAfterIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  )
+{
+  return;
+}
+
+/**
+  Filter memory IO before Read operation.
+
+  It will return the flag to decide whether require read real MMIO.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in,out]   Buffer   The destination buffer to store the results.
+
+  @retval TRUE         Need to excute the MMIO read.
+  @retval FALSE        Skip the MMIO read.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMmIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN OUT VOID         *Buffer
+  )
+{
+  return TRUE;
+}
+
+/**
+  Tracer memory IO after read operation.
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The destination buffer to store the results.
+
+**/
+VOID
+EFIAPI
+FilterAfterMmIoRead (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  )
+{
+  return;
+}
+
+/**
+  Filter memory IO before write operation.
+
+  It will return the flag to decide whether require wirte real MMIO.
+  It can be used for emulation environment.
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The source buffer from which to write data.
+
+  @retval TRUE         Need to excute the MMIO write.
+  @retval FALSE        Skip the MMIO write.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMmIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  )
+{
+  return TRUE;
+}
+
+/**
+  Tracer memory IO after write operation.
+
+  @param[in]       Width    Signifies the width of the memory I/O operation.
+  @param[in]       Address  The base address of the memory I/O operation.
+  @param[in]       Buffer   The source buffer from which to write data.
+
+**/
+VOID
+EFIAPI
+FilterAfterMmIoWrite (
+  IN FILTER_IO_WIDTH  Width,
+  IN UINTN            Address,
+  IN VOID             *Buffer
+  )
+{
+  return;
+}
+
+/**
+  Filter MSR before read operation.
+
+  It will return the flag to decide whether require read real MSR.
+  It can be used for emulation environment.
+
+  @param  Index                     The Register index of the MSR.
+  @param  Value                     Point to the data will be read from the MSR.
+
+  @retval TRUE         Need to excute the MSR read.
+  @retval FALSE        Skip the MSR read.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMsrRead (
+  IN UINT32        Index,
+  IN OUT UINT64    *Value
+  )
+{
+  return TRUE;
+}
+
+/**
+  Trace MSR after read operation.
+
+  @param  Index                     The Register index of the MSR.
+  @param  Value                     Point to the data has been be read from the MSR.
+
+**/
+VOID
+EFIAPI
+FilterAfterMsrRead (
+  IN UINT32    Index,
+  IN UINT64    *Value
+  )
+{
+  return;
+}
+
+/**
+  Filter MSR before write operation.
+
+  It will return the flag to decide whether require write real MSR.
+  It can be used for emulation environment.
+
+  @param  Index                     The Register index of the MSR.
+  @param  Value                     Point to the data want to be written to the MSR.
+
+  @retval TRUE         Need to excute the MSR write.
+  @retval FALSE        Skip the MSR write.
+
+**/
+BOOLEAN
+EFIAPI
+FilterBeforeMsrWrite (
+  IN UINT32    Index,
+  IN UINT64    *Value
+  )
+{
+  return TRUE;
+}
+
+/**
+  Trace MSR after write operation.
+
+  @param  Index                     The Register index of the MSR.
+  @param  Value                     Point to the data has been be written to the MSR.
+
+**/
+VOID
+EFIAPI
+FilterAfterMsrWrite (
+  IN UINT32    Index,
+  IN UINT64    *Value
+  )
+{
+  return;
+}
+
diff --git a/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf b/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf
new file mode 100644
index 0000000000..a7fc7497ed
--- /dev/null
+++ b/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf
@@ -0,0 +1,23 @@
+## @file
+#  Null instance of RegisterFilterLib.
+#
+#  Copyright (c) 2021, Intel Corporation. All rights reserved.<BR>
+#
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  INF_VERSION                    = 0x00010005
+  BASE_NAME                      = FilterLibNull
+  MODULE_UNI_FILE                = FilterLibNull.uni
+  FILE_GUID                      = 9F555194-A410-4AD6-B3FC-53F6E10FA793
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.0
+  LIBRARY_CLASS                  = RegisterFilterLib
+
+[Sources]
+  RegisterFilterLibNull.c
+
+[Packages]
+  MdePkg/MdePkg.dec
diff --git a/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.uni b/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.uni
new file mode 100644
index 0000000000..ed64c7e63d
--- /dev/null
+++ b/MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.uni
@@ -0,0 +1,13 @@
+// /** @file
+// Null instance of RegisterFilterLib.
+//
+// Copyright (c) 2021, Intel Corporation. All rights reserved.<BR>
+//
+// SPDX-License-Identifier: BSD-2-Clause-Patent
+//
+// **/
+
+
+#string STR_MODULE_ABSTRACT              #language en-US "Null instance of RegisterFilterLib."
+#string STR_MODULE_DESCRIPTION           #language en-US "Null instance of RegisterFilterLib."
+
diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 1d2637acc2..65de5c4052 100644
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -2,11 +2,11 @@
 # This Package provides all definitions, library classes and libraries instances.
 #
 # It also provides the definitions(including PPIs/PROTOCOLs/GUIDs) of
 # EFI1.10/UEFI2.7/PI1.7 and some Industry Standards.
 #
-# Copyright (c) 2007 - 2020, Intel Corporation. All rights reserved.<BR>
+# Copyright (c) 2007 - 2021, Intel Corporation. All rights reserved.<BR>
 # Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
 # (C) Copyright 2016 - 2020 Hewlett Packard Enterprise Development LP<BR>
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 #
@@ -260,10 +260,15 @@ [LibraryClasses]
   ##  @libraryclass  This library provides an interface to request non-MMRAM pages to be mapped
   #                  or unblocked from inside MM environment.
   #
   MmUnblockMemoryLib|Include/Library/MmUnblockMemoryLib.h
 
+  ##  @libraryclass  This library provides interfances to filter and trace port IO/MMIO/MSR access.
+  #
+  #
+  RegisterFilterLib|Include/Library/RegisterFilterLib.h
+
 [LibraryClasses.IA32, LibraryClasses.X64]
   ##  @libraryclass  Abstracts both S/W SMI generation and detection.
   ##
   SmmLib|Include/Library/SmmLib.h
 
diff --git a/MdePkg/MdePkg.dsc b/MdePkg/MdePkg.dsc
index 79629e3f93..be89e28eef 100644
--- a/MdePkg/MdePkg.dsc
+++ b/MdePkg/MdePkg.dsc
@@ -1,9 +1,9 @@
 ## @file
 # EFI/PI MdePkg Package
 #
-# Copyright (c) 2007 - 2020, Intel Corporation. All rights reserved.<BR>
+# Copyright (c) 2007 - 2021, Intel Corporation. All rights reserved.<BR>
 # Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
 # (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
 #
 #    SPDX-License-Identifier: BSD-2-Clause-Patent
 #
@@ -125,10 +125,12 @@ [Components]
   MdePkg/Library/BaseExtractGuidedSectionLib/BaseExtractGuidedSectionLib.inf
 
   MdePkg/Library/StandaloneMmDriverEntryPoint/StandaloneMmDriverEntryPoint.inf
   MdePkg/Library/StandaloneMmServicesTableLib/StandaloneMmServicesTableLib.inf
 
+  MdePkg/Library/RegisterFilterLibNull/RegisterFilterLibNull.inf
+
 [Components.IA32, Components.X64, Components.ARM, Components.AARCH64]
   #
   # Add UEFI Target Based Unit Tests
   #
   MdePkg/Test/UnitTest/Library/BaseLib/BaseLibUnitTestsUefi.inf
-- 
2.18.0.windows.1