DynamicTablesPkg/Include/DeviceTreeTableGenerator.h

   1 /** @file
   2
   3   Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.
   4
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Glossary:
   8     - Cm or CM   - Configuration Manager
   9     - Obj or OBJ - Object
  10     - Std or STD - Standard
  11 **/
  12
  13 #ifndef DEVICETREE_TABLE_GENERATOR_H_
  14 #define DEVICETREE_TABLE_GENERATOR_H_
  15
  16 #include <TableGenerator.h>
  17
  18 #pragma pack(1)
  19
  20 /** The DT_TABLE_GENERATOR_ID type describes Device Tree table generator ID.
  21 */
  22 typedef TABLE_GENERATOR_ID DT_TABLE_GENERATOR_ID;
  23
  24 /** The ESTD_DT_TABLE_ID enum describes the DT table IDs reserved for
  25   the standard generators.
  26 */
  27 typedef enum StdDtTableId {
  28   EStdDtTableIdReserved = 0x0000,             ///< Reserved.
  29   EStdDtTableIdRaw,                           ///< RAW Generator.
  30   EStdDtTableIdMax
  31 } ESTD_DT_TABLE_ID;
  32
  33 /** This macro checks if the Table Generator ID is for an DT Table Generator.
  34
  35   @param [in] TableGeneratorId  The table generator ID.
  36
  37   @return TRUE if the table generator ID is for an DT Table
  38             Generator.
  39 **/
  40 #define IS_GENERATOR_TYPE_DT(TableGeneratorId) \
  41           (GET_TABLE_TYPE(TableGeneratorId) == ETableGeneratorTypeDt)
  42
  43 /** This macro checks if the Table Generator ID is for a standard DT
  44     Table Generator.
  45
  46   @param [in] TableGeneratorId  The table generator ID.
  47
  48   @return TRUE if the table generator ID is for a standard DT
  49             Table Generator.
  50 **/
  51 #define IS_VALID_STD_DT_GENERATOR_ID(TableGeneratorId)           \
  52           (                                                      \
  53           IS_GENERATOR_NAMESPACE_STD(TableGeneratorId) &&        \
  54           IS_GENERATOR_TYPE_DT(TableGeneratorId)       &&        \
  55           ((GET_TABLE_ID(GeneratorId) >= EStdDtTableIdRaw) &&    \
  56            (GET_TABLE_ID(GeneratorId) < EStdDtTableIdMax))       \
  57           )
  58
  59 /** This macro creates a standard DT Table Generator ID.
  60
  61   @param [in] TableId  The table generator ID.
  62
  63   @return a standard DT table generator ID.
  64 **/
  65 #define CREATE_STD_DT_TABLE_GEN_ID(TableId) \
  66           CREATE_TABLE_GEN_ID (             \
  67             ETableGeneratorTypeDt,          \
  68             ETableGeneratorNameSpaceStd,    \
  69             TableId                         \
  70             )
  71
  72 /** Forward declarations.
  73 */
  74 typedef struct ConfigurationManagerProtocol EDKII_CONFIGURATION_MANAGER_PROTOCOL;
  75 typedef struct CmAStdObjDtTableInfo         CM_STD_OBJ_DT_TABLE_INFO;
  76 typedef struct DtTableGenerator             DT_TABLE_GENERATOR;
  77
  78 /** This function pointer describes the interface to DT table build
  79     functions provided by the DT table generator and called by the
  80     Table Manager to build an DT table.
  81
  82   @param [in]  Generator       Pointer to the DT table generator.
  83   @param [in]  DtTableInfo     Pointer to the DT table information.
  84   @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager
  85                                Protocol interface.
  86   @param [out] Table           Pointer to the generated DT table.
  87
  88   @return EFI_SUCCESS  If the table is generated successfully or other
  89                         failure codes as returned by the generator.
  90 **/
  91 typedef EFI_STATUS (*DT_TABLE_GENERATOR_BUILD_TABLE) (
  92   IN  CONST DT_TABLE_GENERATOR                    *       Generator,
  93   IN  CONST CM_STD_OBJ_DT_TABLE_INFO              * CONST DtTableInfo,
  94   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,
  95   OUT       VOID                                 **       Table
  96   );
  97
  98 /** This function pointer describes the interface to used by the
  99     Table Manager to give the generator an opportunity to free
 100     any resources allocated for building the DT table.
 101
 102   @param [in]  Generator       Pointer to the DT table generator.
 103   @param [in]  DtTableInfo     Pointer to the DT table information.
 104   @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager
 105                                Protocol interface.
 106   @param [in]  Table           Pointer to the generated DT table.
 107
 108   @return EFI_SUCCESS  If freed successfully or other failure codes
 109                         as returned by the generator.
 110 **/
 111 typedef EFI_STATUS (*DT_TABLE_GENERATOR_FREE_TABLE) (
 112   IN  CONST DT_TABLE_GENERATOR                    *       Generator,
 113   IN  CONST CM_STD_OBJ_DT_TABLE_INFO              * CONST DtTableInfo,
 114   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,
 115   IN        VOID                                 **       Table
 116   );
 117
 118 /** The DT_TABLE_GENERATOR structure provides an interface that the
 119     Table Manager can use to invoke the functions to build DT tables.
 120 */
 121 typedef struct DtTableGenerator {
 122   /// The DT table generator ID.
 123   DT_TABLE_GENERATOR_ID                  GeneratorID;
 124
 125   /// String describing the DT table generator.
 126   CONST CHAR16                         * Description;
 127
 128   /// DT table build function pointer.
 129   DT_TABLE_GENERATOR_BUILD_TABLE         BuildDtTable;
 130
 131   /// The function to free any resources allocated for building the DT table.
 132   DT_TABLE_GENERATOR_FREE_TABLE          FreeTableResources;
 133 } DT_TABLE_GENERATOR;
 134
 135 /** Register DT table factory generator.
 136
 137   The DT table factory maintains a list of the Standard and OEM DT
 138   table generators.
 139
 140   @param [in]  Generator       Pointer to the DT table generator.
 141
 142   @retval  EFI_SUCCESS          The Generator was registered
 143                                 successfully.
 144   @retval EFI_INVALID_PARAMETER The Generator ID is invalid or
 145                                 the Generator pointer is NULL.
 146   @retval EFI_ALREADY_STARTED   The Generator for the Table ID is
 147                                 already registered.
 148 **/
 149 EFI_STATUS
 150 EFIAPI
 151 RegisterDtTableGenerator (
 152   IN CONST DT_TABLE_GENERATOR                   * CONST Generator
 153   );
 154
 155 /** Deregister DT generator.
 156
 157   This function is called by the DT table generator to deregister itself
 158   from the DT table factory.
 159
 160   @param [in]  Generator       Pointer to the DT table generator.
 161
 162   @retval EFI_SUCCESS           Success.
 163   @retval EFI_INVALID_PARAMETER The generator is invalid.
 164   @retval EFI_NOT_FOUND         The requested generator is not found
 165                                 in the list of registered generators.
 166 **/
 167 EFI_STATUS
 168 EFIAPI
 169 DeregisterDtTableGenerator (
 170   IN CONST DT_TABLE_GENERATOR                   * CONST Generator
 171   );
 172
 173 #pragma pack()
 174
 175 #endif // DEVICETREE_TABLE_GENERATOR_H_
 176