Re: [edk2-devel] [patch V2 01/29] MdePkg: Add RegisterFilterLib class and NULL instance

["Abner Chang" <abner.chang@hpe.com>]

Reviewed-by: Abner Chang <abner.chang@hpe.com>

Thanks for adding description of return values.


> -----Original Message-----
> From: devel@edk2.groups.io [mailto:devel@edk2.groups.io] On Behalf Of
> Dandan Bi
> Sent: Monday, March 22, 2021 4:09 PM
> To: devel@edk2.groups.io
> Cc: Michael D Kinney <michael.d.kinney@intel.com>; Liming Gao
> <gaoliming@byosoft.com.cn>; Zhiguang Liu <zhiguang.liu@intel.com>
> Subject: [edk2-devel] [patch V2 01/29] MdePkg: Add RegisterFilterLib class
> and NULL instance
> 
> REF: INVALID URI REMOVED
> 3A__bugzilla.tianocore.org_show-5Fbug.cgi-3Fid-
> 3D3246&d=DwIBAg&c=C5b8zRQO1miGmBeVZ2LFWg&r=_SN6FZBN4Vgi4Ulks
> kz6qU3NYRO03nHp9P7Z5q59A3E&m=0EinCfro8QrVJOUHqC9SQrGFKTLw_fpn
> ApwpgZrJTFI&s=fInsRu_7K_UxMpaoSvL_C5dtlLIZ8c8g12wuPvHoi-4&e=
> 
> 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>
> ---
>  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/StandaloneMmDriverEntry
> Point.inf
> 
> MdePkg/Library/StandaloneMmServicesTableLib/StandaloneMmServicesTab
> leLib.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
> 
> 
> 
> 
>