DynamicTablesPkg/Include/AcpiTableGenerator.h

   1 /** @file
   2
   3   Copyright (c) 2017 - 2022, 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   EStdAcpiTableIdPcct,                          ///< PCCT Generator
 102   EStdAcpiTableIdMax
 103 } ESTD_ACPI_TABLE_ID;
 104
 105 /** This macro checks if the Table Generator ID is for an ACPI Table Generator.
 106
 107   @param [in] TableGeneratorId  The table generator ID.
 108
 109   @return TRUE if the table generator ID is for an ACPI Table
 110         Generator.
 111 **/
 112 #define IS_GENERATOR_TYPE_ACPI(TableGeneratorId) \
 113           (GET_TABLE_TYPE (TableGeneratorId) == ETableGeneratorTypeAcpi)
 114
 115 /** This macro checks if the Table Generator ID is for a standard ACPI
 116     Table Generator.
 117
 118   @param [in] TableGeneratorId  The table generator ID.
 119
 120   @return TRUE if the table generator ID is for a standard ACPI
 121           Table Generator.
 122 **/
 123 #define IS_VALID_STD_ACPI_GENERATOR_ID(TableGeneratorId)           \
 124           (                                                        \
 125           IS_GENERATOR_NAMESPACE_STD (TableGeneratorId) &&         \
 126           IS_GENERATOR_TYPE_ACPI (TableGeneratorId)     &&         \
 127           ((GET_TABLE_ID (GeneratorId) >= EStdAcpiTableIdRaw) &&   \
 128            (GET_TABLE_ID (GeneratorId) < EStdAcpiTableIdMax))      \
 129           )
 130
 131 /** This macro creates a standard ACPI Table Generator ID.
 132
 133   @param [in] TableId  The table generator ID.
 134
 135   @return a standard ACPI table generator ID.
 136 **/
 137 #define CREATE_STD_ACPI_TABLE_GEN_ID(TableId) \
 138           CREATE_TABLE_GEN_ID (               \
 139             ETableGeneratorTypeAcpi,          \
 140             ETableGeneratorNameSpaceStd,      \
 141             TableId                           \
 142             )
 143
 144 /** This macro creates an OEM ACPI Table Generator ID.
 145
 146   @param [in] TableId  The table generator ID.
 147
 148   @return an OEM ACPI table generator ID.
 149 **/
 150 #define CREATE_OEM_ACPI_TABLE_GEN_ID(TableId) \
 151           CREATE_TABLE_GEN_ID (               \
 152             ETableGeneratorTypeAcpi,          \
 153             ETableGeneratorNameSpaceOem,      \
 154             TableId                           \
 155             )
 156
 157 /** The Creator ID for the ACPI tables generated using
 158   the standard ACPI table generators.
 159 */
 160 #define TABLE_GENERATOR_CREATOR_ID_ARM  SIGNATURE_32('A', 'R', 'M', 'H')
 161
 162 /** A macro to initialise the common header part of EFI ACPI tables as
 163     defined by the EFI_ACPI_DESCRIPTION_HEADER structure.
 164
 165   @param [in] Signature The ACPI table signature.
 166   @param [in] Type      The ACPI table structure.
 167   @param [in] Revision  The ACPI table revision.
 168 **/
 169 #define ACPI_HEADER(Signature, Type, Revision)  {             \
 170           Signature,             /* UINT32  Signature */      \
 171           sizeof (Type),         /* UINT32  Length */         \
 172           Revision,              /* UINT8   Revision */       \
 173           0,                     /* UINT8   Checksum */       \
 174           { 0, 0, 0, 0, 0, 0 },  /* UINT8   OemId[6] */       \
 175           0,                     /* UINT64  OemTableId */     \
 176           0,                     /* UINT32  OemRevision */    \
 177           0,                     /* UINT32  CreatorId */      \
 178           0                      /* UINT32  CreatorRevision */ \
 179           }
 180
 181 /** A macro to dump the common header part of EFI ACPI tables as
 182     defined by the EFI_ACPI_DESCRIPTION_HEADER structure.
 183
 184   @param [in] AcpiHeader The pointer to the ACPI table header.
 185 **/
 186 #define DUMP_ACPI_TABLE_HEADER(AcpiHeader)                        \
 187           DEBUG ((                                                \
 188             DEBUG_INFO,                                           \
 189             "ACPI TABLE %c%c%c%c : Rev 0x%x : Length : 0x%x\n",   \
 190             (AcpiHeader->Signature & 0xFF),                       \
 191             ((AcpiHeader->Signature >> 8) & 0xFF),                \
 192             ((AcpiHeader->Signature >> 16) & 0xFF),               \
 193             ((AcpiHeader->Signature >> 24) & 0xFF),               \
 194             AcpiHeader->Revision,                                 \
 195             AcpiHeader->Length                                    \
 196             ));
 197
 198 /** Forward declarations.
 199 */
 200 typedef struct ConfigurationManagerProtocol EDKII_CONFIGURATION_MANAGER_PROTOCOL;
 201 typedef struct CmAStdObjAcpiTableInfo       CM_STD_OBJ_ACPI_TABLE_INFO;
 202 typedef struct AcpiTableGenerator           ACPI_TABLE_GENERATOR;
 203
 204 /** This function pointer describes the interface to ACPI table build
 205     functions provided by the ACPI table generator and called by the
 206     Table Manager to build an ACPI table.
 207
 208   @param [in]  This            Pointer to the ACPI table generator.
 209   @param [in]  AcpiTableInfo   Pointer to the ACPI table information.
 210   @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager
 211                                Protocol interface.
 212   @param [out] Table           Pointer to the generated ACPI table.
 213
 214   @return  EFI_SUCCESS If the table is generated successfully or other
 215                         failure codes as returned by the generator.
 216 **/
 217 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_BUILD_TABLE) (
 218   IN  CONST ACPI_TABLE_GENERATOR                           *This,
 219   IN  CONST CM_STD_OBJ_ACPI_TABLE_INFO             *CONST  AcpiTableInfo,
 220   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   *CONST  CfgMgrProtocol,
 221   OUT       EFI_ACPI_DESCRIPTION_HEADER                    **Table
 222   );
 223
 224 /** This function pointer describes the interface used by the
 225     Table Manager to give the generator an opportunity to free
 226     any resources allocated for building the ACPI table.
 227
 228   @param [in]      This           Pointer to the ACPI table generator.
 229   @param [in]      AcpiTableInfo  Pointer to the ACPI Table Info.
 230   @param [in]      CfgMgrProtocol Pointer to the Configuration Manager
 231                                   Protocol Interface.
 232   @param [in, out] Table          Pointer to the ACPI Table.
 233
 234   @return EFI_SUCCESS  If freed successfully or other failure codes
 235                         as returned by the generator.
 236 **/
 237 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_FREE_TABLE) (
 238   IN      CONST ACPI_TABLE_GENERATOR                   *CONST  This,
 239   IN      CONST CM_STD_OBJ_ACPI_TABLE_INFO             *CONST  AcpiTableInfo,
 240   IN      CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   *CONST  CfgMgrProtocol,
 241   IN OUT        EFI_ACPI_DESCRIPTION_HEADER           **CONST  Table
 242   );
 243
 244 /** This function pointer describes an extended interface to build
 245     ACPI Tables. The ACPI table generator can generate multiple
 246     ACPI Tables and return a pointer to the list of ACPI tables.
 247     The FreeTableResourcesEx() must be called to free any resources
 248     that may have been allocated using this interface.
 249
 250   @param [in]  This            Pointer to the ACPI table generator.
 251   @param [in]  AcpiTableInfo   Pointer to the ACPI table information.
 252   @param [in]  CfgMgrProtocol  Pointer to the Configuration Manager
 253                                Protocol interface.
 254   @param [out] Table           Pointer to a list of generated ACPI table(s).
 255   @param [out] TableCount      Number of generated ACPI table(s).
 256
 257   @return  EFI_SUCCESS If the table is generated successfully or other
 258                         failure codes as returned by the generator.
 259 **/
 260 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_BUILD_TABLEEX) (
 261   IN  CONST ACPI_TABLE_GENERATOR                           *This,
 262   IN  CONST CM_STD_OBJ_ACPI_TABLE_INFO             *CONST  AcpiTableInfo,
 263   IN  CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   *CONST  CfgMgrProtocol,
 264   OUT       EFI_ACPI_DESCRIPTION_HEADER                    ***Table,
 265   OUT       UINTN                                  *CONST  TableCount
 266   );
 267
 268 /** This function pointer describes an extended interface used by the
 269     Table Manager to give the generator an opportunity to free
 270     any resources allocated for building the ACPI table. This interface
 271     must be used in conjunction with the BuildAcpiTableEx interface.
 272
 273   @param [in]      This           Pointer to the ACPI table generator.
 274   @param [in]      AcpiTableInfo  Pointer to the ACPI Table Info.
 275   @param [in]      CfgMgrProtocol Pointer to the Configuration Manager
 276                                   Protocol Interface.
 277   @param [in, out] Table          Pointer to the list of ACPI Table(s).
 278   @param [in]      TableCount     Number of ACPI table(s).
 279
 280   @return EFI_SUCCESS  If freed successfully or other failure codes
 281                         as returned by the generator.
 282 **/
 283 typedef EFI_STATUS (*ACPI_TABLE_GENERATOR_FREE_TABLEEX) (
 284   IN      CONST ACPI_TABLE_GENERATOR                   *CONST  This,
 285   IN      CONST CM_STD_OBJ_ACPI_TABLE_INFO             *CONST  AcpiTableInfo,
 286   IN      CONST EDKII_CONFIGURATION_MANAGER_PROTOCOL   *CONST  CfgMgrProtocol,
 287   IN OUT        EFI_ACPI_DESCRIPTION_HEADER          ***CONST  Table,
 288   IN      CONST UINTN                                          TableCount
 289   );
 290
 291 /** The ACPI_TABLE_GENERATOR structure provides an interface that the
 292     Table Manager can use to invoke the functions to build ACPI tables.
 293
 294     Note: Although the Generator is required to implement at least
 295           one pair of interfaces (BuildAcpiTable & FreeTableResources or
 296           BuildAcpiTableEx & FreeTableResourcesEx) for generating the ACPI
 297           table(s), if both pair of interfaces are implemented the extended
 298           version will take precedence.
 299 **/
 300 typedef struct AcpiTableGenerator {
 301   /// The ACPI table generator ID.
 302   ACPI_TABLE_GENERATOR_ID               GeneratorID;
 303
 304   /// String describing the ACPI table generator.
 305   CONST CHAR16                          *Description;
 306
 307   /// The ACPI table signature.
 308   UINT32                                AcpiTableSignature;
 309
 310   /// The ACPI table revision.
 311   UINT8                                 AcpiTableRevision;
 312
 313   /// The minimum supported ACPI table revision.
 314   UINT8                                 MinAcpiTableRevision;
 315
 316   /// The ACPI table creator ID.
 317   UINT32                                CreatorId;
 318
 319   /// The ACPI table creator revision.
 320   UINT32                                CreatorRevision;
 321
 322   /// ACPI table build function pointer.
 323   ACPI_TABLE_GENERATOR_BUILD_TABLE      BuildAcpiTable;
 324
 325   /** The function to free any resources
 326       allocated for building the ACPI table.
 327   */
 328   ACPI_TABLE_GENERATOR_FREE_TABLE       FreeTableResources;
 329
 330   /// ACPI table extended build function pointer.
 331   ACPI_TABLE_GENERATOR_BUILD_TABLEEX    BuildAcpiTableEx;
 332
 333   /** The function to free any resources
 334       allocated for building the ACPI table
 335       using the extended interface.
 336   */
 337   ACPI_TABLE_GENERATOR_FREE_TABLEEX     FreeTableResourcesEx;
 338 } ACPI_TABLE_GENERATOR;
 339
 340 /** Register ACPI table factory generator.
 341
 342   The ACPI table factory maintains a list of the Standard and OEM ACPI
 343   table generators.
 344
 345   @param [in]  Generator       Pointer to the ACPI table generator.
 346
 347   @retval EFI_SUCCESS           The Generator was registered
 348                                 successfully.
 349   @retval EFI_INVALID_PARAMETER The Generator ID is invalid or
 350                                 the Generator pointer is NULL.
 351   @retval EFI_ALREADY_STARTED   The Generator for the Table ID is
 352                                 already registered.
 353 **/
 354 EFI_STATUS
 355 EFIAPI
 356 RegisterAcpiTableGenerator (
 357   IN CONST ACPI_TABLE_GENERATOR                 *CONST  Generator
 358   );
 359
 360 /** Deregister ACPI generator.
 361
 362   This function is called by the ACPI table generator to deregister itself
 363   from the ACPI table factory.
 364
 365   @param [in]  Generator       Pointer to the ACPI table generator.
 366
 367   @retval EFI_SUCCESS           Success.
 368   @retval EFI_INVALID_PARAMETER The generator is invalid.
 369   @retval EFI_NOT_FOUND         The requested generator is not found
 370                                 in the list of registered generators.
 371 **/
 372 EFI_STATUS
 373 EFIAPI
 374 DeregisterAcpiTableGenerator (
 375   IN CONST ACPI_TABLE_GENERATOR                 *CONST  Generator
 376   );
 377
 378 #pragma pack()
 379
 380 #endif // ACPI_TABLE_GENERATOR_H_