DynamicTablesPkg: DT Table Generator

This patch introduces the interfaces and definitions for
implementing a Device Tree table generator.

Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <alexei.fedorov@arm.com>

diff --git a/DynamicTablesPkg/Include/DeviceTreeTableGenerator.h b/DynamicTablesPkg/Include/DeviceTreeTableGenerator.h
new file mode 100644 (file)
index 0000000..c2066c9
--- /dev/null
+++ b/DynamicTablesPkg/Include/DeviceTreeTableGenerator.h
@@ -0,0 +1,182 @@
+/** @file\r
+\r
+  Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.\r
+\r
+  This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions of the BSD License\r
+  which accompanies this distribution.  The full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+  @par Glossary:\r
+    - Cm or CM   - Configuration Manager\r
+    - Obj or OBJ - Object\r
+    - Std or STD - Standard\r
+**/\r
+\r
+#ifndef DEVICETREE_TABLE_GENERATOR_H_\r
+#define DEVICETREE_TABLE_GENERATOR_H_\r
+\r
+#include <TableGenerator.h>\r
+\r
+#pragma pack(1)\r
+\r
+/** The DT_TABLE_GENERATOR_ID type describes Device Tree table generator ID.\r
+*/\r
+typedef TABLE_GENERATOR_ID DT_TABLE_GENERATOR_ID;\r
+\r
+/** The ESTD_DT_TABLE_ID enum describes the DT table IDs reserved for\r
+  the standard generators.\r
+*/\r
+typedef enum StdDtTableId {\r
+  EStdDtTableIdReserved = 0x0000,             ///< Reserved.\r
+  EStdDtTableIdRaw,                           ///< RAW Generator.\r
+  EStdDtTableIdMax\r
+} ESTD_DT_TABLE_ID;\r
+\r
+/** This macro checks if the Table Generator ID is for an DT Table Generator.\r
+\r
+  @param [in] TableGeneratorId  The table generator ID.\r
+\r
+  @return TRUE if the table generator ID is for an DT Table\r
+            Generator.\r
+**/\r
+#define IS_GENERATOR_TYPE_DT(TableGeneratorId) \\r
+          (GET_TABLE_TYPE(TableGeneratorId) == ETableGeneratorTypeDt)\r
+\r
+/** This macro checks if the Table Generator ID is for a standard DT\r
+    Table Generator.\r
+\r
+  @param [in] TableGeneratorId  The table generator ID.\r
+\r
+  @return TRUE if the table generator ID is for a standard DT\r
+            Table Generator.\r
+**/\r
+#define IS_VALID_STD_DT_GENERATOR_ID(TableGeneratorId)           \\r
+          (                                                      \\r
+          IS_GENERATOR_NAMESPACE_STD(TableGeneratorId) &&        \\r
+          IS_GENERATOR_TYPE_DT(TableGeneratorId)       &&        \\r
+          ((GET_TABLE_ID(GeneratorId) >= EStdDtTableIdRaw) &&    \\r
+           (GET_TABLE_ID(GeneratorId) < EStdDtTableIdMax))       \\r
+          )\r
+\r
+/** This macro creates a standard DT Table Generator ID.\r
+\r
+  @param [in] TableId  The table generator ID.\r
+\r
+  @return a standard DT table generator ID.\r
+**/\r
+#define CREATE_STD_DT_TABLE_GEN_ID(TableId) \\r
+          CREATE_TABLE_GEN_ID (             \\r
+            ETableGeneratorTypeDt,          \\r
+            ETableGeneratorNameSpaceStd,    \\r
+            TableId                         \\r
+            )\r
+\r
+/** Forward declarations.\r
+*/\r
+typedef struct ConfigurationManagerProtocol EDKII_CONFIGURATION_MANAGER_PROTOCOL;\r
+typedef struct CmAStdObjDtTableInfo         CM_STD_OBJ_DT_TABLE_INFO;\r
+typedef struct DtTableGenerator             DT_TABLE_GENERATOR;\r
+\r
+/** This function pointer describes the interface to DT table build\r
+    functions provided by the DT table generator and called by the\r
+    Table Manager to build an DT table.\r
+\r
+  @param [in]  Generator       Pointer to the DT table generator.\r
+  @param [in]  DtTableInfo     Pointer to the DT table information.\r
+  @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager\r
+                               Protocol interface.\r
+  @param [out] Table           Pointer to the generated DT table.\r
+\r
+  @return EFI_SUCCESS  If the table is generated successfully or other\r
+                        failure codes as returned by the generator.\r
+**/\r
+typedef EFI_STATUS (*DT_TABLE_GENERATOR_BUILD_TABLE) (\r
+  IN  CONST DT_TABLE_GENERATOR                    *       Generator,\r
+  IN  CONST CM_STD_OBJ_DT_TABLE_INFO              * CONST DtTableInfo,\r
+  IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,\r
+  OUT       VOID                                 **       Table\r
+  );\r
+\r
+/** This function pointer describes the interface to used by the\r
+    Table Manager to give the generator an opportunity to free\r
+    any resources allocated for building the DT table.\r
+\r
+  @param [in]  Generator       Pointer to the DT table generator.\r
+  @param [in]  DtTableInfo     Pointer to the DT table information.\r
+  @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager\r
+                               Protocol interface.\r
+  @param [in]  Table           Pointer to the generated DT table.\r
+\r
+  @return EFI_SUCCESS  If freed successfully or other failure codes\r
+                        as returned by the generator.\r
+**/\r
+typedef EFI_STATUS (*DT_TABLE_GENERATOR_FREE_TABLE) (\r
+  IN  CONST DT_TABLE_GENERATOR                    *       Generator,\r
+  IN  CONST CM_STD_OBJ_DT_TABLE_INFO              * CONST DtTableInfo,\r
+  IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL  * CONST CfgMgrProtocol,\r
+  IN        VOID                                 **       Table\r
+  );\r
+\r
+/** The DT_TABLE_GENERATOR structure provides an interface that the\r
+    Table Manager can use to invoke the functions to build DT tables.\r
+*/\r
+typedef struct DtTableGenerator {\r
+  /// The DT table generator ID.\r
+  DT_TABLE_GENERATOR_ID                  GeneratorID;\r
+\r
+  /// String describing the DT table generator.\r
+  CONST CHAR16                         * Description;\r
+\r
+  /// DT table build function pointer.\r
+  DT_TABLE_GENERATOR_BUILD_TABLE         BuildDtTable;\r
+\r
+  /// The function to free any resources allocated for building the DT table.\r
+  DT_TABLE_GENERATOR_FREE_TABLE          FreeTableResources;\r
+} DT_TABLE_GENERATOR;\r
+\r
+/** Register DT table factory generator.\r
+\r
+  The DT table factory maintains a list of the Standard and OEM DT\r
+  table generators.\r
+\r
+  @param [in]  Generator       Pointer to the DT table generator.\r
+\r
+  @retval  EFI_SUCCESS          The Generator was registered\r
+                                successfully.\r
+  @retval EFI_INVALID_PARAMETER The Generator ID is invalid or\r
+                                the Generator pointer is NULL.\r
+  @retval EFI_ALREADY_STARTED   The Generator for the Table ID is\r
+                                already registered.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+RegisterDtTableGenerator (\r
+  IN CONST DT_TABLE_GENERATOR                   * CONST Generator\r
+  );\r
+\r
+/** Deregister DT generator.\r
+\r
+  This function is called by the DT table generator to deregister itself\r
+  from the DT table factory.\r
+\r
+  @param [in]  Generator       Pointer to the DT table generator.\r
+\r
+  @retval EFI_SUCCESS           Success.\r
+  @retval EFI_INVALID_PARAMETER The generator is invalid.\r
+  @retval EFI_NOT_FOUND         The requested generator is not found\r
+                                in the list of registered generators.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+DeregisterDtTableGenerator (\r
+  IN CONST DT_TABLE_GENERATOR                   * CONST Generator\r
+  );\r
+\r
+#pragma pack()\r
+\r
+#endif // DEVICETREE_TABLE_GENERATOR_H_\r
+\r