[PATCH v2 3/8] Ovmf/HardwareInfoLib: Add core to parse heterogenous data


Ojeda Leon, Nicolas
 

Following the Hardware Info library, this commit extends the base lib
and the static parsing methods to the generic, and thus the core of
the library, approach, capable of parsing heterogeneous hardware
information. The list-like API grants callers a flexible and common
pattern to retrieve the data. Moreover, the initial source is a BLOB
which generalizes the host-to-guest transmission mechanism.

The Hardware Info library main objective is to provide a way to
describe non-discoverable hardware so that the host can share the
available resources with the guest in Ovmf platforms. This change
features and embraces the main idea behind the library by providing
an API that parses a BLOB into a linked list to retrieve hardware
data from any source. Additionally, list-like APIs are provided so
that the hardware info list can be traversed conveniently.
Similarly, the capability is provided to filter results by specific
hardware types. However, heterogeneous elements can be added to the
list, increasing the flexibility. This way, a single source, for
example a fw-cfg file, can be used to describe several instances of
multiple types of hardware.

This part of the Hardware Info library makes use of dynamic memory
and is intended for stages in which memory services are available.
A motivation example is the PciHostBridgeLib. This library, part
of the PCI driver populates the list of PCI root bridges during DXE
stage for future steps to discover the resources under them. The
hardware info library can be used to obtain the detailed description
of available host bridges, for instance in the form of a fw-cfg file,
and parse that information into a dynmaic list that allows, first to
verify consistency of the data, and second discover the resources
availabe for each root bridge.

Cc: Alexander Graf <graf@...>
Cc: Gerd Hoffmann <kraxel@...>

Signed-off-by: Nicolas Ojeda Leon <ncoleon@...>
---
OvmfPkg/Include/Library/HardwareInfoLib.h | 128 +++++++++
.../Library/HardwareInfoLib/HardwareInfoLib.c | 256 ++++++++++++++++++
.../HardwareInfoLib/HardwareInfoLib.inf | 43 +++
OvmfPkg/OvmfPkgX64.dsc | 1 +
4 files changed, 428 insertions(+)
create mode 100644 OvmfPkg/Include/Library/HardwareInfoLib.h
create mode 100644 OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.c
create mode 100644 OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf

diff --git a/OvmfPkg/Include/Library/HardwareInfoLib.h b/OvmfPkg/Include/Library/HardwareInfoLib.h
new file mode 100644
index 0000000000..dc7f209b09
--- /dev/null
+++ b/OvmfPkg/Include/Library/HardwareInfoLib.h
@@ -0,0 +1,128 @@
+/*/@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 "QemuFwCfgHardwareInfoLib.h"
+
+/**
+ 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/HardwareInfoLib.c b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.c
new file mode 100644
index 0000000000..5136c55031
--- /dev/null
+++ b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.c
@@ -0,0 +1,256 @@
+/*/@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.
+**/
+
+#include <string.h>
+#include <Uefi/UefiBaseType.h>
+#include <Uefi/UefiSpec.h>
+#include <Library/DebugLib.h>
+#include <Library/MemoryAllocationLib.h>
+#include <Library/BaseMemoryLib.h>
+#include <Library/BaseLib.h>
+#include <Library/UefiLib.h>
+
+#include <Library/HardwareInfoLib.h>
+
+EFI_STATUS
+CreateHardwareInfoList (
+ IN UINT8 *Blob,
+ IN UINTN BlobSize,
+ IN HARDWARE_INFO_TYPE TypeFilter,
+ OUT LIST_ENTRY *ListHead
+ )
+{
+ UINT8 *Index;
+ HARDWARE_INFO *HwComponent;
+
+ if ((Blob == NULL) || (BlobSize <= 0) ||
+ (ListHead == NULL))
+ {
+ return EFI_INVALID_PARAMETER;
+ }
+
+ Index = Blob;
+ while (Index < (Blob + BlobSize)) {
+ HwComponent = AllocateZeroPool (sizeof (HARDWARE_INFO));
+
+ if (HwComponent == NULL) {
+ goto FailedAllocate;
+ }
+
+ HwComponent->Header.Type.Uint64 = *((UINT64 *)Index);
+ Index += sizeof (HwComponent->Header.Type);
+ HwComponent->Header.Size = *((UINT64 *)(Index));
+ Index += sizeof (HwComponent->Header.Size);
+
+ //
+ // Check if optional TypeFilter is set, skip if the current
+ // object is of a different type and release the partially
+ // allocated object
+ //
+ if ((TypeFilter != HardwareInfoTypeUndefined) &&
+ (HwComponent->Header.Type.Value != TypeFilter))
+ {
+ FreePool (HwComponent);
+ Index += HwComponent->Header.Size;
+ continue;
+ }
+
+ HwComponent->Data.Raw = AllocateZeroPool (HwComponent->Header.Size);
+ if (HwComponent->Data.Raw == NULL) {
+ goto FreeResources;
+ }
+
+ CopyMem (HwComponent->Data.Raw, Index, HwComponent->Header.Size);
+ Index += HwComponent->Header.Size;
+
+ InsertTailList (ListHead, &HwComponent->Link);
+ }
+
+ return EFI_SUCCESS;
+
+FreeResources:
+ //
+ // Clean the resources allocated in the incomplete cycle
+ //
+ FreePool (HwComponent);
+
+FailedAllocate:
+ DEBUG ((
+ EFI_D_ERROR,
+ "%a: Failed to allocate memory for hardware info\n",
+ __FUNCTION__
+ ));
+
+ return EFI_OUT_OF_RESOURCES;
+}
+
+VOID
+FreeHardwareInfoList (
+ IN OUT LIST_ENTRY *ListHead
+ )
+{
+ LIST_ENTRY *CurrentLink;
+ HARDWARE_INFO *HwComponent;
+
+ if (IsListEmpty (ListHead)) {
+ return;
+ }
+
+ CurrentLink = ListHead->ForwardLink;
+ while (CurrentLink != NULL && CurrentLink != ListHead) {
+ HwComponent = HARDWARE_INFO_FROM_LINK (CurrentLink);
+
+ //
+ // Remove item from list before invalidating the pointers
+ //
+ CurrentLink = RemoveEntryList (CurrentLink);
+
+ FreePool (HwComponent->Data.Raw);
+ FreePool (HwComponent);
+ }
+}
+
+/**
+ Validates if the specified Node has a valid data size and is of
+ specified type.
+ The data size can be less or equal to the provided type size to be
+ regarded as valid and thus accessible with the typed pointer.
+
+ For future compatibility the size is allowed to be smaller so that
+ different versions interpret fields differently and, particularly,
+ have smaller data structures. However, it cannot be larger than the
+ type size to avoid accessing memory out of bounds.
+
+ @param[in] Node Hardware Info node to be validated
+ @param[in] TypeSize Size (in bytes) of the data type intended to be
+ used to dereference the data.
+ @retval TRUE Node is valid and can be accessed
+ @retval FALSE Node is not valid
+/*/
+STATIC
+BOOLEAN
+IsHardwareInfoNodeValidByType (
+ IN LIST_ENTRY *ListHead,
+ IN LIST_ENTRY *Link,
+ IN HARDWARE_INFO_TYPE Type,
+ IN UINTN TypeSize
+ )
+{
+ HARDWARE_INFO *HwComponent;
+
+ if (IsNull (ListHead, Link)) {
+ return FALSE;
+ }
+
+ HwComponent = HARDWARE_INFO_FROM_LINK (Link);
+
+ //
+ // Verify if the node type is the specified one and the size of
+ // the data allocated to the node is greater than the size of
+ // the type intended to dereference it in order to avoid access
+ // to memory out of bondaries.
+ //
+ if ((HwComponent->Header.Type.Value == Type) &&
+ (HwComponent->Header.Size >= TypeSize))
+ {
+ return TRUE;
+ }
+
+ return FALSE;
+}
+
+UINTN
+GetHardwareInfoCountByType (
+ IN LIST_ENTRY *ListHead,
+ IN HARDWARE_INFO_TYPE Type,
+ IN UINTN TypeSize
+ )
+{
+ UINTN Count;
+ LIST_ENTRY *Link;
+
+ Count = 0;
+ for (Link = GetFirstHardwareInfoByType (ListHead, Type, TypeSize);
+ !IsNull (ListHead, Link);
+ Link = GetNextHardwareInfoByType (ListHead, Link, Type, TypeSize))
+ {
+ if (IsHardwareInfoNodeValidByType (ListHead, Link, Type, TypeSize)) {
+ Count++;
+ }
+ }
+
+ return Count;
+}
+
+LIST_ENTRY *
+GetFirstHardwareInfoByType (
+ IN LIST_ENTRY *ListHead,
+ IN HARDWARE_INFO_TYPE Type,
+ IN UINTN TypeSize
+ )
+{
+ LIST_ENTRY *Link;
+
+ if (IsListEmpty (ListHead)) {
+ return ListHead;
+ }
+
+ Link = GetFirstNode (ListHead);
+
+ if (IsHardwareInfoNodeValidByType (ListHead, Link, Type, TypeSize)) {
+ return Link;
+ }
+
+ return GetNextHardwareInfoByType (ListHead, Link, Type, TypeSize);
+}
+
+LIST_ENTRY *
+GetNextHardwareInfoByType (
+ IN LIST_ENTRY *ListHead,
+ IN LIST_ENTRY *Node,
+ IN HARDWARE_INFO_TYPE Type,
+ IN UINTN TypeSize
+ )
+{
+ LIST_ENTRY *Link;
+
+ Link = GetNextNode (ListHead, Node);
+
+ while (!IsNull (ListHead, Link)) {
+ if (IsHardwareInfoNodeValidByType (ListHead, Link, Type, TypeSize)) {
+ //
+ // Found a node of specified type and with valid size. Break and
+ // return the found node.
+ //
+ break;
+ }
+
+ Link = GetNextNode (ListHead, Link);
+ }
+
+ return Link;
+}
+
+BOOLEAN
+EndOfHardwareInfoList (
+ IN LIST_ENTRY *ListHead,
+ IN LIST_ENTRY *Node
+ )
+{
+ return IsNull (ListHead, Node);
+}
diff --git a/OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf
new file mode 100644
index 0000000000..c099b072a3
--- /dev/null
+++ b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf
@@ -0,0 +1,43 @@
+## @file
+# Hardware information library to describe non-discoverable hardware resources
+#
+# 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 = HardwareInfoLib
+ FILE_GUID = F60B206A-5C56-11EC-AEAC-67CB080BCFF2
+ MODULE_TYPE = BASE
+ VERSION_STRING = 1.0
+ LIBRARY_CLASS = HardwareInfoLib
+
+#
+# The following information is for reference only and not required by the build
+# tools.
+#
+# VALID_ARCHITECTURES = X64
+#
+
+[Sources]
+ HardwareInfoLib.c
+ HardwareInfoPciHostBridgeLib.c
+ QemuFwCfgHardwareInfoLib.c
+
+[Packages]
+ MdeModulePkg/MdeModulePkg.dec
+ MdePkg/MdePkg.dec
+ OvmfPkg/OvmfPkg.dec
+
+[LibraryClasses]
+ BaseMemoryLib
+ DebugLib
+ MemoryAllocationLib
diff --git a/OvmfPkg/OvmfPkgX64.dsc b/OvmfPkg/OvmfPkgX64.dsc
index fb82fd02eb..062e16482d 100644
--- a/OvmfPkg/OvmfPkgX64.dsc
+++ b/OvmfPkg/OvmfPkgX64.dsc
@@ -175,6 +175,7 @@
SecurityManagementLib|MdeModulePkg/Library/DxeSecurityManagementLib/DxeSecurityManagementLib.inf
UefiUsbLib|MdePkg/Library/UefiUsbLib/UefiUsbLib.inf
SerializeVariablesLib|OvmfPkg/Library/SerializeVariablesLib/SerializeVariablesLib.inf
+ HardwareInfoLib|OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf
QemuFwCfgHardwareInfoLib|OvmfPkg/Library/HardwareInfoLib/QemuFwCfgHardwareInfoLib.inf
QemuFwCfgLib|OvmfPkg/Library/QemuFwCfgLib/QemuFwCfgDxeLib.inf
QemuFwCfgSimpleParserLib|OvmfPkg/Library/QemuFwCfgSimpleParserLib/QemuFwCfgSimpleParserLib.inf
--
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


Gerd Hoffmann
 

+++ b/OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf
+[Sources]
+ HardwareInfoLib.c
+ HardwareInfoPciHostBridgeLib.c
+ QemuFwCfgHardwareInfoLib.c
+ HardwareInfoLib|OvmfPkg/Library/HardwareInfoLib/HardwareInfoLib.inf
QemuFwCfgHardwareInfoLib|OvmfPkg/Library/HardwareInfoLib/QemuFwCfgHardwareInfoLib.inf
Hmm, the QemuFwCfgHardwareInfoLib.inf file created by patch #2 has
HardwareInfoPciHostBridgeLib.c + QemuFwCfgHardwareInfoLib.c too.

I'm wondering why you add two inf files in the first place?

take care,
Gerd


Gerd Hoffmann
 

On Fri, Jan 21, 2022 at 10:48:06AM +0000, Ojeda Leon, Nicolas wrote:
Hi Gerd,

Hmm, the QemuFwCfgHardwareInfoLib.inf file created by patch #2 has HardwareInfoPciHostBridgeLib.c + QemuFwCfgHardwareInfoLib.c too.
I'm wondering why you add two inf files in the first place?
My idea was to provide 2 variations of the library:

- One offering no dynamic memory and list features and only read functions to, statically, parse data out of a fw-cfg file -> QemuFwCfgHardwareInfo
- The other one being the general one having everything. Both the list and dynamic features as well as the fw-cfg wrappers -> HardwareInfoLib
Why do you need the former? To figure the highest address used in PEI,
whereas the DXE drivers use the other one?

Usual naming convention for that case would be PeiHardwareInfoLib + DxeHardwareInfoLib ...

take care,
Gerd


Ojeda Leon, Nicolas <ncoleon@...>
 

Hi Gerd,

Hmm, the QemuFwCfgHardwareInfoLib.inf file created by patch #2 has HardwareInfoPciHostBridgeLib.c + QemuFwCfgHardwareInfoLib.c too.
I'm wondering why you add two inf files in the first place?
My idea was to provide 2 variations of the library:

- One offering no dynamic memory and list features and only read functions to, statically, parse data out of a fw-cfg file -> QemuFwCfgHardwareInfo
- The other one being the general one having everything. Both the list and dynamic features as well as the fw-cfg wrappers -> HardwareInfoLib

Now that you mention it one option forward could be to add QemuFwCfgHardwareInfo as a dependency in HardwareInfoLib.
Or we could have a single inf file (the general one) and not use the dynamic functions where not possible, if you think this would be a cleaner solution.

Thank you for your comment.

Best regards,

Nicolas



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


Ojeda Leon, Nicolas <ncoleon@...>
 

Why do you need the former? To figure the highest address used in PEI, whereas the DXE drivers use the other one?
Yes that's right.

Usual naming convention for that case would be PeiHardwareInfoLib + DxeHardwareInfoLib ...
Understood, will change the naming to comply with the convention.

Thank you.

Best regards,

Nicolas




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