Commit 83ce0efc authored by Al Stone's avatar Al Stone Committed by Catalin Marinas

ARM64: ACPI: Update documentation for latest specification version

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.
Signed-off-by: default avatarAl Stone <al.stone@linaro.org>
Acked-by: default avatarLorenzo Pieralisi <lorenzo.pieralisi@arm.com>
Reviewed-by: default avatarHanjun Guo <hanjun.guo@linaro.org>
Reviewed-by: default avatarRoy Franz <roy.franz@hpe.com>
Signed-off-by: default avatarCatalin Marinas <catalin.marinas@arm.com>
parent 5e4c7549
This diff is collapsed.
...@@ -34,7 +34,7 @@ of the summary text almost directly, to be honest. ...@@ -34,7 +34,7 @@ of the summary text almost directly, to be honest.
The short form of the rationale for ACPI on ARM is: The short form of the rationale for ACPI on ARM is:
-- ACPI’s bytecode (AML) allows the platform to encode hardware behavior, -- ACPI’s byte code (AML) allows the platform to encode hardware behavior,
while DT explicitly does not support this. For hardware vendors, being while DT explicitly does not support this. For hardware vendors, being
able to encode behavior is a key tool used in supporting operating able to encode behavior is a key tool used in supporting operating
system releases on new hardware. system releases on new hardware.
...@@ -57,11 +57,11 @@ The short form of the rationale for ACPI on ARM is: ...@@ -57,11 +57,11 @@ The short form of the rationale for ACPI on ARM is:
-- The new ACPI governance process works well and Linux is now at the same -- The new ACPI governance process works well and Linux is now at the same
table as hardware vendors and other OS vendors. In fact, there is no table as hardware vendors and other OS vendors. In fact, there is no
longer any reason to feel that ACPI is only belongs to Windows or that longer any reason to feel that ACPI only belongs to Windows or that
Linux is in any way secondary to Microsoft in this arena. The move of Linux is in any way secondary to Microsoft in this arena. The move of
ACPI governance into the UEFI forum has significantly opened up the ACPI governance into the UEFI forum has significantly opened up the
specification development process, and currently, a large portion of the specification development process, and currently, a large portion of the
changes being made to ACPI is being driven by Linux. changes being made to ACPI are being driven by Linux.
Key to the use of ACPI is the support model. For servers in general, the Key to the use of ACPI is the support model. For servers in general, the
responsibility for hardware behaviour cannot solely be the domain of the responsibility for hardware behaviour cannot solely be the domain of the
...@@ -110,7 +110,7 @@ ACPI support in drivers and subsystems for ARMv8 should never be mutually ...@@ -110,7 +110,7 @@ ACPI support in drivers and subsystems for ARMv8 should never be mutually
exclusive with DT support at compile time. exclusive with DT support at compile time.
At boot time the kernel will only use one description method depending on At boot time the kernel will only use one description method depending on
parameters passed from the bootloader (including kernel bootargs). parameters passed from the boot loader (including kernel bootargs).
Regardless of whether DT or ACPI is used, the kernel must always be capable Regardless of whether DT or ACPI is used, the kernel must always be capable
of booting with either scheme (in kernels with both schemes enabled at compile of booting with either scheme (in kernels with both schemes enabled at compile
...@@ -159,7 +159,7 @@ Further, the ACPI core will only use the 64-bit address fields in the FADT ...@@ -159,7 +159,7 @@ Further, the ACPI core will only use the 64-bit address fields in the FADT
(Fixed ACPI Description Table). Any 32-bit address fields in the FADT will (Fixed ACPI Description Table). Any 32-bit address fields in the FADT will
be ignored on arm64. be ignored on arm64.
Hardware reduced mode (see Section 4.1 of the ACPI 5.1 specification) will Hardware reduced mode (see Section 4.1 of the ACPI 6.1 specification) will
be enforced by the ACPI core on arm64. Doing so allows the ACPI core to be enforced by the ACPI core on arm64. Doing so allows the ACPI core to
run less complex code since it no longer has to provide support for legacy run less complex code since it no longer has to provide support for legacy
hardware from other architectures. Any fields that are not to be used for hardware from other architectures. Any fields that are not to be used for
...@@ -167,7 +167,7 @@ hardware reduced mode must be set to zero. ...@@ -167,7 +167,7 @@ hardware reduced mode must be set to zero.
For the ACPI core to operate properly, and in turn provide the information For the ACPI core to operate properly, and in turn provide the information
the kernel needs to configure devices, it expects to find the following the kernel needs to configure devices, it expects to find the following
tables (all section numbers refer to the ACPI 5.1 specfication): tables (all section numbers refer to the ACPI 6.1 specification):
-- RSDP (Root System Description Pointer), section 5.2.5 -- RSDP (Root System Description Pointer), section 5.2.5
...@@ -185,9 +185,23 @@ tables (all section numbers refer to the ACPI 5.1 specfication): ...@@ -185,9 +185,23 @@ tables (all section numbers refer to the ACPI 5.1 specfication):
-- If PCI is supported, the MCFG (Memory mapped ConFiGuration -- If PCI is supported, the MCFG (Memory mapped ConFiGuration
Table), section 5.2.6, specifically Table 5-31. Table), section 5.2.6, specifically Table 5-31.
-- If booting without a console=<device> kernel parameter is
supported, the SPCR (Serial Port Console Redirection table),
section 5.2.6, specifically Table 5-31.
-- If necessary to describe the I/O topology, SMMUs and GIC ITSs,
the IORT (Input Output Remapping Table, section 5.2.6, specifically
Table 5-31).
-- If NUMA is supported, the SRAT (System Resource Affinity Table)
and SLIT (System Locality distance Information Table), sections
5.2.16 and 5.2.17, respectively.
If the above tables are not all present, the kernel may or may not be If the above tables are not all present, the kernel may or may not be
able to boot properly since it may not be able to configure all of the able to boot properly since it may not be able to configure all of the
devices available. devices available. This list of tables is not meant to be all inclusive;
in some environments other tables may be needed (e.g., any of the APEI
tables from section 18) to support specific functionality.
ACPI Detection ACPI Detection
...@@ -198,7 +212,7 @@ the device structure. This is detailed further in the "Driver ...@@ -198,7 +212,7 @@ the device structure. This is detailed further in the "Driver
Recommendations" section. Recommendations" section.
In non-driver code, if the presence of ACPI needs to be detected at In non-driver code, if the presence of ACPI needs to be detected at
runtime, then check the value of acpi_disabled. If CONFIG_ACPI is not run time, then check the value of acpi_disabled. If CONFIG_ACPI is not
set, acpi_disabled will always be 1. set, acpi_disabled will always be 1.
...@@ -233,7 +247,7 @@ that looks like this: Name(KEY0, "value0"). An ACPI device driver would ...@@ -233,7 +247,7 @@ that looks like this: Name(KEY0, "value0"). An ACPI device driver would
then retrieve the value of the property by evaluating the KEY0 object. then retrieve the value of the property by evaluating the KEY0 object.
However, using Name() this way has multiple problems: (1) ACPI limits However, using Name() this way has multiple problems: (1) ACPI limits
names ("KEY0") to four characters unlike DT; (2) there is no industry names ("KEY0") to four characters unlike DT; (2) there is no industry
wide registry that maintains a list of names, minimzing re-use; (3) wide registry that maintains a list of names, minimizing re-use; (3)
there is also no registry for the definition of property values ("value0"), there is also no registry for the definition of property values ("value0"),
again making re-use difficult; and (4) how does one maintain backward again making re-use difficult; and (4) how does one maintain backward
compatibility as new hardware comes out? The _DSD method was created compatibility as new hardware comes out? The _DSD method was created
...@@ -434,7 +448,8 @@ The ACPI specification changes regularly. During the year 2014, for instance, ...@@ -434,7 +448,8 @@ The ACPI specification changes regularly. During the year 2014, for instance,
version 5.1 was released and version 6.0 substantially completed, with most of version 5.1 was released and version 6.0 substantially completed, with most of
the changes being driven by ARM-specific requirements. Proposed changes are the changes being driven by ARM-specific requirements. Proposed changes are
presented and discussed in the ASWG (ACPI Specification Working Group) which presented and discussed in the ASWG (ACPI Specification Working Group) which
is a part of the UEFI Forum. is a part of the UEFI Forum. The current version of the ACPI specification
is 6.1 release in January 2016.
Participation in this group is open to all UEFI members. Please see Participation in this group is open to all UEFI members. Please see
http://www.uefi.org/workinggroup for details on group membership. http://www.uefi.org/workinggroup for details on group membership.
...@@ -443,7 +458,7 @@ It is the intent of the ARMv8 ACPI kernel code to follow the ACPI specification ...@@ -443,7 +458,7 @@ It is the intent of the ARMv8 ACPI kernel code to follow the ACPI specification
as closely as possible, and to only implement functionality that complies with as closely as possible, and to only implement functionality that complies with
the released standards from UEFI ASWG. As a practical matter, there will be the released standards from UEFI ASWG. As a practical matter, there will be
vendors that provide bad ACPI tables or violate the standards in some way. vendors that provide bad ACPI tables or violate the standards in some way.
If this is because of errors, quirks and fixups may be necessary, but will If this is because of errors, quirks and fix-ups may be necessary, but will
be avoided if possible. If there are features missing from ACPI that preclude be avoided if possible. If there are features missing from ACPI that preclude
it from being used on a platform, ECRs (Engineering Change Requests) should be it from being used on a platform, ECRs (Engineering Change Requests) should be
submitted to ASWG and go through the normal approval process; for those that submitted to ASWG and go through the normal approval process; for those that
...@@ -480,8 +495,7 @@ References ...@@ -480,8 +495,7 @@ References
Software on ARM Platforms", dated 16 Aug 2014 Software on ARM Platforms", dated 16 Aug 2014
[2] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015, [2] http://www.secretlab.ca/archives/151, 10 Jan 2015, Copyright (c) 2015,
Linaro Ltd., written by Grant Likely. A copy of the verbatim text (apart Linaro Ltd., written by Grant Likely.
from formatting) is also in Documentation/arm64/why_use_acpi.txt.
[3] AMD ACPI for Seattle platform documentation: [3] AMD ACPI for Seattle platform documentation:
http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment