[RESEND PATCH v2] ARM64: ACPI: Update documentation for latest specification version
Al Stone
al.stone at linaro.org
Thu Mar 17 14:38:29 PDT 2016
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 at linaro.org> 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 at linaro.org>
>> Cc: Catalin Marinas <catalin.marinas at arm.com>
>> Cc: Will Deacon <will.deacon at arm.com>
>> Cc: Jonathan Corbet <corbet at lwn.net>
>> ---
>> 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 at linaro.org
-----------------------------------
More information about the linux-arm-kernel
mailing list