DynamicTablesPkg: Add FdtHwInfoParser library

Hardware information parser is an optional module defined
by the Dynamic Tables Framework. It can either parse an
XML, a Device Tree or a Json file containing the platform
hardware information to populate the platform information
repository.

FdtHwInfoParser library is an instance of a HwInfoParser
that parses a Device Tree and populates the Configuration
Manager Platform information repository.

FdtHwInfoParser library is aimed at providing a solution
for generating ACPI tables for Guest Partitions launched
by virtual machine managers (VMMs). One such use case is
Kvmtool where the Device Tree for the Guest is passed on
to the firmware by Kvmtool. The Configuration Manager for
Kvmtool firmware shall invoke the FdtHwInfoParser to parse
the Device Tree to populate the hardware information in
the Platform Info Repository. The Kvmtool Configuration
Manager can the process this information to generate the
required ACPI tables for the Guest VM.

This approach also scales well if the number of CPUs or
if the hardware configuration of the Guest partition is
varied.

FdtHwInfoParser thereby introduces 'Dynamic Tables for
Virtual Machines'.

Ref:https://bugzilla.tianocore.org/show_bug.cgi?id=3741
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>

DynamicTablesPkg/DynamicTablesPkg.dsc

@@ -2,7 +2,7 @@
 #  Dsc file for Dynamic Tables Framework.
 #
 #  Copyright (c) 2019, Linaro Limited. All rights reserved.<BR>
-#  Copyright (c) 2019 - 2020, Arm Limited. All rights reserved.<BR>
+#  Copyright (c) 2019 - 2021, Arm Limited. All rights reserved.<BR>
 #
 #  SPDX-License-Identifier: BSD-2-Clause-Patent
 #
@@ -43,6 +43,7 @@
   DynamicTablesPkg/Library/Common/AmlLib/AmlLib.inf
   DynamicTablesPkg/Library/Common/SsdtSerialPortFixupLib/SsdtSerialPortFixupLib.inf
   DynamicTablesPkg/Library/Common/TableHelperLib/TableHelperLib.inf
+  DynamicTablesPkg/Library/FdtHwInfoParserLib/FdtHwInfoParserLib.inf
 
 [BuildOptions]
   *_*_*_CC_FLAGS = -D DISABLE_NEW_DEPRECATED_INTERFACES

DynamicTablesPkg/Library/FdtHwInfoParserLib/FdtHwInfoParser.c

@@ -0,0 +1,192 @@
+/** @file
+  Flattened Device Tree parser library for KvmTool.
+
+  Copyright (c) 2021, ARM Limited. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#include "FdtHwInfoParser.h"
+#include "BootArch/ArmBootArchParser.h"
+#include "GenericTimer/ArmGenericTimerParser.h"
+#include "Gic/ArmGicDispatcher.h"
+#include "Pci/ArmPciConfigSpaceParser.h"
+#include "Serial/ArmSerialPortParser.h"
+
+/** Ordered table of parsers/dispatchers.
+
+  A parser parses a Device Tree to populate a specific CmObj type. None,
+  one or many CmObj can be created by the parser.
+  The created CmObj are then handed to the parser's caller through the
+  HW_INFO_ADD_OBJECT interface.
+  This can also be a dispatcher. I.e. a function that not parsing a
+  Device Tree but calling other parsers.
+*/
+STATIC CONST FDT_HW_INFO_PARSER_FUNC  HwInfoParserTable[] = {
+  ArmBootArchInfoParser,
+  ArmGenericTimerInfoParser,
+  ArmGicDispatcher,
+  ArmPciConfigInfoParser,
+  SerialPortDispatcher
+};
+
+/** Main dispatcher: sequentially call the parsers/dispatchers
+    of the HwInfoParserTable.
+
+  A parser parses a Device Tree to populate a specific CmObj type. None,
+  one or many CmObj can be created by the parser.
+  The created CmObj are then handed to the parser's caller through the
+  HW_INFO_ADD_OBJECT interface.
+  This can also be a dispatcher. I.e. a function that not parsing a
+  Device Tree but calling other parsers.
+
+  @param [in]  FdtParserHandle A handle to the parser instance.
+  @param [in]  FdtBranch       When searching for DT node name, restrict
+                               the search to this Device Tree branch.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_ABORTED             An error occurred.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_NOT_FOUND           Not found.
+  @retval EFI_UNSUPPORTED         Unsupported.
+**/
+STATIC
+EFI_STATUS
+EFIAPI
+MainDispatcher (
+  IN  CONST FDT_HW_INFO_PARSER_HANDLE  FdtParserHandle,
+  IN        INT32                      FdtBranch
+  )
+{
+  EFI_STATUS  Status;
+  UINT32      Index;
+
+  if (fdt_check_header (FdtParserHandle->Fdt) < 0) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  for (Index = 0; Index < ARRAY_SIZE (HwInfoParserTable); Index++) {
+    Status = HwInfoParserTable[Index](
+                                      FdtParserHandle,
+                                      FdtBranch
+                                      );
+    if (EFI_ERROR (Status)  &&
+        (Status != EFI_NOT_FOUND))
+    {
+      // If EFI_NOT_FOUND, the parser didn't find information in the DT.
+      // Don't trigger an error.
+      ASSERT (0);
+      return Status;
+    }
+  } // for
+
+  return EFI_SUCCESS;
+}
+
+/** Initialise the HwInfoParser.
+
+  The HwInfoParser shall use the information provided by the HwDataSource
+  to initialise the internal state of the parser or to index the data. This
+  internal state shall be linked to the ParserHandle using an implementation
+  defined mechanism.
+
+  @param [in]   HwDataSource    Pointer to the blob containing the hardware
+                                information. It can be a pointer to a Device
+                                Tree, an XML file, etc. or any other data
+                                structure defined by the HwInfoParser.
+  @param [in]   Context         A pointer to the caller's context.
+  @param [in]   HwInfoAdd       Function pointer called by the parser when
+                                adding information.
+  @param [out]  ParserHandle    A handle to the parser instance.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+HwInfoParserInit (
+  IN    VOID                   *HwDataSource,
+  IN    VOID                   *Context,
+  IN    HW_INFO_ADD_OBJECT     HwInfoAdd,
+  OUT   HW_INFO_PARSER_HANDLE  *ParserHandle
+  )
+{
+  FDT_HW_INFO_PARSER  *FdtParserHandle;
+
+  if ((ParserHandle == NULL)  ||
+      (HwInfoAdd == NULL)     ||
+      (HwDataSource == NULL)  ||
+      (fdt_check_header (HwDataSource) < 0))
+  {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  FdtParserHandle = AllocateZeroPool (sizeof (FDT_HW_INFO_PARSER));
+  if (FdtParserHandle == NULL) {
+    *ParserHandle = NULL;
+    return EFI_OUT_OF_RESOURCES;
+  }
+
+  // The HwDataSource is a pointer to the FDT data.
+  FdtParserHandle->Fdt       = HwDataSource;
+  FdtParserHandle->Context   = Context;
+  FdtParserHandle->HwInfoAdd = HwInfoAdd;
+
+  *ParserHandle = (HW_INFO_PARSER_HANDLE)FdtParserHandle;
+  return EFI_SUCCESS;
+}
+
+/** Parse the data provided by the HwDataSource.
+
+  @param [in]  ParserHandle    A handle to the parser instance.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_OUT_OF_RESOURCES    An allocation has failed.
+**/
+EFI_STATUS
+EFIAPI
+HwInfoParse (
+  IN  HW_INFO_PARSER_HANDLE  ParserHandle
+  )
+{
+  EFI_STATUS  Status;
+
+  if (ParserHandle == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  // Call all the parsers from the root node (-1).
+  Status = MainDispatcher (
+             (FDT_HW_INFO_PARSER_HANDLE)ParserHandle,
+             -1
+             );
+  ASSERT_EFI_ERROR (Status);
+  return Status;
+}
+
+/** Cleanup any internal state and resources that were allocated
+    by the the HwInfoParser.
+
+  @param [in]  ParserHandle    A handle to the parser instance.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+**/
+EFI_STATUS
+EFIAPI
+HwInfoParserShutdown (
+  IN  HW_INFO_PARSER_HANDLE  ParserHandle
+  )
+{
+  if (ParserHandle == NULL) {
+    ASSERT (0);
+    return EFI_INVALID_PARAMETER;
+  }
+
+  FreePool (ParserHandle);
+
+  return EFI_SUCCESS;
+}

DynamicTablesPkg/Library/FdtHwInfoParserLib/FdtHwInfoParser.h

@@ -0,0 +1,63 @@
+/** @file
+  Flattened Device Tree parser definitions.
+
+  Copyright (c) 2021, ARM Limited. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef FDT_HW_INFO_PARSER_H_
+#define FDT_HW_INFO_PARSER_H_
+
+#include <FdtHwInfoParserInclude.h>
+
+#include <ConfigurationManagerObject.h>
+#include <Library/HwInfoParserLib.h>
+
+#include "FdtUtility.h"
+
+/** A structure describing the instance of the FdtHwInfoParser.
+*/
+typedef struct FdtHwInfoParser {
+  /// Pointer to the HwDataSource i.e. the
+  /// Flattened Device Tree (Fdt).
+  VOID                  *Fdt;
+
+  /// Pointer to the caller's context.
+  VOID                  *Context;
+
+  /// Function pointer called by the
+  /// parser when adding information.
+  HW_INFO_ADD_OBJECT    HwInfoAdd;
+} FDT_HW_INFO_PARSER;
+
+/** A pointer type for FDT_HW_INFO_PARSER.
+*/
+typedef FDT_HW_INFO_PARSER *FDT_HW_INFO_PARSER_HANDLE;
+
+/** Function pointer to a parser function.
+
+  A parser parses a Device Tree to populate a specific CmObj type. None,
+  one or many CmObj can be created by the parser.
+  The created CmObj are then handed to the parser's caller through the
+  HW_INFO_ADD_OBJECT interface.
+  This can also be a dispatcher. I.e. a function that not parsing a
+  Device Tree but calling other parsers.
+
+  @param [in]  ParserHandle    Handle to the parser instance.
+  @param [in]  FdtBranch       When searching for DT node name, restrict
+                               the search to this Device Tree branch.
+
+  @retval EFI_SUCCESS             The function completed successfully.
+  @retval EFI_ABORTED             An error occurred.
+  @retval EFI_INVALID_PARAMETER   Invalid parameter.
+  @retval EFI_NOT_FOUND           Not found.
+  @retval EFI_UNSUPPORTED         Unsupported.
+**/
+typedef
+EFI_STATUS
+(EFIAPI *FDT_HW_INFO_PARSER_FUNC)(
+  IN  CONST FDT_HW_INFO_PARSER_HANDLE ParserHandle,
+  IN        INT32                     FdtBranch
+  );
+
+#endif // FDT_HW_INFO_PARSER_H_

DynamicTablesPkg/Library/FdtHwInfoParserLib/FdtHwInfoParserInclude.h

@@ -0,0 +1,17 @@
+/** @file
+  Include file for Fdt HwInfoParser.
+
+  Copyright (c) 2021, ARM Limited. All rights reserved.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+**/
+
+#ifndef FDT_HW_INFO_PARSER_INCLUDE_H_
+#define FDT_HW_INFO_PARSER_INCLUDE_H_
+
+#include <Base.h>
+#include <libfdt.h>
+#include <Library/ArmLib.h>
+#include <Library/DebugLib.h>
+#include <Library/MemoryAllocationLib.h>
+
+#endif // FDT_HW_INFO_PARSER_INCLUDE_H_

DynamicTablesPkg/Library/FdtHwInfoParserLib/FdtHwInfoParserLib.inf

@@ -0,0 +1,56 @@
+## @file
+#  Flattened Device Tree information parser.
+#
+#  Copyright (c) 2021, ARM Limited. All rights reserved.
+#
+#  SPDX-License-Identifier: BSD-2-Clause-Patent
+##
+
+[Defines]
+  INF_VERSION    = 0x00010019
+  BASE_NAME      = FdtHwInfoParserLib
+  FILE_GUID      = F174A422-BC86-41E2-9E9C-C6D6E437F4AD
+  VERSION_STRING = 1.0
+  MODULE_TYPE    = DXE_DRIVER
+  LIBRARY_CLASS  = HwInfoParserLib
+
+[Sources]
+  CmObjectDescUtility.c
+  CmObjectDescUtility.h
+  FdtHwInfoParserInclude.h
+  FdtHwInfoParser.c
+  FdtHwInfoParser.h
+  FdtUtility.c
+  FdtUtility.h
+  BootArch/ArmBootArchParser.c
+  BootArch/ArmBootArchParser.h
+  GenericTimer/ArmGenericTimerParser.c
+  GenericTimer/ArmGenericTimerParser.h
+  Gic/ArmGicCParser.c
+  Gic/ArmGicCParser.h
+  Gic/ArmGicDispatcher.c
+  Gic/ArmGicDispatcher.h
+  Gic/ArmGicDParser.c
+  Gic/ArmGicDParser.h
+  Gic/ArmGicItsParser.c
+  Gic/ArmGicItsParser.h
+  Gic/ArmGicMsiFrameParser.c
+  Gic/ArmGicMsiFrameParser.h
+  Gic/ArmGicRParser.c
+  Gic/ArmGicRParser.h
+  Pci/ArmPciConfigSpaceParser.c
+  Pci/ArmPciConfigSpaceParser.h
+  Serial/ArmSerialPortParser.c
+  Serial/ArmSerialPortParser.h
+
+[Packages]
+  ArmPkg/ArmPkg.dec
+  DynamicTablesPkg/DynamicTablesPkg.dec
+  EmbeddedPkg/EmbeddedPkg.dec
+  MdeModulePkg/MdeModulePkg.dec
+  MdePkg/MdePkg.dec
+
+[LibraryClasses]
+  DebugLib
+  FdtLib
+  MemoryAllocationLib