arch/arm64/arm-acpi.rst

10 of rules defined in SBSA (Server Base System Architecture) [2].
12 The Arm kernel implements the reduced hardware model of ACPI version
18 If an Arm system does not meet the requirements of the BSA and BBR,
23 industry-standard Arm systems, they also apply to more than one operating
24 system.  The purpose of this document is to describe the interaction between
25 ACPI and Linux only, on an Arm system -- that is, what Linux expects of
26 ACPI and what ACPI can expect of Linux.
30 ----------------
31 Before examining the details of the interface between ACPI and Linux, it is
33 exist in Linux for describing non-enumerable hardware, after all.  In this
36 of the summary text almost directly, to be honest.
38 The short form of the rationale for ACPI on Arm is:
40 -  ACPI’s byte code (AML) allows the platform to encode hardware behavior,
45 -  ACPI’s OSPM defines a power management model that constrains what the
49 -  In the enterprise server environment, ACPI has established bindings (such
55 -  Choosing a single interface to describe the abstraction between a platform
58    agreeing on a single interface instead of being fragmented into per OS
61 -  The new ACPI governance process works well and Linux is now at the same
64    Linux is in any way secondary to Microsoft in this arena.  The move of
66    specification development process, and currently, a large portion of the
69 Key to the use of ACPI is the support model.  For servers in general, the
70 responsibility for hardware behaviour cannot solely be the domain of the
73 to understand all the minute details of the hardware so that the OS doesn’t
75 hardware vendors to take responsibility for power management behaviour without
87 interfaces -- one for Linux and one for Windows.
91 --------------------
92 One of the primary motivations for ACPI is standardization, and using that
97 abstraction is supported, systems can be updated without necessarily having
101 definition ends up requiring a specific version of the ACPI specification
102 -- its baseline.  ACPI firmware must continue to work, even though it may
104 for that baseline version of ACPI.  There may be a need for additional drivers,
107 recent version of the kernel.
111 -----------------------------
118 Regardless of whether DT or ACPI is used, the kernel must always be capable
119 of booting with either scheme (in kernels with both schemes enabled at compile
123 Booting using ACPI tables
124 -------------------------
138 Processing of ACPI tables may be disabled by passing acpi=off on the kernel
159 for 32-bit addresses.
161 Further, the ACPI core will only use the 64-bit address fields in the FADT
162 (Fixed ACPI Description Table).  Any 32-bit address fields in the FADT will
165 Hardware reduced mode (see Section 4.1 of the ACPI 6.1 specification) will
175     -  RSDP (Root System Description Pointer), section 5.2.5
177     -  XSDT (eXtended System Description Table), section 5.2.8
179     -  FADT (Fixed ACPI Description Table), section 5.2.9
181     -  DSDT (Differentiated System Description Table), section
184     -  MADT (Multiple APIC Description Table), section 5.2.12
186     -  GTDT (Generic Timer Description Table), section 5.2.24
188     -  PPTT (Processor Properties Topology Table), section 5.2.30
190     -  DBG2 (DeBuG port table 2), section 5.2.6, specifically Table 5-6.
192     -  APMT (Arm Performance Monitoring unit Table), section 5.2.6, specifically Table 5-6.
194 …-  AGDI (Arm Generic diagnostic Dump and Reset Device Interface Table), section 5.2.6, specificall…
196     -  If PCI is supported, the MCFG (Memory mapped ConFiGuration
197        Table), section 5.2.6, specifically Table 5-6.
199     -  If booting without a console=<device> kernel parameter is
201        section 5.2.6, specifically Table 5-6.
203     -  If necessary to describe the I/O topology, SMMUs and GIC ITSs,
205        Table 5-6).
207     -  If NUMA is supported, the following tables are required:
209        - SRAT (System Resource Affinity Table), section 5.2.16
211        - SLIT (System Locality distance Information Table), section 5.2.17
213     -  If NUMA is supported, and the system contains heterogeneous memory,
216     -  If the ACPI Platform Error Interfaces are required, the following
219        - BERT (Boot Error Record Table, section 18.3.1)
221        - EINJ (Error INJection table, section 18.6.1)
223        - ERST (Error Record Serialization Table, section 18.5)
225        - HEST (Hardware Error Source Table, section 18.3.2)
227        - SDEI (Software Delegated Exception Interface table, section 5.2.6,
228          specifically Table 5-6)
230        - AEST (Arm Error Source Table, section 5.2.6,
231          specifically Table 5-6)
233        - RAS2 (ACPI RAS2 feature table, section 5.2.21)
235     -  If the system contains controllers using PCC channel, the
238     -  If the system contains a controller to capture board-level system state,
242     -  If NVDIMM is supported, the NFIT (NVDIMM Firmware Interface Table), section 5.2.26
244     -  If video framebuffer is present, the BGRT (Boot Graphics Resource Table), section 5.2.23
246     -  If IPMI is implemented, the SPMI (Server Platform Management Interface),
247        section 5.2.6, specifically Table 5-6.
249     -  If the system contains a CXL Host Bridge, the CEDT (CXL Early Discovery
250        Table), section 5.2.6, specifically Table 5-6.
252 …-  If the system supports MPAM, the MPAM (Memory Partitioning And Monitoring table), section 5.2.6,
253        specifically Table 5-6.
255     -  If the system lacks persistent storage, the IBFT (ISCSI Boot Firmware
256        Table), section 5.2.6, specifically Table 5-6.
260 able to boot properly since it may not be able to configure all of the
261 devices available.  This list of tables is not meant to be all inclusive;
262 in some environments other tables may be needed (e.g., any of the APEI
267 --------------
273 In non-driver code, if the presence of ACPI needs to be detected at
274 run time, then check the value of acpi_disabled. If CONFIG_ACPI is not
279 ------------------
282 Tree description for the same device.  This is also one of the reasons that
283 ACPI can be useful -- the driver takes into account that it may have less
286 time without the driver having to change at all.
302 Source Language (section 19 of the specification).  This means that there
303 are always multiple ways to describe the same thing -- including device
306 then retrieve the value of the property by evaluating the KEY0 object.
309 wide registry that maintains a list of names, minimizing re-use; (3)
310 there is also no registry for the definition of property values ("value0"),
311 again making re-use difficult; and (4) how does one maintain backward
313 to solve precisely these sorts of problems; Linux drivers should ALWAYS
320 regulation of the use of _DSM than there is of _DSD.  Drivers that depend
321 on the contents of _DSM objects will be more difficult to maintain over
322 time because of this; as of this writing, the use of _DSM is the cause
323 of quite a few firmware problems and is not recommended.
327 describes how to define the structure of an object returned via _DSD, and
331    - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
336 but not as "uefi-" common properties.
345 synthesize the definition of a binding so it can be used in any firmware,
350 properties will not be considered complete without their definitions.  Once
357 intent to register a previously unused device property name as a means of
363 interface for looking up device properties in a manner independent of
365 eliminate some duplication of code paths in driver probing functions and
370 ------------------------------------
377 The kernel assumes that power control of these resources is represented with
380 get that to work, ACPI assumes each device has defined D-states and that these
387    -  be managed in a _PSx method which gets called on entry to power
390    -  be declared separately as power resources with their own _ON and _OFF
391       methods.  They are then tied back to D-states for a particular device
393       while in Dx.  Kernel then tracks number of devices using a power resource
399    -  If either _PS0 or _PS3 is implemented, then the other method must also
402    -  If a device requires usage or setup of a power resource when on, the ASL
405    -  Resources allocated or enabled in the _PS0 method should be disabled
406       or de-allocated in the _PS3 method.
408    -  Firmware will leave the resources in a reasonable state before handing
411 Such code in _PSx methods will of course be very platform specific.  But,
413 and avoid having to read special non-standard values from ACPI tables. Further,
414 abstracting the use of these resources allows the hardware to change over time
415 without requiring updates to the driver.
419 ------
420 ACPI makes the assumption that clocks are initialized by the firmware --
421 UEFI, in this case -- to some working value before control is handed over
422 to the kernel.  This has implications for devices such as UARTs, or SoC-driven
426 working values.  If for some reason the frequency needs to change -- e.g.,
427 throttling for power management -- the device driver should expect that
434 If an SoC vendor wants to provide fine-grained control of the system clocks,
439 to a very specific SoC, or tie an SoC to a very specific version of the
440 kernel, both of which we are trying to avoid.
444 ----------------------
448 DO try to structure the driver so that it is data-driven.  That is, set up
449 a struct containing internal per-device state based on defaults and whatever
451 of the driver operate off of the contents of that struct.  Doing so should
453 the probe function instead of being scattered throughout the driver.  For
471          struct device_node node = pdev->dev.of_node;
476          else if (ACPI_HANDLE(&pdev->dev))
493   MODULE_DEVICE_TABLE(of, virtio_mmio_match);
503 ----
505 version 5.1 was released and version 6.0 substantially completed, with most of
506 the changes being driven by Arm-specific requirements.  Proposed changes are
508 is a part of the UEFI Forum.  The current version of the ACPI specification
514 It is the intent of the Arm ACPI kernel code to follow the ACPI specification
518 If this is because of errors, quirks and fix-ups may be necessary, but will
522 are not UEFI members, many other members of the Linux community are and would
527 ----------
541 ------------
547 ----------
549     document Arm-DEN-0094: "Arm Base System Architecture", version 1.0C, dated 6 Oct 2022
552     Document Arm-DEN-0044: "Arm Base Boot Requirements", version 2.0G, dated 15 Apr 2022
555     Document Arm-DEN-0029: "Arm Server Base System Architecture", version 7.1, dated 06 Oct 2022
562     https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf
570 -------
571 - Al Stone <al.stone@linaro.org>
572 - Graeme Gregory <graeme.gregory@linaro.org>
573 - Hanjun Guo <hanjun.guo@linaro.org>
575 - Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section