[mirror_edk2.git] / EmbeddedPkg / Include / Library / AcpiLib.h

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