c4ef05965fc02707307e59130e9caa359e66239b
[mirror_edk2.git] / DynamicTablesPkg / Include / AcpiTableGenerator.h
1 /** @file\r
2 \r
3   Copyright (c) 2017 - 2019, ARM Limited. All rights reserved.\r
4 \r
5   SPDX-License-Identifier: BSD-2-Clause-Patent\r
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 ACPI_TABLE_GENERATOR_H_\r
14 #define ACPI_TABLE_GENERATOR_H_\r
15 \r
16 #include <IndustryStandard/Acpi.h>\r
17 \r
18 // Module specific include files.\r
19 #include <TableGenerator.h>\r
20 \r
21 #pragma pack(1)\r
22 \r
23 /**\r
24 The Dynamic Tables Framework provisions two classes of ACPI table\r
25 generators.\r
26  - Standard generators: The ACPI table generators implemented by the\r
27                         Dynamic Tables Framework.\r
28  - OEM generators:      The ACPI table generators customized by the OEM.\r
29 \r
30 The Dynamic Tables Framework implements the following ACPI table generators:\r
31   - RAW   : This is the simplest ACPI table generator. It simply installs\r
32             the ACPI table provided in the AcpiTableData member of the\r
33             CM_STD_OBJ_ACPI_TABLE_INFO. The ACPI table data is provided by\r
34             the Configuration Manager and is generated using an implementation\r
35             defined mechanism.\r
36   - DSDT  : The DSDT generator is a clone of the RAW generator. The difference\r
37             is in the way the ACPI Table Data is generated from an AML file.\r
38   - SSDT  : The SSDT generator is a clone of the RAW generator. The difference\r
39             is in the way the ACPI Table Data is generated from an AML file.\r
40   - FADT  : The FADT generator collates the required platform information from\r
41             the Configuration Manager and builds the FADT table.\r
42   - MADT  : The MADT generator collates the GIC information  from the\r
43             Configuration Manager and builds the MADT table.\r
44   - GTDT  : The GTDT generator collates the Timer information from the\r
45             Configuration Manager and builds the GTDT table.\r
46   - DBG2  : The DBG2 generator collates the debug serial port information from\r
47             the Configuration Manager and builds the DBG2 table.\r
48   - SPCR  : The SPCR generator collates the serial port information from the\r
49             Configuration Manager and builds the SPCR table.\r
50   - MCFG  : The MCFG generator collates the PCI configuration space information\r
51             from the Configuration Manager and builds the MCFG table.\r
52   - IORT  : The IORT generator collates the IO Topology information from the\r
53             Configuration Manager and builds the IORT table.\r
54 */\r
55 \r
56 /** The ACPI_TABLE_GENERATOR_ID type describes ACPI table generator ID.\r
57 */\r
58 typedef TABLE_GENERATOR_ID ACPI_TABLE_GENERATOR_ID;\r
59 \r
60 /** The ESTD_ACPI_TABLE_ID enum describes the ACPI table IDs reserved for\r
61   the standard generators.\r
62 */\r
63 typedef enum StdAcpiTableId {\r
64   EStdAcpiTableIdReserved = 0x0000,             ///< Reserved\r
65   EStdAcpiTableIdRaw,                           ///< RAW Generator\r
66   EStdAcpiTableIdDsdt = EStdAcpiTableIdRaw,     ///< DSDT Generator\r
67   EStdAcpiTableIdSsdt = EStdAcpiTableIdRaw,     ///< SSDT Generator\r
68   EStdAcpiTableIdFadt,                          ///< FADT Generator\r
69   EStdAcpiTableIdMadt,                          ///< MADT Generator\r
70   EStdAcpiTableIdGtdt,                          ///< GTDT Generator\r
71   EStdAcpiTableIdDbg2,                          ///< DBG2 Generator\r
72   EStdAcpiTableIdSpcr,                          ///< SPCR Generator\r
73   EStdAcpiTableIdMcfg,                          ///< MCFG Generator\r
74   EStdAcpiTableIdIort,                          ///< IORT Generator\r
75   EStdAcpiTableIdMax\r
76 } ESTD_ACPI_TABLE_ID;\r
77 \r
78 /** This macro checks if the Table Generator ID is for an ACPI Table Generator.\r
79 \r
80   @param [in] TableGeneratorId  The table generator ID.\r
81 \r
82   @return TRUE if the table generator ID is for an ACPI Table\r
83         Generator.\r
84 **/\r
85 #define IS_GENERATOR_TYPE_ACPI(TableGeneratorId) \\r
86           (GET_TABLE_TYPE (TableGeneratorId) == ETableGeneratorTypeAcpi)\r
87 \r
88 /** This macro checks if the Table Generator ID is for a standard ACPI\r
89     Table Generator.\r
90 \r
91   @param [in] TableGeneratorId  The table generator ID.\r
92 \r
93   @return TRUE if the table generator ID is for a standard ACPI\r
94           Table Generator.\r
95 **/\r
96 #define IS_VALID_STD_ACPI_GENERATOR_ID(TableGeneratorId)           \\r
97           (                                                        \\r
98           IS_GENERATOR_NAMESPACE_STD (TableGeneratorId) &&         \\r
99           IS_GENERATOR_TYPE_ACPI (TableGeneratorId)     &&         \\r
100           ((GET_TABLE_ID (GeneratorId) >= EStdAcpiTableIdRaw) &&   \\r
101            (GET_TABLE_ID (GeneratorId) < EStdAcpiTableIdMax))      \\r
102           )\r
103 \r
104 /** This macro creates a standard ACPI Table Generator ID.\r
105 \r
106   @param [in] TableId  The table generator ID.\r
107 \r
108   @return a standard ACPI table generator ID.\r
109 **/\r
110 #define CREATE_STD_ACPI_TABLE_GEN_ID(TableId) \\r
111           CREATE_TABLE_GEN_ID (               \\r
112             ETableGeneratorTypeAcpi,          \\r
113             ETableGeneratorNameSpaceStd,      \\r
114             TableId                           \\r
115             )\r
116 \r
117 /** This macro creates an OEM ACPI Table Generator ID.\r
118 \r
119   @param [in] TableId  The table generator ID.\r
120 \r
121   @return an OEM ACPI table generator ID.\r
122 **/\r
123 #define CREATE_OEM_ACPI_TABLE_GEN_ID(TableId) \\r
124           CREATE_TABLE_GEN_ID (               \\r
125             ETableGeneratorTypeAcpi,          \\r
126             ETableGeneratorNameSpaceOem,      \\r
127             TableId                           \\r
128             )\r
129 \r
130 /** The Creator ID for the ACPI tables generated using\r
131   the standard ACPI table generators.\r
132 */\r
133 #define TABLE_GENERATOR_CREATOR_ID_ARM  SIGNATURE_32('A', 'R', 'M', 'H')\r
134 \r
135 /** A macro to initialise the common header part of EFI ACPI tables as\r
136     defined by the EFI_ACPI_DESCRIPTION_HEADER structure.\r
137 \r
138   @param [in] Signature The ACPI table signature.\r
139   @param [in] Type      The ACPI table structure.\r
140   @param [in] Revision  The ACPI table revision.\r
141 **/\r
142 #define ACPI_HEADER(Signature, Type, Revision) {              \\r
143           Signature,             /* UINT32  Signature */      \\r
144           sizeof (Type),         /* UINT32  Length */         \\r
145           Revision,              /* UINT8   Revision */       \\r
146           0,                     /* UINT8   Checksum */       \\r
147           { 0, 0, 0, 0, 0, 0 },  /* UINT8   OemId[6] */       \\r
148           0,                     /* UINT64  OemTableId */     \\r
149           0,                     /* UINT32  OemRevision */    \\r
150           0,                     /* UINT32  CreatorId */      \\r
151           0                      /* UINT32  CreatorRevision */\\r
152           }\r
153 \r
154 /** A macro to dump the common header part of EFI ACPI tables as\r
155     defined by the EFI_ACPI_DESCRIPTION_HEADER structure.\r
156 \r
157   @param [in] AcpiHeader The pointer to the ACPI table header.\r
158 **/\r
159 #define DUMP_ACPI_TABLE_HEADER(AcpiHeader)                        \\r
160           DEBUG ((                                                \\r
161             DEBUG_INFO,                                           \\r
162             "ACPI TABLE %c%c%c%c : Rev 0x%x : Length : 0x%x\n",   \\r
163             (AcpiHeader->Signature & 0xFF),                       \\r
164             ((AcpiHeader->Signature >> 8) & 0xFF),                \\r
165             ((AcpiHeader->Signature >> 16) & 0xFF),               \\r
166             ((AcpiHeader->Signature >> 24) & 0xFF),               \\r
167             AcpiHeader->Revision,                                 \\r
168             AcpiHeader->Length                                    \\r
169             ));\r
170 \r
171 /** Forward declarations.\r
172 */\r
173 typedef struct ConfigurationManagerProtocol EDKII_CONFIGURATION_MANAGER_PROTOCOL;\r
174 typedef struct CmAStdObjAcpiTableInfo       CM_STD_OBJ_ACPI_TABLE_INFO;\r
175 typedef struct AcpiTableGenerator           ACPI_TABLE_GENERATOR;\r
176 \r
177 /** This function pointer describes the interface to ACPI table build\r
178     functions provided by the ACPI table generator and called by the\r
179     Table Manager to build an ACPI table.\r
180 \r
181   @param [in]  This            Pointer to the ACPI table generator.\r
182   @param [in]  AcpiTableInfo   Pointer to the ACPI table information.\r
183   @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager\r
184                                Protocol interface.\r
185   @param [out] Table           Pointer to the generated ACPI table.\r
186 \r
187   @return  EFI_SUCCESS If the table is generated successfully or other\r
188                         failure codes as returned by the generator.\r
189 **/\r
190 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_BUILD_TABLE) (\r
191   IN  CONST ACPI_TABLE_GENERATOR                   *       This,\r
192   IN  CONST CM_STD_OBJ_ACPI_TABLE_INFO             * CONST AcpiTableInfo,\r
193   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   * CONST CfgMgrProtocol,\r
194   OUT       EFI_ACPI_DESCRIPTION_HEADER           **       Table\r
195   );\r
196 \r
197 /** This function pointer describes the interface used by the\r
198     Table Manager to give the generator an opportunity to free\r
199     any resources allocated for building the ACPI table.\r
200 \r
201   @param [in]      This           Pointer to the ACPI table generator.\r
202   @param [in]      AcpiTableInfo  Pointer to the ACPI Table Info.\r
203   @param [in]      CfgMgrProtocol Pointer to the Configuration Manager\r
204                                   Protocol Interface.\r
205   @param [in, out] Table          Pointer to the ACPI Table.\r
206 \r
207   @return EFI_SUCCESS  If freed successfully or other failure codes\r
208                         as returned by the generator.\r
209 **/\r
210 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_FREE_TABLE) (\r
211   IN      CONST ACPI_TABLE_GENERATOR                   * CONST This,\r
212   IN      CONST CM_STD_OBJ_ACPI_TABLE_INFO             * CONST AcpiTableInfo,\r
213   IN      CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   * CONST CfgMgrProtocol,\r
214   IN OUT        EFI_ACPI_DESCRIPTION_HEADER           ** CONST Table\r
215   );\r
216 \r
217 /** This function pointer describes an extended interface to build\r
218     ACPI Tables. The ACPI table generator can generate multiple\r
219     ACPI Tables and return a pointer to the list of ACPI tables.\r
220     The FreeTableResourcesEx() must be called to free any resources\r
221     that may have been allocated using this interface.\r
222 \r
223   @param [in]  This            Pointer to the ACPI table generator.\r
224   @param [in]  AcpiTableInfo   Pointer to the ACPI table information.\r
225   @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager\r
226                                Protocol interface.\r
227   @param [out] Table           Pointer to a list of generated ACPI table(s).\r
228   @param [out] TableCount      Number of generated ACPI table(s).\r
229 \r
230   @return  EFI_SUCCESS If the table is generated successfully or other\r
231                         failure codes as returned by the generator.\r
232 **/\r
233 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_BUILD_TABLEEX) (\r
234   IN  CONST ACPI_TABLE_GENERATOR                   *       This,\r
235   IN  CONST CM_STD_OBJ_ACPI_TABLE_INFO             * CONST AcpiTableInfo,\r
236   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   * CONST CfgMgrProtocol,\r
237   OUT       EFI_ACPI_DESCRIPTION_HEADER          ***       Table,\r
238   OUT       UINTN                                  * CONST TableCount\r
239   );\r
240 \r
241 /** This function pointer describes an extended interface used by the\r
242     Table Manager to give the generator an opportunity to free\r
243     any resources allocated for building the ACPI table. This interface\r
244     must be used in conjunction with the BuildAcpiTableEx interface.\r
245 \r
246   @param [in]      This           Pointer to the ACPI table generator.\r
247   @param [in]      AcpiTableInfo  Pointer to the ACPI Table Info.\r
248   @param [in]      CfgMgrProtocol Pointer to the Configuration Manager\r
249                                   Protocol Interface.\r
250   @param [in, out] Table          Pointer to the list of ACPI Table(s).\r
251   @param [in]      TableCount     Number of ACPI table(s).\r
252 \r
253   @return EFI_SUCCESS  If freed successfully or other failure codes\r
254                         as returned by the generator.\r
255 **/\r
256 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_FREE_TABLEEX) (\r
257   IN      CONST ACPI_TABLE_GENERATOR                   * CONST This,\r
258   IN      CONST CM_STD_OBJ_ACPI_TABLE_INFO             * CONST AcpiTableInfo,\r
259   IN      CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   * CONST CfgMgrProtocol,\r
260   IN OUT        EFI_ACPI_DESCRIPTION_HEADER          *** CONST Table,\r
261   IN      CONST UINTN                                          TableCount\r
262   );\r
263 \r
264 /** The ACPI_TABLE_GENERATOR structure provides an interface that the\r
265     Table Manager can use to invoke the functions to build ACPI tables.\r
266 \r
267     Note: Although the Generator is required to implement at least\r
268           one pair of interfaces (BuildAcpiTable & FreeTableResources or\r
269           BuildAcpiTableEx & FreeTableResourcesEx) for generating the ACPI\r
270           table(s), if both pair of interfaces are implemented the extended\r
271           version will take precedence.\r
272 **/\r
273 typedef struct AcpiTableGenerator {\r
274   /// The ACPI table generator ID.\r
275   ACPI_TABLE_GENERATOR_ID                GeneratorID;\r
276 \r
277   /// String describing the ACPI table generator.\r
278   CONST CHAR16                         * Description;\r
279 \r
280   /// The ACPI table signature.\r
281   UINT32                                 AcpiTableSignature;\r
282 \r
283   /// The ACPI table revision.\r
284   UINT32                                 AcpiTableRevision;\r
285 \r
286   /// The minimum supported ACPI table revision.\r
287   UINT32                                 MinAcpiTableRevision;\r
288 \r
289   /// The ACPI table creator ID.\r
290   UINT32                                 CreatorId;\r
291 \r
292   /// The ACPI table creator revision.\r
293   UINT32                                 CreatorRevision;\r
294 \r
295   /// ACPI table build function pointer.\r
296   ACPI_TABLE_GENERATOR_BUILD_TABLE       BuildAcpiTable;\r
297 \r
298   /** The function to free any resources\r
299       allocated for building the ACPI table.\r
300   */\r
301   ACPI_TABLE_GENERATOR_FREE_TABLE        FreeTableResources;\r
302 \r
303   /// ACPI table extended build function pointer.\r
304   ACPI_TABLE_GENERATOR_BUILD_TABLEEX     BuildAcpiTableEx;\r
305 \r
306   /** The function to free any resources\r
307       allocated for building the ACPI table\r
308       using the extended interface.\r
309   */\r
310   ACPI_TABLE_GENERATOR_FREE_TABLEEX      FreeTableResourcesEx;\r
311 } ACPI_TABLE_GENERATOR;\r
312 \r
313 /** Register ACPI table factory generator.\r
314 \r
315   The ACPI table factory maintains a list of the Standard and OEM ACPI\r
316   table generators.\r
317 \r
318   @param [in]  Generator       Pointer to the ACPI table generator.\r
319 \r
320   @retval EFI_SUCCESS           The Generator was registered\r
321                                 successfully.\r
322   @retval EFI_INVALID_PARAMETER The Generator ID is invalid or\r
323                                 the Generator pointer is NULL.\r
324   @retval EFI_ALREADY_STARTED   The Generator for the Table ID is\r
325                                 already registered.\r
326 **/\r
327 EFI_STATUS\r
328 EFIAPI\r
329 RegisterAcpiTableGenerator (\r
330   IN CONST ACPI_TABLE_GENERATOR                 * CONST Generator\r
331   );\r
332 \r
333 /** Deregister ACPI generator.\r
334 \r
335   This function is called by the ACPI table generator to deregister itself\r
336   from the ACPI table factory.\r
337 \r
338   @param [in]  Generator       Pointer to the ACPI table generator.\r
339 \r
340   @retval EFI_SUCCESS           Success.\r
341   @retval EFI_INVALID_PARAMETER The generator is invalid.\r
342   @retval EFI_NOT_FOUND         The requested generator is not found\r
343                                 in the list of registered generators.\r
344 **/\r
345 EFI_STATUS\r
346 EFIAPI\r
347 DeregisterAcpiTableGenerator (\r
348   IN CONST ACPI_TABLE_GENERATOR                 * CONST Generator\r
349   );\r
350 \r
351 #pragma pack()\r
352 \r
353 #endif // ACPI_TABLE_GENERATOR_H_\r
354 \r