DynamicTablesPkg/Include/AcpiTableGenerator.h

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