[PATCH v4 2/8] Ovmf/HardwareInfoLib: Create Pei lib to parse directly from fw-cfg

["Ojeda Leon, Nicolas" <ncoleon@amazon.com>]

Define the HardwareInfoLib API and create the PeiHardwareInfoLib
which implements it, specifically for Pei usage, supporting
only static accesses to parse data directly from a fw-cfg file.
All list-like APIs are implemented as unsupported and only a
fw-cfg wrapper to read hardware info elements is provided.

The Hardware Info library is intended to describe non-discoverable
hardware information and share that from the host to the guest in Ovmf
platforms. The QEMU fw-cfg extension for this library provides a first
variation to parse hardware info by reading it directly from a fw-cfg
file. This library offers a wrapper function to the plain
QmeuFwCfgReadBytes which, specifically, parses header-data pairs out
of the binary values in the file. For this purpose, the approach is
incremental, reading the file block by block and outputting the values
only for a specific known hardware type (e.g. PCI host bridges). One
element is returned in each call until the end of the file is reached.

Considering fw-cfg as the first means to transport hardware info from
the host to the guest, this wrapping library offers the possibility
to statically, and in steps, read a specific type of hardware info
elements out of the file. This method reads one hardware element of a
specific type at a time, without the need to pre-allocate memory and
read the whole file or dynamically allocate memory for each new
element found.

As a usage example, the static approach followed by this library
enables early UEFI stages to use and read hardware information
supplied by the host. For instance, in early times of the PEI stage,
hardware information can be parsed out from a fw-cfg file prescinding
from memory services, that may not yet be available, and avoiding
dynamic memory allocations.

Cc: Alexander Graf <graf@amazon.de>
Cc: Gerd Hoffmann <kraxel@redhat.com>
Acked-by: Gerd Hoffmann <kraxel@redhat.com>
Signed-off-by: Nicolas Ojeda Leon <ncoleon@amazon.com>
---
 OvmfPkg/Include/Library/HardwareInfoLib.h     | 165 ++++++++++++++++++
 .../Library/HardwareInfoLib/HardwareInfoPei.c |  85 +++++++++
 .../HardwareInfoLib/PeiHardwareInfoLib.inf    |  43 +++++
 .../QemuFwCfgHardwareInfoLib.c                |  89 ++++++++++
 OvmfPkg/OvmfPkgX64.dsc                        |   1 +
 5 files changed, 383 insertions(+)
 create mode 100644 OvmfPkg/Include/Library/HardwareInfoLib.h
 create mode 100644 OvmfPkg/Library/HardwareInfoLib/HardwareInfoPei.c
 create mode 100644 OvmfPkg/Library/HardwareInfoLib/PeiHardwareInfoLib.inf
 create mode 100644 OvmfPkg/Library/HardwareInfoLib/QemuFwCfgHardwareInfoLib.c

diff --git a/OvmfPkg/Include/Library/HardwareInfoLib.h b/OvmfPkg/Include/Library/HardwareInfoLib.h
new file mode 100644
index 0000000000..9a8149bf20
--- /dev/null
+++ b/OvmfPkg/Include/Library/HardwareInfoLib.h
@@ -0,0 +1,165 @@
+/*/@file
+  Hardware info parsing functions.
+  Binary data is expected as a consecutive series of header - object pairs.
+  Complete library providing static Qemu fw-cfg wrappers as well as list-like
+  interface to dynamically manipulate hardware info objects and parsing from
+  a generic blob.
+
+  Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+**/
+
+#ifndef __HARDWARE_INFO_LIB_H__
+#define __HARDWARE_INFO_LIB_H__
+
+#include "../Library/HardwareInfoLib/HardwareInfoTypesLib.h"
+
+/**
+  Read, if available, the next Type element in the FwCfg file.
+  The FwCfg item must already be selected, this is a wrapper around
+  QemuFwCfgReadBytes and the Data pointer should be set to an existent
+  memory location with TypeSize bytes allocated for the date to be
+  properly written. If a Type element is found in the file which has a
+  size (in the header) greater than TypeSize, it is skipped.
+
+  @param[in]    Type             Hardware Info Type to search for
+  @param[in]    TypeSize         Size (in bytes) of the structure intended to
+                                 be used to dereference the data
+  @param[in]    TotalFileSize    Total size (in bytes) of the FwCfg file from
+                                 which the data is read.
+  @param[out]   Data             Pointer to a memory allocated instance into
+                                 which the data is written to.
+  @param[out]   DataSize         Size in bytes of the actually filled
+                                 data available in the Data object after a
+                                 successful operation
+  @param[inout] ReadIndex        Index of the next byte to be read. Incremented
+                                 accordingly after a read operation to reflect
+                                 up to date status
+
+  @retval EFI_SUCCESS             Next element found and read into Data
+  @retval EFI_INVALID_PARAMETER   Operation failed
+  @retval EFI_END_OF_FILE         End of the file reached, no more elements
+                                  to read.
+**/
+EFI_STATUS
+QemuFwCfgReadNextHardwareInfoByType (
+  IN      HARDWARE_INFO_TYPE  Type,
+  IN      UINTN               TypeSize,
+  IN      UINTN               TotalFileSize,
+  OUT     VOID                *Data,
+  OUT     UINTN               *DataSize         OPTIONAL,
+  IN OUT  UINTN               *ReadIndex
+  );
+
+/**
+  Parse binary data containing resource information of multiple hardware
+  elements into a list of interpreted resources.
+  The translation is done on a copy-parse base so the blob can be freed
+  afterwards.
+
+  @param[in]  Blob           Binary data to be parsed
+  @param[in]  BlobSize       Size (in bytes) of the binary data
+  @param[in]  TypeFilter     Optional type to filter entries. Set to
+                             undefined to disable filtering and retrieve all
+  @param[out] ListHead       Head of the list to populate hardware information
+
+  @retval EFI_SUCCESS            Succeed.
+  @retval EFI_INVALID_PARAMETER  Provided Blob inforation is invalid
+  @retval EFI_OUT_OF_RESOURCES   Out of memory, list populated as far as
+                                 possible
+**/
+EFI_STATUS
+CreateHardwareInfoList (
+  IN  UINT8               *Blob,
+  IN  UINTN               BlobSize,
+  IN  HARDWARE_INFO_TYPE  TypeFilter,
+  OUT LIST_ENTRY          *ListHead
+  );
+
+/**
+  Free the dynamically allocated list of HADWARE_INFO items populated
+  during parsing of Blob
+
+  @param ListHead         Head of the list to be destroyed
+**/
+VOID
+FreeHardwareInfoList (
+  IN OUT  LIST_ENTRY  *ListHead
+  );
+
+/**
+  Retrieve the number of hardware components of a specific type
+  in the list.
+
+  @param[in]  ListHead       Head of the hardware info list
+  @param[in]  Type           Type of hardware elements to count
+  @param[in]  TypeSize       Size (in bytes) of the structure intended to
+                             be used to dereference the data
+  @return Count of elements of Type found
+**/
+UINTN
+GetHardwareInfoCountByType (
+  IN  LIST_ENTRY          *ListHead,
+  IN  HARDWARE_INFO_TYPE  Type,
+  IN  UINTN               TypeSize
+  );
+
+/**
+  Get the First Hardware Info entry in the list of the specified type
+
+  @param[in]  ListHead     Head of the hardware info list
+  @param[in]  Type         Hardware Info Type to search for
+  @param[in]  TypeSize     Size (in bytes) of the structure intended to
+                           be used to dereference the data
+  @return Link of first entry of specified type or list head if not found
+**/
+LIST_ENTRY *
+GetFirstHardwareInfoByType (
+  IN  LIST_ENTRY          *ListHead,
+  IN  HARDWARE_INFO_TYPE  Type,
+  IN  UINTN               TypeSize
+  );
+
+/**
+  Get the Next Hardware Info entry in the list with the specified
+  type, which follows the provided Node.
+
+  @param[in]  ListHead       Head of the hardware info list
+  @param[in]  Node           Current, already processed, node's link
+  @param[in]  Type           Hardware Info Type to search for
+  @param[in]  TypeSize       Size (in bytes) of the structure intended to
+                             be used to dereference the data
+  @return Link of next entry, after Node, of the specified type.
+          List head otherwise
+**/
+LIST_ENTRY *
+GetNextHardwareInfoByType (
+  IN  LIST_ENTRY          *ListHead,
+  IN  LIST_ENTRY          *Node,
+  IN  HARDWARE_INFO_TYPE  Type,
+  IN  UINTN               TypeSize
+  );
+
+/**
+  Assess if Node stands at the end of the doubly linked list
+
+  @param[in]  ListHead      Head of the hardware info list
+  @param[in]  Node          Current Node link
+
+  @retval TRUE  Node is at the end of the list
+  @retval FALSE Node is not at the end of the list
+**/
+BOOLEAN
+EndOfHardwareInfoList (
+  IN  LIST_ENTRY  *ListHead,
+  IN  LIST_ENTRY  *Node
+  );
+
+#endif // __HARDWARE_INFO_LIB_H__
diff --git a/OvmfPkg/Library/HardwareInfoLib/HardwareInfoPei.c b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoPei.c
new file mode 100644
index 0000000000..40d27f69ad
--- /dev/null
+++ b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoPei.c
@@ -0,0 +1,85 @@
+/*/@file
+  Hardware info parsing functions.
+  Binary data is expected as a consecutive series of header - object pairs.
+  Provides static Qemu fw-cfg wrappers as well as list-like interface to
+  dynamically manipulate hardware info objects and parsing from a generic
+  blob.
+
+  Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+**/
+
+#include <Library/DebugLib.h>
+
+#include <Library/HardwareInfoLib.h>
+
+EFI_STATUS
+CreateHardwareInfoList (
+  IN  UINT8               *Blob,
+  IN  UINTN               BlobSize,
+  IN  HARDWARE_INFO_TYPE  TypeFilter,
+  OUT LIST_ENTRY          *ListHead
+  )
+{
+  ASSERT (FALSE);
+  return EFI_UNSUPPORTED;
+}
+
+VOID
+FreeHardwareInfoList (
+  IN OUT  LIST_ENTRY  *ListHead
+  )
+{
+  ASSERT (FALSE);
+}
+
+UINTN
+GetHardwareInfoCountByType (
+  IN  LIST_ENTRY          *ListHead,
+  IN  HARDWARE_INFO_TYPE  Type,
+  IN  UINTN               TypeSize
+  )
+{
+  ASSERT (FALSE);
+  return 0;
+}
+
+LIST_ENTRY *
+GetFirstHardwareInfoByType (
+  IN  LIST_ENTRY          *ListHead,
+  IN  HARDWARE_INFO_TYPE  Type,
+  IN  UINTN               TypeSize
+  )
+{
+  ASSERT (FALSE);
+  return ListHead;
+}
+
+LIST_ENTRY *
+GetNextHardwareInfoByType (
+  IN  LIST_ENTRY          *ListHead,
+  IN  LIST_ENTRY          *Node,
+  IN  HARDWARE_INFO_TYPE  Type,
+  IN  UINTN               TypeSize
+  )
+{
+  ASSERT (FALSE);
+  return ListHead;
+}
+
+BOOLEAN
+EndOfHardwareInfoList (
+  IN  LIST_ENTRY  *ListHead,
+  IN  LIST_ENTRY  *Node
+  )
+{
+  ASSERT (FALSE);
+  return TRUE;
+}
diff --git a/OvmfPkg/Library/HardwareInfoLib/PeiHardwareInfoLib.inf b/OvmfPkg/Library/HardwareInfoLib/PeiHardwareInfoLib.inf
new file mode 100644
index 0000000000..540c0d0a8d
--- /dev/null
+++ b/OvmfPkg/Library/HardwareInfoLib/PeiHardwareInfoLib.inf
@@ -0,0 +1,43 @@
+## @file
+#  Hardware information library wrappers over Qemu fw-cfg functionality to parse,
+#  in a static manner, non-discoverable hardware information.
+#
+#  Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+#  This program and the accompanying materials
+#  are licensed and made available under the terms and conditions of the BSD License
+#  which accompanies this distribution.  The full text of the license may be found at
+#  http://opensource.org/licenses/bsd-license.php
+#  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+#
+##
+
+[Defines]
+  INF_VERSION                    = 0x00010005
+  BASE_NAME                      = PeiHardwareInfoLib
+  FILE_GUID                      = 3D5011B3-9CBB-4C0B-88E8-1D758283C659
+  MODULE_TYPE                    = BASE
+  VERSION_STRING                 = 1.0
+  LIBRARY_CLASS                  = PeiHardwareInfoLib
+
+#
+# The following information is for reference only and not required by the build
+# tools.
+#
+#  VALID_ARCHITECTURES           = X64
+#
+
+[Sources]
+  HardwareInfoPei.c
+  QemuFwCfgHardwareInfoLib.c
+  HardwareInfoPciHostBridgeLib.c
+
+[Packages]
+  MdeModulePkg/MdeModulePkg.dec
+  MdePkg/MdePkg.dec
+  OvmfPkg/OvmfPkg.dec
+
+[LibraryClasses]
+  DebugLib
+  QemuFwCfgLib
diff --git a/OvmfPkg/Library/HardwareInfoLib/QemuFwCfgHardwareInfoLib.c b/OvmfPkg/Library/HardwareInfoLib/QemuFwCfgHardwareInfoLib.c
new file mode 100644
index 0000000000..31ffff290a
--- /dev/null
+++ b/OvmfPkg/Library/HardwareInfoLib/QemuFwCfgHardwareInfoLib.c
@@ -0,0 +1,89 @@
+/*/@file
+  Qemu fw-cfg wrappers for hardware info parsing.
+  Provides an alternative to parse hardware information from a fw-cfg
+  file without relying on dynamic memory allocations.
+
+  Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+  This program and the accompanying materials
+  are licensed and made available under the terms and conditions of the BSD License
+  which accompanies this distribution.  The full text of the license may be found at
+  http://opensource.org/licenses/bsd-license.php
+
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+**/
+
+#include <Library/DebugLib.h>
+#include <Library/QemuFwCfgLib.h>
+
+#include <Library/HardwareInfoLib.h>
+
+/**
+  Update an optional pointer value if possible
+
+  @param[out] DataSize     Pointer to variable to be updated
+  @param[in]  Value        Value to set the pointed variable to.
+**/
+STATIC
+VOID
+UpdateDataSize (
+  OUT UINTN  *DataSize,
+  IN  UINTN  Value
+  )
+{
+  if (DataSize == NULL) {
+    return;
+  }
+
+  *DataSize = Value;
+}
+
+EFI_STATUS
+QemuFwCfgReadNextHardwareInfoByType (
+  IN      HARDWARE_INFO_TYPE  Type,
+  IN      UINTN               TypeSize,
+  IN      UINTN               TotalFileSize,
+  OUT     VOID                *Data,
+  OUT     UINTN               *DataSize         OPTIONAL,
+  IN OUT  UINTN               *ReadIndex
+  )
+{
+  HARDWARE_INFO_HEADER  Header;
+
+  if ((Data == NULL) ||
+      (ReadIndex == NULL) ||
+      (TypeSize == 0) ||
+      (Type == HardwareInfoTypeUndefined) ||
+      (TotalFileSize == 0))
+  {
+    return EFI_INVALID_PARAMETER;
+  }
+
+  UpdateDataSize (DataSize, 0);
+
+  while (*ReadIndex < TotalFileSize) {
+    QemuFwCfgReadBytes (sizeof (Header), &Header);
+    *ReadIndex += sizeof (Header);
+
+    if ((Header.Type.Value == Type) && (Header.Size <= TypeSize)) {
+      QemuFwCfgReadBytes (Header.Size, Data);
+
+      *ReadIndex += Header.Size;
+      UpdateDataSize (DataSize, Header.Size);
+
+      return EFI_SUCCESS;
+    }
+
+    //
+    // Skip the bytes corresponding to the next element as it is
+    // not of the expected type and/or size. The TotalFileSize
+    // and individual elements sizes should match so the size
+    // check is skipped.
+    //
+    QemuFwCfgSkipBytes (Header.Size);
+    *ReadIndex += Header.Size;
+  }
+
+  return EFI_END_OF_FILE;
+}
diff --git a/OvmfPkg/OvmfPkgX64.dsc b/OvmfPkg/OvmfPkgX64.dsc
index 4589adff38..7a36f62e9f 100644
--- a/OvmfPkg/OvmfPkgX64.dsc
+++ b/OvmfPkg/OvmfPkgX64.dsc
@@ -180,6 +180,7 @@
   VirtioLib|OvmfPkg/Library/VirtioLib/VirtioLib.inf
   LoadLinuxLib|OvmfPkg/Library/LoadLinuxLib/LoadLinuxLib.inf
   MemEncryptSevLib|OvmfPkg/Library/BaseMemEncryptSevLib/DxeMemEncryptSevLib.inf
+  PeiHardwareInfoLib|OvmfPkg/Library/HardwareInfoLib/PeiHardwareInfoLib.inf
 !if $(SMM_REQUIRE) == FALSE
   LockBoxLib|OvmfPkg/Library/LockBoxLib/LockBoxBaseLib.inf
 !endif
-- 
2.17.1




Amazon Development Center Germany GmbH
Krausenstr. 38
10117 Berlin
Geschaeftsfuehrung: Christian Schlaeger, Jonathan Weiss
Eingetragen am Amtsgericht Charlottenburg unter HRB 149173 B
Sitz: Berlin
Ust-ID: DE 289 237 879