audk/DynamicTablesPkg/Include/DeviceTreeTableGenerator.h

177 lines
6.3 KiB
C

/** @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_