OvmfPkg/Include/Library/HardwareInfoLib.h

   1 /*/@file
   2   Hardware info parsing functions.
   3   Binary data is expected as a consecutive series of header - object pairs.
   4   Complete library providing static Qemu fw-cfg wrappers as well as list-like
   5   interface to dynamically manipulate hardware info objects and parsing from
   6   a generic blob.
   7
   8   Copyright 2021 - 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12
  13 #ifndef __HARDWARE_INFO_LIB_H__
  14 #define __HARDWARE_INFO_LIB_H__
  15
  16 #include "../Library/HardwareInfoLib/HardwareInfoTypesLib.h"
  17
  18 /**
  19   Read, if available, the next Type element in the FwCfg file.
  20   The FwCfg item must already be selected, this is a wrapper around
  21   QemuFwCfgReadBytes and the Data pointer should be set to an existent
  22   memory location with TypeSize bytes allocated for the date to be
  23   properly written. If a Type element is found in the file which has a
  24   size (in the header) greater than TypeSize, it is skipped.
  25
  26   @param[in]    Type             Hardware Info Type to search for
  27   @param[in]    TypeSize         Size (in bytes) of the structure intended to
  28                                  be used to dereference the data
  29   @param[in]    TotalFileSize    Total size (in bytes) of the FwCfg file from
  30                                  which the data is read.
  31   @param[out]   Data             Pointer to a memory allocated instance into
  32                                  which the data is written to.
  33   @param[out]   DataSize         Size in bytes of the actually filled
  34                                  data available in the Data object after a
  35                                  successful operation
  36   @param[inout] ReadIndex        Index of the next byte to be read. Incremented
  37                                  accordingly after a read operation to reflect
  38                                  up to date status
  39
  40   @retval EFI_SUCCESS             Next element found and read into Data
  41   @retval EFI_INVALID_PARAMETER   Operation failed
  42   @retval EFI_END_OF_FILE         End of the file reached, no more elements
  43                                   to read.
  44 **/
  45 EFI_STATUS
  46 QemuFwCfgReadNextHardwareInfoByType (
  47   IN      HARDWARE_INFO_TYPE  Type,
  48   IN      UINTN               TypeSize,
  49   IN      UINTN               TotalFileSize,
  50   OUT     VOID                *Data,
  51   OUT     UINTN               *DataSize         OPTIONAL,
  52   IN OUT  UINTN               *ReadIndex
  53   );
  54
  55 /**
  56   Parse binary data containing resource information of multiple hardware
  57   elements into a list of interpreted resources.
  58   The translation is done on a copy-parse base so the blob can be freed
  59   afterwards.
  60
  61   @param[in]  Blob           Binary data to be parsed
  62   @param[in]  BlobSize       Size (in bytes) of the binary data
  63   @param[in]  TypeFilter     Optional type to filter entries. Set to
  64                              undefined to disable filtering and retrieve all
  65   @param[out] ListHead       Head of the list to populate hardware information
  66
  67   @retval EFI_SUCCESS            Succeed.
  68   @retval EFI_INVALID_PARAMETER  Provided Blob inforation is invalid
  69   @retval EFI_OUT_OF_RESOURCES   Out of memory, list populated as far as
  70                                  possible
  71 **/
  72 EFI_STATUS
  73 CreateHardwareInfoList (
  74   IN  UINT8               *Blob,
  75   IN  UINTN               BlobSize,
  76   IN  HARDWARE_INFO_TYPE  TypeFilter,
  77   OUT LIST_ENTRY          *ListHead
  78   );
  79
  80 /**
  81   Free the dynamically allocated list of HADWARE_INFO items populated
  82   during parsing of Blob
  83
  84   @param ListHead         Head of the list to be destroyed
  85 **/
  86 VOID
  87 FreeHardwareInfoList (
  88   IN OUT  LIST_ENTRY  *ListHead
  89   );
  90
  91 /**
  92   Retrieve the number of hardware components of a specific type
  93   in the list.
  94
  95   @param[in]  ListHead       Head of the hardware info list
  96   @param[in]  Type           Type of hardware elements to count
  97   @param[in]  TypeSize       Size (in bytes) of the structure intended to
  98                              be used to dereference the data
  99   @return Count of elements of Type found
 100 **/
 101 UINTN
 102 GetHardwareInfoCountByType (
 103   IN  LIST_ENTRY          *ListHead,
 104   IN  HARDWARE_INFO_TYPE  Type,
 105   IN  UINTN               TypeSize
 106   );
 107
 108 /**
 109   Get the First Hardware Info entry in the list of the specified type
 110
 111   @param[in]  ListHead     Head of the hardware info list
 112   @param[in]  Type         Hardware Info Type to search for
 113   @param[in]  TypeSize     Size (in bytes) of the structure intended to
 114                            be used to dereference the data
 115   @return Link of first entry of specified type or list head if not found
 116 **/
 117 LIST_ENTRY *
 118 GetFirstHardwareInfoByType (
 119   IN  LIST_ENTRY          *ListHead,
 120   IN  HARDWARE_INFO_TYPE  Type,
 121   IN  UINTN               TypeSize
 122   );
 123
 124 /**
 125   Get the Next Hardware Info entry in the list with the specified
 126   type, which follows the provided Node.
 127
 128   @param[in]  ListHead       Head of the hardware info list
 129   @param[in]  Node           Current, already processed, node's link
 130   @param[in]  Type           Hardware Info Type to search for
 131   @param[in]  TypeSize       Size (in bytes) of the structure intended to
 132                              be used to dereference the data
 133   @return Link of next entry, after Node, of the specified type.
 134           List head otherwise
 135 **/
 136 LIST_ENTRY *
 137 GetNextHardwareInfoByType (
 138   IN  LIST_ENTRY          *ListHead,
 139   IN  LIST_ENTRY          *Node,
 140   IN  HARDWARE_INFO_TYPE  Type,
 141   IN  UINTN               TypeSize
 142   );
 143
 144 /**
 145   Assess if Node stands at the end of the doubly linked list
 146
 147   @param[in]  ListHead      Head of the hardware info list
 148   @param[in]  Node          Current Node link
 149
 150   @retval TRUE  Node is at the end of the list
 151   @retval FALSE Node is not at the end of the list
 152 **/
 153 BOOLEAN
 154 EndOfHardwareInfoList (
 155   IN  LIST_ENTRY  *ListHead,
 156   IN  LIST_ENTRY  *Node
 157   );
 158
 159 #endif // __HARDWARE_INFO_LIB_H__