/** @file

  Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.

  SPDX-License-Identifier: BSD-2-Clause-Patent

  @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_