Documentation: ACPI: move namespace.txt to firmware-guide/acpi and convert to reST
This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>hifive-unleashed-5.2
Changbin Du
Rafael J. Wysocki
parent
680e6ffa15
commit
8a2fe04b44
|
|
@ -7,3 +7,4 @@ ACPI Support
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
namespace
|
||||
|
|
|
|||
|
|
@ -1,85 +1,90 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0
|
||||
.. include:: <isonum.txt>
|
||||
|
||||
===================================================
|
||||
ACPI Device Tree - Representation of ACPI Namespace
|
||||
===================================================
|
||||
|
||||
Copyright (C) 2013, Intel Corporation
|
||||
Author: Lv Zheng <lv.zheng@intel.com>
|
||||
:Copyright: |copy| 2013, Intel Corporation
|
||||
|
||||
:Author: Lv Zheng <lv.zheng@intel.com>
|
||||
|
||||
Abstract:
|
||||
:Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and
|
||||
Rafael J.Wysocki <rafael.j.wysocki@intel.com>.
|
||||
|
||||
Abstract
|
||||
========
|
||||
The Linux ACPI subsystem converts ACPI namespace objects into a Linux
|
||||
device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
|
||||
receiving ACPI hotplug notification events. For each device object in this
|
||||
hierarchy there is a corresponding symbolic link in the
|
||||
receiving ACPI hotplug notification events. For each device object
|
||||
in this hierarchy there is a corresponding symbolic link in the
|
||||
/sys/bus/acpi/devices.
|
||||
|
||||
This document illustrates the structure of the ACPI device tree.
|
||||
|
||||
ACPI Definition Blocks
|
||||
======================
|
||||
|
||||
Credit:
|
||||
The ACPI firmware sets up RSDP (Root System Description Pointer) in the
|
||||
system memory address space pointing to the XSDT (Extended System
|
||||
Description Table). The XSDT always points to the FADT (Fixed ACPI
|
||||
Description Table) using its first entry, the data within the FADT
|
||||
includes various fixed-length entries that describe fixed ACPI features
|
||||
of the hardware. The FADT contains a pointer to the DSDT
|
||||
(Differentiated System Descripition Table). The XSDT also contains
|
||||
entries pointing to possibly multiple SSDTs (Secondary System
|
||||
Description Table).
|
||||
|
||||
Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
|
||||
Wysocki <rafael.j.wysocki@intel.com>.
|
||||
The DSDT and SSDT data is organized in data structures called definition
|
||||
blocks that contain definitions of various objects, including ACPI
|
||||
control methods, encoded in AML (ACPI Machine Language). The data block
|
||||
of the DSDT along with the contents of SSDTs represents a hierarchical
|
||||
data structure called the ACPI namespace whose topology reflects the
|
||||
structure of the underlying hardware platform.
|
||||
|
||||
The relationships between ACPI System Definition Tables described above
|
||||
are illustrated in the following diagram::
|
||||
|
||||
+---------+ +-------+ +--------+ +------------------------+
|
||||
| RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
|
||||
+---------+ | +-------+ | +--------+ +-|->| DSDT | |
|
||||
| Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
|
||||
+---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
|
||||
| Pointer |-+ | ..... | | ...... | | +-------------------+ |
|
||||
+---------+ +-------+ +--------+ | +-------------------+ |
|
||||
| Entry |------------------|->| SSDT | |
|
||||
+- - - -+ | +-------------------| |
|
||||
| Entry | - - - - - - - -+ | | Definition Blocks | |
|
||||
+- - - -+ | | +-------------------+ |
|
||||
| | +- - - - - - - - - -+ |
|
||||
+-|->| SSDT | |
|
||||
| +-------------------+ |
|
||||
| | Definition Blocks | |
|
||||
| +- - - - - - - - - -+ |
|
||||
+------------------------+
|
||||
|
|
||||
OSPM Loading |
|
||||
\|/
|
||||
+----------------+
|
||||
| ACPI Namespace |
|
||||
+----------------+
|
||||
|
||||
Figure 1. ACPI Definition Blocks
|
||||
|
||||
.. note:: RSDP can also contain a pointer to the RSDT (Root System
|
||||
Description Table). Platforms provide RSDT to enable
|
||||
compatibility with ACPI 1.0 operating systems. The OS is expected
|
||||
to use XSDT, if present.
|
||||
|
||||
|
||||
1. ACPI Definition Blocks
|
||||
Example ACPI Namespace
|
||||
======================
|
||||
|
||||
The ACPI firmware sets up RSDP (Root System Description Pointer) in the
|
||||
system memory address space pointing to the XSDT (Extended System
|
||||
Description Table). The XSDT always points to the FADT (Fixed ACPI
|
||||
Description Table) using its first entry, the data within the FADT
|
||||
includes various fixed-length entries that describe fixed ACPI features
|
||||
of the hardware. The FADT contains a pointer to the DSDT
|
||||
(Differentiated System Descripition Table). The XSDT also contains
|
||||
entries pointing to possibly multiple SSDTs (Secondary System
|
||||
Description Table).
|
||||
All definition blocks are loaded into a single namespace. The namespace
|
||||
is a hierarchy of objects identified by names and paths.
|
||||
The following naming conventions apply to object names in the ACPI
|
||||
namespace:
|
||||
|
||||
The DSDT and SSDT data is organized in data structures called definition
|
||||
blocks that contain definitions of various objects, including ACPI
|
||||
control methods, encoded in AML (ACPI Machine Language). The data block
|
||||
of the DSDT along with the contents of SSDTs represents a hierarchical
|
||||
data structure called the ACPI namespace whose topology reflects the
|
||||
structure of the underlying hardware platform.
|
||||
|
||||
The relationships between ACPI System Definition Tables described above
|
||||
are illustrated in the following diagram.
|
||||
|
||||
+---------+ +-------+ +--------+ +------------------------+
|
||||
| RSDP | +->| XSDT | +->| FADT | | +-------------------+ |
|
||||
+---------+ | +-------+ | +--------+ +-|->| DSDT | |
|
||||
| Pointer | | | Entry |-+ | ...... | | | +-------------------+ |
|
||||
+---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | |
|
||||
| Pointer |-+ | ..... | | ...... | | +-------------------+ |
|
||||
+---------+ +-------+ +--------+ | +-------------------+ |
|
||||
| Entry |------------------|->| SSDT | |
|
||||
+- - - -+ | +-------------------| |
|
||||
| Entry | - - - - - - - -+ | | Definition Blocks | |
|
||||
+- - - -+ | | +-------------------+ |
|
||||
| | +- - - - - - - - - -+ |
|
||||
+-|->| SSDT | |
|
||||
| +-------------------+ |
|
||||
| | Definition Blocks | |
|
||||
| +- - - - - - - - - -+ |
|
||||
+------------------------+
|
||||
|
|
||||
OSPM Loading |
|
||||
\|/
|
||||
+----------------+
|
||||
| ACPI Namespace |
|
||||
+----------------+
|
||||
|
||||
Figure 1. ACPI Definition Blocks
|
||||
|
||||
NOTE: RSDP can also contain a pointer to the RSDT (Root System
|
||||
Description Table). Platforms provide RSDT to enable
|
||||
compatibility with ACPI 1.0 operating systems. The OS is expected
|
||||
to use XSDT, if present.
|
||||
|
||||
|
||||
2. Example ACPI Namespace
|
||||
|
||||
All definition blocks are loaded into a single namespace. The namespace
|
||||
is a hierarchy of objects identified by names and paths.
|
||||
The following naming conventions apply to object names in the ACPI
|
||||
namespace:
|
||||
1. All names are 32 bits long.
|
||||
2. The first byte of a name must be one of 'A' - 'Z', '_'.
|
||||
3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
|
||||
|
|
@ -91,7 +96,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
|
|||
(i.e. names prepended with '^' are relative to the parent of the
|
||||
current namespace node).
|
||||
|
||||
The figure below shows an example ACPI namespace.
|
||||
The figure below shows an example ACPI namespace::
|
||||
|
||||
+------+
|
||||
| \ | Root
|
||||
|
|
@ -184,19 +189,20 @@ Wysocki <rafael.j.wysocki@intel.com>.
|
|||
Figure 2. Example ACPI Namespace
|
||||
|
||||
|
||||
3. Linux ACPI Device Objects
|
||||
Linux ACPI Device Objects
|
||||
=========================
|
||||
|
||||
The Linux kernel's core ACPI subsystem creates struct acpi_device
|
||||
objects for ACPI namespace objects representing devices, power resources
|
||||
processors, thermal zones. Those objects are exported to user space via
|
||||
sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
|
||||
format of their names is <bus_id:instance>, where 'bus_id' refers to the
|
||||
ACPI namespace representation of the given object and 'instance' is used
|
||||
for distinguishing different object of the same 'bus_id' (it is
|
||||
two-digit decimal representation of an unsigned integer).
|
||||
The Linux kernel's core ACPI subsystem creates struct acpi_device
|
||||
objects for ACPI namespace objects representing devices, power resources
|
||||
processors, thermal zones. Those objects are exported to user space via
|
||||
sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The
|
||||
format of their names is <bus_id:instance>, where 'bus_id' refers to the
|
||||
ACPI namespace representation of the given object and 'instance' is used
|
||||
for distinguishing different object of the same 'bus_id' (it is
|
||||
two-digit decimal representation of an unsigned integer).
|
||||
|
||||
The value of 'bus_id' depends on the type of the object whose name it is
|
||||
part of as listed in the table below.
|
||||
The value of 'bus_id' depends on the type of the object whose name it is
|
||||
part of as listed in the table below::
|
||||
|
||||
+---+-----------------+-------+----------+
|
||||
| | Object/Feature | Table | bus_id |
|
||||
|
|
@ -226,10 +232,11 @@ Wysocki <rafael.j.wysocki@intel.com>.
|
|||
|
||||
Table 1. ACPI Namespace Objects Mapping
|
||||
|
||||
The following rules apply when creating struct acpi_device objects on
|
||||
the basis of the contents of ACPI System Description Tables (as
|
||||
indicated by the letter in the first column and the notation in the
|
||||
second column of the table above):
|
||||
The following rules apply when creating struct acpi_device objects on
|
||||
the basis of the contents of ACPI System Description Tables (as
|
||||
indicated by the letter in the first column and the notation in the
|
||||
second column of the table above):
|
||||
|
||||
N:
|
||||
The object's source is an ACPI namespace node (as indicated by the
|
||||
named object's type in the second column). In that case the object's
|
||||
|
|
@ -249,13 +256,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
|
|||
struct acpi_device object with LNXVIDEO 'bus_id' will be created for
|
||||
it.
|
||||
|
||||
The third column of the above table indicates which ACPI System
|
||||
Description Tables contain information used for the creation of the
|
||||
struct acpi_device objects represented by the given row (xSDT means DSDT
|
||||
or SSDT).
|
||||
The third column of the above table indicates which ACPI System
|
||||
Description Tables contain information used for the creation of the
|
||||
struct acpi_device objects represented by the given row (xSDT means DSDT
|
||||
or SSDT).
|
||||
|
||||
The forth column of the above table indicates the 'bus_id' generation
|
||||
rule of the struct acpi_device object:
|
||||
|
||||
The forth column of the above table indicates the 'bus_id' generation
|
||||
rule of the struct acpi_device object:
|
||||
_HID:
|
||||
_HID in the last column of the table means that the object's bus_id
|
||||
is derived from the _HID/_CID identification objects present under
|
||||
|
|
@ -275,45 +283,47 @@ Wysocki <rafael.j.wysocki@intel.com>.
|
|||
object's bus_id.
|
||||
|
||||
|
||||
4. Linux ACPI Physical Device Glue
|
||||
Linux ACPI Physical Device Glue
|
||||
===============================
|
||||
|
||||
ACPI device (i.e. struct acpi_device) objects may be linked to other
|
||||
objects in the Linux' device hierarchy that represent "physical" devices
|
||||
(for example, devices on the PCI bus). If that happens, it means that
|
||||
the ACPI device object is a "companion" of a device otherwise
|
||||
represented in a different way and is used (1) to provide configuration
|
||||
information on that device which cannot be obtained by other means and
|
||||
(2) to do specific things to the device with the help of its ACPI
|
||||
control methods. One ACPI device object may be linked this way to
|
||||
multiple "physical" devices.
|
||||
ACPI device (i.e. struct acpi_device) objects may be linked to other
|
||||
objects in the Linux' device hierarchy that represent "physical" devices
|
||||
(for example, devices on the PCI bus). If that happens, it means that
|
||||
the ACPI device object is a "companion" of a device otherwise
|
||||
represented in a different way and is used (1) to provide configuration
|
||||
information on that device which cannot be obtained by other means and
|
||||
(2) to do specific things to the device with the help of its ACPI
|
||||
control methods. One ACPI device object may be linked this way to
|
||||
multiple "physical" devices.
|
||||
|
||||
If an ACPI device object is linked to a "physical" device, its sysfs
|
||||
directory contains the "physical_node" symbolic link to the sysfs
|
||||
directory of the target device object. In turn, the target device's
|
||||
sysfs directory will then contain the "firmware_node" symbolic link to
|
||||
the sysfs directory of the companion ACPI device object.
|
||||
The linking mechanism relies on device identification provided by the
|
||||
ACPI namespace. For example, if there's an ACPI namespace object
|
||||
representing a PCI device (i.e. a device object under an ACPI namespace
|
||||
object representing a PCI bridge) whose _ADR returns 0x00020000 and the
|
||||
bus number of the parent PCI bridge is 0, the sysfs directory
|
||||
representing the struct acpi_device object created for that ACPI
|
||||
namespace object will contain the 'physical_node' symbolic link to the
|
||||
/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
|
||||
corresponding PCI device.
|
||||
If an ACPI device object is linked to a "physical" device, its sysfs
|
||||
directory contains the "physical_node" symbolic link to the sysfs
|
||||
directory of the target device object. In turn, the target device's
|
||||
sysfs directory will then contain the "firmware_node" symbolic link to
|
||||
the sysfs directory of the companion ACPI device object.
|
||||
The linking mechanism relies on device identification provided by the
|
||||
ACPI namespace. For example, if there's an ACPI namespace object
|
||||
representing a PCI device (i.e. a device object under an ACPI namespace
|
||||
object representing a PCI bridge) whose _ADR returns 0x00020000 and the
|
||||
bus number of the parent PCI bridge is 0, the sysfs directory
|
||||
representing the struct acpi_device object created for that ACPI
|
||||
namespace object will contain the 'physical_node' symbolic link to the
|
||||
/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
|
||||
corresponding PCI device.
|
||||
|
||||
The linking mechanism is generally bus-specific. The core of its
|
||||
implementation is located in the drivers/acpi/glue.c file, but there are
|
||||
complementary parts depending on the bus types in question located
|
||||
elsewhere. For example, the PCI-specific part of it is located in
|
||||
drivers/pci/pci-acpi.c.
|
||||
The linking mechanism is generally bus-specific. The core of its
|
||||
implementation is located in the drivers/acpi/glue.c file, but there are
|
||||
complementary parts depending on the bus types in question located
|
||||
elsewhere. For example, the PCI-specific part of it is located in
|
||||
drivers/pci/pci-acpi.c.
|
||||
|
||||
|
||||
5. Example Linux ACPI Device Tree
|
||||
Example Linux ACPI Device Tree
|
||||
=================================
|
||||
|
||||
The sysfs hierarchy of struct acpi_device objects corresponding to the
|
||||
example ACPI namespace illustrated in Figure 2 with the addition of
|
||||
fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
|
||||
The sysfs hierarchy of struct acpi_device objects corresponding to the
|
||||
example ACPI namespace illustrated in Figure 2 with the addition of
|
||||
fixed PWR_BUTTON/SLP_BUTTON devices is shown below::
|
||||
|
||||
+--------------+---+-----------------+
|
||||
| LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
|
||||
|
|
@ -377,12 +387,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
|
|||
|
||||
Figure 3. Example Linux ACPI Device Tree
|
||||
|
||||
NOTE: Each node is represented as "object/path/modalias", where:
|
||||
1. 'object' is the name of the object's directory in sysfs.
|
||||
2. 'path' is the ACPI namespace path of the corresponding
|
||||
ACPI namespace object, as returned by the object's 'path'
|
||||
sysfs attribute.
|
||||
3. 'modalias' is the value of the object's 'modalias' sysfs
|
||||
attribute (as described earlier in this document).
|
||||
NOTE: N/A indicates the device object does not have the 'path' or the
|
||||
'modalias' attribute.
|
||||
.. note:: Each node is represented as "object/path/modalias", where:
|
||||
|
||||
1. 'object' is the name of the object's directory in sysfs.
|
||||
2. 'path' is the ACPI namespace path of the corresponding
|
||||
ACPI namespace object, as returned by the object's 'path'
|
||||
sysfs attribute.
|
||||
3. 'modalias' is the value of the object's 'modalias' sysfs
|
||||
attribute (as described earlier in this document).
|
||||
|
||||
.. note:: N/A indicates the device object does not have the 'path' or the
|
||||
'modalias' attribute.
|
||||
Loading…
Reference in New Issue