DynamicTablesPkg/Include/Library/TableHelperLib.h

   1 /** @file
   2
   3   Copyright (c) 2017 - 2021, Arm Limited. All rights reserved.<BR>
   4
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Glossary:
   8     - PFN   - Pointer to a Function
   9
  10 **/
  11
  12 #ifndef TABLE_HELPER_LIB_H_
  13 #define TABLE_HELPER_LIB_H_
  14
  15 #include <Library/AmlLib/AmlLib.h>
  16
  17 /** The GetCgfMgrInfo function gets the CM_STD_OBJ_CONFIGURATION_MANAGER_INFO
  18     object from the Configuration Manager.
  19
  20   @param [in]  CfgMgrProtocol Pointer to the Configuration Manager protocol
  21                               interface.
  22   @param [out] CfgMfrInfo     Pointer to the Configuration Manager Info
  23                               object structure.
  24
  25   @retval EFI_SUCCESS           The object is returned.
  26   @retval EFI_INVALID_PARAMETER The Object ID is invalid.
  27   @retval EFI_NOT_FOUND         The requested Object is not found.
  28   @retval EFI_BAD_BUFFER_SIZE   The size returned by the Configuration
  29                                 Manager is less than the Object size.
  30 **/
  31 EFI_STATUS
  32 EFIAPI
  33 GetCgfMgrInfo (
  34   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL      * CONST  CfgMgrProtocol,
  35   OUT       CM_STD_OBJ_CONFIGURATION_MANAGER_INFO    **        CfgMfrInfo
  36   );
  37
  38 /** The AddAcpiHeader function updates the ACPI header structure. It uses the
  39     ACPI table Generator and the Configuration Manager protocol to obtain the
  40     information required for constructing the header.
  41
  42   @param [in]     CfgMgrProtocol Pointer to the Configuration Manager
  43                                  protocol interface.
  44   @param [in]     Generator      Pointer to the ACPI table Generator.
  45   @param [in,out] AcpiHeader     Pointer to the ACPI table header to be
  46                                  updated.
  47   @param [in]     AcpiTableInfo  Pointer to the ACPI table info structure.
  48   @param [in]     Length         Length of the ACPI table.
  49
  50   @retval EFI_SUCCESS           The ACPI table is updated successfully.
  51   @retval EFI_INVALID_PARAMETER A parameter is invalid.
  52   @retval EFI_NOT_FOUND         The required object information is not found.
  53   @retval EFI_BAD_BUFFER_SIZE   The size returned by the Configuration
  54                                 Manager is less than the Object size for the
  55                                 requested object.
  56 **/
  57 EFI_STATUS
  58 EFIAPI
  59 AddAcpiHeader (
  60   IN      CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,
  61   IN      CONST ACPI_TABLE_GENERATOR                  * CONST Generator,
  62   IN OUT  EFI_ACPI_DESCRIPTION_HEADER                 * CONST AcpiHeader,
  63   IN      CONST CM_STD_OBJ_ACPI_TABLE_INFO            * CONST AcpiTableInfo,
  64   IN      CONST UINT32                                        Length
  65   );
  66
  67 /** Build a RootNode containing SSDT ACPI header information using the AmlLib.
  68
  69   The function utilizes the ACPI table Generator and the Configuration
  70   Manager protocol to obtain any information required for constructing the
  71   header. It then creates a RootNode. The SSDT ACPI header is part of the
  72   RootNode.
  73
  74   This is essentially a wrapper around AmlCodeGenDefinitionBlock ()
  75   from the AmlLib.
  76
  77   @param [in]   CfgMgrProtocol Pointer to the Configuration Manager
  78                                protocol interface.
  79   @param [in]   Generator      Pointer to the ACPI table Generator.
  80   @param [in]   AcpiTableInfo  Pointer to the ACPI table info structure.
  81   @param [out]  RootNode       If success, contains the created RootNode.
  82                                The SSDT ACPI header is part of the RootNode.
  83
  84   @retval EFI_SUCCESS           Success.
  85   @retval EFI_INVALID_PARAMETER A parameter is invalid.
  86   @retval EFI_NOT_FOUND         The required object information is not found.
  87   @retval EFI_BAD_BUFFER_SIZE   The size returned by the Configuration
  88                                 Manager is less than the Object size for the
  89                                 requested object.
  90 **/
  91 EFI_STATUS
  92 EFIAPI
  93 AddSsdtAcpiHeader (
  94   IN      CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,
  95   IN      CONST ACPI_TABLE_GENERATOR                  * CONST Generator,
  96   IN      CONST CM_STD_OBJ_ACPI_TABLE_INFO            * CONST AcpiTableInfo,
  97       OUT       AML_ROOT_NODE_HANDLE                  *       RootNode
  98   );
  99
 100 /**
 101   Function prototype for testing if two arbitrary objects are equal.
 102
 103   @param [in] Object1           Pointer to the first object to compare.
 104   @param [in] Object2           Pointer to the second object to compare.
 105   @param [in] Index1            Index of Object1. This value is optional and
 106                                 can be ignored by the specified implementation.
 107   @param [in] Index2            Index of Object2. This value is optional and
 108                                 can be ignored by the specified implementation.
 109
 110   @retval TRUE                  Object1 and Object2 are equal.
 111   @retval FALSE                 Object1 and Object2 are NOT equal.
 112 **/
 113 typedef
 114 BOOLEAN
 115 (EFIAPI *PFN_IS_EQUAL)(
 116   IN CONST  VOID            * Object1,
 117   IN CONST  VOID            * Object2,
 118   IN        UINTN             Index1 OPTIONAL,
 119   IN        UINTN             Index2 OPTIONAL
 120   );
 121
 122 /**
 123   Test and report if a duplicate entry exists in the given array of comparable
 124   elements.
 125
 126   @param [in] Array                 Array of elements to test for duplicates.
 127   @param [in] Count                 Number of elements in Array.
 128   @param [in] ElementSize           Size of an element in bytes
 129   @param [in] EqualTestFunction     The function to call to check if any two
 130                                     elements are equal.
 131
 132   @retval TRUE                      A duplicate element was found or one of
 133                                     the input arguments is invalid.
 134   @retval FALSE                     Every element in Array is unique.
 135 **/
 136 BOOLEAN
 137 EFIAPI
 138 FindDuplicateValue (
 139   IN  CONST VOID          * Array,
 140   IN  CONST UINTN           Count,
 141   IN  CONST UINTN           ElementSize,
 142   IN        PFN_IS_EQUAL    EqualTestFunction
 143   );
 144
 145 /** Parse and print a CmObjDesc.
 146
 147   @param [in]  CmObjDesc  The CmObjDesc to parse and print.
 148 **/
 149 VOID
 150 EFIAPI
 151 ParseCmObjDesc (
 152   IN  CONST CM_OBJ_DESCRIPTOR * CmObjDesc
 153   );
 154
 155 #endif // TABLE_HELPER_LIB_H_