DynamicTablesPkg/Include/DeviceTreeTableGenerator.h

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