[mirror_edk2.git] / DynamicTablesPkg / Include / DeviceTreeTableGenerator.h

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