[PATCH v2 05/22] DynamicTablesPkg: DT Table Generator

[Sami Mujawar <sami.mujawar@arm.com>]

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>
---
 DynamicTablesPkg/Include/DeviceTreeTableGenerator.h | 182 ++++++++++++++++++++
 1 file changed, 182 insertions(+)

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