DeviceTreeTableGenerator.h 6.3 KB

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