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

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