^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ACPI on ARMv8 Servers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ACPI can be used for ARMv8 general purpose servers designed to follow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) the ARM SBSA (Server Base System Architecture) [0] and SBBR (Server
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Base Boot Requirements) [1] specifications. Please note that the SBBR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) can be retrieved simply by visiting [1], but the SBSA is currently only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) available to those with an ARM login due to ARM IP licensing concerns.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) The ARMv8 kernel implements the reduced hardware model of ACPI version
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 5.1 or later. Links to the specification and all external documents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) it refers to are managed by the UEFI Forum. The specification is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) available at http://www.uefi.org/specifications and documents referenced
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) by the specification can be found via http://www.uefi.org/acpi.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) If an ARMv8 system does not meet the requirements of the SBSA and SBBR,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) or cannot be described using the mechanisms defined in the required ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) specifications, then ACPI may not be a good fit for the hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) While the documents mentioned above set out the requirements for building
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) industry-standard ARMv8 servers, they also apply to more than one operating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) system. The purpose of this document is to describe the interaction between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) ACPI and Linux only, on an ARMv8 system -- that is, what Linux expects of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) ACPI and what ACPI can expect of Linux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Why ACPI on ARM?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Before examining the details of the interface between ACPI and Linux, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) useful to understand why ACPI is being used. Several technologies already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) exist in Linux for describing non-enumerable hardware, after all. In this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) section we summarize a blog post [2] from Grant Likely that outlines the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) reasoning behind ACPI on ARMv8 servers. Actually, we snitch a good portion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) of the summary text almost directly, to be honest.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) The short form of the rationale for ACPI on ARM is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) - ACPI’s byte code (AML) allows the platform to encode hardware behavior,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) while DT explicitly does not support this. For hardware vendors, being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) able to encode behavior is a key tool used in supporting operating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) system releases on new hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) - ACPI’s OSPM defines a power management model that constrains what the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) platform is allowed to do into a specific model, while still providing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) flexibility in hardware design.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - In the enterprise server environment, ACPI has established bindings (such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) as for RAS) which are currently used in production systems. DT does not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) Such bindings could be defined in DT at some point, but doing so means ARM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) and x86 would end up using completely different code paths in both firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) and the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) - Choosing a single interface to describe the abstraction between a platform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) and an OS is important. Hardware vendors would not be required to implement
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) both DT and ACPI if they want to support multiple operating systems. And,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) agreeing on a single interface instead of being fragmented into per OS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) interfaces makes for better interoperability overall.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) - The new ACPI governance process works well and Linux is now at the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) table as hardware vendors and other OS vendors. In fact, there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) longer any reason to feel that ACPI only belongs to Windows or that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) Linux is in any way secondary to Microsoft in this arena. The move of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) ACPI governance into the UEFI forum has significantly opened up the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) specification development process, and currently, a large portion of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) changes being made to ACPI are being driven by Linux.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Key to the use of ACPI is the support model. For servers in general, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) responsibility for hardware behaviour cannot solely be the domain of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) kernel, but rather must be split between the platform and the kernel, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) order to allow for orderly change over time. ACPI frees the OS from needing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) to understand all the minute details of the hardware so that the OS doesn’t
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) need to be ported to each and every device individually. It allows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) hardware vendors to take responsibility for power management behaviour without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) depending on an OS release cycle which is not under their control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) ACPI is also important because hardware and OS vendors have already worked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) out the mechanisms for supporting a general purpose computing ecosystem. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) infrastructure is in place, the bindings are in place, and the processes are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) in place. DT does exactly what Linux needs it to when working with vertically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) integrated devices, but there are no good processes for supporting what the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) server vendors need. Linux could potentially get there with DT, but doing so
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) really just duplicates something that already works. ACPI already does what
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) the hardware vendors need, Microsoft won’t collaborate on DT, and hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) vendors would still end up providing two completely separate firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) interfaces -- one for Linux and one for Windows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) Kernel Compatibility
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) One of the primary motivations for ACPI is standardization, and using that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) to provide backward compatibility for Linux kernels. In the server market,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) software and hardware are often used for long periods. ACPI allows the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) kernel and firmware to agree on a consistent abstraction that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) maintained over time, even as hardware or software change. As long as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) abstraction is supported, systems can be updated without necessarily having
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) to replace the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) When a Linux driver or subsystem is first implemented using ACPI, it by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) definition ends up requiring a specific version of the ACPI specification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) -- it's baseline. ACPI firmware must continue to work, even though it may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) not be optimal, with the earliest kernel version that first provides support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) for that baseline version of ACPI. There may be a need for additional drivers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) but adding new functionality (e.g., CPU power management) should not break
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) older kernel versions. Further, ACPI firmware must also work with the most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) recent version of the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Relationship with Device Tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) ACPI support in drivers and subsystems for ARMv8 should never be mutually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) exclusive with DT support at compile time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) At boot time the kernel will only use one description method depending on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) parameters passed from the boot loader (including kernel bootargs).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) Regardless of whether DT or ACPI is used, the kernel must always be capable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) of booting with either scheme (in kernels with both schemes enabled at compile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) time).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Booting using ACPI tables
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) The only defined method for passing ACPI tables to the kernel on ARMv8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) is via the UEFI system configuration table. Just so it is explicit, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) means that ACPI is only supported on platforms that boot via UEFI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) When an ARMv8 system boots, it can either have DT information, ACPI tables,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) or in some very unusual cases, both. If no command line parameters are used,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) the kernel will try to use DT for device enumeration; if there is no DT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) present, the kernel will try to use ACPI tables, but only if they are present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) In neither is available, the kernel will not boot. If acpi=force is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) on the command line, the kernel will attempt to use ACPI tables first, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) fall back to DT if there are no ACPI tables present. The basic idea is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) the kernel will not fail to boot unless it absolutely has no other choice.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) Processing of ACPI tables may be disabled by passing acpi=off on the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) command line; this is the default behavior.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) In order for the kernel to load and use ACPI tables, the UEFI implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) MUST set the ACPI_20_TABLE_GUID to point to the RSDP table (the table with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) the ACPI signature "RSD PTR "). If this pointer is incorrect and acpi=force
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) is used, the kernel will disable ACPI and try to use DT to boot instead; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) kernel has, in effect, determined that ACPI tables are not present at that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) point.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) If the pointer to the RSDP table is correct, the table will be mapped into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) the kernel by the ACPI core, using the address provided by UEFI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) The ACPI core will then locate and map in all other ACPI tables provided by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) using the addresses in the RSDP table to find the XSDT (eXtended System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Description Table). The XSDT in turn provides the addresses to all other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) ACPI tables provided by the system firmware; the ACPI core will then traverse
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) this table and map in the tables listed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) The ACPI core will ignore any provided RSDT (Root System Description Table).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) RSDTs have been deprecated and are ignored on arm64 since they only allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) for 32-bit addresses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) Further, the ACPI core will only use the 64-bit address fields in the FADT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) (Fixed ACPI Description Table). Any 32-bit address fields in the FADT will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) be ignored on arm64.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Hardware reduced mode (see Section 4.1 of the ACPI 6.1 specification) will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) be enforced by the ACPI core on arm64. Doing so allows the ACPI core to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) run less complex code since it no longer has to provide support for legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) hardware from other architectures. Any fields that are not to be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) hardware reduced mode must be set to zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) For the ACPI core to operate properly, and in turn provide the information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) the kernel needs to configure devices, it expects to find the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) tables (all section numbers refer to the ACPI 6.1 specification):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) - RSDP (Root System Description Pointer), section 5.2.5
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) - XSDT (eXtended System Description Table), section 5.2.8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) - FADT (Fixed ACPI Description Table), section 5.2.9
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) - DSDT (Differentiated System Description Table), section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 5.2.11.1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) - MADT (Multiple APIC Description Table), section 5.2.12
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) - GTDT (Generic Timer Description Table), section 5.2.24
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) - If PCI is supported, the MCFG (Memory mapped ConFiGuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Table), section 5.2.6, specifically Table 5-31.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) - If booting without a console=<device> kernel parameter is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) supported, the SPCR (Serial Port Console Redirection table),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) section 5.2.6, specifically Table 5-31.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) - If necessary to describe the I/O topology, SMMUs and GIC ITSs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) the IORT (Input Output Remapping Table, section 5.2.6, specifically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Table 5-31).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) - If NUMA is supported, the SRAT (System Resource Affinity Table)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) and SLIT (System Locality distance Information Table), sections
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 5.2.16 and 5.2.17, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) If the above tables are not all present, the kernel may or may not be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) able to boot properly since it may not be able to configure all of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) devices available. This list of tables is not meant to be all inclusive;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) in some environments other tables may be needed (e.g., any of the APEI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) tables from section 18) to support specific functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) ACPI Detection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) Drivers should determine their probe() type by checking for a null
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) value for ACPI_HANDLE, or checking .of_node, or other information in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) the device structure. This is detailed further in the "Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) Recommendations" section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) In non-driver code, if the presence of ACPI needs to be detected at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) run time, then check the value of acpi_disabled. If CONFIG_ACPI is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) set, acpi_disabled will always be 1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) Device Enumeration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) Device descriptions in ACPI should use standard recognized ACPI interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) These may contain less information than is typically provided via a Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) Tree description for the same device. This is also one of the reasons that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) ACPI can be useful -- the driver takes into account that it may have less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) detailed information about the device and uses sensible defaults instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) If done properly in the driver, the hardware can change and improve over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) time without the driver having to change at all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) Clocks provide an excellent example. In DT, clocks need to be specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) and the drivers need to take them into account. In ACPI, the assumption
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) is that UEFI will leave the device in a reasonable default state, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) any clock settings. If for some reason the driver needs to change a clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) value, this can be done in an ACPI method; all the driver needs to do is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) invoke the method and not concern itself with what the method needs to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) to change the clock. Changing the hardware can then take place over time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) by changing what the ACPI method does, and not the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) In DT, the parameters needed by the driver to set up clocks as in the example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) above are known as "bindings"; in ACPI, these are known as "Device Properties"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) and provided to a driver via the _DSD object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) ACPI tables are described with a formal language called ASL, the ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) Source Language (section 19 of the specification). This means that there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) are always multiple ways to describe the same thing -- including device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) properties. For example, device properties could use an ASL construct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) that looks like this: Name(KEY0, "value0"). An ACPI device driver would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) then retrieve the value of the property by evaluating the KEY0 object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) However, using Name() this way has multiple problems: (1) ACPI limits
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) names ("KEY0") to four characters unlike DT; (2) there is no industry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) wide registry that maintains a list of names, minimizing re-use; (3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) there is also no registry for the definition of property values ("value0"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) again making re-use difficult; and (4) how does one maintain backward
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) compatibility as new hardware comes out? The _DSD method was created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) to solve precisely these sorts of problems; Linux drivers should ALWAYS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) use the _DSD method for device properties and nothing else.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) The _DSM object (ACPI Section 9.14.1) could also be used for conveying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) device properties to a driver. Linux drivers should only expect it to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) be used if _DSD cannot represent the data required, and there is no way
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) to create a new UUID for the _DSD object. Note that there is even less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) regulation of the use of _DSM than there is of _DSD. Drivers that depend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) on the contents of _DSM objects will be more difficult to maintain over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) time because of this; as of this writing, the use of _DSM is the cause
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) of quite a few firmware problems and is not recommended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) Drivers should look for device properties in the _DSD object ONLY; the _DSD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) object is described in the ACPI specification section 6.2.5, but this only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) describes how to define the structure of an object returned via _DSD, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) how specific data structures are defined by specific UUIDs. Linux should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) only use the _DSD Device Properties UUID [5]:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) - UUID: daffd814-6eba-4d8c-8a91-bc9bbf4aa301
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) The UEFI Forum provides a mechanism for registering device properties [4]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) so that they may be used across all operating systems supporting ACPI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) Device properties that have not been registered with the UEFI Forum should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) not be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) Before creating new device properties, check to be sure that they have not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) been defined before and either registered in the Linux kernel documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) as DT bindings, or the UEFI Forum as device properties. While we do not want
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) to simply move all DT bindings into ACPI device properties, we can learn from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) what has been previously defined.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) If it is necessary to define a new device property, or if it makes sense to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) synthesize the definition of a binding so it can be used in any firmware,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) both DT bindings and ACPI device properties for device drivers have review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) processes. Use them both. When the driver itself is submitted for review
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) to the Linux mailing lists, the device property definitions needed must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) submitted at the same time. A driver that supports ACPI and uses device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) properties will not be considered complete without their definitions. Once
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) the device property has been accepted by the Linux community, it must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) registered with the UEFI Forum [4], which will review it again for consistency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) within the registry. This may require iteration. The UEFI Forum, though,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) will always be the canonical site for device property definitions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) It may make sense to provide notice to the UEFI Forum that there is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) intent to register a previously unused device property name as a means of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) reserving the name for later use. Other operating system vendors will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) also be submitting registration requests and this may help smooth the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) process.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) Once registration and review have been completed, the kernel provides an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) interface for looking up device properties in a manner independent of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) whether DT or ACPI is being used. This API should be used [6]; it can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) eliminate some duplication of code paths in driver probing functions and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) discourage divergence between DT bindings and ACPI device properties.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) Programmable Power Control Resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) ------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Programmable power control resources include such resources as voltage/current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) providers (regulators) and clock sources.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) With ACPI, the kernel clock and regulator framework is not expected to be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) at all.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) The kernel assumes that power control of these resources is represented with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) Power Resource Objects (ACPI section 7.1). The ACPI core will then handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) correctly enabling and disabling resources as they are needed. In order to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) get that to work, ACPI assumes each device has defined D-states and that these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) can be controlled through the optional ACPI methods _PS0, _PS1, _PS2, and _PS3;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) in ACPI, _PS0 is the method to invoke to turn a device full on, and _PS3 is for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) turning a device full off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) There are two options for using those Power Resources. They can:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) - be managed in a _PSx method which gets called on entry to power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) state Dx.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) - be declared separately as power resources with their own _ON and _OFF
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) methods. They are then tied back to D-states for a particular device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) via _PRx which specifies which power resources a device needs to be on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) while in Dx. Kernel then tracks number of devices using a power resource
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) and calls _ON/_OFF as needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) The kernel ACPI code will also assume that the _PSx methods follow the normal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) ACPI rules for such methods:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) - If either _PS0 or _PS3 is implemented, then the other method must also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) be implemented.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) - If a device requires usage or setup of a power resource when on, the ASL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) should organize that it is allocated/enabled using the _PS0 method.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) - Resources allocated or enabled in the _PS0 method should be disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) or de-allocated in the _PS3 method.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) - Firmware will leave the resources in a reasonable state before handing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) over control to the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) Such code in _PSx methods will of course be very platform specific. But,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) this allows the driver to abstract out the interface for operating the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) and avoid having to read special non-standard values from ACPI tables. Further,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) abstracting the use of these resources allows the hardware to change over time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) without requiring updates to the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) Clocks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) ------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) ACPI makes the assumption that clocks are initialized by the firmware --
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) UEFI, in this case -- to some working value before control is handed over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) to the kernel. This has implications for devices such as UARTs, or SoC-driven
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) LCD displays, for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) When the kernel boots, the clocks are assumed to be set to reasonable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) working values. If for some reason the frequency needs to change -- e.g.,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) throttling for power management -- the device driver should expect that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) process to be abstracted out into some ACPI method that can be invoked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) (please see the ACPI specification for further recommendations on standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) methods to be expected). The only exceptions to this are CPU clocks where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) CPPC provides a much richer interface than ACPI methods. If the clocks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) are not set, there is no direct way for Linux to control them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) If an SoC vendor wants to provide fine-grained control of the system clocks,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) they could do so by providing ACPI methods that could be invoked by Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) drivers. However, this is NOT recommended and Linux drivers should NOT use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) such methods, even if they are provided. Such methods are not currently
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) standardized in the ACPI specification, and using them could tie a kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) to a very specific SoC, or tie an SoC to a very specific version of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) kernel, both of which we are trying to avoid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) Driver Recommendations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) DO NOT remove any DT handling when adding ACPI support for a driver. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) same device may be used on many different systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) DO try to structure the driver so that it is data-driven. That is, set up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) a struct containing internal per-device state based on defaults and whatever
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) else must be discovered by the driver probe function. Then, have the rest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) of the driver operate off of the contents of that struct. Doing so should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) allow most divergence between ACPI and DT functionality to be kept local to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) the probe function instead of being scattered throughout the driver. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) static int device_probe_dt(struct platform_device *pdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) /* DT specific functionality */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) static int device_probe_acpi(struct platform_device *pdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) /* ACPI specific functionality */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) static int device_probe(struct platform_device *pdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) struct device_node node = pdev->dev.of_node;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) if (node)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) ret = device_probe_dt(pdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) else if (ACPI_HANDLE(&pdev->dev))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) ret = device_probe_acpi(pdev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) /* other initialization */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) /* Continue with any generic probe operations */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) DO keep the MODULE_DEVICE_TABLE entries together in the driver to make it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) clear the different names the driver is probed for, both from DT and from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) ACPI::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) static struct of_device_id virtio_mmio_match[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) { .compatible = "virtio,mmio", },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) { }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) MODULE_DEVICE_TABLE(of, virtio_mmio_match);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) static const struct acpi_device_id virtio_mmio_acpi_match[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) { "LNRO0005", },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) { }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) MODULE_DEVICE_TABLE(acpi, virtio_mmio_acpi_match);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) ASWG
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) ----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) The ACPI specification changes regularly. During the year 2014, for instance,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) version 5.1 was released and version 6.0 substantially completed, with most of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) the changes being driven by ARM-specific requirements. Proposed changes are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) presented and discussed in the ASWG (ACPI Specification Working Group) which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) is a part of the UEFI Forum. The current version of the ACPI specification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) is 6.1 release in January 2016.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) Participation in this group is open to all UEFI members. Please see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) http://www.uefi.org/workinggroup for details on group membership.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) It is the intent of the ARMv8 ACPI kernel code to follow the ACPI specification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) as closely as possible, and to only implement functionality that complies with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) the released standards from UEFI ASWG. As a practical matter, there will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) vendors that provide bad ACPI tables or violate the standards in some way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) If this is because of errors, quirks and fix-ups may be necessary, but will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) be avoided if possible. If there are features missing from ACPI that preclude
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) it from being used on a platform, ECRs (Engineering Change Requests) should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) submitted to ASWG and go through the normal approval process; for those that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) are not UEFI members, many other members of the Linux community are and would
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) likely be willing to assist in submitting ECRs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) Linux Code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) Individual items specific to Linux on ARM, contained in the Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) source code, are in the list that follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) ACPI_OS_NAME
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) This macro defines the string to be returned when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) an ACPI method invokes the _OS method. On ARM64
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) systems, this macro will be "Linux" by default.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) The command line parameter acpi_os=<string>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) can be used to set it to some other value. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) default value for other architectures is "Microsoft
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) Windows NT", for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) ACPI Objects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) Detailed expectations for ACPI tables and object are listed in the file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) Documentation/arm64/acpi_object_usage.rst.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) References
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) [0] http://silver.arm.com
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) document ARM-DEN-0029, or newer:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) "Server Base System Architecture", version 2.3, dated 27 Mar 2014
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) [1] http://infocenter.arm.com/help/topic/com.arm.doc.den0044a/Server_Base_Boot_Requirements.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) Document ARM-DEN-0044A, or newer: "Server Base Boot Requirements, System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) Software on ARM Platforms", dated 16 Aug 2014
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) [2] http://www.secretlab.ca/archives/151,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) 10 Jan 2015, Copyright (c) 2015,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) Linaro Ltd., written by Grant Likely.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) [3] AMD ACPI for Seattle platform documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) http://amd-dev.wpengine.netdna-cdn.com/wordpress/media/2012/10/Seattle_ACPI_Guide.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) [4] http://www.uefi.org/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) please see the link for the "ACPI _DSD Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) Property Registry Instructions"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) [5] http://www.uefi.org/acpi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) please see the link for the "_DSD (Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) Specific Data) Implementation Guide"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) [6] Kernel code for the unified device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) property interface can be found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) include/linux/property.h and drivers/base/property.c.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) Authors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) - Al Stone <al.stone@linaro.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) - Graeme Gregory <graeme.gregory@linaro.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) - Hanjun Guo <hanjun.guo@linaro.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) - Grant Likely <grant.likely@linaro.org>, for the "Why ACPI on ARM?" section
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags