On 03/15/2016 10:50 PM, Vikas Sajjan wrote: > Hi Al Stone, > > On Wed, Mar 16, 2016 at 1:58 AM, Al Stone <al.stone@xxxxxxxxxx> wrote: >> The ACPI 6.1 specification was recently released at the end of January 2016, >> but the arm64 kernel documentation for the use of ACPI was written for the >> 5.1 version of the spec. There were significant additions to the spec that >> had not yet been mentioned -- for example, the 6.0 mechanisms added to make >> it easier to define processors and low power idle states, as well as the >> 6.1 addition allowing regular interrupts (not just from GPIO) be used to >> signal ACPI general purpose events. >> >> This patch reflects going back through and examining the specs in detail >> and updating content appropriately. Whilst there, a few odds and ends of >> typos were caught as well. This brings the documentation up to date with >> ACPI 6.1 for arm64. >> >> RESEND: >> -- Corrected From: header and added missing Cc's >> >> Changes for v2: >> -- Clean up white space (Harb Abdulhahmid) >> -- Clarification on _CCA usage (Harb Abdulhamid) >> -- IORT moved to required from recommended (Hanjun Guo) >> -- Clarify IORT description (Hanjun Guo) >> >> Signed-off-by: Al Stone <al.stone@xxxxxxxxxx> >> Cc: Catalin Marinas <catalin.marinas@xxxxxxx> >> Cc: Will Deacon <will.deacon@xxxxxxx> >> Cc: Jonathan Corbet <corbet@xxxxxxx> >> --- >> Documentation/arm64/acpi_object_usage.txt | 445 ++++++++++++++++++++++-------- >> Documentation/arm64/arm-acpi.txt | 28 +- >> 2 files changed, 356 insertions(+), 117 deletions(-) >> >> diff --git a/Documentation/arm64/acpi_object_usage.txt b/Documentation/arm64/acpi_object_usage.txt >> index a6e1a18..29bc1a1 100644 >> --- a/Documentation/arm64/acpi_object_usage.txt >> +++ b/Documentation/arm64/acpi_object_usage.txt >> @@ -11,15 +11,16 @@ outside of the UEFI Forum (see Section 5.2.6 of the specification). >> >> For ACPI on arm64, tables also fall into the following categories: >> >> - -- Required: DSDT, FADT, GTDT, MADT, MCFG, RSDP, SPCR, XSDT >> + -- Required: DSDT, FADT, GTDT, IORT, MADT, MCFG, RSDP, SPCR, XSDT >> >> - -- Recommended: BERT, EINJ, ERST, HEST, SSDT >> + -- Recommended: BERT, EINJ, ERST, HEST, PCCT, SSDT >> >> - -- Optional: BGRT, CPEP, CSRT, DRTM, ECDT, FACS, FPDT, MCHI, MPST, >> - MSCT, RASF, SBST, SLIT, SPMI, SRAT, TCPA, TPM2, UEFI >> + -- Optional: BGRT, CPEP, CSRT, DBG2, DRTM, ECDT, FACS, FPDT, MCHI, >> + MPST, MSCT, NFIT, PMTT, RASF, SBST, SLIT, SPMI, SRAT, STAO, TCPA, >> + TPM2, UEFI, XENV >> >> - -- Not supported: BOOT, DBG2, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, >> - LPIT, MSDM, RSDT, SLIC, WAET, WDAT, WDRT, WPBT >> + -- Not supported: BOOT, DBGP, DMAR, ETDT, HPET, IBFT, IVRS, LPIT, >> + MSDM, OEMx, PSDT, RSDT, SLIC, WAET, WDAT, WDRT, WPBT >> >> >> Table Usage for ARMv8 Linux >> @@ -50,7 +51,8 @@ CSRT Signature Reserved (signature == "CSRT") >> >> DBG2 Signature Reserved (signature == "DBG2") >> == DeBuG port table 2 == >> - Microsoft only table, will not be supported. >> + License has changed and should be usable. Optional if used instead >> + of earlycon=<device> on the command line. >> >> DBGP Signature Reserved (signature == "DBGP") >> == DeBuG Port table == >> @@ -133,10 +135,11 @@ GTDT Section 5.2.24 (signature == "GTDT") >> >> HEST Section 18.3.2 (signature == "HEST") >> == Hardware Error Source Table == >> - Until further error source types are defined, use only types 6 (AER >> - Root Port), 7 (AER Endpoint), 8 (AER Bridge), or 9 (Generic Hardware >> - Error Source). Firmware first error handling is possible if and only >> - if Trusted Firmware is being used on arm64. >> + ARM-specific error sources have been defined; please use those or the >> + PCI types such as type 6 (AER Root Port), 7 (AER Endpoint), or 8 (AER >> + Bridge), or use type 9 (Generic Hardware Error Source). Firmware first >> + error handling is possible if and only if Trusted Firmware is being >> + used on arm64. >> >> Must be supplied if RAS support is provided by the platform. It >> is recommended this table be supplied. >> @@ -149,20 +152,27 @@ IBFT Signature Reserved (signature == "IBFT") >> == iSCSI Boot Firmware Table == >> Microsoft defined table, support TBD. >> >> +IORT Signature Reserved (signature == "IORT") >> + == Input Output Remapping Table == >> + arm64 only table, required in order to describe IO topology, SMMUs, >> + and GIC ITSs, and how those various components are connected together, >> + such as identifying which components are behind which SMMUs/ITSs. >> + >> IVRS Signature Reserved (signature == "IVRS") >> == I/O Virtualization Reporting Structure == >> x86_64 (AMD) only table, will not be supported. >> >> LPIT Signature Reserved (signature == "LPIT") >> == Low Power Idle Table == >> - x86 only table as of ACPI 5.1; future versions have been adapted for >> - use with ARM and will be recommended in order to support ACPI power >> - management. >> + x86 only table as of ACPI 5.1; starting with ACPI 6.0, processor >> + descriptions and power states on ARM platforms should use the DSDT >> + and define processor container devices (_HID ACPI0010, Section 8.4, >> + and more specifically 8.4.3 and and 8.4.4). >> >> MADT Section 5.2.12 (signature == "APIC") >> == Multiple APIC Description Table == >> Required for arm64. Only the GIC interrupt controller structures >> - should be used (types 0xA - 0xE). >> + should be used (types 0xA - 0xF). >> >> MCFG Signature Reserved (signature == "MCFG") >> == Memory-mapped ConFiGuration space == >> @@ -176,14 +186,38 @@ MPST Section 5.2.21 (signature == "MPST") >> == Memory Power State Table == >> Optional, not currently supported. >> >> +MSCT Section 5.2.19 (signature == "MSCT") >> + == Maximum System Characteristic Table == >> + Optional, not currently supported. >> + >> MSDM Signature Reserved (signature == "MSDM") >> == Microsoft Data Management table == >> Microsoft only table, will not be supported. >> >> -MSCT Section 5.2.19 (signature == "MSCT") >> - == Maximum System Characteristic Table == >> +NFIT Section 5.2.25 (signature == "NFIT") >> + == NVDIMM Firmware Interface Table == >> Optional, not currently supported. >> >> +OEMx Signature of "OEMx" only >> + == OEM Specific Tables == >> + All tables starting with a signature of "OEM" are reserved for OEM >> + use. Since these are not meant to be of general use but are limited >> + to very specific end users, they are not recommended for use and are >> + not supported by the kernel for arm64. >> + >> +PCCT Section 14.1 (signature == "PCCT) >> + == Platform Communications Channel Table == >> + Recommend for use on arm64, and required when using CPPC to control >> + power on the platform. >> + >> +PMTT Section 5.2.21.12 (signature == "PMTT") >> + == Platform Memory Topology Table == >> + Optional, but useful, but not currently supported. >> + >> +PSDT Section 5.2.11.3 (signature == "PSDT") >> + == Persistent System Description Table == >> + Obsolete table, will not be supported. >> + >> RASF Section 5.2.20 (signature == "RASF") >> == RAS Feature table == >> Optional, not currently supported. >> @@ -195,7 +229,7 @@ RSDP Section 5.2.5 (signature == "RSD PTR") >> RSDT Section 5.2.7 (signature == "RSDT") >> == Root System Description Table == >> Since this table can only provide 32-bit addresses, it is deprecated >> - on arm64, and will not be used. >> + on arm64, and will not be used. If provided, it will be ignored. >> >> SBST Section 5.2.14 (signature == "SBST") >> == Smart Battery Subsystem Table == >> @@ -207,7 +241,7 @@ SLIC Signature Reserved (signature == "SLIC") >> >> SLIT Section 5.2.17 (signature == "SLIT") >> == System Locality distance Information Table == >> - Optional in general, but required for NUMA systems. >> + Optional in general, but required for arm64 NUMA systems. >> >> SPCR Signature Reserved (signature == "SPCR") >> == Serial Port Console Redirection table == >> @@ -220,7 +254,7 @@ SPMI Signature Reserved (signature == "SPMI") >> SRAT Section 5.2.16 (signature == "SRAT") >> == System Resource Affinity Table == >> Optional, but if used, only the GICC Affinity structures are read. >> - To support NUMA, this table is required. >> + To support arm64 NUMA, this table is required. >> >> SSDT Section 5.2.11.2 (signature == "SSDT") >> == Secondary System Description Table == >> @@ -235,6 +269,11 @@ SSDT Section 5.2.11.2 (signature == "SSDT") >> These tables are optional, however. ACPI tables should contain only >> one DSDT but can contain many SSDTs. >> >> +STAO Signature Reserved (signature == "STAO") >> + == _STA Override table == >> + Optional, but only necessary in virtualized environments in order to >> + hide devices from guest OSs. >> + >> TCPA Signature Reserved (signature == "TCPA") >> == Trusted Computing Platform Alliance table == >> Optional, not currently supported, and may need changes to fully >> @@ -266,6 +305,10 @@ WPBT Signature Reserved (signature == "WPBT") >> == Windows Platform Binary Table == >> Microsoft only table, will not be supported. >> >> +XENV Signature Reserved (signature == "XENV") >> + == Xen project table == >> + Optional, used only by Xen at present. >> + >> XSDT Section 5.2.8 (signature == "XSDT") >> == eXtended System Description Table == >> Required for arm64. >> @@ -273,31 +316,57 @@ XSDT Section 5.2.8 (signature == "XSDT") >> >> ACPI Objects >> ------------ >> -The expectations on individual ACPI objects are discussed in the list that >> -follows: >> +The expectations on individual ACPI objects that are likely to be used are >> +shown in the list that follows: >> >> Name Section Usage for ARMv8 Linux >> ---- ------------ ------------------------------------------------- >> +_ACx 11.4.1 Use as needed. >> + >> _ADR 6.1.1 Use as needed. >> >> +_ALx 11.4.2 Use as needed. >> + >> +_ART 11.4.3 Use as needed. >> + >> _BBN 6.5.5 Use as needed; PCI-specific. >> >> -_BDN 6.5.3 Optional; not likely to be used on arm64. >> +_CCA 6.2.17 This method must be defined for all bus masters >> + on arm64 -- there are no assumptions made about >> + whether such devices are cache coherent or not. >> + The _CCA value is inherited by all descendants of >> + these devices so it does not need to be repeated. >> + Without _CCA on arm64, the kernel does not know what >> + to do about setting up DMA for the device. >> >> -_CCA 6.2.17 This method should be defined for all bus masters >> - on arm64. While cache coherency is assumed, making >> - it explicit ensures the kernel will set up DMA as >> - it should. >> + NB: this method provides default cache coherency >> + attributes; the presence of an SMMU can be used to >> + modify that, however. For example, a master could >> + default to non-coherent, but be made coherent with >> + the appropriate SMMU configuration (see Table 17 of >> + the IORT specification, ARM Document DEN 0049B). >> >> -_CDM 6.2.1 Optional, to be used only for processor devices. >> +_CDM 6.2.1 Use as needed, to be used only for processor devices. >> >> -_CID 6.1.2 Use as needed. >> +_CID 6.1.2 Use as needed, see also _HID. >> >> -_CLS 6.1.3 Use as needed. >> +_CLS 6.1.3 Use as needed, see also _HID. >> + >> +_CPC 8.4.7.1 Use as needed; power management specific. CPPC is >> + recommended on arm64. >> + >> +_CR3 11.4.5 Use as needed. >> >> _CRS 6.2.2 Required on arm64. >> >> -_DCK 6.5.2 Optional; not likely to be used on arm64. >> +_CRT 11.4.4 Use as needed. >> + >> +_CSD 8.4.2.2 Use as needed, used only in conjuction with _CST. >> + >> +_CST 8.4.2.1 Low power idle states (8.4.4) are recommended instead >> + of C-states. >> + >> +_CWS 9.18.6 Use as needed. >> >> _DDN 6.1.4 This field can be used for a device name. However, >> it is meant for DOS device names (e.g., COM1), so be >> @@ -305,11 +374,11 @@ _DDN 6.1.4 This field can be used for a device name. However, >> >> _DEP 6.5.8 Use as needed. >> >> -_DIS 6.2.3 Optional, for power management use. >> +_DIS 6.2.3 Use as needed, for power management use. >> >> -_DLM 5.7.5 Optional. >> +_DLM 5.7.5 Use as needed. >> >> -_DMA 6.2.4 Optional. >> +_DMA 6.2.4 Use as needed. >> >> _DSD 6.2.5 To be used with caution. If this object is used, try >> to use it within the constraints already defined by the >> @@ -325,19 +394,29 @@ _DSD 6.2.5 To be used with caution. If this object is used, try >> with the UEFI Forum; this may cause some iteration as >> more than one OS will be registering entries. >> >> -_DSM Do not use this method. It is not standardized, the >> +_DSM 9.1.1 Do not use this method. It is not standardized, the >> return values are not well documented, and it is >> currently a frequent source of error. >> >> -_DSW 7.2.1 Use as needed; power management specific. >> +_DSW 7.3.1 Use as needed; power management specific. >> >> -_EDL 6.3.1 Optional. >> +_DTI 11.4.6 Use as needed. >> >> -_EJD 6.3.2 Optional. >> +_EDL 6.3.1 Use as needed. >> >> -_EJx 6.3.3 Optional. >> +_EJD 6.3.2 Use as needed. >> >> -_FIX 6.2.7 x86 specific, not used on arm64. >> +_EJx 6.3.3 Use as needed. >> + >> +_FIF 11.3.1.1 Use as needed. >> + >> +_FPS 11.3.1.2 Use as needed. >> + >> +_FSL 11.3.1.3 Use as needed. >> + >> +_FST 11.3.1.4 Use as needed. >> + >> +_GCP 9.18.2 Use as needed. >> >> \_GL 5.7.1 This object is not to be used in hardware reduced >> mode, and therefore should not be used on arm64. >> @@ -349,35 +428,57 @@ _GLK 6.5.7 This object requires a global lock be defined; there >> \_GPE 5.3.1 This namespace is for x86 use only. Do not use it >> on arm64. >> >> -_GSB 6.2.7 Optional. >> +_GRT 9.18.3 Use as needed. >> + >> +_GSB 6.2.7 Use as needed. >> + >> +_GTF 9.9.1.1 Use as needed. >> + >> +_GWS 9.18.5 Use as needed. >> >> _HID 6.1.5 Use as needed. This is the primary object to use in >> device probing, though _CID and _CLS may also be used. >> >> -_HPP 6.2.8 Optional, PCI specific. >> +_HOT 11.4.7 Use as needed. >> + >> +_HPP 6.2.8 Use as needed, PCI specific. >> >> -_HPX 6.2.9 Optional, PCI specific. >> +_HPX 6.2.9 Use as needed, PCI specific. >> >> -_HRV 6.1.6 Optional, use as needed to clarify device behavior; in >> - some cases, this may be easier to use than _DSD. >> +_HRV 6.1.6 Use as needed, use as needed to clarify device >> + behavior; in some cases, this may be easier to use >> + than _DSD. >> >> _INI 6.5.1 Not required, but can be useful in setting up devices >> when UEFI leaves them in a state that may not be what >> the driver expects before it starts probing. >> >> -_IRC 7.2.15 Use as needed; power management specific. >> +_IRC 7.3.15 Use as needed; power management specific. >> + >> +_LCK 6.3.4 Use as needed. >> + >> +_LPI 8.4.4.3 Use as needed, but recommended for use with processor >> + definitions (_HID ACPI0010) on arm64. >> >> -_LCK 6.3.4 Optional. >> +_MAT 6.2.10 Use as needed; see also the MADT. >> >> -_MAT 6.2.10 Optional; see also the MADT. >> +_MBM 9.13.2.1 Use as needed. >> >> -_MLS 6.1.7 Optional, but highly recommended for use in >> +_MLS 6.1.7 Use as needed, but highly recommended for use in >> internationalization. >> >> -_OFF 7.1.2 It is recommended to define this method for any device >> +_MSG 9.2.2 Use as needed. >> + >> +_MSM 9.13.2.2 Use as needed. >> + >> +_MTL 11.4.8 Use as needed. >> + >> +_NTT 11.4.9 Use as needed. >> + >> +_OFF 7.2.2 It is recommended to define this method for any device >> that can be turned on or off. >> >> -_ON 7.1.3 It is recommended to define this method for any device >> +_ON 7.2.3 It is recommended to define this method for any device >> that can be turned on or off. >> >> \_OS 5.7.3 This method will return "Linux" by default (this is >> @@ -405,115 +506,219 @@ _OSC 6.2.11 This method can be a global method in ACPI (i.e., >> being used or what functionality is provided. The >> _OSC method is to be used instead. >> >> -_OST 6.3.5 Optional. >> +_OST 6.3.5 Use as needed. >> + >> +_PCT 8.4.6.1 Use as needed; power management specific. >> >> _PDC 8.4.1 Deprecated, do not use on arm64. >> >> +_PDL 8.4.6.2 Use as needed; power management specific. >> + >> \_PIC 5.8.1 The method should not be used. On arm64, the only >> interrupt model available is GIC. >> >> -_PLD 6.1.8 Optional. >> +_PLD 6.1.8 Use as needed. >> + >> +_PPC 8.4.6.3 Use as needed; power management specific. >> + >> +_PPE 8.4.8 Use as needed. >> >> \_PR 5.3.1 This namespace is for x86 use only on legacy systems. >> Do not use it on arm64. >> >> -_PRS 6.2.12 Optional. >> +_PRE 7.3.12 Use as needed; power management specific. >> + >> +_PRR 7.3.26 Use as needed; power management specific. >> + >> +_PRS 6.2.12 Use as needed. >> >> _PRT 6.2.13 Required as part of the definition of all PCI root >> devices. >> >> -_PRW 7.2.13 Use as needed; power management specific. >> +_PRW 7.3.13 Use as needed; power management specific. >> >> -_PRx 7.2.8-11 Use as needed; power management specific. If _PR0 is >> +_PRx 7.3.8-11 Use as needed; power management specific. If _PR0 is >> defined, _PR3 must also be defined. >> >> -_PSC 7.2.6 Use as needed; power management specific. >> +_PSC 7.3.6 Use as needed; power management specific. >> + >> +_PSD 8.4.6.5 Use as needed; power management specific. >> >> -_PSE 7.2.7 Use as needed; power management specific. >> +_PSE 7.3.7 Use as needed; power management specific. >> >> -_PSW 7.2.14 Use as needed; power management specific. >> +_PSL 11.4.10 Use as needed. >> >> -_PSx 7.2.2-5 Use as needed; power management specific. If _PS0 is >> +_PSS 8.4.6.2 Use as needed; power management specific. >> + >> +_PSV 11.4.11 Use as needed. >> + >> +_PSW 7.3.14 Use as needed; power management specific. >> + >> +_PSx 7.3.2-5 Use as needed; power management specific. If _PS0 is >> defined, _PS3 must also be defined. If clocks or >> regulators need adjusting to be consistent with power >> usage, change them in these methods. >> >> -\_PTS 7.3.1 Use as needed; power management specific. >> +_PTC 8.4.5.1 Use as needed; power management specific. >> + >> +\_PTS 7.4.1 Use as needed; power management specific. >> + >> +_PUR 8.5.1.1 Use as needed. >> + >> +_PXM 6.2.14 Use as needed. >> >> -_PXM 6.2.14 Optional. >> +_RDI 8.4.4.4 Use as needed, but recommended for use with processor >> + definitions (_HID ACPI0010) on arm64. >> > > Should we also mention here that _RDI used only in conjuction with _LPI. > > Because as per section 8.4.4.4 "The dependency between the power > resources and the LPI state is described in _RDI" > It definitely wouldn't hurt. I've tried to avoid duplicating content in the spec and focus on how this applies to arm64 in particular; I'll play with some wording and see if I can make it work, though. Thanks for the review. -- ciao, al ----------------------------------- Al Stone Software Engineer Linaro Enterprise Group al.stone@xxxxxxxxxx ----------------------------------- -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
