EmbeddedPkg/Include/Library/AcpiLib.h

   1 /** @file
   2   Helper Library for ACPI
   3
   4   Copyright (c) 2014-2016, ARM Ltd. All rights reserved.
   5   Copyright (c) 2021, Ampere Computing LLC. All rights reserved.
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef __ACPI_LIB_H__
  12 #define __ACPI_LIB_H__
  13
  14 #include <Uefi.h>
  15
  16 #include <IndustryStandard/Acpi10.h>
  17 #include <Protocol/AcpiSystemDescriptionTable.h>
  18
  19 //
  20 // Macros for the Generic Address Space
  21 //
  22 #define NULL_GAS  { EFI_ACPI_5_0_SYSTEM_MEMORY,  0, 0, EFI_ACPI_5_0_UNDEFINED, 0L }
  23 #define ARM_GAS8(Address)   { EFI_ACPI_5_0_SYSTEM_MEMORY,  8, 0, EFI_ACPI_5_0_BYTE,      Address }
  24 #define ARM_GAS16(Address)  { EFI_ACPI_5_0_SYSTEM_MEMORY, 16, 0, EFI_ACPI_5_0_WORD,      Address }
  25 #define ARM_GAS32(Address)  { EFI_ACPI_5_0_SYSTEM_MEMORY, 32, 0, EFI_ACPI_5_0_DWORD,     Address }
  26 #define ARM_GASN(Address)   { EFI_ACPI_5_0_SYSTEM_MEMORY,  0, 0, EFI_ACPI_5_0_DWORD,     Address }
  27
  28 //
  29 // Macros for the Multiple APIC Description Table (MADT)
  30 //
  31 #define EFI_ACPI_5_0_GIC_DISTRIBUTOR_INIT(GicDistHwId, GicDistBase, GicDistVector) \
  32   { \
  33     EFI_ACPI_5_0_GICD, sizeof (EFI_ACPI_5_0_GIC_DISTRIBUTOR_STRUCTURE), EFI_ACPI_RESERVED_WORD, \
  34     GicDistHwId, GicDistBase, GicDistVector, EFI_ACPI_RESERVED_DWORD \
  35   }
  36
  37 #define EFI_ACPI_6_0_GIC_DISTRIBUTOR_INIT(GicDistHwId, GicDistBase, GicDistVector, GicVersion) \
  38   { \
  39     EFI_ACPI_6_0_GICD, sizeof (EFI_ACPI_6_0_GIC_DISTRIBUTOR_STRUCTURE), EFI_ACPI_RESERVED_WORD, \
  40     GicDistHwId, GicDistBase, GicDistVector, GicVersion, \
  41     {EFI_ACPI_RESERVED_BYTE, EFI_ACPI_RESERVED_BYTE, EFI_ACPI_RESERVED_BYTE} \
  42   }
  43
  44 // Note the parking protocol is configured by UEFI if required
  45 #define EFI_ACPI_5_0_GIC_STRUCTURE_INIT(GicId, AcpiCpuId, Flags, PmuIrq, GicBase) \
  46   { \
  47     EFI_ACPI_5_0_GIC, sizeof (EFI_ACPI_5_0_GIC_STRUCTURE), EFI_ACPI_RESERVED_WORD, \
  48     GicId, AcpiCpuId, Flags, 0, PmuIrq, 0, GicBase \
  49   }
  50
  51 // Note the parking protocol is configured by UEFI if required
  52 #define EFI_ACPI_5_1_GICC_STRUCTURE_INIT(GicId, AcpiCpuUid, Mpidr, Flags, PmuIrq,    \
  53                                          GicBase, GicVBase, GicHBase, GsivId, GicRBase)                                   \
  54   {                                                                                  \
  55     EFI_ACPI_5_1_GIC, sizeof (EFI_ACPI_5_1_GIC_STRUCTURE), EFI_ACPI_RESERVED_WORD,   \
  56     GicId, AcpiCpuUid, Flags, 0, PmuIrq, 0, GicBase, GicVBase, GicHBase,             \
  57     GsivId, GicRBase, Mpidr                                                          \
  58   }
  59
  60 #define EFI_ACPI_6_0_GICC_STRUCTURE_INIT(GicId, AcpiCpuUid, Mpidr, Flags, PmuIrq,    \
  61                                          GicBase, GicVBase, GicHBase, GsivId, GicRBase, Efficiency)                       \
  62   {                                                                                  \
  63     EFI_ACPI_6_0_GIC, sizeof (EFI_ACPI_6_0_GIC_STRUCTURE), EFI_ACPI_RESERVED_WORD,   \
  64     GicId, AcpiCpuUid, Flags, 0, PmuIrq, 0, GicBase, GicVBase, GicHBase,             \
  65     GsivId, GicRBase, Mpidr, Efficiency,                                             \
  66     {EFI_ACPI_RESERVED_BYTE, EFI_ACPI_RESERVED_BYTE, EFI_ACPI_RESERVED_BYTE}         \
  67   }
  68
  69 #define EFI_ACPI_6_3_GICC_STRUCTURE_INIT(GicId, AcpiCpuUid, Mpidr, Flags, PmuIrq,    \
  70                                          GicBase, GicVBase, GicHBase, GsivId, GicRBase, Efficiency, SpeOvflIrq)           \
  71   {                                                                                  \
  72     EFI_ACPI_6_0_GIC, sizeof (EFI_ACPI_6_3_GIC_STRUCTURE), EFI_ACPI_RESERVED_WORD,   \
  73     GicId, AcpiCpuUid, Flags, 0, PmuIrq, 0, GicBase, GicVBase, GicHBase,             \
  74     GsivId, GicRBase, Mpidr, Efficiency, EFI_ACPI_RESERVED_BYTE, SpeOvflIrq          \
  75   }
  76
  77 #define EFI_ACPI_6_0_GIC_MSI_FRAME_INIT(GicMsiFrameId, PhysicalBaseAddress, Flags, SPICount, SPIBase) \
  78   { \
  79     EFI_ACPI_6_0_GIC_MSI_FRAME, sizeof (EFI_ACPI_6_0_GIC_MSI_FRAME_STRUCTURE), EFI_ACPI_RESERVED_WORD, \
  80     GicMsiFrameId, PhysicalBaseAddress, Flags, SPICount, SPIBase \
  81   }
  82
  83 //
  84 // SBSA Generic Watchdog
  85 //
  86 #define EFI_ACPI_5_1_SBSA_GENERIC_WATCHDOG_STRUCTURE_INIT(RefreshFramePhysicalAddress,                  \
  87                                                           ControlFramePhysicalAddress, WatchdogTimerGSIV, WatchdogTimerFlags)                                 \
  88   {                                                                                                     \
  89     EFI_ACPI_5_1_GTDT_SBSA_GENERIC_WATCHDOG, sizeof(EFI_ACPI_5_1_GTDT_SBSA_GENERIC_WATCHDOG_STRUCTURE), \
  90     EFI_ACPI_RESERVED_BYTE, RefreshFramePhysicalAddress, ControlFramePhysicalAddress,                   \
  91     WatchdogTimerGSIV, WatchdogTimerFlags                                                               \
  92   }
  93
  94 typedef
  95 BOOLEAN
  96 (EFIAPI *EFI_LOCATE_ACPI_CHECK)(
  97   IN  EFI_ACPI_DESCRIPTION_HEADER *AcpiHeader
  98   );
  99
 100 /**
 101   Locate and Install the ACPI tables from the Firmware Volume if it verifies
 102   the function condition.
 103
 104   @param  AcpiFile                Guid of the ACPI file into the Firmware Volume
 105   @param  CheckAcpiTableFunction  Function that checks if the ACPI table should be installed
 106
 107   @return EFI_SUCCESS             The function completed successfully.
 108   @return EFI_NOT_FOUND           The protocol could not be located.
 109   @return EFI_OUT_OF_RESOURCES    There are not enough resources to find the protocol.
 110
 111 **/
 112 EFI_STATUS
 113 LocateAndInstallAcpiFromFvConditional (
 114   IN CONST EFI_GUID         *AcpiFile,
 115   IN EFI_LOCATE_ACPI_CHECK  CheckAcpiTableFunction
 116   );
 117
 118 /**
 119   Locate and Install the ACPI tables from the Firmware Volume
 120
 121   @param  AcpiFile              Guid of the ACPI file into the Firmware Volume
 122
 123   @return EFI_SUCCESS           The function completed successfully.
 124   @return EFI_NOT_FOUND         The protocol could not be located.
 125   @return EFI_OUT_OF_RESOURCES  There are not enough resources to find the protocol.
 126
 127 **/
 128 EFI_STATUS
 129 LocateAndInstallAcpiFromFv (
 130   IN CONST EFI_GUID  *AcpiFile
 131   );
 132
 133 /**
 134   This function calculates and updates a UINT8 checksum
 135   in an ACPI description table header.
 136
 137   @param  Buffer          Pointer to buffer to checksum
 138   @param  Size            Number of bytes to checksum
 139
 140   @retval EFI_SUCCESS             The function completed successfully.
 141   @retval EFI_INVALID_PARAMETER   Invalid parameter.
 142
 143 **/
 144 EFI_STATUS
 145 EFIAPI
 146 AcpiUpdateChecksum (
 147   IN OUT  UINT8  *Buffer,
 148   IN      UINTN  Size
 149   );
 150
 151 /**
 152   This function uses the ACPI SDT protocol to search an ACPI table
 153   with a given signature.
 154
 155   @param  AcpiTableSdtProtocol    Pointer to ACPI SDT protocol.
 156   @param  TableSignature          ACPI table signature.
 157   @param  Index                   The zero-based index of the table where to search the table.
 158                                   The index will be updated to the next instance if the table
 159                                   is found with the matched TableSignature.
 160   @param  Table                   Pointer to the table.
 161   @param  TableKey                Pointer to the table key.
 162
 163   @return EFI_SUCCESS             The function completed successfully.
 164   @return EFI_INVALID_PARAMETER   At least one of parameters is invalid.
 165   @retval EFI_NOT_FOUND           The requested index is too large and a table was not found.
 166
 167 **/
 168 EFI_STATUS
 169 EFIAPI
 170 AcpiLocateTableBySignature (
 171   IN      EFI_ACPI_SDT_PROTOCOL        *AcpiSdtProtocol,
 172   IN      UINT32                       TableSignature,
 173   IN OUT  UINTN                        *Index,
 174   OUT     EFI_ACPI_DESCRIPTION_HEADER  **Table,
 175   OUT     UINTN                        *TableKey
 176   );
 177
 178 /**
 179   This function updates the integer value of an AML Object.
 180
 181   @param  AcpiTableSdtProtocol    Pointer to ACPI SDT protocol.
 182   @param  TableHandle             Points to the table representing the starting point
 183                                   for the object path search.
 184   @param  AsciiObjectPath         Pointer to the ACPI path of the object being updated.
 185   @param  Value                   New value to write to the object.
 186
 187   @return EFI_SUCCESS             The function completed successfully.
 188   @return EFI_INVALID_PARAMETER   At least one of parameters is invalid or the data type
 189                                   of the ACPI object is not an integer value.
 190   @retval EFI_NOT_FOUND           The object is not found with the given path.
 191
 192 **/
 193 EFI_STATUS
 194 EFIAPI
 195 AcpiAmlObjectUpdateInteger (
 196   IN  EFI_ACPI_SDT_PROTOCOL  *AcpiSdtProtocol,
 197   IN  EFI_ACPI_HANDLE        TableHandle,
 198   IN  CHAR8                  *AsciiObjectPath,
 199   IN  UINTN                  Value
 200   );
 201
 202 #endif // __ACPI_LIB_H__