Documentation/arm64/arm-acpi.rst

2 ACPI on ARMv8 Servers
5 ACPI can be used for ARMv8 general purpose servers designed to follow
11 The ARMv8 kernel implements the reduced hardware model of ACPI version
15 by the specification can be found via http://www.uefi.org/acpi.
18 or cannot be described using the mechanisms defined in the required ACPI
19 specifications, then ACPI may not be a good fit for the hardware.
24 ACPI and Linux only, on an ARMv8 system -- that is, what Linux expects of
25 ACPI and what ACPI can expect of Linux.
28 Why ACPI on ARM?
30 Before examining the details of the interface between ACPI and Linux, it is
31 useful to understand why ACPI is being used.  Several technologies already
34 reasoning behind ACPI on ARMv8 servers.  Actually, we snitch a good portion
37 The short form of the rationale for ACPI on ARM is:
39 -  ACPI’s byte code (AML) allows the platform to encode hardware behavior,
44 -  ACPI’s OSPM defines a power management model that constrains what the
48 -  In the enterprise server environment, ACPI has established bindings (such
56    both DT and ACPI if they want to support multiple operating systems.  And,
60 -  The new ACPI governance process works well and Linux is now at the same
62    longer any reason to feel that ACPI only belongs to Windows or that
64    ACPI governance into the UEFI forum has significantly opened up the
66    changes being made to ACPI are being driven by Linux.
68 Key to the use of ACPI is the support model.  For servers in general, the
71 order to allow for orderly change over time.  ACPI frees the OS from needing
77 ACPI is also important because hardware and OS vendors have already worked
83 really just duplicates something that already works.  ACPI already does what
91 One of the primary motivations for ACPI is standardization, and using that
93 software and hardware are often used for long periods.  ACPI allows the
99 When a Linux driver or subsystem is first implemented using ACPI, it by
100 definition ends up requiring a specific version of the ACPI specification
101 -- it's baseline.  ACPI firmware must continue to work, even though it may
103 for that baseline version of ACPI.  There may be a need for additional drivers,
105 older kernel versions.  Further, ACPI firmware must also work with the most
111 ACPI support in drivers and subsystems for ARMv8 should never be mutually
117 Regardless of whether DT or ACPI is used, the kernel must always be capable
122 Booting using ACPI tables
124 The only defined method for passing ACPI tables to the kernel on ARMv8
126 means that ACPI is only supported on platforms that boot via UEFI.
128 When an ARMv8 system boots, it can either have DT information, ACPI tables,
131 present, the kernel will try to use ACPI tables, but only if they are present.
132 In neither is available, the kernel will not boot.  If acpi=force is used
133 on the command line, the kernel will attempt to use ACPI tables first, but
134 fall back to DT if there are no ACPI tables present.  The basic idea is that
137 Processing of ACPI tables may be disabled by passing acpi=off on the kernel
140 In order for the kernel to load and use ACPI tables, the UEFI implementation
142 the ACPI signature "RSD PTR ").  If this pointer is incorrect and acpi=force
143 is used, the kernel will disable ACPI and try to use DT to boot instead; the
144 kernel has, in effect, determined that ACPI tables are not present at that
148 the kernel by the ACPI core, using the address provided by UEFI.
150 The ACPI core will then locate and map in all other ACPI tables provided by
153 ACPI tables provided by the system firmware; the ACPI core will then traverse
156 The ACPI core will ignore any provided RSDT (Root System Description Table).
160 Further, the ACPI core will only use the 64-bit address fields in the FADT
161 (Fixed ACPI Description Table).  Any 32-bit address fields in the FADT will
164 Hardware reduced mode (see Section 4.1 of the ACPI 6.1 specification) will
165 be enforced by the ACPI core on arm64.  Doing so allows the ACPI core to
170 For the ACPI core to operate properly, and in turn provide the information
172 tables (all section numbers refer to the ACPI 6.1 specification):
178     -  FADT (Fixed ACPI Description Table), section 5.2.9
209 ACPI Detection
216 In non-driver code, if the presence of ACPI needs to be detected at
223 Device descriptions in ACPI should use standard recognized ACPI interfaces.
226 ACPI can be useful -- the driver takes into account that it may have less
232 and the drivers need to take them into account.  In ACPI, the assumption
235 value, this can be done in an ACPI method; all the driver needs to do is
238 by changing what the ACPI method does, and not the driver.
241 above are known as "bindings"; in ACPI, these are known as "Device Properties"
244 ACPI tables are described with a formal language called ASL, the ACPI
248 that looks like this: Name(KEY0, "value0").  An ACPI device driver would
250 However, using Name() this way has multiple problems: (1) ACPI limits
259 The _DSM object (ACPI Section 9.14.1) could also be used for conveying
269 object is described in the ACPI specification section 6.2.5, but this only
279 so that they may be used across all operating systems supporting ACPI.
286 to simply move all DT bindings into ACPI device properties, we can learn from
291 both DT bindings and ACPI device properties for device drivers have review
294 submitted at the same time.  A driver that supports ACPI and uses device
309 whether DT or ACPI is being used.  This API should be used [6]; it can
311 discourage divergence between DT bindings and ACPI device properties.
319 With ACPI, the kernel clock and regulator framework is not expected to be used
323 Power Resource Objects (ACPI section 7.1).  The ACPI core will then handle
325 get that to work, ACPI assumes each device has defined D-states and that these
326 can be controlled through the optional ACPI methods _PS0, _PS1, _PS2, and _PS3;
327 in ACPI, _PS0 is the method to invoke to turn a device full on, and _PS3 is for
341 The kernel ACPI code will also assume that the _PSx methods follow the normal
342 ACPI rules for such methods:
358 and avoid having to read special non-standard values from ACPI tables. Further,
365 ACPI makes the assumption that clocks are initialized by the firmware --
373 process to be abstracted out into some ACPI method that can be invoked
374 (please see the ACPI specification for further recommendations on standard
376 CPPC provides a much richer interface than ACPI methods.  If the clocks
380 they could do so by providing ACPI methods that could be invoked by Linux
383 standardized in the ACPI specification, and using them could tie a kernel
390 DO NOT remove any DT handling when adding ACPI support for a driver.  The
397 allow most divergence between ACPI and DT functionality to be kept local to
409          /* ACPI specific functionality */
432 ACPI::
444   MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
449 The ACPI specification changes regularly.  During the year 2014, for instance,
452 presented and discussed in the ASWG (ACPI Specification Working Group) which
453 is a part of the UEFI Forum.  The current version of the ACPI specification
459 It is the intent of the ARMv8 ACPI kernel code to follow the ACPI specification
462 vendors that provide bad ACPI tables or violate the standards in some way.
464 be avoided if possible.  If there are features missing from ACPI that preclude
478                        an ACPI method invokes the _OS method.  On ARM64
485 ACPI Objects
487 Detailed expectations for ACPI tables and object are listed in the file
505 [3] AMD ACPI for Seattle platform documentation
509 [4] http://www.uefi.org/acpi
510     please see the link for the "ACPI _DSD Device
513 [5] http://www.uefi.org/acpi
528 - Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section