^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. include:: <isonum.txt>
^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 Device Tree - Representation of ACPI Namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ===================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) :Copyright: |copy| 2013, Intel Corporation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) :Author: Lv Zheng <lv.zheng@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) :Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) Rafael J.Wysocki <rafael.j.wysocki@intel.com>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Abstract
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) The Linux ACPI subsystem converts ACPI namespace objects into a Linux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) receiving ACPI hotplug notification events. For each device object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) in this hierarchy there is a corresponding symbolic link in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) /sys/bus/acpi/devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) This document illustrates the structure of the ACPI device tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) ACPI Definition Blocks
^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) The ACPI firmware sets up RSDP (Root System Description Pointer) in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) system memory address space pointing to the XSDT (Extended System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) Description Table). The XSDT always points to the FADT (Fixed ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Description Table) using its first entry, the data within the FADT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) includes various fixed-length entries that describe fixed ACPI features
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) of the hardware. The FADT contains a pointer to the DSDT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) (Differentiated System Descripition Table). The XSDT also contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) entries pointing to possibly multiple SSDTs (Secondary System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Description Table).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) The DSDT and SSDT data is organized in data structures called definition
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) blocks that contain definitions of various objects, including ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) control methods, encoded in AML (ACPI Machine Language). The data block
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) of the DSDT along with the contents of SSDTs represents a hierarchical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) data structure called the ACPI namespace whose topology reflects the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) structure of the underlying hardware platform.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The relationships between ACPI System Definition Tables described above
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) are illustrated in the following diagram::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) +---------+ +-------+ +--------+ +------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) | RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) +---------+ | +-------+ | +--------+ +-|->| DSDT | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) | Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) | Pointer |-+ | ..... | | ...... | | +-------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) +---------+ +-------+ +--------+ | +-------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) | Entry |------------------|->| SSDT | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) +- - - -+ | +-------------------| |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) | Entry | - - - - - - - -+ | | Definition Blocks | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) +- - - -+ | | +-------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) | | +- - - - - - - - - -+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) +-|->| SSDT | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) | +-------------------+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) | | Definition Blocks | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) | +- - - - - - - - - -+ |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) +------------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) OSPM Loading |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) \|/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) +----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) | ACPI Namespace |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) +----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) Figure 1. ACPI Definition Blocks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) .. note:: RSDP can also contain a pointer to the RSDT (Root System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) Description Table). Platforms provide RSDT to enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) compatibility with ACPI 1.0 operating systems. The OS is expected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) to use XSDT, if present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) Example ACPI Namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) All definition blocks are loaded into a single namespace. The namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) is a hierarchy of objects identified by names and paths.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) The following naming conventions apply to object names in the ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) namespace:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) 1. All names are 32 bits long.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) 2. The first byte of a name must be one of 'A' - 'Z', '_'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) - '9', '_'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) 4. Names starting with '_' are reserved by the ACPI specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) 5. The '\' symbol represents the root of the namespace (i.e. names
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) prepended with '\' are relative to the namespace root).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) 6. The '^' symbol represents the parent of the current namespace node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) (i.e. names prepended with '^' are relative to the parent of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) current namespace node).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) The figure below shows an example ACPI namespace::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) | \ | Root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) +-| _PR | Scope(_PR): the processor namespace
^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) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) | +-| CPU0 | Processor(CPU0): the first processor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) +-| _SB | Scope(_SB): the system bus namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) | +-| LID0 | Device(LID0); the lid device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) | | +------+
^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) | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) | | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) | | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) | | +-| _STA | Method(_STA): the status control method
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) | +-| PCI0 | Device(PCI0); the PCI root bridge
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) | +-| RP03 | Scope(RP03): the PCI0 power scope
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) | | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) | +-| GFX0 | Device(GFX0): the graphics adapter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) | +-| DD01 | Device(DD01): the LCD output device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) | +-| _BCL | Method(_BCL): the backlight control method
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) +-| _TZ | Scope(_TZ): the thermal zone namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) | +-| FN00 | PowerResource(FN00): the FAN0 power resource
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) | +-| FAN0 | Device(FAN0): the FAN0 cooling device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) | | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) | | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) | +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) +-| _GPE | Scope(_GPE): the GPE namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) +------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) Figure 2. Example ACPI Namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) Linux ACPI Device Objects
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) The Linux kernel's core ACPI subsystem creates struct acpi_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) objects for ACPI namespace objects representing devices, power resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) processors, thermal zones. Those objects are exported to user space via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) format of their names is <bus_id:instance>, where 'bus_id' refers to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) ACPI namespace representation of the given object and 'instance' is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) for distinguishing different object of the same 'bus_id' (it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) two-digit decimal representation of an unsigned integer).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) The value of 'bus_id' depends on the type of the object whose name it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) part of as listed in the table below::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) | | Object/Feature | Table | bus_id |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) | N | Root | xSDT | LNXSYSTM |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) | N | Device | xSDT | _HID |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) | N | Processor | xSDT | LNXCPU |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) | N | ThermalZone | xSDT | LNXTHERM |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) | N | PowerResource | xSDT | LNXPOWER |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) | N | Other Devices | xSDT | device |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) | F | PWR_BUTTON | FADT | LNXPWRBN |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) | F | SLP_BUTTON | FADT | LNXSLPBN |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) | M | Video Extension | xSDT | LNXVIDEO |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) | M | ATA Controller | xSDT | LNXIOBAY |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) | M | Docking Station | xSDT | LNXDOCK |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) +---+-----------------+-------+----------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) Table 1. ACPI Namespace Objects Mapping
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) The following rules apply when creating struct acpi_device objects on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) the basis of the contents of ACPI System Description Tables (as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) indicated by the letter in the first column and the notation in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) second column of the table above):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) N:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) The object's source is an ACPI namespace node (as indicated by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) named object's type in the second column). In that case the object's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) directory in sysfs will contain the 'path' attribute whose value is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) the full path to the node from the namespace root.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) F:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) The struct acpi_device object is created for a fixed hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) feature (as indicated by the fixed feature flag's name in the second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) column), so its sysfs directory will not contain the 'path'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) M:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) The struct acpi_device object is created for an ACPI namespace node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) with specific control methods (as indicated by the ACPI defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) device's type in the second column). The 'path' attribute containing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) its namespace path will be present in its sysfs directory. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) example, if the _BCL method is present for an ACPI namespace node, a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) struct acpi_device object with LNXVIDEO 'bus_id' will be created for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) The third column of the above table indicates which ACPI System
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) Description Tables contain information used for the creation of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) struct acpi_device objects represented by the given row (xSDT means DSDT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) or SSDT).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) The fourth column of the above table indicates the 'bus_id' generation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) rule of the struct acpi_device object:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) _HID:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) _HID in the last column of the table means that the object's bus_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) is derived from the _HID/_CID identification objects present under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) the corresponding ACPI namespace node. The object's sysfs directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) will then contain the 'hid' and 'modalias' attributes that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) used to retrieve the _HID and _CIDs of that object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) LNXxxxxx:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) The 'modalias' attribute is also present for struct acpi_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) objects having bus_id of the "LNXxxxxx" form (pseudo devices), in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) which cases it contains the bus_id string itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) device:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) 'device' in the last column of the table indicates that the object's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) bus_id cannot be determined from _HID/_CID of the corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) ACPI namespace node, although that object represents a device (for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) example, it may be a PCI device with _ADR defined and without _HID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) or _CID). In that case the string 'device' will be used as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) object's bus_id.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) Linux ACPI Physical Device Glue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) ACPI device (i.e. struct acpi_device) objects may be linked to other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) objects in the Linux' device hierarchy that represent "physical" devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) (for example, devices on the PCI bus). If that happens, it means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) the ACPI device object is a "companion" of a device otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) represented in a different way and is used (1) to provide configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) information on that device which cannot be obtained by other means and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) (2) to do specific things to the device with the help of its ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) control methods. One ACPI device object may be linked this way to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) multiple "physical" devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) If an ACPI device object is linked to a "physical" device, its sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) directory contains the "physical_node" symbolic link to the sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) directory of the target device object. In turn, the target device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) sysfs directory will then contain the "firmware_node" symbolic link to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) the sysfs directory of the companion ACPI device object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) The linking mechanism relies on device identification provided by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) ACPI namespace. For example, if there's an ACPI namespace object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) representing a PCI device (i.e. a device object under an ACPI namespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) object representing a PCI bridge) whose _ADR returns 0x00020000 and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) bus number of the parent PCI bridge is 0, the sysfs directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) representing the struct acpi_device object created for that ACPI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) namespace object will contain the 'physical_node' symbolic link to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) corresponding PCI device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) The linking mechanism is generally bus-specific. The core of its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) implementation is located in the drivers/acpi/glue.c file, but there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) complementary parts depending on the bus types in question located
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) elsewhere. For example, the PCI-specific part of it is located in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) drivers/pci/pci-acpi.c.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) Example Linux ACPI Device Tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) The sysfs hierarchy of struct acpi_device objects corresponding to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) example ACPI namespace illustrated in Figure 2 with the addition of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) fixed PWR_BUTTON/SLP_BUTTON devices is shown below::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) +--------------+---+-----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) +--------------+---+-----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) | +-------------+-----+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) | +-------------+-----+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) | +-------------+-----+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) | +-------------+-----+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) | +-----------+------------+--------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) | +-----------+------------+--------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) | +-------------+-------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) | +-------------+-------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) | | +- - - - - - - +- - - - - - +- - - - - - - -+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) | | +- - - - - - - +- - - - - - +- - - - - - - -+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) | | +------------+------------+-----------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) | +------------+------------+-----------------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) | | +-----------+-----------------+-----+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) | +-| device:00 | \_SB_.PCI0.RP03 | N/A |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) | | +-----------+-----------------+-----+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) | | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) | | | +-------------+----------------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) | | +-------------+----------------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) | | +-------------+-----------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) | +-------------+-----------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) | |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) | | +-----------+-----------------+-----+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) | +-| device:01 | \_SB_.PCI0.DD01 | N/A |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) | +-----------+-----------------+-----+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) | +-------------+-------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) +-------------+-------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) | +-------------+------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) | +-------------+------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) | +------------+------------+---------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) | +------------+------------+---------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) | +-------------+------------+----------------+
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: |
^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) Figure 3. Example Linux ACPI Device Tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) .. note:: Each node is represented as "object/path/modalias", where:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) 1. 'object' is the name of the object's directory in sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) 2. 'path' is the ACPI namespace path of the corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) ACPI namespace object, as returned by the object's 'path'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) sysfs attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) 3. 'modalias' is the value of the object's 'modalias' sysfs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) attribute (as described earlier in this document).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) .. note:: N/A indicates the device object does not have the 'path' or the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) 'modalias' attribute.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags