| Message ID | 20190423162932.21428-3-changbin.du@gmail.com (mailing list archive) |
|---|---|
| State | Not Applicable |
| Headers | show |
| Series | Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand |
Em Wed, 24 Apr 2019 00:28:31 +0800 Changbin Du <changbin.du@gmail.com> escreveu: > This converts the plain text documentation to reStructuredText format and > add it to Sphinx TOC tree. No essential content change. > > Signed-off-by: Changbin Du <changbin.du@gmail.com> > --- > Documentation/firmware-guide/acpi/index.rst | 1 + > .../acpi/namespace.rst} | 310 +++++++++--------- > 2 files changed, 161 insertions(+), 150 deletions(-) > rename Documentation/{acpi/namespace.txt => firmware-guide/acpi/namespace.rst} (54%) > > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst > index 0ec7d072ba22..210ad8acd6df 100644 > --- a/Documentation/firmware-guide/acpi/index.rst > +++ b/Documentation/firmware-guide/acpi/index.rst > @@ -7,3 +7,4 @@ ACPI Support > .. toctree:: > :maxdepth: 1 > > + namespace > diff --git a/Documentation/acpi/namespace.txt b/Documentation/firmware-guide/acpi/namespace.rst > similarity index 54% > rename from Documentation/acpi/namespace.txt > rename to Documentation/firmware-guide/acpi/namespace.rst > index 1860cb3865c6..443f0e5d0617 100644 > --- a/Documentation/acpi/namespace.txt > +++ b/Documentation/firmware-guide/acpi/namespace.rst > @@ -1,85 +1,88 @@ > +.. SPDX-License-Identifier: GPL-2.0 > +.. include:: <isonum.txt> > + > +=================================================== > ACPI Device Tree - Representation of ACPI Namespace > +=================================================== > + > +:Copyright: |copy| 2013, Intel Corporation > + > +:Author: Lv Zheng <lv.zheng@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 > + /sys/bus/acpi/devices. > + This document illustrates the structure of the ACPI device tree. Well, this is a matter of preference. I would add Abstract as a chapter, as this would make it part of the top index, with can be useful. In any case: Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> > + > +:Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and > + Rafael J.Wysocki <rafael.j.wysocki@intel.com>. > + > + > +ACPI Definition Blocks > +====================== > + > +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). > + > +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. > + > + > +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: > > -Copyright (C) 2013, Intel Corporation > -Author: Lv Zheng <lv.zheng@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 > -/sys/bus/acpi/devices. > -This document illustrates the structure of the ACPI device tree. > - > - > -Credit: > - > -Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J. > -Wysocki <rafael.j.wysocki@intel.com>. > - > - > -1. ACPI Definition Blocks > - > - 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). > - > - 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 +94,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 +187,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 +230,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 +254,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 +281,47 @@ Wysocki <rafael.j.wysocki@intel.com>. > object's bus_id. > > > -4. 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. > - > - 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. > - > - > -5. 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. > +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. > + > +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. > + > + > +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:: > > +--------------+---+-----------------+ > | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: | > @@ -377,12 +385,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. Thanks, Mauro
On Tue, Apr 23, 2019 at 05:38:40PM -0300, Mauro Carvalho Chehab wrote: > Em Wed, 24 Apr 2019 00:28:31 +0800 > Changbin Du <changbin.du@gmail.com> escreveu: > > > This converts the plain text documentation to reStructuredText format and > > add it to Sphinx TOC tree. No essential content change. > > > > Signed-off-by: Changbin Du <changbin.du@gmail.com> > > --- > > Documentation/firmware-guide/acpi/index.rst | 1 + > > .../acpi/namespace.rst} | 310 +++++++++--------- > > 2 files changed, 161 insertions(+), 150 deletions(-) > > rename Documentation/{acpi/namespace.txt => firmware-guide/acpi/namespace.rst} (54%) > > > > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst > > index 0ec7d072ba22..210ad8acd6df 100644 > > --- a/Documentation/firmware-guide/acpi/index.rst > > +++ b/Documentation/firmware-guide/acpi/index.rst > > @@ -7,3 +7,4 @@ ACPI Support > > .. toctree:: > > :maxdepth: 1 > > > > + namespace > > diff --git a/Documentation/acpi/namespace.txt b/Documentation/firmware-guide/acpi/namespace.rst > > similarity index 54% > > rename from Documentation/acpi/namespace.txt > > rename to Documentation/firmware-guide/acpi/namespace.rst > > index 1860cb3865c6..443f0e5d0617 100644 > > --- a/Documentation/acpi/namespace.txt > > +++ b/Documentation/firmware-guide/acpi/namespace.rst > > @@ -1,85 +1,88 @@ > > +.. SPDX-License-Identifier: GPL-2.0 > > +.. include:: <isonum.txt> > > + > > +=================================================== > > ACPI Device Tree - Representation of ACPI Namespace > > +=================================================== > > + > > +:Copyright: |copy| 2013, Intel Corporation > > + > > +:Author: Lv Zheng <lv.zheng@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 > > + /sys/bus/acpi/devices. > > + This document illustrates the structure of the ACPI device tree. > > Well, this is a matter of preference. I would add Abstract as a chapter, > as this would make it part of the top index, with can be useful. > Now it becomes a chapter. Thanks. > In any case: > > Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> > > > + > > +:Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and > > + Rafael J.Wysocki <rafael.j.wysocki@intel.com>. > > + > > + > > +ACPI Definition Blocks > > +====================== > > + > > +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). > > + > > +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. > > + > > + > > +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: > > > > -Copyright (C) 2013, Intel Corporation > > -Author: Lv Zheng <lv.zheng@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 > > -/sys/bus/acpi/devices. > > -This document illustrates the structure of the ACPI device tree. > > - > > - > > -Credit: > > - > > -Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J. > > -Wysocki <rafael.j.wysocki@intel.com>. > > - > > - > > -1. ACPI Definition Blocks > > - > > - 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). > > - > > - 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 +94,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 +187,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 +230,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 +254,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 +281,47 @@ Wysocki <rafael.j.wysocki@intel.com>. > > object's bus_id. > > > > > > -4. 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. > > - > > - 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. > > - > > - > > -5. 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. > > +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. > > + > > +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. > > + > > + > > +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:: > > > > +--------------+---+-----------------+ > > | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: | > > @@ -377,12 +385,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. > > > > Thanks, > Mauro
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 0ec7d072ba22..210ad8acd6df 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -7,3 +7,4 @@ ACPI Support .. toctree:: :maxdepth: 1 + namespace diff --git a/Documentation/acpi/namespace.txt b/Documentation/firmware-guide/acpi/namespace.rst similarity index 54% rename from Documentation/acpi/namespace.txt rename to Documentation/firmware-guide/acpi/namespace.rst index 1860cb3865c6..443f0e5d0617 100644 --- a/Documentation/acpi/namespace.txt +++ b/Documentation/firmware-guide/acpi/namespace.rst @@ -1,85 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=================================================== ACPI Device Tree - Representation of ACPI Namespace +=================================================== + +:Copyright: |copy| 2013, Intel Corporation + +:Author: Lv Zheng <lv.zheng@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 + /sys/bus/acpi/devices. + This document illustrates the structure of the ACPI device tree. + +:Credit: Thanks for the help from Zhang Rui <rui.zhang@intel.com> and + Rafael J.Wysocki <rafael.j.wysocki@intel.com>. + + +ACPI Definition Blocks +====================== + +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). + +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. + + +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: -Copyright (C) 2013, Intel Corporation -Author: Lv Zheng <lv.zheng@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 -/sys/bus/acpi/devices. -This document illustrates the structure of the ACPI device tree. - - -Credit: - -Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J. -Wysocki <rafael.j.wysocki@intel.com>. - - -1. ACPI Definition Blocks - - 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). - - 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 +94,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 +187,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 +230,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 +254,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 +281,47 @@ Wysocki <rafael.j.wysocki@intel.com>. object's bus_id. -4. 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. - - 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. - - -5. 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. +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. + +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. + + +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:: +--------------+---+-----------------+ | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: | @@ -377,12 +385,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.
This converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du <changbin.du@gmail.com> --- Documentation/firmware-guide/acpi/index.rst | 1 + .../acpi/namespace.rst} | 310 +++++++++--------- 2 files changed, 161 insertions(+), 150 deletions(-) rename Documentation/{acpi/namespace.txt => firmware-guide/acpi/namespace.rst} (54%)