diff mbox series

[v4,02/63] Documentation: ACPI: move namespace.txt to firmware-guide/acpi and convert to reST

Message ID 20190423162932.21428-3-changbin.du@gmail.com (mailing list archive)
State New, archived
Delegated to: Bjorn Helgaas
Headers show
Series Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand

Commit Message

Changbin Du April 23, 2019, 4:28 p.m. UTC
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%)

Comments

Mauro Carvalho Chehab April 23, 2019, 8:38 p.m. UTC | #1
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
Changbin Du April 24, 2019, 4:09 p.m. UTC | #2
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 mbox series

Patch

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.